Apache Configuration and Directives

---

Apache configuration operations take the form of directives entered into the Apache configuration files. With these directives, you can enter basic configuration information, such as your server name, or perform more complex operations, such as implementing virtual hosts. The design is flexible enough to enable you to define configuration features for particular directories and different virtual hosts. Apache has a variety of different directives performing operations as diverse as controlling directory access, assigning file icon formats, and creating log files. Most directives set values such as DirectoryRoot, which holds the root directory for the server's Web pages, or Port, which holds the port on the system that the server listens on for requests. Table 23-4 provides a listing of the more commonly used Apache directives. The syntax for a simple directive is shown here:

directive option option ... 

Certain directives create blocks able to hold directives that apply to specific server components (also referred to as sectional directives). For example, the Directory directive is used to define a block within which you place directives that apply only to a particular directory. Block directives are entered in pairs: a beginning directive and a terminating directive. The terminating directive defines the end of the block and consists of the same name beginning with a slash. Block directives take an argument that specifies the particular object to which the directives apply. For the Directory block directive, you must specify a directory name to which it will apply. The <Directory mydir> block directive creates a block whose directives within it apply to the mydir directory. The block is terminated by a </Directory> directive. The <VirtualHost hostaddress> block directive is used to configure a specific virtual Web server and must include the IP or domain name address used for that server. </VirtualHost> is its terminating directive. Any directives you place within this block are applied to that virtual Web server. The <Limit method> directive specifies the kind of access method you want to limit, such as GET or POST. The access control directives located within the block list the controls you are placing on those methods. The syntax for a block directive is as follows:

<block-directive option ... >  directive option ...  directive option ... </block-directive>

Usually, directives are placed in one of the main configuration files. Directory directives in those files can be used to configure a particular directory. However, Apache also makes use of directory-based configuration files. Any directory may have its own .htaccess file that holds directives to configure only that directory. If your site has many directories, or if any directories have special configuration needs, you can place their configuration directives in their .htaccess files, instead of filling the main configuration file with specific Directory directives for each one. You can control what directives in an .htaccess file take precedence over those in the main configuration files. If your site allows user- or client-controlled directories, you may want to carefully monitor or disable the use of .htaccess files in them. (It is possible for directives in an .htaccess file to override those in the standard configuration files unless disabled with AllowOverride directives.)

Much of the power and flexibility of the Apache Web server comes from its use of modules to extend its capabilities. Apache is implemented with a core set of directives. Modules can be created that hold definitions of other directives. They can be loaded into Apache, enabling you to use those directives for your server. A standard set of modules is included with the Apache distribution, though you can download others and even create your own. For example, the mod_autoindex module holds the directives for automatically indexing directories (as described in the following section). The mod_mime module holds the MIME type and handler directives. Modules are loaded with the LoadModule directive. You can find LoadModule directives in the httpd.conf configuration file for most of the standard modules.

LoadModule mime_module modules/mod_mime.so

The apxs application provided with the Apache package can be used to build Apache extension modules. With the apxs application, you can compile Apache module source code in C and create dynamically shared objects that can be loaded with the LoadModule directive. The apxs application requires that the mod_so module be part of your Apache application. It includes extensive options such as -n to specify the module name, -a to add an entry for it in the httpd.conf file, and -i to install the module on your Web server.

You can find a complete listing of Apache Web configuration directives at the Apache Web site, http.apache.org, and in the Apache manual located in your site's Web site root directory. On many systems, this is located in the manual subdirectory in the Web site default directory set up by the distribution (on Red Hat, this is /var/www/manual). Many of the more commonly used directives are listed in Table 22-4.

Server Configuration

Certain directives are used to configure your server's overall operations. These directives are placed in the httpd.conf configuration file. Some require pathnames, whereas others only need to be turned on or off with the keywords on and off. Apache provides a default httpd.conf configuration file. The httpd.conf file already contains these directives. Some are commented out with a preceding # symbol. You can activate a directive by removing its # sign. Many of the entries are preceded by comments explaining their purpose. Several of the commonly used server level directives are listed in Table 22-4. The following is an example of the ServerAdmin directive used to set the address where users can send mail for administrative issues. You replace the [e-mail] entry with the address you want to use to receive system administration mail. By default, this is set to root@localhost.

# ServerAdmin: Your address, where problems should be e-mailed. ServerAdmin [e-mail] 

Table 22-4: Server Directives

Directive	Description
AddModule module module ...	Apache 1.3: Enables use of modules compiled, but not in use (dropped in Apache 2.0). Context: server config
Alias url-path directory-filename	Enables access to documents stored in the local file system, other than under the document root.
BindAddress saddr	Binds the server to a specified IP address. For more control over the address and ports listened to, use the Listen directive. (Replaced in Apache 2.0 with the Listen directive.)
DefaultLanguage MIME-lang	Specifies MIME-lang as the default file language. Context: server config, virtual host, directory, .htaccess
DefaultType MIME-type	Default type for documents whose type cannot be determined by their MIME types mappings.
DocumentRoot directory-filename	The directory from which httpd serves files. Default: DocumentRoot /usr/local/apache/htdocs (/var/www/html on Red Hat systems)
Group unix-group	Sets the group for the server. The standalone server must be run initially as root. The recommendation is you set up a new group specifically for running the server.
HostNameLookups on | off | double	Enables DNS lookups so hostnames can be logged. Double refers to double-reverse DNS.
<IfDefine [!]parameter-name> ... </IfDefine>	The <IfDefine test>...</IfDefine> section specifies conditional directives. Directives within an IfDefine section are processed if the test is true and are ignored otherwise. The test consists of a parameter name, which is true if the parameter is defined, and false if undefined. An ! placed before the parameter makes the test true if the parameter is undefined (not).
<IfModule [!]module-name> ... </IfModule>	The <IfModule test>...</IfModule> section specifies conditional directives. The test checks to see if a module is compiled in Apache. It is true if present, and false if not. An !module-name is true if the module is not present.
Include filename	Inclusion of other configuration files.
KeepAlive on/off	Enables persistent connections, "Off" to disable.
KeepAliveTimeout seconds	The number of seconds Apache waits for another request before closing the connection.
Listen [IP address:]port number	Listens to more than one IP address or port. By default, it responds to requests on all IP interfaces, but only on the port given by the Port directive. Context: server config
ListenBacklog backlog	The maximum length of the queue of pending connections.
LoadFile filename filename ...	Links in the named object files or libraries when the server is started or restarted. Used to load additional code required for some module to work.
LoadModule module filename	Links in the object file or library filename and adds the module structure named module to the list of active modules.
LockFile filename	Path to the lockfile used when Apache is compiled.
MaxClients number	Limits the number of simultaneous requests that can be supported. Any connection attempts over the MaxClients limit are normally queued, up to a number based on the ListenBacklog directive.
MaxKeepAliveRequests number	Limits the number of requests allowed per connection when KeepAlive is on.
Port number	If no Listen or BindAddress directives exist, a port directive sets the network port on which the server listens. Ports for a virtual host are set by the VirtualHost directive.
ServerAdmin e-mail-address	The e-mail address for the server administrator.
ServerAlias host1 host2 ...	Sets the alternate names for a host, for use with name-based virtual hosts.
ServerName fully qualified domain name	Sets the hostname of the server. This is used only when creating redirection URLs. If it is not specified, the server attempts to deduce it from its own IP address.
ServerPath pathname	Sets the legacy URL pathname for a host, for use with name-based virtual hosts.
ServerRoot directory-filename	Sets the directory in which the server resides.
ServerSignature Off | On | EMail	Configures a trailing footer line under server-generated documents, such as error messages.
SetHandler handler-name	Forces all matching files to be parsed through the handler given by handler-name.
User unix-userid	Specifies the user ID for the server. The standalone server must be run as root initially. You can use a username or a user ID number. The user should have no access to system files. The recommendation is for you to set up a new user and group specifically for running the server.
UserDir directory/filename	Sets the real directory in a user's home directory to use when a request for a document for a user is received.
Redirect [ status ] url-path url	Maps an old URL into a new one.
ScoreBoardFile filename	Specifies the ScoreBoardFile file.
TimeOut number	Sets the timeout in seconds for receiving GET requests, receipt of POST and PUT requests, and TCP packet transmissions acknowledgments.

Some directives require specific information about your system. For example, ServerName holds the hostname for your Web server. Specifying a hostname is important to avoid unnecessary DNS lookup failures that can hang your server. Notice the entry is commented with a preceding #. Simply remove the # and type your Web server's hostname in place of new.host.name.

# ServerName allows you to set a hostname which is sent # back to clients for your server if it's different than the # one the program would get (i.e. use # "www" instead of the host's real name).     #ServerName new.host.name

On Red Hat systems, entries have already been made for the standard Web server installation using /var/www as your Web site directory. You can tailor your Web site to your own needs by changing the appropriate directives. The DocumentRoot directive determines the home directory for your Web pages. The ServerRoot directive specifies where your Web server configuration, error, and log files are kept.

DocumentRoot /var/www/html ServerRoot /etc/httpd

The MaxClients directive sets the maximum number of clients that can connect to your server at the same time.

MaxClients 150

Note 

You can also configure Apache to operate as just a proxy and/or cache server. Default proxy and cache server directives are already included in the httpd.conf file. The ProxyRequests directive turns proxy activity on. Caching can be configured with directives like CacheRoot to specify the cache directory, CachSize for the cache size (500KB default), and CacheMaxExpire to set a time limit on unmodified documents.

Directory-Level Configuration: .htaccess and <Directory>

One of the most flexible aspects of Apache is its ability to configure individual directories. With the Directory directive, you can define a block of directives that apply only to a particular directory. Directory directives are listed in Table 22-5. Such a directive can be placed in the httpd.conf or access.conf configuration file. You can also use an .htaccess file within a particular directory to hold configuration directives. Those directives are then applied only to that directory. The name ".htaccess" is actually set with the AccessFileName directive. You can change this if you want.

AccessFileName .htaccess 

Table 22-5: Directory Directives

Directive	Description
AccessFileName filename filename ...	Default directory configuration filenames located within directories.
<Directory directory> ... </Directory>	<Directory> and </Directory> directives operate as tags that enclose a group of directives applying only to the named directory and subdirectories of that directory.
<DirectoryMatch regex> ... </DirectoryMatch>	<DirectoryMatch> and </DirectoryMatch> enclose a group of directives that apply only to the named directory. It operates the same as <Directory>, but takes a regular expression as an argument.
DirectoryIndex local-url local-url ...	Specifies the list of resources to look for when the client requests an index of the directory by specifying a / at the end of a directory name (usually index.html).
Options [+|-]option [+|-]option ...	Controls the server features available in a particular directory. OPTIONS None If set to None, none of the extra features are enabled. All All options except for MultiViews. This is the default setting. ExecCGI Execution of CGI scripts is permitted. FollowSymLinks The server follows symbolic links in this directory. Includes Server-side includes are permitted. IncludesNOEXEC Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled. Indexes Returns a formatted listing of the directory for directories with no DirectoryIndex. MultiViews Content negotiated MultiViews are allowed. SymLinksIfOwnerMatch The server follows only symbolic links for which the target file or directory is owned by the same user ID as the link.
AllowOverride override override ...	Directives that can be overridden by entries in an .htaccess file. All allows overrides, and none denies them. Default: AllowOverride All Context: directory

A Directory block begins with a <Directory pathname> directive, where pathname is the directory to be configured. The ending directive uses the same <> symbols, but with a slash preceding the word "Directory": </Directory>. Directives placed within this block apply only to the specified directory. The following example denies access to only the mypics directory by requests from www.myvids.com.

<Directory /var/www/html/mypics> Order Deny,Allow Deny from www.myvids.com </Directory>

With the Options directive, you can enable certain features in a directory, such as the use of symbolic links, automatic indexing, execution of CGI scripts, and content negotiation. The default is the All option, which turns on all features except content negotiation (Multiviews). The following example enables automatic indexing (Indexes), symbolic links (FollowSymLinks), and content negotiation (Multiviews).

Options Indexes FollowSymLinks Multiviews 

Configurations made by directives in main configuration files or in upper-level directories are inherited by lower-level directories. Directives for a particular directory held in .htaccess files and Directory blocks can be allowed to override those configurations. This capability can be controlled by the AllowOverride directive. With the all argument, .htaccess files can override any previous configurations. The none argument disallows overrides, effectively disabling the .htaccess file. You can further control the override of specific groups of directives. AuthConfig enables use of authorization directives, FileInfo is for type directives, Indexes is for indexing directives, Limit is for access control directives, and Options is for the options directive.

AllowOverride all

Access Control

With access control directives, such as allow and deny, you can control access to your Web site by remote users and hosts. Access control directives are listed in Table 22-6. The allow directive followed by a list of hostnames restricts access to only those hosts. The deny directive with a list of hostnames denies access by those systems. The argument all applies the directive to all hosts. The order directive specifies in what order the access control directives are to be applied. Other access control directives, such as require, can establish authentication controls, requiring users to log in. The access control directives can be used globally to control access to the entire site or placed within Directory directives to control access to individual directives. In the following example, all users are allowed access:

order allow,deny allow from all 

Table 22-6: Access Control Directives (continued)

Directive	Description
deny from host host ...	Determines hosts that can access a given directory: all, or partial or full domain name or IP address.
allow from host host ...	Determines which hosts can access a given directory: all, partial, or full domain name, or IP address.
<Files filename> ... </Files>	Provides for access control by filename. Similar to the <Directory> directive and <Location> directive. <Files> sections are processed in the order they appear in the configuration file, after the <Directory> sections and .htaccess files are read, but before <Location> sections. <Files> can be nested inside <Directory> sections to restrict the portion of the file system to which they apply.
<FilesMatch regex> ... </FilesMatch>	Provides for access control by filename like the <Files> directive, but uses a regular expression.
<Limit method method ... > ... </Limit>	<Limit> and </Limit> specify a group of access control directives that apply only to the specified access methods, any valid HTTP method. Access control directives appearing outside a <Limit> directive apply to all access methods. Method names are GET, POST, PUT, DELETE, CONNECT, and OPTIONS.
<LimitExcept method method ... > ... </LimitExcept>	<LimitExcept> and </LimitExcept> specify a group of access control directives, which then apply to any HTTP access method not listed in the arguments.
<Location URL> ... </Location>	The <Location> directive provides for access control by URL. Similar to the <Directory> directive.
<LocationMatch regex> ... </LocationMatch>	Provides access control by URL, in an identical manner to <Location>, using a regular expression as an argument.
order ordering	Controls the order in which allow and deny directives are evaluated.
Satisfy directive	Access policy if both allow and require are used. The parameter can be either all or any.
LimitRequestBody number	Limits the size of an HTTP request message body.

You can further qualify access control directives by limiting them to certain HTML access methods. HTML access methods are ways a browser interacts with your Web site. For example, a browser could get information from a page (GET) or send information through it (POST). You can control such access methods using the <Limit> directive. Limit takes as its argument a list of access methods to be controlled. The directive then pairs with a </Limit> directive to define a Limit block within which you can place access control directives. These directives apply only to the specified access methods. You can place such Limit blocks with a Directory block to set up controls of access methods for a specific directory. The following Directory block in the /etc/config/httpd.conf file controls access methods for your Web site's home directory, /var/www/html.

# This should be changed to whatever you set DocumentRoot to. <Directory /var/www/html>    Options Indexes FollowSymLinks    AllowOverride All    <Limit GET>      order allow,deny      allow from all    </Limit> </Directory> 

Controls are inherited from upper-level directories to lower-level ones. If you want to control access strictly on a per-directory basis to your entire Web site, you can use the following entry to deny access to all users. Then, in individual directories, you can allow access to certain users, groups, or hosts.

<Directory /var/www/html>  Order Deny,Allow  Deny from All </Directory>

URL Pathnames

Certain directives can modify or complete pathname segments of a URL used to access your site. The pathname segment of the URL specifies a particular directory or Web page on your site. Directives enable you to alias or redirect pathnames, as well as to select a default Web page. With the Alias directive, you can let users access resources located in other parts of your system, on other file systems, or on other Web sites. An alias can use a URL for sites on the Internet, instead of a pathname for a directory on your system. With the Redirect directive, you can redirect a user to another site.

Alias /mytrain /home/dylan/trainproj Redirect /mycars http://www.myautos.com/mycars

If Apache is given only a directory to access, rather than a specific Web page, it looks for an index Web page located in that directory and displays it. The possible names for a default Web page are listed by the DirectoryIndex directive. The name usually used is index.html, but you can add others. The standard names are shown here. When Apache is given only a Web directory to access, it looks for and displays the index.html Web page located in it.

DirectoryIndex index.html index.shtml index.cgi

Apache also lets a user maintain Web pages located in a special subdirectory in the user's home directory, rather than in the main Web site directory. Using a ~ followed by the username accesses this directory. The name of this directory is specified with the UserDir directive. The default name is public_html, as shown here. The site turtle.mytrek.com/~dylan accesses the directory turtle.mytrek.com/home/dylan/public_html on the host turtle.mytrek.com.

UserDir public_html

MIME Types

When a browser accesses Web pages on a Web site, it is often accessing many different kinds of objects, including HTML files, picture or sound files, and script files. To display these objects correctly, the browser must have some indication of what kind of objects they are. A JPEG picture file is handled differently from a simple text file. The server provides this type information in the form of MIME types (see Chapter 13). MIME types are the same types used for sending attached files through Internet mailers, such as Pine. Each kind of object is associated with a given MIME type. Provided with the MIME type, the browser can correctly handle and display the object.

The MIME protocol associates a certain type with files of a given extension. For example, files with a .jpg extension would have the MIME type image/jpeg. The TypesConfig directive holds the location of the mime.types file, which lists all the MIME types and their associated file extensions. DefaultType is the default MIME type for any file whose type cannot be determined. AddType enables you to modify the mime.type types list without editing the MIME file.

TypesConfig /etc/mime.types DefaultType text/plain

Other type directives are used to specify actions to be taken on certain documents. AddEncoding lets browsers decompress compressed files on the fly. AddHandler maps file extensions to actions, and AddLanguage enables you to specify the language for a document. The following example marks filenames with the .gz extension as gzip-encoded files and files with the .fr extension as French language files:

AddEncoding x-gzip gz AddLanguage fr .fr

A Web server can display and execute many different types of files and programs. Not all Web browsers are able to display all those files, though. Older browsers are the most limited. Some browsers, such as Lynx, are not designed to display even simple graphics. To allow a Web browser to display a page, the server negotiates with it to determine the type of files it can handle. To enable such negotiation, you need to enable the Multiviews option.

Option multiviews

CGI Files

Common Gateway Interface (CGI) files are programs that can be executed by Web browsers accessing your site. CGI files are usually initiated by Web pages that execute the program as part of the content they display. Traditionally, CGI programs were placed in a directory called cgi-bin and could only be executed if they resided in such a special directory. Usually, only one cgi-bin directory exists per Web site. Distributions will normally set up a cgi-bin directory in the default Web server directory (/var/www/cgi-bin on Red Hat). Here, you place any CGI programs that can be executed on your Web site. The ScriptAlias directive specifies an alias for your cgi-bin directory. Any Web pages or browsers can use the alias to reference this directory.

ScriptAlias /cgi-bin/ /var/www/cgi-bin/

If you want to execute CGI programs that reside anywhere on your Web site, you can specify that files with a .cgi extension are treated as executable CGI programs. You do this with the AddHandler directive (see Table 22-7). This directive applies certain handlers to files of a given type. The handler directive to do this is included in the default httpd.conf file, provided with the Apache source code files, though commented out. You can remove the comment symbol (#) to enable it.

AddHandler cgi-script cgi

Table 22-7: CGI Directives

Directive	Description
Action action-type cgi-script	Adds an action, which activates cgi-script when action-type is triggered by the request.
AddHandler handler-name extension extension ...	Maps the filename extensions extension to the handler handler-name.
RemoveHandler extension extension ...	Removes handler associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server configuration files.
Script method cgi-script	Adds an action, which activates cgi-script when a file is requested using the method of method, which can be one of GET, POST, PUT, or DELETE.
ScriptAlias url-path directory-filename	Marks the target directory as containing CGI scripts.
ScriptInterpreterSource 'registry' or 'script'	Finds the interpreter used to run CGI scripts. The default method is to use the interpreter pointed to by the #! line in the script.

Automatic Directory Indexing

When given a URL for a directory instead of an HTML file, and when no default Web page is in the directory, Apache creates a page on the fly and displays it. This is usually only a listing of the different files in the directory. In effect, Apache indexes the items in the directory for you. You can set several options for generating and displaying such an index. Indexing directives are listed in Table 22-8. If FancyIndexing is turned on, Web page items are displayed with icons and column headers that can be used to sort the listing.

FancyIndexing on

Icon directives tell Apache what icon to display for a certain type of file. The AddIconByType and AddIconByEncoding directives use MIME-type information to determine the file's type and then associate the specified image with it. AddIcon uses the file's extension to determine its type.

With the IndexOptions directive, you can set different options for displaying a generated index. Options exist for setting the heights and widths of icons and filenames. The IconsAreLinks option makes icons part of filename anchors. The ScanHTMLTitles option reads the titles in HTML documents and uses those to display entries in the index listing instead of filenames. Various options exist for suppressing different index display features such as sorting, descriptions, and header/readme inserts.

Table 22-8: Indexing Directives

Directive	Description
AddDescription string file file ...	Sets the description to display for a file. Can be a file extension, partial filename, wildcard expression, or full filename. String is enclosed in double quotes (").
IndexOptions [+|-]option [+|-]option ...	Set options for directory indexing: FancyIndexing, IconHeight, IconsAreLinks, IconWidth, NameWidth, ScanHTMLTitles, SuppressDescription.
ReadmeName filename	Specifies the name of the file to be appended to the end of the index listing.
AddIcon icon name name ...	Specifies the icon to display next to a file ending in name.
AddIconByEncoding icon MIME-encoding MIME-encoding ...	Specifies the icon to display next to files with MIME-encoding (FancyIndexing).
AddLanguage MIME-lang extension extension ...	Maps the given filename extensions to the specified content language.
FancyIndexing Boolean	Sets the FancyIndexing option for a directory. Boolean can be on or off.
DefaultIcon url	Specifies the icon to display for files when no specific icon is known (FancyIndexing).
HeaderName filename	Specifies the name of the file to be inserted at the top of the index listing (FancyIndexing).

Authentication

Your Web server can also control access on a per-user or per-group basis to particular directories on your Web site. You can require various levels for authentication. Access can be limited to particular users and require passwords, or expanded to allow members of a group access. You can dispense with passwords altogether or set up an anonymous type of access, as used with FTP. Authentication directives are shown in Table 22-9.

Table 22-9: Authentication Directives

Directive	Description
allow from host host ...	Determines which hosts can access a given directory: all, partial, or full domain name, or IP address.
AllowOverride override override ...	Directives that can be overridden by entries in an .htaccess file. All allows overrides, and none denies them.
Anonymous user user ...	Users who are allowed access without password verification. User is usually anonymous (case-sensitive).
Anonymous_Authoritative on | off	When on, there is no fall-through to other authorization methods.
AuthDBMUserFile filename	DBM file containing the list of users and passwords for user authentication.
AuthName auth-domain	The authorization realm for a directory. A realm is given to the client so the user knows which username and password to send.
AuthType type	Type of user authentication for a directory. Only Basic and Digest are currently implemented.
require entity-name entity entity ...	Selects the authenticated users that can access a directory. entity-name is either the user or group, followed by a list of users or groups. require user userid userid ... require group group-name group-name ...
AuthUserFile filename	Sets the name of the file with the list of users and passwords for user authentication.

To apply authentication directives to a certain directory, you place those directives within either a Directory block or the directory's .htaccess file. You use the require directive to determine what users can access the directory. You can list particular users or groups. The AuthName directive provides the authentication realm to the user, the name used to identify the particular set of resources accessed by this authentication process. The AuthType directive specifies the type of authentication, such as basic or digest. A require directive requires also AuthType, AuthName, and directives specifying the locations of group and user authentication files. In the following example, only the users george, robert, and mark are allowed access to the newpics directory:

<Directory /var/www/html/newpics      AuthType Basic      AuthName Newpics      AuthUserFile /web/users      AuthGroupFile /web/groups      <Limit GET POST>         require users george robert mark      </Limit> </Directory>

The next example allows group access by administrators to the CGI directory:

<Directory /var/www/html/cgi-bin      AuthType Basic      AuthName CGI      AuthGroupFile /web/groups    <Limit GET POST>         require groups admin    </Limit> </Directory>

To set up anonymous access for a directory, place the Anonymous directive with the user anonymous as its argument in the directory's Directory block or .htaccess file. You can also use the Anonymous directive to provide access to particular users without requiring passwords from them.

Apache maintains its own user and group authentication files specifying what users and groups are allowed to which directories. These files are normally simple flat files, such as your system's password and group files. They can become large, however, possibly slowing down authentication lookups. As an alternative, many sites have used database management files in place of these flat files. Database methods are then used to access the files, providing a faster response time. Apache has directives for specifying the authentication files, depending on the type of file you are using. The AuthUserfile and AuthGroupFile directives are used to specify the location of authentication files that have a standard flat file format. The AuthDBUserFile and AuthDBGroupFile directives are used for DB database files, and the AuthDBMGUserFIle and AuthDBMGGroupFile are used for DBMG database files.

The programs htdigest, htpasswd, and dbmmanage are tools provided with the Apache software package for creating and maintaining user authentication files, which are user password files listing users who have access to specific directories or resources on your Web site. htdigest and htpasswd manage a simple flat file of user authentication records, whereas dbmmanage uses a more complex database management format. If your user list is extensive, you may want to use a database file for fast lookups. htdigest takes as its arguments the authentication file, the realm, and the username, creating or updating the user entry. htpasswd can also employ encryption on the password. dbmmanage has an extensive set of options to add, delete, and update user entries. A variety of different database formats are used to set up such files. Three common ones are Berkeley DB2, NDBM, and GNU GBDM. dbmmanage looks for the system libraries for these formats in that order. Be careful to be consistent in using the same format for your authentication files.

Log Files

Apache maintains logs of all requests by users to your Web site. By default, these logs include records using the Common Log Format (CLF). The record for each request takes up a line composed of several fields: host, identity check, authenticated user (for logins), the date, the request line submitted by the client, the status sent to the client, and the size of the object sent in bytes. Log file directives are listed in Table 22-10.

Webalizer

Reports on Web logs can be generated using the Webalizer tool. Webalizer will display information on your Web site usage. When you run the webalizer command, usage reports will be placed in the /var/www/html/usage directory. Access the index page to display a page with links to monthly reports, file:/var/www/html/usage/index.html. Report configuration is specified in the /etc/webalizer.conf file. Previous summaries are kept in the /etc/webalizer.history file.

Customizing Logs

Using the LogFormat and CustomLog directives, you can customize your log record to add more fields with varying levels of detail. These directives use a format string consisting of field specifiers to determine the fields to record in a log record. You add whatever fields you want and in any order. A field specifier consists of a percent (%) symbol followed by an identifying character. For example, %h is the field specifier for a remote host, %b for the size in bytes, and %s for the status. See the documentation for the mod_log_config module for a complete listing. Table 22-11 lists several of the commonly used ones. You should quote fields whose contents may take up more than one word. The quotes themselves must be quoted with a backslash to be included in the format string. The following example is the Common Log Format implemented as a FormatLog directive:

FormatLog "%h %l %u %t \"%r\" %s %b"

Certain field specifiers in the log format can be qualified to record specific information. The %i specifier records header lines in requests the server receives. The reference for the specific header line to record is placed within braces between the % and the field specifier. For example, User-agent is the header line that indicates the browser software used in the request. To record User-agent header information, use the conversion specifier %{User-agent}i.

To maintain compatibility with NCSA servers, Apache originally implemented AgentLog and RefererLog directives to record User-agent and Referer headers. These have since been replaced by qualified %i field specifiers used for the LogFormat and CustomLog directives. A Referer header records link information from clients, detecting who may have links to your site. The following is an NCSA-compliant log format:

"%h %l %u %t \"%r\" %s %b\"%{Referer}i\" \"%{User-agent}i\"". 

Table 22-10: Logging Directives

Directive	Description
CustomLog file-pipe format-or-nickname	Creates a new log file with the specified format.
ErrorDocument error-code document	Redirects to a local or external URL to handle the problem/error.
ErrorLog filename|syslog[:facility]	The file on which the server logs errors.
LogFormat format [nickname]	Sets the format of the default log file named by the TransferLog directive. Default: LogFormat "%h %l %u %t \"%r\" %s %b"
TransferLog file-pipe	Adds a log file in the format defined by the most recent LogFormat directive or Common Log Format if default is specified.
LogLevel level	Adjusts the verbosity of the messages recorded in the error logs.

Table 22-11: Apache Log Field Specifiers

Field Specifier	Description
%a	Remote IP address
%A	Local IP address
%b	Bytes sent, excluding HTTP headers
%{variable}e:	The contents of the environment variable
%f	Filename
%h	Remote host
%l	Remote logname (from identd, if supplied)
%m	The request method
%P	The process ID of the child that serviced the request
%r	First line of request
%s	Status
%t	Time, in Common Log Format time format (standard English format)
%u	Remote user (from auth; may be bogus if return status (%s) is 401)
%U	The URL path requested
%v	The canonical ServerName of the server serving the request

Generating and Managing Log Files

Instead of maintaining one large log file, you can create several log files using the CustomLog or TransferLog directive. This is helpful for virtual hosts where you may want to maintain a separate log file for each host. You use the FormatLog directive to define a default format for log records. The TransferLog then uses this default as its format when creating a new log file. CustomLog combines both operations, enabling you to create a new file and to define a format for it.

FormatLog "%h %l %u %t \"%r\" %s %b" # Create a new log file called myprojlog using the FormatLog format TransferLog myprojlog # Create a new log file called mypicslog using its own format CustomLog mypicslog "%h %l %u %t \"%r\" %s %b"

Apache provides two utilities for processing and managing log files. logresolve resolves IP addresses in your log file to hostnames. rotatelogs rotates log files without having to kill the server. You can specify the rotation time.

Note 

The Apache Web server can also provide detailed reports on server activity and configuration, letting you display this information to remote servers. The Location directive server-info will display the configuration details of your Web server, and the server-status directive will show Web processes. The pages server-info and server-status will display the reports, as in http://localhost/server-info. Use the ExtendedStatus directive to enable detailed reports.

---