PC World 2000 December/PCWorld_2000-12_cd.bin/Komunikace/Comanche/docs/user/userguide.sgml

SGML Document | 2000-11-02 | 16.3 KB | 336 lines

<!doctype linuxdoc system>

<article>

<!-- Title Information -->

<title>Comanche User Guide
<author>Daniel Lopez Ridruejo, <tt/[e-mail]/
<date>v0.2, 1 December 1999

<!-- Abstract -->
<abstract>
This document explains how to get started with Comanche and gives an
overview of its capabilities.
</abstract>

<!-- Table of Contents -->
<toc>


<sect>User Guide for Comanche
<p>
This document introduces Comanche from an end user perspective, with an
emphasis on how to quickly become productive with Comanche. As a guiding
example, this introduction deals with the Apache module for Comanche.
There is one section on Samba. Samba support is more experimental than Apache.
<p>
This release of Comanche is completely functional. As in any other complex
piece of software, there is always room for improvements and a decision
needs to be made as to when to make a release. The author believes this
release is a good blend of functionality and ease of use.
<p>
<sect1>Downloading and installing Comanche
<p>
You can download Comanche at <htmlurl
url="http://www.covalent.net/projects/comanche/downloads">. Comanche runs on
most Unices and Windows 95/98/NT. There are binaries available for the
following platforms: Linux intel, Irix MIPS, Solaris Sparc, HP parisc and
Windows. It is recommended that you download first the binary since it is
ready to run. If you wish you may compile the source later (basically you
have to compile Tcl/Tk and the incr Tcl extension). More on this in the
appendix.

<sect2>Apache on Windows
<p>
<itemize>
<item>Install Apache 1.3.x for Windows from
<htmlurl url="http://www.apache.org/">. You can
download it from <htmlurl url="http://www.apache.org/dist/">
<item>Install Comanche: Uncompress the downloaded file using <url
url="http://www.winzip.com" name="Winzip"> or a similar tool
</itemize>

<sect2>Apache on Unix
<p> Download the appropriate binary file for your platform. Type: gunzip
comanche-XX.tgz ; tar xvf comanche-XX.tar<br>

<sect1>Back up the configuration files
<p>
   Before the user becomes familiar with Comanche, it is a good idea for him
to back up the configuration files. In Unix they are usually located under
the conf subdirectory of the place where the user installed Apache. If he
installed Apache from the source release and he did not changed the
destination directory, it defaults to /usr/local/apache. If Apache came
preinstalled, different distributions tend to place configuration files in
different places. In Red Hat look under /etc/httpd. In other distributions
the user may need to look into /usr/local/etc/httpd/.
<p>
   In the conf subdirectory the user will find at least three files:
httpd.conf, srm.conf, and access.conf. Later versions of Apache only need to
deal with one configuration file, httpd.conf
<p>
   The user should make  a copy of those files and put them in a safe place.

<sect1>Starting Comanche
<p>
<sect2>Windows
<p>In the Windows platform, the user needs to open the folder that contains
the Comanche executable (Comanche.exe) and double-click on the icon. This
will start up Comanche. There is no need for further configuration, since
Apache stores it settings in the Windows Registry. Comanche reads these
settings and provides the user the possibility to configure all installed
versions of Apache. In case there is no version of Apache installed,
Comanche will prompt you with a dialog to manually specify where Apache
files are located. This is useful if you just want to write configuration
files without the need to have Apache installed or you have a custom version
of Apache that is not in the registry (take a look to the following Starting
Comanche on Unix section for more details in this dialog)

<sect2>Unix
<p> The first time you install Comanche in Unix, you have to tell it where
to find the Apache binaries and configuration files. It will display a
dialog where you can specify:
<itemize>
<item>One-line server comment: Short description to help you identify the
server (e.g "Production server" or "Apache SSL test machine").
<item>Apache executable: usually named httpd. It is the Apache binary program.
<item>Config file: the file containing the configuration directives, usually
named httpd.conf or apache.conf. Older versions of Apache used 3
configuration files (httpd.conf, srm.conf and access.conf, although any
content can appear in any of the files). It is suggested that you combine
the contents of the three files in one httpd.conf if you plan to use it
with Comanche.
<item>Commands: Here you can specify commands for
starting, stopping or restarting the server
</itemize>
If you have installed Apache yourself from the source in the default
directory /usr/local/apache then the information to fill is:
<itemize>
<item>Executable: /usr/local/apache/bin/httpd
<item>Config file: /usr/local/apache/conf/htppd.conf or
/usr/local/apache/conf/apache.conf
<item>Commands (name; command; icon):
<itemize>
<item>start; /usr/local/apache/bin/apachectl start; start
<item>stop; /usr/local/apache/bin/apachectl stop; stop
<item>restart; /usr/local/apache/bin/apachectl restart; refresh
<item> Other ones that you may want to consider if you have the lynx browser
installed:
<item>status; /usr/local/apache/bin/apachectl status ;wheelSmall
<item>fullstatus; /usr/local/apache/bin/apachectl fullstatus ;wheelSmall
</itemize>
</itemize>

If you are running Red Hat Linux:
<itemize>
<item>Executable: /usr/sbin/httpd
<item>Config file: /etc/httpd/conf/htppd.conf
<item>Commands (name; command; icon):
<itemize>
<item>start; /etc/rc.d/init.d/httpd start ; start
<item>stop; /etc/rc.d/init.d/httpd stop ; stop
<item>restart; /etc/rc.d/init.d/httpd restart ; refresh
<item>status; /etc/rc.d/init.d/httpd status ;wheelSmall
</itemize>
</itemize>
People with other distributions of Linux please contact me with the default
location of files, so I can include them here. You can have a look and
manually alter this configuration at plugins/apache/apache.conf

<sect1>The interface
<p>
   Once Comanche has been started, it displays a Windows Explorer like
interface. It is divided in several parts. On the top, there is a Menubar.
These menus can be used to exit Comanche, access online help or display an
About box.
<p>
   There is a tree structure in the left, which allows the user to connect
to each of the managed machines, represented by icons, by double clicking on
them. This expands them into various nodes representing services that can be
managed. The user can navigate clicking the nodes or using the navigation
buttons in the upper task bar.
<p><img src="images/ug-console-general.gif">
<p>
   When a user selects a node by clicking on it, the right panel will be
loaded with a HTML page that will display information about the currently
selected node. The user can request further inforamtion or execute actions
by clicking in the appropriate links.
<p>
   By right-clicking on a node, Comanche will pop up a menu. This menu is
context sensitive and will vary depending on the node. In this version of
Comanche it enables the user to request the property pages for a certain
node or create new nodes
<p><img src="images/ug-console-menu.gif">

<sect1>Apache module for Comanche.
<p>
  The current Apache module for Comanche supports the most commonly used
options of Apache. All others options are preserved and can be edited via
the command line interface if the needs arises. Support for new directives
can be easily added through XML configuration files as described in other
sections of this document.
<p>
  To access the Apache plugin, click on the computer icon it will display
the currently installed modules. One of them must be the Apache module.
Expand that node and you will see at least the following nodes:
<p>
<bf>Server Management</bf>. Here you can Start/Stop/Restart the Apache
server process. If you have certain parameters configured you can also have
access to the current statistics served (via the status module).
<p>
<bf>Default Server</bf>. With Apache you can host several websites
just using a single Apache server. This is a popular technique named virtual
hosting. Comanche lets you configure different virtual hosts. These virtual
hosts inherit certain settings from a main server (Default server).
Characteristics defined here will be inherited by all virtual hosts. Certain
Apache properties can only be configured in the Default Server node.
<p>
   Setting an Apache server is simple using Comanche. If the user just wants
a web server to server static files, there is only a few pieces of
information that Apache needs to know in order to do its job.
<p>
   Right clicking on the node named "Default Server" and selecting
configure brings up a set of Property Pages.
<p>First thing to fill in the property page is the server name (look figure).
   Usually Apache is able to know the name of the machine it is installed
via a reverse lookup of its IP address (given that my IP number is X, what
is my name?). This entry should be filled with the Fully Qualified Domain
Name for the machine, which is probably something similar to
www.somedomain.com. This name has to have a DNS record set up
to work if it is to be accessed from the internet (that is, you cannot just
come up with a name and hope it works). If you do not know what a DNS record
is contact your system admin, have a look at the file /etc/hosts on Unix
Systems or just set server name to the IP address of the machine. Another
important piece of information is the web master email address, which will
get transmitted to the visitors if they encounter a problem while browsing
the web site.
<p>
   To complete the basic set up it is necessary to tell Apache the document
root, which is the directory containing the web pages to be served. That is,
if you choose your document root to be /usr/local/apache/htdocs and the user
requests http://www.somedomain.com/bla.html, Apache will get him the file
/usr/local/apache/htdocs/bla.html by default.<p>
   Once you have changed these parameters, you can go back to the <bf>Server
Management</bf> node and restart the server so the changes take place.
<p><img src="images/ug-console-main-server-servername.gif">
<p>
   Other settings that can be configured are:
<p>
   <bf>Listening settings</bf>: Web servers can listen to a specific port. The
default port that Apache listens to is 80. To access ports lower than
1024 requires administrator privileges. Changing this parameter to a
different number allows a normal user to run his own web server at a higher
port. As an experiment, change the Port parameter to 8080 and restart the
server. Try connecting to your webserver like http://www.somedomain.com. It
will give you an error. Now try connecting to http://www.somedomain.com:8080 .
It should work (just remember to restart the server everytime you apply
changes.
<p>
   Also, the user may choose to only listen to a certain IP address or to
all the available IP addresses.
<p><img src="images/ug-main-server-listen.gif">
<p>
   <bf>Logging</bf>: When Apache finds an error, it can report it to a file
(the error log) or it can notify system logging system (syslog in
Unix machines). The error logging files are the first place that should be
checked when there is a problem with a web server configuration,
permissions, etc.
<p><img src="images/ug-main-server-logs.gif">
<p>
   <bf>Directory aliases</bf>: It is possible to map certain URLs to
directories in the filesystem. It is possible to map /images to
/ftp/pub/images, and thus when the user requests the file
http://www.someserver.com/images/button.gif the server will deliver the file
/ftp/pub/images/button.gif
<p><img src="images/ug-main-server-alias.gif">
<p>
   <bf>CGI</bf>: CGI does the same, but it instructs the web server that the
destination directory contains cgi programs. Cgi programs are not served as
is, but executed and they provide content to the user.
<p><img src="images/ug-main-server-cgi.gif">
<p>
   <bf>Redirection</bf>: Allows an user to redirect requests for certain
urls to a different location.
<p><img src="images/ug-main-server-redirect.gif">
<p>Redirection, Directory and CGI aliases allow for regular expression
modes. Regular expressions allow for matching of URLs against certain
predefined patterns.
<p>
   Comanche makes it possible to easily create virtual hosts. As explained
before, virtual hosts allows a single Apache installation to serve requests for
different internet domains. To create a new virtual host, the user can
select with the right mouse button the Apache icon, and select the "Add new
node" entry. This will pop up a window where the user can enter the IP
address of the web server. The newly created node can then be administered
with similar options to those of the Default Web Server.
<p>
Note: It is possible to enter the domain name in the previous dialog, but it
is usually desirable to use the IP address. If a domain name is used instead,
Apache must use DNS to find the address of www.somedomain.com. If for some
reason DNS is not available at the time your server is parsing its config
file, then this virtual host will not be configured. It won't be able to
respond to any hits to this virtual host
<p><img src="images/ug-create-vhost.gif">
<p>
It is possible to create directory, location and files nodes under the
default web server and virtual hosts. Directory and location nodes allow to
place restrictions or configure properties based on the URL or file
requested by the client. Files sections do the same for certain files or
files patterns.
<p>
   To add a new directory or location, right click in the default web server
or one of the virtual hosts node and select aqdd new node. Type in either
the path to the directory or the URL of the location (For example, if we
want to create a location that will be accesed when the user types
http://www.somedomain.com/mylocation, the name of the location will be
/mylocation).
<p><img src="images/ug-create-directory.gif">
<p>
   The features currently implemented for location and directories have to
do basically with IP based access control and user authentication.
<p>
<bf>IP based access control</bf>.You can control who have access to these
directories based on their IP address or domain name. You can choose in
which order the directives will be evaluated and construct statements that
allow denying or granting access based on certain IP, domain name or the
existence of a certain environment variable (i.e specific version of a
browser)
<p><img src="images/ug-directory-ipaccess.gif">
<p>
<bf>User authentication</bf>. With IP based access restrictions we can place
restrictions on who can get our web pages based on <bf>where</bf> they come
from. With user authentication, we can place restrictions based on
<bf>who</bf> they are. For that we require a user name and a password (the
password dialog box that appears on browsers when accessing restricted areas
of a website).<p>
The parameters that can be configured are:
<itemize>
<item><bf>Authentication realm</bf>: In the password pop up dialog box, it
will indicate which resources the server is asking the password for (Member
services, Administration, etc...)
<item><bf>Authentication type</bf>: It can be basic (clear text) or based on
a digest algorithm (supported by most modern browsers).
<item><bf>Access based on user/group</bf>: Any valid user can have access,
only certain users or only the users that belong to certain groups
<item><bf>User/group files</bf>: Apache does not use Unix user/groups files,
but instead maintains a database of its own. These configuration properties
allows to specify the location of the files describing the users and groups.
</itemize>
<p><img src="images/ug-directory-auth-files.gif">
<p><img src="images/ug-directory-user-group.gif">
<p><img src="images/ug-directory-auth-realm.gif">


<sect1>Samba support
<p>
Samba support in Comanche is still experimental. In fact, the whole Samba
module was developed in one day. It offers similar options to SWAT (the
excellent web based admin tool that comes with Samba). The file that
the Samba module for Apache configures is (Comanche directory )/conf/samba/smb.conf
 Replace that one with your own smb.conf file to configure your Samba
installation. Expect support for Samba to improve in the near future.

</article>