home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 December / PCWorld_2000-12_cd.bin / Komunikace / Comanche / docs / user / userguide.sgml < prev   
SGML Document  |  2000-11-02  |  17KB
  1.  
  2. <!doctype linuxdoc system>
  3.  
  4. <article>
  5.  
  6. <!-- Title Information -->
  7.  
  8. <title>Comanche User Guide
  9. <author>Daniel Lopez Ridruejo, <tt/ridruejo@apache.org/
  10. <date>v0.2, 1 December 1999
  11.  
  12. <!-- Abstract -->
  13. <abstract>
  14. This document explains how to get started with Comanche and gives an
  15. overview of its capabilities.
  16. </abstract>
  17.  
  18. <!-- Table of Contents -->
  19. <toc>
  20.  
  21.  
  22. <sect>User Guide for Comanche
  23. <p>
  24. This document introduces Comanche from an end user perspective, with an
  25. emphasis on how to quickly become productive with Comanche. As a guiding
  26. example, this introduction deals with the Apache module for Comanche.
  27. There is one section on Samba. Samba support is more experimental than Apache.
  28. <p>
  29. This release of Comanche is completely functional. As in any other complex
  30. piece of software, there is always room for improvements and a decision
  31. needs to be made as to when to make a release. The author believes this
  32. release is a good blend of functionality and ease of use.
  33. <p>
  34. <sect1>Downloading and installing Comanche
  35. <p>
  36. You can download Comanche at <htmlurl
  37. url="http://www.covalent.net/projects/comanche/downloads">. Comanche runs on
  38. most Unices and Windows 95/98/NT. There are binaries available for the
  39. following platforms: Linux intel, Irix MIPS, Solaris Sparc, HP parisc and
  40. Windows. It is recommended that you download first the binary since it is
  41. ready to run. If you wish you may compile the source later (basically you
  42. have to compile Tcl/Tk and the incr Tcl extension). More on this in the
  43. appendix.
  44.  
  45. <sect2>Apache on Windows
  46. <p> 
  47. <itemize>
  48. <item>Install Apache 1.3.x for Windows from 
  49. <htmlurl url="http://www.apache.org/">. You can
  50. download it from <htmlurl url="http://www.apache.org/dist/">
  51. <item>Install Comanche: Uncompress the downloaded file using <url
  52. url="http://www.winzip.com" name="Winzip"> or a similar tool
  53. </itemize>
  54.  
  55. <sect2>Apache on Unix
  56. <p> Download the appropriate binary file for your platform. Type: gunzip
  57. comanche-XX.tgz ; tar xvf comanche-XX.tar<br>
  58.  
  59. <sect1>Back up the configuration files
  60. <p>
  61.    Before the user becomes familiar with Comanche, it is a good idea for him
  62. to back up the configuration files. In Unix they are usually located under
  63. the conf subdirectory of the place where the user installed Apache. If he
  64. installed Apache from the source release and he did not changed the
  65. destination directory, it defaults to /usr/local/apache. If Apache came
  66. preinstalled, different distributions tend to place configuration files in
  67. different places. In Red Hat look under /etc/httpd. In other distributions
  68. the user may need to look into /usr/local/etc/httpd/.
  69. <p>
  70.    In the conf subdirectory the user will find at least three files:
  71. httpd.conf, srm.conf, and access.conf. Later versions of Apache only need to
  72. deal with one configuration file, httpd.conf
  73. <p>
  74.    The user should make  a copy of those files and put them in a safe place.
  75.  
  76. <sect1>Starting Comanche
  77. <p>
  78. <sect2>Windows
  79. <p>In the Windows platform, the user needs to open the folder that contains
  80. the Comanche executable (Comanche.exe) and double-click on the icon. This
  81. will start up Comanche. There is no need for further configuration, since
  82. Apache stores it settings in the Windows Registry. Comanche reads these
  83. settings and provides the user the possibility to configure all installed
  84. versions of Apache. In case there is no version of Apache installed,
  85. Comanche will prompt you with a dialog to manually specify where Apache
  86. files are located. This is useful if you just want to write configuration
  87. files without the need to have Apache installed or you have a custom version
  88. of Apache that is not in the registry (take a look to the following Starting
  89. Comanche on Unix section for more details in this dialog)
  90.  
  91. <sect2>Unix
  92. <p> The first time you install Comanche in Unix, you have to tell it where
  93. to find the Apache binaries and configuration files. It will display a
  94. dialog where you can specify:
  95. <itemize>
  96. <item>One-line server comment: Short description to help you identify the
  97. server (e.g "Production server" or "Apache SSL test machine").
  98. <item>Apache executable: usually named httpd. It is the Apache binary program.
  99. <item>Config file: the file containing the configuration directives, usually
  100. named httpd.conf or apache.conf. Older versions of Apache used 3
  101. configuration files (httpd.conf, srm.conf and access.conf, although any
  102. content can appear in any of the files). It is suggested that you combine
  103. the contents of the three files in one httpd.conf if you plan to use it
  104. with Comanche.
  105. <item>Commands: Here you can specify commands for
  106. starting, stopping or restarting the server
  107. </itemize>
  108. If you have installed Apache yourself from the source in the default
  109. directory /usr/local/apache then the information to fill is:
  110. <itemize>
  111. <item>Executable: /usr/local/apache/bin/httpd
  112. <item>Config file: /usr/local/apache/conf/htppd.conf or
  113. /usr/local/apache/conf/apache.conf
  114. <item>Commands (name; command; icon):
  115. <itemize>
  116. <item>start; /usr/local/apache/bin/apachectl start; start 
  117. <item>stop; /usr/local/apache/bin/apachectl stop; stop
  118. <item>restart; /usr/local/apache/bin/apachectl restart; refresh
  119. <item> Other ones that you may want to consider if you have the lynx browser
  120. installed:
  121. <item>status; /usr/local/apache/bin/apachectl status ;wheelSmall
  122. <item>fullstatus; /usr/local/apache/bin/apachectl fullstatus ;wheelSmall
  123. </itemize>
  124. </itemize>
  125.  
  126. If you are running Red Hat Linux:
  127. <itemize>
  128. <item>Executable: /usr/sbin/httpd
  129. <item>Config file: /etc/httpd/conf/htppd.conf
  130. <item>Commands (name; command; icon):
  131. <itemize>
  132. <item>start; /etc/rc.d/init.d/httpd start ; start 
  133. <item>stop; /etc/rc.d/init.d/httpd stop ; stop
  134. <item>restart; /etc/rc.d/init.d/httpd restart ; refresh
  135. <item>status; /etc/rc.d/init.d/httpd status ;wheelSmall
  136. </itemize>
  137. </itemize>
  138. People with other distributions of Linux please contact me with the default
  139. location of files, so I can include them here. You can have a look and
  140. manually alter this configuration at plugins/apache/apache.conf
  141.  
  142. <sect1>The interface
  143. <p>
  144.    Once Comanche has been started, it displays a Windows Explorer like
  145. interface. It is divided in several parts. On the top, there is a Menubar.
  146. These menus can be used to exit Comanche, access online help or display an
  147. About box.
  148. <p>
  149.    There is a tree structure in the left, which allows the user to connect
  150. to each of the managed machines, represented by icons, by double clicking on
  151. them. This expands them into various nodes representing services that can be
  152. managed. The user can navigate clicking the nodes or using the navigation
  153. buttons in the upper task bar.
  154. <p><img src="images/ug-console-general.gif">
  155. <p>
  156.    When a user selects a node by clicking on it, the right panel will be
  157. loaded with a HTML page that will display information about the currently
  158. selected node. The user can request further inforamtion or execute actions
  159. by clicking in the appropriate links.
  160. <p>
  161.    By right-clicking on a node, Comanche will pop up a menu. This menu is
  162. context sensitive and will vary depending on the node. In this version of
  163. Comanche it enables the user to request the property pages for a certain
  164. node or create new nodes
  165. <p><img src="images/ug-console-menu.gif">
  166.  
  167. <sect1>Apache module for Comanche.
  168. <p>
  169.   The current Apache module for Comanche supports the most commonly used
  170. options of Apache. All others options are preserved and can be edited via
  171. the command line interface if the needs arises. Support for new directives
  172. can be easily added through XML configuration files as described in other
  173. sections of this document.
  174. <p>
  175.   To access the Apache plugin, click on the computer icon it will display
  176. the currently installed modules. One of them must be the Apache module.
  177. Expand that node and you will see at least the following nodes:
  178. <p>
  179. <bf>Server Management</bf>. Here you can Start/Stop/Restart the Apache
  180. server process. If you have certain parameters configured you can also have
  181. access to the current statistics served (via the status module). 
  182. <p>
  183. <bf>Default Server</bf>. With Apache you can host several websites
  184. just using a single Apache server. This is a popular technique named virtual
  185. hosting. Comanche lets you configure different virtual hosts. These virtual
  186. hosts inherit certain settings from a main server (Default server).
  187. Characteristics defined here will be inherited by all virtual hosts. Certain
  188. Apache properties can only be configured in the Default Server node.
  189. <p>
  190.    Setting an Apache server is simple using Comanche. If the user just wants
  191. a web server to server static files, there is only a few pieces of
  192. information that Apache needs to know in order to do its job.
  193. <p>
  194.    Right clicking on the node named "Default Server" and selecting
  195. configure brings up a set of Property Pages.
  196. <p>First thing to fill in the property page is the server name (look figure).
  197.    Usually Apache is able to know the name of the machine it is installed
  198. via a reverse lookup of its IP address (given that my IP number is X, what
  199. is my name?). This entry should be filled with the Fully Qualified Domain
  200. Name for the machine, which is probably something similar to
  201. www.somedomain.com. This name has to have a DNS record set up 
  202. to work if it is to be accessed from the internet (that is, you cannot just
  203. come up with a name and hope it works). If you do not know what a DNS record
  204. is contact your system admin, have a look at the file /etc/hosts on Unix
  205. Systems or just set server name to the IP address of the machine. Another
  206. important piece of information is the web master email address, which will
  207. get transmitted to the visitors if they encounter a problem while browsing
  208. the web site. 
  209. <p>
  210.    To complete the basic set up it is necessary to tell Apache the document
  211. root, which is the directory containing the web pages to be served. That is,
  212. if you choose your document root to be /usr/local/apache/htdocs and the user
  213. requests http://www.somedomain.com/bla.html, Apache will get him the file
  214. /usr/local/apache/htdocs/bla.html by default.<p>
  215.    Once you have changed these parameters, you can go back to the <bf>Server
  216. Management</bf> node and restart the server so the changes take place.
  217. <p><img src="images/ug-console-main-server-servername.gif">
  218. <p>
  219.    Other settings that can be configured are:
  220. <p>
  221.    <bf>Listening settings</bf>: Web servers can listen to a specific port. The
  222. default port that Apache listens to is 80. To access ports lower than
  223. 1024 requires administrator privileges. Changing this parameter to a
  224. different number allows a normal user to run his own web server at a higher
  225. port. As an experiment, change the Port parameter to 8080 and restart the
  226. server. Try connecting to your webserver like http://www.somedomain.com. It
  227. will give you an error. Now try connecting to http://www.somedomain.com:8080 .
  228. It should work (just remember to restart the server everytime you apply
  229. changes.
  230. <p>
  231.    Also, the user may choose to only listen to a certain IP address or to
  232. all the available IP addresses.
  233. <p><img src="images/ug-main-server-listen.gif">
  234. <p>
  235.    <bf>Logging</bf>: When Apache finds an error, it can report it to a file
  236. (the error log) or it can notify system logging system (syslog in
  237. Unix machines). The error logging files are the first place that should be
  238. checked when there is a problem with a web server configuration,
  239. permissions, etc.
  240. <p><img src="images/ug-main-server-logs.gif">
  241. <p>
  242.    <bf>Directory aliases</bf>: It is possible to map certain URLs to
  243. directories in the filesystem. It is possible to map /images to
  244. /ftp/pub/images, and thus when the user requests the file
  245. http://www.someserver.com/images/button.gif the server will deliver the file
  246. /ftp/pub/images/button.gif 
  247. <p><img src="images/ug-main-server-alias.gif">
  248. <p>
  249.    <bf>CGI</bf>: CGI does the same, but it instructs the web server that the
  250. destination directory contains cgi programs. Cgi programs are not served as
  251. is, but executed and they provide content to the user.
  252. <p><img src="images/ug-main-server-cgi.gif">
  253. <p>
  254.    <bf>Redirection</bf>: Allows an user to redirect requests for certain
  255. urls to a different location.
  256. <p><img src="images/ug-main-server-redirect.gif">
  257. <p>Redirection, Directory and CGI aliases allow for regular expression
  258. modes. Regular expressions allow for matching of URLs against certain
  259. predefined patterns. 
  260. <p>
  261.    Comanche makes it possible to easily create virtual hosts. As explained
  262. before, virtual hosts allows a single Apache installation to serve requests for
  263. different internet domains. To create a new virtual host, the user can
  264. select with the right mouse button the Apache icon, and select the "Add new
  265. node" entry. This will pop up a window where the user can enter the IP
  266. address of the web server. The newly created node can then be administered
  267. with similar options to those of the Default Web Server.
  268. <p>
  269. Note: It is possible to enter the domain name in the previous dialog, but it
  270. is usually desirable to use the IP address. If a domain name is used instead,
  271. Apache must use DNS to find the address of www.somedomain.com. If for some
  272. reason DNS is not available at the time your server is parsing its config
  273. file, then this virtual host will not be configured. It won't be able to
  274. respond to any hits to this virtual host 
  275. <p><img src="images/ug-create-vhost.gif">
  276. <p>
  277. It is possible to create directory, location and files nodes under the
  278. default web server and virtual hosts. Directory and location nodes allow to
  279. place restrictions or configure properties based on the URL or file
  280. requested by the client. Files sections do the same for certain files or
  281. files patterns.
  282. <p>
  283.    To add a new directory or location, right click in the default web server
  284. or one of the virtual hosts node and select aqdd new node. Type in either
  285. the path to the directory or the URL of the location (For example, if we
  286. want to create a location that will be accesed when the user types
  287. http://www.somedomain.com/mylocation, the name of the location will be
  288. /mylocation).
  289. <p><img src="images/ug-create-directory.gif">
  290. <p>
  291.    The features currently implemented for location and directories have to
  292. do basically with IP based access control and user authentication. 
  293. <p>
  294. <bf>IP based access control</bf>.You can control who have access to these
  295. directories based on their IP address or domain name. You can choose in
  296. which order the directives will be evaluated and construct statements that
  297. allow denying or granting access based on certain IP, domain name or the
  298. existence of a certain environment variable (i.e specific version of a
  299. browser) 
  300. <p><img src="images/ug-directory-ipaccess.gif">
  301. <p>
  302. <bf>User authentication</bf>. With IP based access restrictions we can place
  303. restrictions on who can get our web pages based on <bf>where</bf> they come
  304. from. With user authentication, we can place restrictions based on
  305. <bf>who</bf> they are. For that we require a user name and a password (the
  306. password dialog box that appears on browsers when accessing restricted areas
  307. of a website).<p>
  308. The parameters that can be configured are:
  309. <itemize>
  310. <item><bf>Authentication realm</bf>: In the password pop up dialog box, it
  311. will indicate which resources the server is asking the password for (Member
  312. services, Administration, etc...)
  313. <item><bf>Authentication type</bf>: It can be basic (clear text) or based on
  314. a digest algorithm (supported by most modern browsers).
  315. <item><bf>Access based on user/group</bf>: Any valid user can have access,
  316. only certain users or only the users that belong to certain groups
  317. <item><bf>User/group files</bf>: Apache does not use Unix user/groups files,
  318. but instead maintains a database of its own. These configuration properties
  319. allows to specify the location of the files describing the users and groups.
  320. </itemize>
  321. <p><img src="images/ug-directory-auth-files.gif">
  322. <p><img src="images/ug-directory-user-group.gif">
  323. <p><img src="images/ug-directory-auth-realm.gif">
  324.  
  325.  
  326. <sect1>Samba support
  327. <p>
  328. Samba support in Comanche is still experimental. In fact, the whole Samba
  329. module was developed in one day. It offers similar options to SWAT (the
  330. excellent web based admin tool that comes with Samba). The file that
  331. the Samba module for Apache configures is (Comanche directory )/conf/samba/smb.conf
  332.  Replace that one with your own smb.conf file to configure your Samba
  333. installation. Expect support for Samba to improve in the near future.
  334.  
  335. </article>
  336.