FIRST PREV NEXT LAST

Covalent Technologies

Configuring Apache 2.0

What are Directives?

Your control over the power and flexibility of the Covalent Enterprise Ready Server, Single Server Edition is found by modifying various directives in its configuration files. Directives are instructions to the Apache 2.0 server that cause it to behave in a specific manner. A directive consists on a name followed by one or more arguments. For example: 

ServerAdmin webmaster@myhost.mydomain
Note
If you manually modify any component of a server that is under the control of the Covalent Management Portal, the CMP will overwrite any manual changes on that server the next time it attempts to manage it.

The Configuration File

The main configuration file for the Covalent Enterprise Ready Server, Single Server Edition is httpsd.conf. It is located in the /path/to/server/$(ServerName)/conf directory (see "Important Files and Directories" for the locations of the files and directories required by Apache 2.0).

The httpsd executable reads the directives in the httpsd.conf file during its start-up routines.

Sections of the Configuration File

The httpsd.conf file is divided into a number of sections:

Global Environment Directives

ServerRoot

Defines the top of the directory tree under which the server's configuration, error, and log files are kept. For example: 

ServerRoot /path/to/server/$(ServerName)
Note
If you intend to place the ServerRoot in an NFS (or other network filesystem) mounted directory, you must set the LockFile directive to point to a file on a local disk.
All Windows directory paths use a slash "/" rather than a backslash "\" inside the httpsd.conf file.
Do not add a slash at the end of the directory path.

The Covalent Installer sets the ServerRoot to the correct directory for your server.

What are Multi-Processing Modules (MPM)?

Multi-Processing Modules (MPMs) extend the modular design of Apache technology used in the Covalent Enterprise Ready Server, Single Server Edition. These modules perform the most basic functions of a web server: binding to network ports on the machine, accepting requests, and dispatching children to handle the requests. MPMs allow Apache technology to cleanly and efficiently support a wide variety of operating systems.

With MPMs, the server can be better customized for the needs of the particular site. For example, sites that need a great deal of scalability can choose to use a threaded model such as the Worker MPM, while sites requiring stability or compatibility with older software can use the Prefork MPM.

MPMs must be compiled into the server. The Covalent Enterprise Ready Server, Single Server Edition for UNIX systems is shipped with two different pre-compiled versions of the Apache 2.0 server: the Prefork MPM and the Worker MPM. The Windows version is shipped with the Windows MPM pre-compiled.

Dynamic Load Handling Directives

The Apache 2.0 server dynamically adapts its load-it maintains enough server processes or threads to manage its current requests as well as a few spare requests to handle transients. You set these parameters for the server depending on which MPM you install.

Prefork MPM

This model implements a non-threaded, pre-forking server. It handles requests in a manner very similar to the default behaviour of Apache 1.3. This server is very robust. For example: 

<IfModule prefork.c> 
    StartServers         5 
    MinSpareServers      5 
    MaxSpareServers     10 
    MaxClients         150 
    MaxRequestsPerChild  0 
</IfModule>

Worker MPM

This model implements a hybrid multi-process multi-threaded server for systems that support POSIX threads. Each process has a fixed number of threads. When a request is received, it is passed to a worker thread for processing. The server adjusts to changes in its load by increasing or decreasing the number of processes. This server scales very easily but emphasizes robustness. For example: 

<IfModule worker.c> 
    StartServers         3 
    MaxClients           8 
    MinSpareThreads      5 
    MaxSpareThreads     75 
    ThreadsPerChild     25 
    MaxRequestsPerChild  0 
</IfModule>

Windows MPM

This module uses a single control process. It launches a single child process which in turn creates threads to handle requests. It handles requests in a manner very similar to the default behaviour of Apache 1.3 on Win32. For example: 

<IfModule mpm_winnt.c> 
    ThreadsPerChild    250 
    MaxRequestsPerChild  0 
</IfModule>

StartServers

The number of server processes to start initially. You may need to increase this value on a very active system.

MaxClients

This sets a limit on the total number of server processes running on this system-that is, a limit on the number of clients who can simultaneously connect. When this limit is reached, subsequent clients will be unable to access the server. Avoid setting it too low.

The MaxClients setting should correlate with the resources available to the host system. You should set this value according to the memory available on your system. If it is set too high, it will induce swapping, which can be catastrophic for your system performance.

MaxRequestsPerChild

This controls the number of requests each server process is allowed to process before it is forced to terminate. The server exits to avoid problems after prolonged use, such as memory leaks or other resource issues. A setting of 0 (zero) means the server process is allowed to handle an unlimited number of requests.

MinSpareServers

The minimum number of server processes to be kept as spares. If there are fewer than the specified number of servers idle, Apache creates enough new processes to reach the minimum. If this number is set to low, your server response will be very slow as new server processes will have to be created when the server load is high.

This directive is only used by the Prefork MPM.

MaxSpareServers

The maximum number of idle server processes to be kept as spares. If there are more than the specified number of servers idle, Apache terminates the additional processes. Increasing this value will allow the server to respond more quickly to changing load conditions. However, note that increasing the number of server processes also increases the load on the host system.

This directive is only used by the Prefork MPM.

MinSpareThreads

Similar to the above, this defines the minimum number of worker threads to be kept as spares. If the number of idle worker threads drops below this number, Apache creates another new server process to handle the load.

Changing this value effects the threads in all worker processes.

This directive is only used by the Worker MPM.

MaxSpareThreads

Similar to the above, this defines the maximum number of worker threads to be kept as spares. If there are more than the specified number of worker threads idle, Apache terminates the process running those threads.

Changing this value effects the threads in all worker processes.

This directive is only used by the Worker MPM.

ThreadsPerChild

This defines the number of worker threads created in each server process. This is a constant value. If you set this to 25, the server will spawn 25 threads in each server process it creates.

This directive is used by the Worker MPM and the Windows MPM.

Dynamic Shared Object (DSO) Support

You can easily reconfigure Apache by adding dynamic modules with the LoadModule directive. Support for loading individual modules is found in the module mod_so.c. This module is statically compiled into both MPMs shipped with the Covalent Enterprise Ready Server, Single Server Edition.

For a list of the built-in (statically linked and thus always available) modules in your HTTP binary, run the command httpsd -l (letter l as in list).
Note
On UNIX systems, you must add /path/to/install/apache/lib/ to your LD_LIBRARY_PATH before you run this command.

The DSO features have the following advantages:

LoadModule

This directive links the named object file or library into the server address space and adds the module structure named module to the list of active modules. For example: 

LoadModule external_module lib/mod_external.so

For more details about the DSO mechanism, see httpd.apache.org/docs/dso.html.

Main Server Configuration Directives

Listen

The port on which the server listens for requests. For ports less than 1023 on UNIX systems, httpsd must initially be run as root. The default port is 80. This directive is mandatory. For example: 

Listen 80

You can have multiple Listen directives defined, allowing your Apache 2.0 server to respond to requests on other ports. You can also define separate Listen ports for each <VirtualHost>. To support other features of the Covalent Enterprise Ready Server, Single Server Edition, you may have to define Listen ports for the Covalent FTP, the Covalent Logging Service, Covalent Authentication and Authorization, and others.

User/Group

These two directives define the name (or UID/GID) of the user/group that owns the running httpsd process. If you wish httpsd to run as a different user or group, you should initially run it as root. During initialization, it switches itself to the defined user/group.

These directives are only valid on UNIX systems.

The default setting is shown in the example: 

User nobody 
Group nobody

By judicious setting of file and directory permissions, it is possible to run Apache on a UNIX system as a non-root user. Check the owner permissions for the DocumentRoot directory as well as the your logging directories.

ServerAdmin

The email address of the administrator of this server. For example: 

ServerAdmin webmaster@myhost.mydomain

This address may appear on some server-generated pages, such as error documents, depending on the setting of the ServerSignature directive. The Covalent installer provides a default definition for this directive by pre-pending the conventional administrator username, webmaster, to the domainname of your server.

ServerName

This allows you to set a hostname for your server that may be different than its default hostname, for example, www instead of its real hostname.
Note
The ServerName must be a valid DNS name for your server. This name must be registered with an authoritative nameserver.
 

ServerName myserver.mydomain

If your server does not have a registered DNS name, assign its IP address to allow for efficient re-direction. The URL for the server is then based on the IP address instead of the registered DNS name.

For example, http://194.168.0.1/ would be: 

ServerName 194.168.0.1

If your server is listening for requests on a non-standard port, you need to include that port in the ServerName directive. For example: 

Listen 8080 
ServerName myserver.mydomain:8080

This is also required for efficient re-direction.

The Covalent Installer automatically sets the directive to the hostname.domain of the server if it can determine it; however, the directive is also commented out (there is a "#" at the beginning of the line).

DocumentRoot

This defines the directory that contains the files and directories this Apache server makes available to its clients. For example: 

DocumentRoot /path/to/server/$(ServerName)/htdocs

All requests are taken from this directory and its sub-directories, but, if the operating system supports them, symbolic links and aliases may be used to point to other locations.

Access Permissions

<Directory>

This directive provides for access control by directory. It is used to enclose a group of directives which apply only to the named directory and any sub-directories of that directory.
Note
URIs defined with this directive must correspond to the local filesystem.

You can define the services and features that are explicitly allowed or disabled in the directories to which the HTTP server has access. The first step is to configure the default with a very restrictive set of permissions: 

<Directory /> 
    Options FollowSymLinks 
    AllowOverride None 
</Directory>

You must allow specific features to be enabled in all subsequent entries. The next step is to configure the permissions for your DocumentRoot directory and its sub-directories:
Note
The directory path must be the same as defined by DocumentRoot.
 

<Directory /path/to/server/$(ServerName)/htdocs> 
    Options Indexes FollowSymLinks MultiViews 
    AllowOverride None 
    Order allow,deny 
    Allow from all 
</Directory>

<Location>

This directive provides access control by using a URL. It is similar to the <Directory> directive, and is used to enclose a group of directives that only apply to the named URL.
Note
URLs do not have to correspond with the filesystem at all. The <Location> directive can be used to refer to resources external to your server.

For example: 

<Location /status> 
    SetHandler server-status 
    Order Deny,Allow 
    Deny from all 
    Allow from www.covalent.net 
</Location>

<Files>

This directive provides access control by filename. It is similar to the <Directory> and <Location> directives, and is used to enclose a group of directives that are applied to any object with a basename (last component of filename) matching the specified filename. You can wildcards as in the following example: 

<Files ~ "^\.ht">

This string matches any filename that begins with .ht. See AccessFileName for a complete example.

Options

This directive controls which server features are available within a particular <Directory>. It takes an argument, option, which can be set to None, in which case no extra features are enabled, or one or more of the following (incomplete) list of options:

AllowOverride

This defines which directives declared in the file specified by AccessFileName (typically .htaccess) can override previously declared access information. When this directive is set to None, then .htaccess files are ignored completely.

Order

This directive controls the default access state and the order in which Allow and Deny directives are evaluated:

<IfModule>

The <IfModule test> ... </IfModule> section is used to mark directives that are conditional. The directives within an IfModule section are only processed if the test is true.

The test in an <IfModule> section directive can be one of two forms:

UserDir

Define this directive if you want your users to have personal websites within their home directories. It defines the name of the directory which may be found in the user's home directory when a request of the form http://host.domain/~user/ is received. For example: 

UserDir public_html


  

    Note 
     
On Windows systems, be especially careful to use forward slashes here. For example, "My Documents/My Website".

The following is an example for a site where these user directories are restricted to read-only. It also defines them to be in the /home directories of your server: 

<Directory /home/*/public_html> 
    AllowOverride FileInfo AuthConfig Limit 
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 
    <Limit GET POST OPTIONS PROPFIND> 
        Order allow,deny 
        Allow from all 
    </Limit> 
    <LimitExcept GET POST OPTIONS PROPFIND> 
        Order deny,allow 
        Deny from all 
    </LimitExcept> 
</Directory>


  

    Note 
     
On Windows systems, the directory would be "C:/Documents and Settings/*/My Documents/My Website". Again, note the forward slashes.

DirectoryIndex

The name of the file or files to use as a pre-written HTML directory index. Separate multiple entries with spaces. For example: 

DirectoryIndex index.html index.htm index.shtml index.jsp index.cgi

AccessFileName

The name of the file to look for in each directory for access control information. For example: 

AccessFileName .htaccess

To protect the AccessFileName from unauthorized viewing, you should set define its permissions: 

<Files ~ "^\.ht"> 
    Order allow,deny 
    Deny from all 
</Files>

The Files string matches any filename that begins with .ht.
Note
Many administrators use .htpasswd as the name for password files. This protects those as well.

TypesConfig

This defines where the mime.types file (or its equivalent) is to be found. For example: 

TypesConfig conf/mime.types

DefaultType

This defines the default MIME type the server uses for a document if it cannot otherwise determine one, such as from filename extensions. If your server contains mostly text or HTML documents, text/plain is a good value. If most of your content is binary, such as applications or images, you may want to use application/octet-stream instead to keep browsers from trying to display binary files as though they are text. For example: 

DefaultType text/plain

HostnameLookups

This directive tells the server to log the domainnames of clients or just their IP addresses, for example, www.apache.org (On) or 204.62.129.132 (Off). The default is Off because otherwise each client request results in AT LEAST one lookup request to a nameserver and thus add a great deal of network overhead and traffic to service the request. For example: 

HostnameLookups Off

ErrorLog

The location of the error log file. If you do not specify an ErrorLog directive within a <VirtualHost> container, error messages relating to that virtual host are also logged here. For example: 

ErrorLog logs/error_log

LogLevel

Control the number of messages logged to the ErrorLog. Possible values include: debug, info, notice, warn, error, crit, alert, and emerg. For example: 

LogLevel warn

LogFormat

This directive specifies the format of the CustomLog. For example: 

LogFormat "%h %l %u %t \"%r\" %>s %b" common

The above string is in Common Log Format (CLF) and expands to the following:

The following line from the server log show the effects of the format directives: 

194.0.0.24 - - [24/Jul/2001:09:12:44 -0800] "GET / HTTP/1.1" 200 658

CustomLog

This directive is used to log requests to the server. For example: 

CustomLog logs/access_log common

The arguments to the directive are the file (or pipe) to write the log to and the LogFormat to employ. In the example above, a nickname is used instead of a format string.

ServerSignature

This directive allows the addition of a line containing the server version and (virtual) hostname to server-generated pages (for example, error documents). Set to EMail to also include a mailto: link to the ServerAdmin. For example: 

ServerSignature Email

Alias

This directive makes available documents and other filesystem resources that exist outside of the DocumentRoot directory. For example: 

Alias /icons/ /path/to/server/$(ServerName)/icons/

ScriptAlias

This controls which directories contain server scripts. A ScriptAlias is essentially the same as an Alias, except that documents in the referenced directory are treated as applications and run by the server when requested. For example: 

ScriptAlias /cgi-bin/ /path/to/server/$(ServerName)/cgi-bin/

Redirect

This directive allows you to tell clients about documents which used to exist in your server's namespace, but do not any more. This allows you to tell the clients where to look for the relocated document. For example: 

Redirect permanent /service http://another.server.domain:8080

SetHandler

When placed into an .htaccess file or a <Directory> or <Location> section, this directive forces all matching files to be parsed through the handler defined by handler_name. For example, if you want the contents of a directory to be considered Perl scripts, regardless of extension, you would put the following into a <Directory> section: 

SetHandler perl-script

AuthType

This directive selects the type of user authentication for a directory. Only Basic and Digest are currently implemented. Basic authorization is the use of a login and password, using a mechanism similar to the UNIX login process. Digest authorization uses an MD5 Digest authorization mechanism. This method is much more secure than Basic authorization but is only supported on some of the available browsers. 

AuthType Basic

AuthType must be accompanied by AuthName and Require directives to work correctly.

Require

This directive selects which authenticated users can access a directory. The authenticated users and groups are determined by the back-end auth module. 

Require user userid [userid] ...

Only the named users can access the directory. 

Require group group-name [group-name] ...

Only users in the named groups can access the directory. 

Require valid-user

All valid users can access the directory.

Require must be accompanied by AuthName and AuthType directives to work correctly.

AuthName

This directive sets the name of the authentication domain for a directory. This auth-domain is given to the client so that the user knows which username and password to send. AuthName takes a single argument. If the auth-domain name contains spaces, it must be enclosed in quotation marks. 

AuthName "Covalent Authentication"

AuthName must be accompanied by AuthType and Require directives to work correctly.

What are Virtual Hosts?

Virtual hosts (or virtual servers) allow you to provide a number of Web servers from a single physical system. Each virtual host has its own domain name. With the first version of the Web protocol (HTTP 1.0), each virtual host needed a unique IP address. HTTP 1.1 eliminated this requirement. The domain name of the virtual hosts must be a valid name known to an authoritative name server.

Virtual Host Directives

<VirtualHost>

This directive is used to enclose a group of directives which apply only to a particular virtual host. It allows you to maintain multiple domains/hostnames on a single server.

Any directive which is allowed in a virtual host context may be used. When the server receives a request for a document on a particular virtual host, it uses the configuration directives enclosed in the <VirtualHost> section. For example: 

<VirtualHost *> 
    ServerAdmin webmaster@virtual.myhost.mydomain 
    DocumentRoot /www/docs/virtual.myhost.mydomain 
    ServerName virtual.myhost.mydomain 
    ErrorLog logs/virtual.myhost.mydomain-error_log 
    CustomLog logs/virtual.myhost.mydomain-access_log common 
</VirtualHost>

See www.apache.org/docs/vhosts for further details.

NameVirtualHost

If you want to use name-based virtual hosts you need to define at least one IP address (and port number) for them. For example: 

NameVirtualHost 194.0.0.24:80

What is suEXEC?
Note
The following section applies to UNIX systems only.

Normally, when a Common Gateway Interface (CGI) or Server-Side Include (SSI) program executes, it runs as the same user who is running the Covalent Enterprise Ready Server, Single Server Edition. By default, this user is nobody, the most unprivileged user on the system. The suEXEC feature provides you the ability to run CGI and SSI programs with a user ID different from the user ID running the Covalent Enterprise Ready Server, Single Server Edition.

suEXEC can reduce the security risks involved with allowing your users to develop and run private CGI or SSI programs. However, if it is improperly configured, it can break your computer's security and possibly cause other problems. If you are unfamiliar with managing setuid programs and the security issues they present, you should consider avoiding suEXEC.

suEXEC and the Covalent Enterprise Ready Server, Single Server Edition

In the Open Source release of Apache 2.0, you build the suEXEC wrapper as part of the process of configuring and compiling the server. During configuration, you define where the suEXEC wrapper is to be installed. The path to the suEXEC wrapper is then compiled into the Apache 2.0 server. If you move the suEXEC wrapper after you have compiled and installed the server, Apache will fail to find it and the suExec feature will be disabled.

The Covalent Enterprise Ready Server, Single Server Edition allows you to install its pre-compiled executables, configuration files, and directories anywhere in your filesystem. However, for the security built into the suEXEC wrapper to function correctly, its path has to be hardwired into the Covalent Enterprise Ready Server, Single Server Edition. This hardwired location is: 

/usr/local/covalent/apache/sbin/suexec

When the Covalent Enterprise Ready Server, Single Server Edition starts, it looks for the file suexec in the pre-defined directory. If it finds the suEXEC wrapper, it will print the following message to the error log: 

[notice] suEXEC mechanism enabled (wrapper: /path/to/sbin/suexec)

If you don't see this message at server start-up, the server is cannot finding the wrapper program where it expects it, or the permissions of the wrapper program have been changed from setuid root.

Disabling suEXEC

If you want to disable suEXEC you must remove or rename the suexec file, then restart the Covalent Enterprise Ready Server, Single Server Edition.


Covalent Technologies Inc.
o: 415/536-5200
f: 415/536-5210
e: sales@covalent.net
w: www.covalent.net
FIRST PREV NEXT LAST