Chapter 10: Apache Modules

• The mod_access Module
  • mod_access Directives
    • allow from
    • deny from
    • order
• [ic:Apache 1.1]The mod_actions Module
  • mod_actions Directives
    • Action
    • Script
• The mod_alias Module
  • mod_alias Directives
    • Alias
    • Redirect
    • ScriptAlias
• The mod_asis Module
• The mod_auth Module
  • mod_auth Directives
    • AuthGroupFile
    • AuthUserFile
• The mod_auth_anon Module
  • mod_auth_anon Directives
    • Anonymous
    • Anonymous_MustGiveEmail
    • Anonymous_LogEmail
    • Anonymous_VerifyEmail
    • Anonymous_NoUserID
    • Anonymous_Authorative
  • mod_auth_anon Configuration Example
• The mod_auth_db Module
  • mod_auth_db Directives
    • AuthDBGroupFile
    • AuthDBUserFile
• The mod_auth_dbm Module
  • mod_auth_dbm Directives
    • AuthDBMGroupFile
    • AuthDBMUserFile
• The mod_auth_msql Module
  • mod_auth_msql Directives
    • Auth_MSQLhost
    • Auth_MSQLdatabase
    • Auth_MSQLpwd_table
    • Auth_MSQLgrp_table
    • Auth_MSQLuid_field
    • Auth_MSQLpwd_field
    • Auth_MSQLgrp_field
    • Auth_MSQL_nopasswd
    • Auth_MSQL_Authorative
    • Auth_MSQL_EncryptedPasswords
  • The mSQL password database
• The mod_cern_meta Module
  • mod_cern_meta Directives
    • MetaDir
    • MetaSuffix
  • MetaSuffix Example
• The mod_cgi Module
• The mod_cookies Module
  • The mod_cookies Directive
    • The CookieLog Directive
• The mod_digest Module
  • The mod_digest Directive
    • AuthDigestFile
  • htdigest
  • Configuring the Server to Use Digest Authentication
• The mod_dir Module
  • mod_dir Directives
    • AddDescription
    • AddIcon
    • AddIconByEncoding
    • AddIconByType
    • DefaultIcon
    • DirectoryIndex
    • FancyIndexing
    • HeaderName
    • IndexIgnore
    • IndexOptions
    • ReadmeName
• The mod_env Module
  • mod_env Directives
    • PassEnv
    • SetEnv
• The mod_dld Module
  • mod_dld Directives
    • LoadFile
    • LoadModule
• The mod_imap Module
  • mod_imap Directives
  • ImapMenu
  • ImapDefault
  • ImapBase
  • Using Server-Side Image Maps
    • A Map File Example
    • Referencing the Map File
• The mod_include Module
  • SPML Command Format
  • SMPL Commands
  • The mod_include Directive
    • XBitHack
• The mod_info Module
• The mod_log_agent Module
  • The mod_log_agent Directive
    • AgentLog
• The mod_log_common Module
  • Logfile Format Description
  • mod_log_common Directives
    • TransferLog
• The mod_log_config Module
  • mod_log_config Directives
    • LogFormat
    • TransferLog
• The mod_log_referer Module
  • Logfile Format Description
  • mod_log_referer Directives
    • RefererIgnore
    • RefererLog
• The mod_mime Module
  • mod_mime Directives
    • AddEncoding
    • AddLanguage
    • AddType
    • TypesConfig
    • AddHandler
    • ForceType
    • SetHandler
• The mod_negotiation Module
  • Type Maps
  • MultiViews
  • mod_negotiation Directives
    • CacheNegotiatedDocs
    • LanguagePriority
• The mod_proxy Module
  • mod_proxy Directives
    • ProxyRequests
    • ProxyRemote
    • ProxyPass
    • CacheRoot
    • CacheSize
    • CacheGcInterval
    • CacheMaxExpire
    • CacheLastModifiedFactor
    • CacheDefaultExpire
    • NoCache
• The mod_status Module
• The mod_userdir Module
  • mod_userdir Directives
    • UserDir
• Summary

10

Apache Modules

Apache's modular structure has simplified the way that functionality is added to the server. Its generalized Application Programmer's Interface (API) greatly simplifies the process of adding new or enhancing existing functionality. Modules are usually developed in a single source code file named after the module. Many of these modules are so useful that they are included on a default server configuration. Modules that are included in this fashion are part of the Base release. er modules are not included in the Base release either because they are in the initial stages of development or have not received a methodical testing to insure that they are of production quality. The lack of inclusion should not be a deterrent to their use, however. The DBM Authentication module is not part of the Base release, yet it is heavily used in many sites.

The following sections describe all the modules shipped with Apache and the directives they provide. For a list of modules provided by third parties take a look at Chapter 7, "Third-Party Modules."

The mod_access Module

The mod_access module is built into Apache by default. It provides host-based (or domain-level) access control security options.

Host-based access control grants or denies access on the basis of the Internet Protocol (IP) address of the machine generating a request. Machines matching an allow or deny description are allowed or denied access as appropriate. Flexible descriptions can be formed by the combination of both lists and the use of the order directive.

mod_access Directives

The mod_access module provides three directives for building the allow and deny criteria:

• allow from
  
  
• deny from
  
  
• order
  
  

These directives are typically specified in the <Directory>, <Limit>, or <Location> sections or inside an .htaccess file. <Location> sections are available only in Apache 1.1 or better.

allow from

allow from specifies hosts that are allowed to access the protected resource. You can specify more than one host or network by separating the additional host specifications with a space. host can be specified in any of the following formats:

all	This option allows all hosts to access the resource.
FQDN	You can specify a host using its fully qualified domain name. A fully qualified domain name must include a hostname, subnets (if any), and a domain name, such as www.xyc.com.
PDN	You can specify a group of hosts by using a partial domain name, which allows you to group several hosts in a particular domain. An entry such as xyc.com would match any host in the xyc.com domain.
	A more selective grouping could be specified by using a network subnet. If available, group.xyc.com would match any host in the group subnet in the xyc.com domain.
IP	You can also specify machines by their IP address. This option may provide tighter security than name-based specifications; however, names are easier for humans to maintain.
PIP	You can also specify partial IP patterns, 1–3 bytes of the IP address, to define groups of hosts. Hosts matching the IP description are included in the group. If 204.95.160.0 is a class C address, specifying 204.95.160 as the PIP would match any host from that network. If the network is subdivided into subnets, you can specify the subnet number to create a more restrictive grouping within a network.

Here's an example of the allow from directive:

allow from .cs.uwm.edu bar.com 204

All hosts from the specified domain are allowed access. Note that the comparison is based on the entire name. The entry for bar.com would not match foobar.com.

deny from

deny from specifies hosts that are to be denied access to the resource. You can specify more than one host or network by separating additional host specifications with a space. host can be specified in any of the following formats:

all	This option allows all hosts to access the resource.
FQDN	You can specify a host using its fully qualified domain name. A fully qualified domain name must include a hostname, subnets if any, and a domain name, such as www.xyc.com.
PDN	You can specify a group of hosts by using a partial domain name. This allows you to group several hosts in a particular domain. An entry like xyc.com would match any host in the xyc.com domain.
	A more selective grouping could be specified by using a network subnet, if available. group.xyc.com would match any host in the group subnet in the xyc.com domain.
IP	You can also specify machines by their IP address. This option may provide tighter security than name-based specifications; however, names are easier for we humans to maintain.
PIP	You can also specify partial IP patterns, 1–3 bytes of the IP address, to define groups of hosts. Hosts matching the IP description are included in the group. If 204.95.160.0 is a class C address, specifying 204.95.160 as the PIP would match any host from that network. If the network is subdivided into subnets, you can specify the subnet number to create a more restrictive grouping within a network.

Here's an example of the deny directive:

deny from .cs.uwm.edu bar.com 204

All hosts from the specified domain are denied access. Note that comparison is based on the entire name. The entry for bar.com would not match foobar.com.

order

The order directive specifies the order in which the allow from and deny from directives are evaluated within a <Limit>, <Location>, or <Directory> section. Possible options are

deny,allow	Evaluates the deny from directive first and then grants exceptions based on the allow from directive.
allow,deny	Evaluates the allow from directive first and then grants exceptions based on the deny from directive.
mutual-failure	Evaluates so that only hosts that appear in the allow from directive and do not appear on the deny from directive are granted access.

Here's an example of the order directive:

order deny,allow deny from all allow from aol.com

In this example, requests from America Online users would be allowed. All other hosts are denied access.

[ic:Apache 1.1]The mod_actions Module

The mod_actions module is compiled into Apache by default. It adds the functionality of setting user-defined handlers that execute CGI programs based on the MIME type of a request or the HTTP access method used for the request.

mod_actions Directives

mod_actions adds two directives:

• Action
  
  
• Script
  
  

Action

The Action directive adds a handler that runs cgi when mime-type is requested. The Action directive sets the URL and filepath of the request using the standard CGI environment variables PATH_INFO and PATH_TRANSLATED, respectively. The CGI program can then perform whatever action it needs to handle the request.

Script

The Script directive adds a handler that runs cgi when a file is requested using the http-method. Supported HTTP methods are GET, POST, PUT, or DELETE. The Action directive sets the URL and filepath of the request using the standard CGI environment variables PATH_INFO and PATH_TRANSLATED, respectively. The CGI program can then perform whatever action it needs to handle the request.

Script handlers only define default actions. If some resource is capable of handling the request internally, that resource will be called. GET requests are only passed to handler when they have query arguments—that is, the query string contains a question mark (?). This directive provides you with a way of implementing the PUT or DELETE methods in Apache.

The mod_alias Module

This module is compiled into Apache by default. It provides directives that allowF you to map document and CGI program directories that are in the local filesystem, but outside of DocumentRoot, into the server's document tree. This allows clients to reference these resources as if they were inside your DocumentRoot. alias module also provides facilities for uniform resource locator (URL) redirection, which allows you to redirect the request to a different URL, perhaps in a different network.

mod_alias Directives

The directives provided are

• Alias
  
  
• Redirect
  
  
• ScriptAlias
  
  

Typically, these directives are specified in the conf/srm.conf configuration file.

Alias

The Alias directive allows you to reference directories in your local filesystem that are outside of your DocumentRoot as if they were located inside it. The Alias directive maps the request to url-path into the directory tree specified by directory-filename:

Alias /icons/ /usr/local/etc/httpd/icons/

A request for http://www.mydomain.com/icons/text.gif will be mapped by the server to the file /usr/local/etc/httpd/icons/text.gif.

Redirect

The Redirect directive allows you to map one URL into another. It can redirect a local request to a different Web server or an external URL. When the server receives a request for url, it returns differenturl to the client along with a REDIRECT HTTP response code. Better clients automatically re-requests the materials from the new URL:

Redirect /projectA http://www.domain.dom/projectA

---

Use Redirect if you change the name of an often-accessed file. That way the error logs won't fill up with requests for the file from users who have bookmarked the URL, and visitors will have less trouble finding the new location.

---

Apache 1.1 allows you to use the Redirect directive from an .htaccess file if the FileInfo option is enabled by the AllowOverride directive.

---

Redirect directives take precedence over Alias and ScriptAlias directives.

---

ScriptAlias

The ScriptAlias directive is similar to the Alias directive. The ScriptAlias directive allows you to reference a CGI directory that is stored outside of your DocumentRoot, but in your local filesystem, as if it were inside your DocumentRoot. The difference is that the server marks the directory as containing CGI programs and permits their execution:

ScriptAlias /cgi-bin/ /usr/local/etc/httpd/cgi-bin/

In this example, a request for http://www.mydomain.com/cgi-bin/foo.cgi will make the server run the program /usr/local/etc/httpd/cgi-bin/foo.cgi.

The mod_asis Module

The mod_asis module is built into Apache by default. This module allows you to specify type as a filetype that is to be sent without HTTP headers except for date and server headers. This module is internally used to send server redirects and other responses without the need for a CGI or a no parse header (nph) program.

Because the server does not return headers, you'll need to add them yourself. You'll need to return a status header (a three-digit HTTP response code) followed by a message. Apache can return any of the following HTTP response codes:

200: OK

302: Found

304: Not Modified

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

500: Server Error

503: Out Of Resources (Service Unavailable)

501: Not Implemented

502: Bad Gateway

Here's an example of how to enable mod_asis:

Syntax: AddType httpd/send-as-is type

The following example defines the filetype .asis as a send-as-is filetype:

AddType httpd/send-as-is asis

Here's an example that implements redirection using the send-as-is feature. A redirection makes the client look for the requested resource in a different location:

Status: 302 Site closed, go to a different server.
Location: http://www.mirror.com/index.html
Content-type: text/html
<HTML>
<HEAD>
<TITLE>This portion of our site is currently under remodeling, please visit a mirror site.</TITLE>
</HEAD>
<BODY>
<H1>This portion of our site is currently under remodeling,
you can find a mirror of this site
<A HREF="http://www.mirror.com/index.html">here</A></H1>
</BODY>
</HTML>

The mod_auth Module

The mod_auth module is built into Apache by default. This module provides user authentication by using text files.

User authentication allows you to control access to a document tree on an individual user basis, using user and password lists to provide the necessary authentication verification. When a user requests a restricted resource, the server requires him to log in by specifying a username and a password. If the user supplies the proper information, access is granted to roam across the site without additional login requests. o, you should be aware that this process is repeated for every document you request (your password and user ID (UID) are sent with every page request, thus your password is sent not once, but many times).

mod_auth Directives

mod_auth provides you with the following directives:

• AuthGroupFile
  
  
• AuthUserFile
  
  

These directives allow you to specify the location of your password and group files. Password files that are usable by this module are maintained with the htpasswd program included in the server's support directory. For more information on how to use the htpasswd program, see Chapter 15, "Access Control and User Authentication."

AuthGroupFile

The AuthGroup directive allows you to specify the location of the group file. filename should be specified with an absolute path—a path beginning with a slash (/)—that is outside of your Web server's DocumentRoot. For security reasons, it is important that filename resides outside of the directory it is trying to protect:

AuthGroupFile /usr/local/etc/httpd/passwords/mygroupfile

The group file is an ASCII file with the following format:

groupname: username1 username2 username3...
groupname2: username1, username3
...

groupname is the name of your group followed by a colon (:) and then followed by a list of valid usernames that appear in the user file. Use your favorite editor to maintain this file.

---

Use AuthGroupFile to authenticate a large group of users, such as a workgroup. This way, you can easily manage multiple levels of access with just one directive.

---

AuthUserFile

The AuthUserFile directive allows you to specify the location of the user/password file. filename should be an absolute path outside of DocumentRoot. For security reasons, it is important that filename is outside of the directory it is trying to protect:

AuthUserFile /usr/local/etc/httpd/passwords/.htpasswd

The password file is maintained with the htpasswd program. The file format of the password file is similar to the /etc/passwd file: it contains a username followed by a colon (:) and a crypt() encrypted password. For information on how to maintain password files, please see Chapter 15.

---

Use the DBM authentication module when the number of users is greater than 100. It will speed up things greatly.

---

The mod_auth_anon Module

The mod_auth_anon module allows you to have an FTP-style anonymous login. This will allow visitors that are not registered with your site to still gain access, if they provide the appropriate information, typically their e-mail addresses.

mod_auth_anon Directives

• Anonymous
  
  
• Anonymous_LogEmail
  
  
• Anonymous_VerifyEmail
  
  
• Anonymous_NoUserID
  
  
• Anonymous_Authorative
  
  

Anonymous

This directive allows you to specify various acceptable anonymous names. Typical logins include: Anonymous, guest, or visitor. These logins are not case sensitive. Because there's no default, be sure to include Anonymous in the very least.

Anonymous_MustGiveEmail

The Anonymous_MustGiveEmail directive specifies that the password field must not be left empty. Typically users will be required to enter their e-mail address.

Anonymous_LogEmail

The Anonymous_LogEmail directive specifies that the password field should be logged in the server's access log.

Anonymous_VerifyEmail

The Anonymous_VerifyEmail directive specifies that the password field must contain a valid e-mail address. That is, it will be checked syntactically for resemblance to an e-mail address. It must contain at least one (@ )and a period (.).

Anonymous_NoUserID

The Anonymous_NoUserID directive permits anonymous logins without entering any values in the user or password fields.

Anonymous_Authorative

The Anonymous_Authorative directive returns a denies access if the UID entered doesn't match one of the anonymous logins specified by Anonymous. The ultimate order of the modules, by which login information is processed, depends on the linking order of the various authentication modules. Modules that appear later in the src/Configuration file can override those that come earlier in the file.

mod_auth_anon Configuration Example

This excerpt, from an access.conf, permits anonymous logins so long as a proper e-mail is entered in the password field.

Anonymous anonymous guest
Anonymous_MustGiveEmail on
Anonymous_VerifyEmail on
Anonymous_NoUserId off
AuthName This resource contains restricted materials.For guest entry use 'anonymous' in the login prompt, and enter you email address as the password.
AuthType basic
<Limit get,post>
order deny,allow
allow from all
require valid-user
</Limit>

The mod_auth_db Module

The mod_auth_dbm module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server. This module provides user authentication using Berkeley DB (BSD) files. It is very similar to mod_auth_dbm and should be used as an alternative to mod_auth_dbm on those systems that support DB and not DBM.

mod_auth_db Directives

mod_auth_db provides you with the AuthDBGroupFile and AuthDBUserFile directives that you can use to specify the location of your password and group files. Password and group files are maintained with the dbmmanage program included in your server's support directory. For more information on how to use the dbmmanage program, see Chapter 15.

AuthDBGroupFile

The AuthDBGroupFile directive allows you to specify the location of the user/password/group file. dbfilename should be an absolute path outside of DocumentRoot. For security reasons, it is important that filename is outside of the directory it is trying to protect:

AuthDBGroupFile /usr/local/etc/httpd/passwords/passworddb

DB password files store username, password, and group information. Typically you'll reference dbfilename on both the AuthDBGroupFile and AuthDBUserFile directives. User information in the group file is maintained using the dbmmanage program included in the server's support directory. You'll need a copy of Perl to run dbmmanage. For information on how to use the dbmmanage program, see Chapter 15.

AuthDBUserFile

The AuthDBUserFile directive allows you to specify the location of the user/password/group file. dbfilename should be an absolute path outside of DocumentRoot. For security reasons, it is important that filename is outside of the directory it is trying to protect:

AuthDBUserFile /usr/local/etc/httpd/passwords/passworddb

DBM password files store username, password, and group information. Typically you'll reference dbfilename on both AuthDBGroupFile and AuthDBUserFile directives. User information in the group file is maintained using the dbmmanage program included in the server's support directory. You'll need a copy of Perl to run dbmmanage. For information on how to use the dbmmanage program, see Chapter 15.

The mod_auth_dbm Module

The mod_auth_dbm module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

This module provides user authentication using DBM files. User authentication allows you to control access to a document tree on an individual user basis, using user and password lists to provide the necessary authentication verification. When a user requests a restricted resource, the server requires him to log in by specifying a username and a password. If the user supplies the proper information, access is granted to roam across the site without additional login requests.

DBM files provide a significant performance improvement over the authentication routines provided by mod_auth. If your password file has more than 100 entries, you should use the mod_auth_dbm module and its directives instead.

mod_auth_dbm Directives

mod_auth_dbm provides you with the AuthDBMGroupFile and AuthDBMUserFile directives that you can use to specify the location of your password and group files. Password and group files are maintained with the dbmmanage program included in your server's support directory. For more information on how to use the dbmmanage program, see Chapter 15.

AuthDBMGroupFile

The AuthDBMGroupFile directive allows you to specify the location of the user/password/group file. dbmfilename should be an absolute path outside of DocumentRoot. For security reasons, it is important that filename is outside of the directory it is trying to protect:

AuthDBMGroupFile /usr/local/etc/httpd/passwords/passworddbm

DBM password files store username, password, and group information. Typically you'll reference dbmfilename on both the AuthDBMGroupFile and AuthDBMUserFile directives. User information in the group file is maintained using the dbmmanage program included in the server's support directory. You'll need a copy of Perl to run dbmmanage. For information on how to use the dbmmanage program, see Chapter 15.

NAME="I33">AuthDBMUserFile

The AuthDBMUserFile directive allows you to specify the location of the user/password/group file. dbmfilename should be an absolute path outside of DocumentRoot. For security reasons, it is important that filename is outside of the directory it is trying to protect:

AuthDBMUserFile /usr/local/etc/httpd/passwords/passworddbm

DBM password files store username, password, and group information. Typically you'll reference dbmfilename on both AuthDBMGroupFile and AuthDBMUserFile directives. User information in the group file is maintained using the dbmmanage program included in the server's support directory. You'll need a copy of Perl to run dbmmanage. For information on how to use the dbmmanage program, please see Chapter 15.

The mod_auth_msql Module

The mod_auth_msql module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

mod_auth_msql allows you to provide access control using the mini SQL (mSQL) relational database engine, which can be obtained from ftp://ftp.bond.edu.au/pub/Minerva/msql. mSQL is not free for commercial or private use. Price for the engine is U.S. $170 for commercial organizations and $50 for private use. For more information, please visit the mSQL FTP site. -line documentation for the server can be found at http://Huges.com.au and http://cscsun1.larc.nasa.gov/~beowulf/msql/msql.html.

mod_auth_msql Directives

mod_auth_msql provides you with several directives that allow you to map the various authentication pieces of information to tables and fields within a mSQL database.

• Auth_MSQLhost
  
  
• Auth_MSQLdatabase
  
  
• Auth_MSQLpwd_table
  
  
• Auth_MSQLgrp_table
  
  
• Auth_MSQLuid_field
  
  
• Auth_MSQLpwd_field
  
  
• Auth_MSQLgrp_field
  
  
• Auth_MSQL_nopasswd
  
  
• Auth_MSQL_Authorative
  
  
• Auth_MSQL_EncryptedPasswords
  
  

Auth_MSQLhost

The Auth_MSQLhost directive sets the address of the host that is running the mSQL server. The host's address can be specified as the fully qualified domain name (FQDN), by IP address (IPaddress), or by specifying localhost, when the Web server host is also the database server. The localhost option forces the use of the faster interface /dev/msql instead of a slower socket connection.

Auth_MSQLdatabase

The Auth_MSQLdatabase directive sets the name of the mSQL database that contains the various authentication tables.

Auth_MSQLpwd_table

The Auth_MSQLpwd_table directive sets the name of the table that contains the fields defined by Auth_MSQLuid_field and Auth_MSQLpwd_field.

Auth_MSQLgrp_table

The Auth_MSQLgrp_table directive sets the name of the table that contains the fields defined by Auth_MSQLgrp_field and Auth_MSQLuid_field.

Auth_MSQLuid_field

The Auth_MSQLuid_field directive sets the name of the field that holds the username in the Auth_MSQLpwd_table and Auth_MSQLgrp_table.

Auth_MSQLpwd_field

The Auth_MSQLpwd_field directive sets the name of the field that holds the password in the Auth_MSQLpwd_table.

Auth_MSQLgrp_field

The Auth_MSQLgrp_field directive sets the name of the field that holds the group membership in the Auth_MSQLgrp_table.

Auth_MSQL_nopasswd

The Auth_MSQL_nopasswd directive sets whether the password authentication is skipped when Auth_MSQLpwd_field is empty (NULL). The default is set to disable this feature.

Auth_MSQL_Authorative

The Auth_MSQL_Authorative directive, when set to off, makes it possible to fall through to other authentication modules. If authentication fails, the server will pass control to other authentication modules such as mod_auth_anon. If authentication fails when set to on, the user is denied access. The default is set to on.

Auth_MSQL_EncryptedPasswords

When set to on, the password field is assumed to be encrypted with the crypt function. Incoming passwords are encrypted before they are compared. When set to off, the passwords are assumed to be in plain text format and are compared directly.

The mSQL password database

Please refer to your mSQL database manual for information on how to install and run the database server. This information assumes that you have some understanding of mSQL and SQL syntax. You can create the mSQL password database by typing the following commands:

msqladmin create passwords
msql passwords
-> create table user (
-> uid char(32) primary key,
-> pwd char(32) not null,
-> grp char(32) null
-> ) \g

To enter records on the password database, type the following:

-> insert into user
-> values ('User Name', 'asdflkjwer2223', 'registered')
-> \g

Note that for this example the password field is not encrypted.

To reference the previous table for authentication, enter the following on your conf/access.conf in a <Directory> section or in a per-directory (.htaccess) file:

Auth_MSQLhost localhost
Auth_MSQLdatabase passwords
Auth_MSQLpwd_table user
Auth_MSQLuid_field uid
Auth_MSQLpwd_field pwd
Auth_MSQLgrp_field grp
Auth_MSQL_Authorative on
Auth_MSQL_EncryptedPassords off
Auth_Name secured area
Auth_Type basic
<Limit GET POST>
 order deny,allow
 allow for all
 require valid-user
</Limit>

For more information, please see Chapter 15.

The mod_cern_meta Module

The mod_cern_meta module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

mod_cern_meta provides you with the ability to include additional HTTP headers into the requested document. This module was originally developed to provide additional compatibility to users of the CERN Web server who were migrating to Apache.

mod_cern_meta Directives

mod_cern_meta provides two additional directives:

• MetaDir
  
  
• MetaSuffix
  
  

MetaDir

The MetaDir directive will set the name of the directory the server will search for additional Meta information files. To have the server search the same directory as the request, set directoryName to a period (.).

MetaSuffix

The MetaSuffix directive will set the file extension of the file containing the additional header information.

MetaSuffix Example

This is a sample configuration:

MetaDir .
MetaSuffix .meta

For a request like http://somehost/index.html, the server will look for a file called index.html.meta in the same directory as the request. The contents of index.html.meta will be included as additional MIME-header information.

The mod_cgi Module

The mod_cgi module is built into Apache by default.

This module enables the execution of CGI programs. Files ending in .cgi or inside a directory defined by ScriptAlias will be processed as a CGI program and run by the server. Output of CGI programs is returned to the client.

When a CGI program is run by the server, the server will add the following variables to the environment:

DOCUMENT_ROOT	This variable will be set to the value of DocumentRoot.
REMOTE_HOST	This variable is added only if the server was not compiled with MINIMAIL_DNS or if the new HostnameLookups runtime directive was enabled in Apache 1.1.
REMOTE_IDENT	This is set to the name of the user if IdentityCheck is enabled and the user is running an RFC931- or RFC1413-compliant identity daemon.
REMOTE_USER	This variable is set to the name of the user if the CGI program is subject to user authentication.

The mod_env module adds additional environment variables. For more information, see the module mod_env later in this chapter.

The mod_cookies Module

The mod_cookies module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

Cookies help a Web server to maintain persistent state by handing the browser a unique identifier. Maintaining state has been one of the tedious programming issues for anyone developing a Web site. The Web is, by design, stateless: The server receives a request, answers the request, and disconnects. It doesn't care what you were doing. It doesn't know where you've been or where you are going.

Initial efforts at maintaining state were put on the server side. Although that works great, it adds to the load and to the complexity of programming Web-based applications. Netscape developed an extension to the HTTP protocol that implements Cookies, which off-load the persistence issue off to the client—a better thing to do. Although cookies are great, they are not part of the HTTP specification; however, browsers from Netscape, Microsoft, and others support them. r a better description of Netscape cookies, please refer to Chapter 7.

The mod_cookies module handles the process of generating and handing out cookies. When a request is received, the server looks for a Cookie: header. If one isn't found, the server assumes that the user has not visited the site in the current session, so it sends a Set_Cookie: header out with the request. Additional requests from the client will maintain the Cookie header sent by the server. Apache generates cookies with every request, no matter what browser was used to make the request. que cookie tags are generated by making a new tag by using the process ID of the server, the time, and the host IP of the client.

Although cookies are generated automatically by the server, it is up to your software to do something useful with them. You can use cookies to implement shopping carts or create meaningful logs that track users. The possibilities are almost endless.

The mod_cookies Directive

The mod_cookies module provides a directive you can use to log cookies: CookieLog.

Versions of Apache prior to 1.1 only support hands-out cookies to Netscape browsers. Apache 1.1 generates cookies for every request no matter what the browser.

The CookieLog Directive

The CookieLog directive sets the filename where the server will log cookies and the request that accompanied them. filename is relative of the path specified by the ServerRoot directive.

---

This directive does not log the initial request— the request that generated the cookie.

---

The mod_digest Module

The mod_digest module is not built into Apache by default. This module adds a new form of authentication called Digest authentication, which uses RSA MD5 encryption technology. Digest authentication encrypts and encodes the password the visitor provided so that it is only useful for retrieving the requested URL. The browser generates encodes a new password for each request. This ensures that if the password sent was compromised, it would only be useful for retrieving one URL only. e of Digest authentication requires the use of a supporting Web browser. Be aware that unless you are using a secure server to access your documents, the information that you transmit is still sent in world-readable form.

Digest authentication requires a compatible browser to operate the work.

The mod_digest Directive

The mod_digest module adds one directive:

• AuthDigestFile
  
  

AuthDigestFile

The AuthDigestFile directive specifies the file that contains the user and password information. This file is created with the htdigest utility found in the support subdirectory of the Apache server distribution. htdigest is similar in functionality to the htpassword utility.

htdigest

Usage: htdigest [-c] filepath realm username

The -c flag creates a new password file in filepath.

realm is the server realm being protected (set with the AuthName directive).

username is the name of the user to add an entry.

The htdigest program will prompt you for the password to add.

Configuring the Server to Use Digest Authentication

Using Digest authentication is very simple. Set authentication the way you normally would (see Chapter 15). Use AuthType Digest and AuthDigestFile instead of AuthType Basic and AuthUserFile. All else should remain the same.

The mod_dir Module

The mod_dir module controls the resource and formatting returned by the server when the request is for a directory. Directory indexes can be generated by a file written by an user, typically called index.html, or on-the-fly by the server (an automatic directory listing).

The DirectoryIndex directive sets the default name for the user-generated index file. The server looks for this file on any request for a directory.

The additional directives control the formatting of server-generated indexes, such as the embellishment of a listing by adding icons and descriptions to filenames. The filename-mapping conventions are very flexible. You can use wildcard expressions to make any file matching a pattern or content type display a particular description and icon next to its name.

mod_dir Directives

mod_dir provides a number of directives that help you associate icons, descriptions, header and footer files, and the selective inclusion of files and other information on a listing, as well as the name of user-generated index files:

• AddDescription
  
  
• AddIcon
  
  
• AddIconByEncoding
  
  
• AddIconByType
  
  
• DefaultIcon
  
  
• DirectoryIndex
  
  
• FancyIndexing
  
  
• HeaderName
  
  
• IndexIgnore
  
  
• IndexOptions
  
  
• HeaderName
  
  
• ReadmeName
  
  

AddDescription

The AddDescription directive maps a description to a filename or a filetype. description is displayed next to the filename on server-generated indexes when the FancyIndexing directive is set to on. description is a text string enclosed by double quotes ("). file can be described by a

file extension:	.gif—This would match files with a .gif extension.
partial filename:	Readme—This would match any file called Readme anywhere in the server.
full filename:	/usr/local/etc/httpd/htdocs/myfile.doc
wildcard expression:	asg??MAR.doc—The ? character matches a single character. The * character matches any sequence of characters. This would provide a match for asg01MAR.doc, asg02MAR.doc, and so on.

Here's an example of the AddDescription directive:

AddDescription "This is a Graphics Interchage Format" *.gif
AddDescription "Read This file before you do anything else" readnow
AddDescription "This is a picture of my boat" boat.gif

AddIcon

This directive sets the icon displayed next to a file listing on server-generated indexes when the FancyIndexing directive is set to on. iconfile can be a relative URL to the icon file or can follow the format (description,iconfile) where description is the text provided to nongraphical browsers.

The description string is enclosed by double quotes ("). file can be specified by a

file extension:	.gif—This would match files with a .gif extension.
partial filename:	Readme—This would match any file called Readme anywhere in the server.
full filename:	/usr/local/etc/httpd/htdocs/myfile.doc
wildcard expression:	asg??MAR.doc—The ? character matches a single character. The * character matches any sequence of characters. This would provide a match for asg01MAR.doc, asg02MAR.doc, and so on.

file can be either

• ^^DIRECTORY^^ for directories
  
  
• ^^BLANKICON^^ for blank lines (to format the list correctly)
  
  
• A file extension, wildcard expression, partial filename, or complete filename
  
  

Here's an example of the AddIcon directive:

AddIcon(image,/icons/image.gif) .gif .jpg .xbm
AddIcon /icons/dir.gif ^^DIRECTORY^^
AddIcon /icons/text.gif *.txt

Use of the AddIconByType directive is preferred over AddIcon.

AddIconByEncoding

When the FancyIndexing directive is set to on, AddIconByEncoding sets the icon displayed next to the file with mime-encoding on a server-generated index. Iconfile can be a relative URL to the file containing the icon or of the format (description,iconfile) where description is the text provided to nongraphical browsers.

mime-encoding is a wildcard expression matching the content encoding of the file. An example includes the following:

AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip

AddIconByType

This directive sets the icon displayed next to a file of type mime-type on server-generated indexes when the FancyIndexing directive is set to on. iconfile can be a relative URL to the file containing the icon or of the format (description,iconfile) where description is the text provided to nongraphical browsers.

mime-type is a wildcard expression matching the required MIME types. The following is an example of this:

AddIconByType (IMG,/icons/image.gif) image/*

DefaultIcon

When the FancyIndexing directive is set to on, this directive sets the icon displayed next to a file that has not been given an icon with any of the other directives on server-generated indexes. iconfile can be a relative URL to the file containing the icon or of the format (description,iconfile) where description is the text provided to nongraphical browsers.

Here's an example of the DefaultIcon directive:

DefaultIcon /icon/unknown.gif

DirectoryIndex

The DirectoryIndex directive identifies which resources to look for when a request ends in a directory name. DirectoryIndex provides a list of files to return if such a request is made.

Here's an example of the DirectoryIndex directive:

DirectoryIndex index.html readme.txt

If a request is made to a directory, the server would first try to return index.html. If that file does not exist, it tries to return a file called readme.txt. If that file doesn't exist, it returns a server-generated index.

URLs don't need to be relative to the directory. In the following example, the output from a program that tells you your fortune would be returned if the first two files didn't exist:

DirectoryIndex index.html readme.txt /cgi-bin/fortune.cgi

FancyIndexing

The FancyIndexing directive sets the FancyIndexing option for a directory. It can be set to on to enable the display of icons and other adornments or to off to provide more generic listings.

The IndexOptions directive described in the following section should be used instead of FancyIndexing, because it gives better control over the format of server-generated indexes. This directive is provided for National Center for Supercomputing Applications (NCSA) httpd server compatibility.

HeaderName

The HeaderName directive specifies the name of the file to include at the top of a server-generated listing. filename is the name of the file to include, and it is taken to be relative to the directory being indexed. The server first tries to include filename.html as an HTML document. Otherwise, it includes filename as an ASCII document:

HeaderName README

When generating a server index for /usr/local/htdocs, the server will include the file /usr/local/htdocs/README.html if such a file is found. Otherwise, it will try to include /usr/local/htdocs/README if it exists.

This is a great way of posting information about a series of documents. (See also ReadmeName.)

IndexIgnore

The IndexIgnore directive specifies the files to omit on server-generated indexes.

file can be specified by a

file extension:	.gif—This would match files with a .gif extension.
partial filename:	Readme—This would match any file called Readme anywhere in the server.
full filename:	/usr/local/etc/httpd/htdocs/myfile.doc
wildcard expression:	asg??MAR.doc—The ? character matches a single character. The * character matches any sequence of characters. This expression would provide a match for asg01MAR.doc, asg02MAR.doc, and so on.

Here's an example of the IndexIgnore directive:

IndexIgnore README core *~

By default, IndexIgnore ignores dotfiles—files that are normally hidden from directory listings. Dotfiles start with a period (.), such as .cshrc, .mailrc, and so on.

IndexOptions

The IndexOptions directive controls the features available on server-generated indexes. option can be

FancyIndexing	This enables fancy indexing of directories.
IconsAreLinks	This makes the icons part of the anchor for the filename. For fancy indexing, clicking on the icon would have the same effect as clicking on the filename (it would retrieve the file).
ScanHTMLTitles	This enables reading the title from HTML documents for fancy indexing. If the file does not have a description associated with an AddDescription directive, the server will scan the document for the value of the <TITLE> tag. Needless to say, this is CPU and disk intensive.
SuppressLastModified	This will suppress display of the last modification date in fancy indexing listings.
SuppressSize	This will suppress the file size in fancy indexing listings.
SuppressDescription	This will suppress the file description in fancy indexing listings.

The default doesn't enable any options. When multiple IndexOptions apply to a directory, only the most specific one is used; the options are not cumulative.

Here's an example of the IndexOptions directive:

<Directory /usr/local/etc/httpd/htdocs/
IndexOptions FancyIndexing
</Directory>
<Directory /usr/local/etc/httpd/htdocs/projectA>
IndexOptions ScanHTMLTitles
</Directory>

In this example, ScanHTMLTitles is the only option used in requests for /usr/local/etc/httpd/htdocs/projectA.

ReadmeName

The ReadmeName directive specifies the name of the file to include at the bottom of a server-generated listing. filename is the name of the file to include, and it is taken to be relative to the directory being indexed. The server first tries to include filename.html as an HTML document. Otherwise, it includes filename as an ASCII document, as in this example:

ReadmeName README

When generating an index for /usr/local/htdocs, the server will include the file /usr/local/htdocs/README.html if such a file is found. Otherwise, the server will try to include /usr/local/htdocs/README if it exists.

This is a great way to post information about a series of documents. (See also HeaderName.)

The mod_env Module

This module extends the environment variables passed to CGI and SSI scripts. It permits CGI and SSI scripts to inherit all environment variables from the shell that invoked the httpd process. It was originally developed to provide additional compatibility to users migrating from the CERN Web server.

mod_env Directives

mod_env provides two additional directives

• PassEnv
  
  
• SetEnv
  
  

PassEnv

The PassEnv directive allows you to define an environment variable, from the server's own environment, that will be passed to CGI and SSI scripts. For example:

PassEnv PATH

SetEnv

The SetEnv directive allows you define an environment variable that will be passed to CGI and SSI scripts. For example:

SetEnv SERVER_TOOL_PATH /usr/lib/tools

The mod_dld Module

The mod_dld module is not built into Apache by default. In order to use any of its directives you need to reconfigure Apache to include this module and recompile the server.

mod_dld is a proof of concept module—that is, it is experimental code. It allows for loading of modules at server-configuration time instead of statically linking them in at compile time. This option may be useful to someone developing modules to reduce the compile and linking process. Its use requires GNU's dynamic linking library, DLD. with any other dynamic linking, the httpd binary and the modules you are dynamically loading should not have their symbols stripped (see strip in your UNIX manual).

mod_dld Directives

The mod_dld module provides two directives:

• LoadFile
  
  
• LoadModule
  
  

LoadFile is for loading support libraries. LoadModule loads modules and properly inserts the module in the server's module list.

LoadFile

The LoadFile directive links at runtime the named object code files or libraries listed in filename at server configuration. The LoadFile directive is used to link additional code that may be required by a module. filename is relative to ServerRoot. Here's an example of the LoadFile directive:

LoadFile /lib/libc.a

LoadModule

The LoadModule directive links in the object file or library filename and adds the module structure named module to the list of active modules. module is the name of the external variable of type module in the file. The following is an example of this:

LoadModule cookies_module modules/mod_cookies.o

The mod_imap Module

The mod_imap module is built into Apache by default. It replaces the image map CGI program for server-side processing of image map (.map) files.

mod_imap Directives

New with Apache 1.1 is an enhanced image map module. The new enhanced dmodule provides three directives:

• ImapMenu
  
  
• ImapDefault
  
  
• ImapBase
  
  

ImapMenu

The ImapMenu directive controls the behavior taken when an image map is called without valid coordinates, such as when a nongraphical browser accesses it. Here are the valid options:

none	If set to none, no menu is generated and the default action is performed. The default action can be set by the ImapDefault directive or by a default entry in the image map itself.
formatted	Generates the simplest menu: A header, a rule (HR), and the link are printed (one per line).
semiformatted	This menu also includes any comments in the image map file. Comments are lines that begin with a pound character (#). They can include HTML tags. Blank lines in the map are turned into HTML BR tags. This menu does not print a header or a rule like the formatted menu.
unformatted	This is the most flexible menu format. Comments are lines that begin with a pound character (#). They can include HTML tags. Blank lines are ignored. All content sent to the client must be specifically included in the image map file. Headers and breaks should be included as comments in the image map file.

ImapDefault

The ImapDefault directive sets the default for image map files. This default can be overridden by a default directive inside the image map file.

error	Returns a 500 Server Error.
nocontent	This option returns a 204 No Content HTTP status code, which keeps the client focused on the original page.
map	Sets the default action to the URL of the image map itself. This option will generate a menu, unless ImapMenu is set to none.
referer	Sets the default action to the URL of the referring document. If no referer header is available, the default URL is set to the server's DocumentRoot.
url	A URL.

ImapBase

The ImapBase directive sets the base URL used in the image map files. This directive will be overridden by the value of the base directive in the image map file. If omitted, the default is set to the server's DocumentRoot.

Using Server-Side Image Maps

Map files define regions within a graphic that behave as a link when clicked on by the user. Regions are defined as simple shapes: circles, rectangles, or polygons.

Documents tagged as being MIME-type application/x-httpd-imap are processed by this module, which offers better performance and more flexibility than the original CGI program used for this purpose. This functionality is compiled into the server, so no external CGI server transaction is generated. To get this module to process .map files, you'll need to associate a MIME-type format to a file extension using the AddType directive in an entry such as

AddType application/x-httpd-imap map

An entry like this already exists in the Apache configuration templates provided, so you don't need to alter this unless you want to use a different filename.

The image map module adds some new features that were not possible with previously distributed image map programs:

• URL can reference documents relative to the Referer: information (relative of the current document).
  
  
• Default <BASE> assignment through a new map field base_uri, which appears in imagemap files.
  
  
• Eliminates the need for the imagemap.conf file, a configuration file that associates .map files to the images. You can now just reference the relevant map file in your HTML document.
  
  
• Supports point references.
  
  

base_uri options appear in an image map and include:

map	Provides the default and old behavior of map relative reference
Referer	Uses the Referer: header information to reference a URL relative to the current document
http://URL	Has the effect of setting <BASE> to that URL, which makes all references relative to that <BASE>

A Map File Example

Here's an example of an imagemap file:

default http://lincoln/
base_uri referer
rect .. 0,0 77,27
poly http://www.inetnebr.com/ 78,0 194,27
circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27
rect search_index 306,0 419,27
point http://www.zyzzyva.com/ 420,0 549,27

Referencing the Map File

Map files are referenced right from the HTML page:

<A HREF="http:/maps/imagmap1.map">
<IMG ISMAP SRC="http:/images/imagemap1.gif">
</A>

The mod_include Module

The mod_include module is built into Apache by default. It provides support for server-parsed HTML (SPML) documents.

SPML documents are processed by the server before they are sent to the client. Documents with a MIME-type text/x-server-parsed-html or text/x-server-parsed-html3 are parsed. The resulting HTML document is sent to the client.

SPML Command Format

The document is parsed as an HTML document with commands embedded as Standard Generalized Markup Language (SGML) comments. The commands can

• Execute programs
  
  
• Obtain file size and modification information
  
  
• Include text from other documents or from a program
  
  
• Configure the format used to display results from the various commands
  
  

Commands follow this syntax:

<!--#command option=value option=value ...-->

SMPL Commands

The available commands are

• config
  
  
• echo
  
  
• exec
  
  
• cmd
  
  
• fsize
  
  
• flastmod
  
  
• include
  
  

A plug-in replacement module called Extended Server Side Includes (XSSI) extends the server-side include syntax (which adds conditional inclusion with if-then-else constructs), adds the capability to set and use variables, and provides regular expression support. This package is available at http://pageplus.com/~hsf/xssi/.

For complete documentation on how to use Server Side Includes and its commands, see Chapter 6.

The mod_include Directive

mod_include adds one directive:

• XBitHack
  
  

XBitHack

The XBitHack directive controls processing of ordinary HTML documents. The following options are available:

off	No special treatment of HTML files marked as executable.
on	Any .html file that has the user-execute bit set will be parsed by the server.
full	The same as for on, but also test the group-execute bit. If it is set, then the server will set the last-modified date of the returned file to be the last-modified time of the file. If the group-execute bit is not set, no last-modified date is sent. Setting this bit allows clients and proxies to cache the result of the request because it is possible to determine the date of the document's last modification.

The mod_info Module

The mod_info module is not built into Apache by default. In order to use its functionality, you need to reconfigure Apache to include it and then rebuild the server. mod_info displays all your server configuration settings. The report includes modules and all runtime configuration settings in a nicely formatted HTML file. It's way cool!

Once you rebuild your server, you'll need to add the following directives to your conf/access.conf configuration file:

<Location /configuration>
SetHandler server-info
</Location>

If you want to keep your server configuration private—an important thing because this report will list all your settings—add a Limit section specifying some access restrictions (see Chapter 15 for more information). Restart the server and point your Web browser to http://yourhost/configuration. The server will return its very detailed configuration report.

The mod_log_agent Module

The mod_log_agent module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and then recompile the server. This module is provided for compatibility with NCSA 1.4.

This module enables logging the client user agents—the browsers used for accessing your site. This feature is not very reliable; because many sites provide different pages to different browsers, there is a trend with some browsers to fake their identity to obtain the more elaborate versions of the site. The faked agent is usually Mozilla, the Netscape Navigator browser.

The mod_log_agent Directive

mod_log_agent adds one directive:

• AgentLog
  
  

AgentLog

The AgentLog directive specifies the file where the server logs the UserAgent header on incoming requests. The options are either filename or |program.

• filename is the name of a file relative of ServerRoot.
  
  
• |program is the pipe symbol (|) followed by path to a program capable of receiving the log information on standard input (stdin).
  
  

As with any program started by the server, the program is run with the UID and GID of the user that started the httpd daemon. If the user starting the program is root, be sure that the user directive demotes the server privileges to those of an unprivileged user such as nobody. Also, make sure the program is secure.

The mod_log_common Module

The mod_cgi module is built into Apache by default.

This module logs requests made to the server using the Common Logfile format. For more information, please see chapter 13.

Logfile Format Description

The Common Logfile Format logs each request in a separate line. A line is composed of several fields separated by spaces:

host ident authuser date request status bytes

Null fields (fields that have no values) contain a dash (-).

The following options are available:

host	The host field contains the fully qualified domain name or, if the name was not available, the IP of the machine that made the request.
Ident	If IdentityCheck is enabled and the client machine is running an identity daemon, this field contains the name of the user that made the request.
Authuser	If the request requires authentication, this field contains the login of the user who made the request.
date	This field contains the date and time of the request. The date format used is day/month/year:hour:minute:second timezone.
request	The request line from the client enclosed in double quotes (").
status	The three-digit HTTP status code returned to the client.
bytes	The size of the transfer in bytes returned to the client, not counting header information.

mod_log_common Directives

The mod_log_common module provides the following directive to set the file where the log information is stored:

• TransferLog
  
  

TransferLog

The TransferLog directive specifies the file where the server logs request information on incoming requests. The options are filename or |program.

• filename is the name of a file relative of ServerRoot.
  
  
• |program is the pipe symbol (|) followed by a path to a program capable of receiving the log information on standard input (stdin).
  
  

As with any program started by the server, the program is run with the UID and GID of the user that started the httpd daemon. If the user starting the program is root, be sure that the user directive demotes the server privileges to those of an unprivileged user such as nobody. Also, make sure the program is secure.

The mod_log_config Module

The mod_log_config module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

This module allows logging server requests using a user-specified format. This module is experimental in nature. It implements the TransferLog directive (same as the mod_log_common) and an additional directive, LogFormat.

The argument to the LogFormat directive is a string that can include literal characters copied into the log files as well as % directives:

%h	Remote host.
%l	Remote logname (from identd, if supplied).
%u	Remote user [from auth; may be bogus if return status (%s) is 401].
%t	Time, in common log format time format.
%r	First line of request.
%s	Status. For requests that got internally redirected, this is the status of the original request.
%>s	Status. For requests that were internally redirected, this is the status of the last request.
%b	Bytes sent.
%{Header}i	Inserts the contents of the HTTP header Header that was received from the client.
%{Header}o	Inserts the contents of the HTTP header Header that was sent back to the client.

You can specify the conditions for inclusion of a particular field by specifying an HTTP status code between the % and the letter code for the field. You can specify more than one by separating them with a comma (,):

%400,500{User-agent}I

This line of code logs User-Agent headers only as Bad Request or Not Implemented errors.

You also can specify that an item should be logged, if a certain HTTP code is not returned by adding an exclamation symbol (!) in front of the code you want to see:

%!200,304,302{Referer}i

This line of code logs Referer header information on all requests not returning a normal return code.

If any condition is not met, the field is null. As with the common log format, a null field is indicated by a dash (-) character.

Virtual hosts can have their own LogFormat and/or TransferLog. If no LogFormat is specified, it is inherited from the main server process. If the virtual host doesn't have its own TransferLog, entries are written to the main server's log.

To differentiate between virtual hosts that are writing to a common log file, you can prepend a label to the log format string like in this next example:

<VirtualHost xxx.com>
LogFormat "xxx formatstring"
...
</VirtualHost>
<VirtualHost yyy.com>
LogFormat "yyy formatstring"
...
</VirtualHost>

mod_log_config Directives

mod_log_config provides two directives:

• LogFormat
  
  
• TransferLog
  
  

LogFormat

This sets the format of the log file.

TransferLog

The TransferLog directive specifies the file where the server logs all request transactions. The options are filename or |program:

• filename is the name of a file relative of ServerRoot.
  
  
• |program is the pipe symbol (|) followed by path to a program capable of receiving the log information on stdin (standard input).
  
  

As with any program started by the server, the program is run with the UID and GID of the user that started the httpd daemon. If the user starting the program is root, be sure that the user directive demotes the server privileges to those of an unprivileged user such as nobody. Also, make sure the program is secure.

The mod_log_referer Module

The mod_log_referer module is not built into Apache by default. In order to use any of its directives, you need to reconfigure Apache to include this module and recompile the server.

This module provides logging of documents that reference documents on the server.

Logfile Format Description

The logfile contains a separate line for each reference. Each line has the format

uri -> document

where uri is the URI for the document that references the one requested by the client, and document is the local URL to the document being referenced.

mod_log_referer Directives

• RefererIgnore
  
  
• RefererLog
  
  

RefererIgnore

The RefererIgnore directive adds to the list of strings to ignore in Referer headers. If any of the strings in the list are contained in the Referer header, no information will be logged for the request. An example of this is as follows:

RefererIgnore webcrawler.com

This avoids logging requests from webcrawler.com.

RefererLog

The RefererLog directive specifies the file where the server logs referer information. The options are filename or |program:

• filename is the name of a file relative of ServerRoot.
  
  
• |program is the pipe symbol (|) followed by a path to a program capable of receiving the log information on stdin.
  
  

As with any program started by the server, the program is run with the UID and GID of the user that started the httpd daemon. If the user starting the program is root, be sure that the user directive demotes the server privileges to those of an unprivileged user such as nobody. Also, make sure the program is secure.

This directive is provided for compatibility with NCSA httpd 1.4.

The mod_mime Module

The mod_mime module is built into Apache by default.

This module maps MIME-encodings of documents based on their filenames. Filenames are composed of a basename followed by one or more extensions:

base.type.language.encoding

The type sets the document type; an HTML document has a .html type. The language extension describes the language in which the document is written. encoding specifies if the document has been processed by a program, such as a compression program.

This module is used to map the MIME types of documents based on their type, language, and encoding extensions. MIME types requiring some special processing by the server are handed down to the appropriate modules, such as the mod_imap module which processes .map files or the mod_include module which processes SPML documents. Types not requiring any processing, such as .gif or .html, are returned to the client where the browser can process the document as needed.

mod_mime Directives

mod_mime adds the following directives:

• AddEncoding
  
  
• AddLanguage
  
  
• AddType
  
  
• TypesConfig
  
  

The following directives are only available in Apache 1.1 or better:

• AddHandler
  
  
• ForceType
  
  
• SetHandler
  
  

AddEncoding

The AddEncoding directive maps file extension's extension to the encoding type mime-enc. The following is an example:

AddEncoding x-gzip gz
AddEncoding x-compress Z

The preceding example will mark files ending in .gz as encoded using the x-gzip encoding, and files ending in .Z as encoded with x-compress encoding.

AddLanguage

The AddLanguage directive maps language extension's extension to the language type mime-lang. mime-lang is the MIME language of the files after any encoding formats have been removed. An example of this is as follows:

AddEncoding x-gzip gz
AddLanguage en .en
AddLanguage fr .fr

Then the document document.en.gz will be treated as being a gzipped-compressed English-language document. The AddLanguage directive is useful in content negotiation, where the server selects from several documents one that is appropriate for the client's language preference.

AddType

The AddType directive maps filename extension's extension to the content type mime-type. mime-type is the content encoding of the file, after any encoding formats and language extensions have been removed. The following is an example:

AddType image/gif GIF

You should add new MIME types using the AddType directive instead of modifying entries in the TypesConfig file (conf/mime.types).

---

Unlike the NCSA httpd, the AddType directive cannot be used to set the type of particular files.

---

TypesConfig

The TypesConfig directive specifies the location of the MIME-types configuration file. filename is a relative of ServerRoot. This file contains the default list of filename extension mappings to content types. Don't alter this file unless you know what you are doing. Use the AddType directive in conf/srm.conf instead.

The MIME types configuration file contains lines in the format of the arguments to an AddType command:

mime-type extension extension...

Extensions are specified in lowercase. Blank lines and lines beginning with a pound sign (#) are ignored.

AddHandler

The AddHandler directive specifies the handler that will process the filetype. handler is nothing more than a program that knows how to handle the specified filetype. For example, CGI programs are handled by the cgi-script handler. Server Side Includes are handled by the server-parsed handler.

In addition to cgi-script and server-parsed handlers, the following handlers are available:

send-as-is	Sends files with HTTP headers. See mod_asis.
imap-file	Processes image map files. See mod_imap.
server-info	Informs you of the server configuration. See mod_info.
server-status	Informs you of the server status. See mod_status.
type-map	Parses type maps for content negotiation information. See mod_negotiation.

To add a handler that will process CGI programs with a .program extension, you might specify in your conf/srm.conf or httpd.conf:

AddHandler cgi-script program

Once the server is restarted, any file with the program extension will be treated as a CGI.

ForceType

The ForceType directive specifies the MIME-type format that will be applied to files matching a <Directory> or <Location> section. This directive is useful to remap many files of a particular type that don't sport the appropriate extension. The following is an example:

<Location /images>
ForceType image/gif
</Location>

Any request in the /images directory will send any file regardless of filetype extension as a GIF.

SetHandler

The SetHandler directive specifies the handler that will process a particular request based on access to a directory or location. Requests matching the directory or location specification will be processed by the handler. This is how you enable the status module (mod_status):

<Location /status>
SetHandler server-status
</Location>

Requests for the /status URI will return a status report.

The mod_negotiation Module

The mod_negotiation module is built into Apache by default.

This module provides for content negotiation. Any document with MIME type application/x-type-map will be processed by this module.

Content selection is the selection of the document that best matches the client's capabilities from several equivalent documents. There are two ways of providing this functionality.

One way is through a type map (a file with the MIME type application/x-type-map), which lists equivalent files.

The other way to provide this functionality is through a MultiViews search (enabled by the Option MultiViews), which forces the server to perform a filename pattern match and choose from the resulting list.

Type Maps

A type map uses the same format as RFC822 mail headers that contain document descriptions separated by blank lines. Lines beginning with a pound (#) are treated as comments.

The description consists of several of these headers. Records may be continued on additional lines if the additional lines start with spaces. The leading space will be deleted and the lines concatenated.

A header record consists of a keyword name, which always ends in a colon, followed by a value. Whitespace is allowed between the header and the value, and between the tokens of value. The headers allowed are

Content-Encoding:	The encoding of the file. Currently only two encodings are recognized by HTTP; x-compress for compressed files and x-gzip for gzipped files.
Content-Language:	The language of the variant as an Internet standard language code, such as en (English).
Content-Length:	The length of the file in bytes. If this header is not present, the actual length of the file is used.
Content-Type:	The MIME media type of the document with optional parameters. Parameters are separated from the media type and from each other by semicolons. Parameter syntax is name=value. Allowed parameters are
	Level: The value is an integer that specifies the version of the media type. For text/HTML, this defaults to 2; otherwise, 0.
	qs: The value is a floating-point number with a value between 0 and 1. It indicates the quality of this variant.
	Example: Content-Type: image/jpeg; qs=0.8
URI:	The path to the file containing this variant, relative to the map file.

MultiViews

A MultiViews search is enabled by the MultiViews option (Options MultiViews). When the server receives a request for a file and it does not exist, the server searches for a file using the name requested as a basename (without any extensions) and tries to match the name to a list of files that use basename as a name.

Here's a sample request:

.../path/file

The server searches for files matching the pattern

.../path/file.*

By using the filetype, language, and encoding-mapping information, the server effectively builds a type map from which to select the best match for the client's requirements, which it will then return to the client.

mod_negotiation Directives

The mod_negotiation module adds the following directives:

• CacheNegotiatedDocs
  
  
• LanguagePriority
  
  

CacheNegotiatedDocs

When set, content-negotiated requests are cachable by proxy servers.

LanguagePriority

The LanguagePriority directive sets the precedence of language encodings in cases when the client does not express a preference. The list of mime-lang is in order of decreasing preference. The following is an example:

LanguagePriority en fr de

In a request for index.html, where the browser did not specify a language preference but only the French and German versions of the document were available, the server would return the French version.

The mod_proxy Module

A proxy server is a Web server that sits between a local client and an external Web server. It acts as an intermediary to the client and fetches information from other Web servers. Instead of having a client connect to a server on the Internet directly, it establishes a connection with a proxy server in the user’s local network. The proxy server then retrieves the resources requested and serves them to the client as if the resources were its own.

Caching proxy servers can be a powerful tool in your arsenal to increase the performance of your internal Web traffic. While originally developed as a way of allowing access to the Web through a firewall, proxy servers have also been used to reduce the traffic your organization generates to popular Web sites.

For additional information on proxy servers, please see Chapter 12, "Web Server Performance Tuning."

mod_proxy Directives

mod_proxy supplies a variety of directives to help you manage the behavior of the server and its cache:

• CacheegotiatedDocs
  
  
• CacheDefaultExpire
  
  
• CacheGcInterval
  
  
• CacheLastModified
  
  
• CacheMaxExpire
  
  
• CacheRoot
  
  
• CacheSize
  
  
• NoCache
  
  
• ProxyPass
  
  
• ProxyRemote
  
  
• ProxyRequests
  
  

ProxyRequests

The ProxyRequest directive enables or disables the proxy functionality of the server. A proxy server is one that is able to act as an intermediary to fulfill requests from a browser to another Web server. It is frequently used as a way of providing access to clients behind a firewall to the Web without compromising the security requirements of the organization.

---

Disabling the ProxyRequest functionality does not disable the ever cool ProxyPass directive functionality provided with the module.

---

ProxyRemote

The ProxyRemote directive allows you to specify remote proxies to this proxy server. Its configuration is based on a pattern specified as a partial URL that the remote server can understand. To indicate that a specified server should be contacted for all requests, specify a dollar sign ($) as the URL.

ProxyRemote http://www.company.com/ http://mirror.somewhere.com

You can specify a server that runs in a different port as:

ProxyRemote http://www.company.com/ http://mirror.somewhere.com:8080

ProxyPass

This is a very cool directive. ProxyPass allows you to map a remote server into your local server’s document tree, much as if you were mounting the remote document tree into your server’s document tree. The local server appears as a mirror of the remote server. ProxyPass takes two arguments: path is the file path you want to use for inserting the remote server into your document tree; and URL is the address of the real server that the proxy request should be sent to:

ProxyPass /SmartSoft.htmld http://www.smartsoft.com/

In this case, a request such as

http://proxy/SmartSoft.htmld/index.html

will get translated into a proxy request to

http://www.SmartSoft.com/index.html

You can specify as many ProxyPass directives as you like.

CacheRoot

CacheRoot specifies the directory that the server should use to store cache information. The server must be able to write to the directory specified by directory-path. Typically, since this means that user nobody must have write privileges to this directory, this translates into a directory that is world writable.

---

If you are concerned about security, you may wish to have the server run under a special UID that has low permissions. This would allow you to create a directory that is writable by the server but not the world.

---

CacheSize

This directive specifies the maximum size of the cache in KB (1024 byte units). While the cache will grow beyond the amount specified by size, at garbage collection intervals, the server will remove cached documents until the space consumed is at or below the amount specified by this directive. The garbage collection interval is specified by the CacheGcInterval directive.

CacheGcInterval

The garbage collection interval is specified by the CacheGcInterval directive. At this time the server will check the disk space consumed by the cache. It will then prune the cache until the disk space consumed is less or equal to the space specified by the CacheSize directive.

time is specified in hours.

CacheMaxExpire

The CacheMaxExpire directive controls how long (in hours) cacheable documents will be kept in the cache without re-requesting documents from the original server.

In effect this setting controls the maximum amount of time that documents could potentially be served out of date because it is feasible that changes may be introduced into documents while they are in cache.

The CacheMaxExpire directive is enforced even when a document has an expiration date supplied in a meta tag within.

CacheLastModifiedFactor

The CacheLastModifiedFactor directive supplies an expiration time for a document based on the formula:

expiry = timeOfLastModification * factor

If a document was modified in the last 24 hours and the factor is set to the default, the expiry period will be set to 2.4 hours (24 x 0.1 = 2.4 hours; 2 hours and 24 minutes).

If the expiration time specified by CacheMaxExpire arrives sooner, it takes precedence over the expiry time calculated by CacheLastModifiedFactor.

CacheDefaultExpire

If a protocol does not supply an expiration time, the value specified by CacheDefaultExpire is used. This expiration time is not overridden by CacheMaxExpire. Currently, the proxy module only provides proying capabilities for FTP and HTTP (both HTTP/0.9 and HTTP/1.0) protocols.

NoCache

The NoCache directive provides you with a mechanism to specify a list of hosts or domains that you don’t want cached by the proxy server. You can specify hosts and/or domain names in a list form where each host or domain is separated by spaces:

NoCache foo.xxxx.com bar.com

This directive is particularly useful if you know a site is dynamic, and you don’t want stale information to ever be served for it.

The mod_status Module

The mod_status module is a great tool for informing the server administrator what the server is doing. It takes a snapshot of all the server processes and creates an HTML report that can be viewed with a browser. The report includes a wealth of information including the following:

• The number of children processes and their status
  
  
• Transfers performed by each child
  
  
• The average number of requests per second
  
  
• The average number of bytes served per second
  
  
• The amount of resources utilized by each child and by the entire group
  
  
• Current clients and the requests being served.
  
  

mod_status is not included by default; you'll need to reconfigure and rebuild the server. Once built, you'll need to add the following directives to your conf/access.conf configuration file:

<Location /status>
SetHandler server-status
</Location>

If you want to keep your server statistics private, add a Limit section specifying some access restrictions (see Chapter 15 for more information). Restart the server and point your Web browser to http://yourhost/status. The server will return its detailed status report.

The mod_userdir Module

The mod_userdir module is built into Apache by default. It provides a mechanism through which users can publish their own home page information.

This module specifies the directory, relative of a local user's home directory, where public HTML documents and home pages can be found. Requests for user's home pages take the form of

http://www.somedomain.com/~user

mod_userdir Directives

The only directive provided by this module is UserDir.

UserDir

The UserDir directive sets the directory name relative of a local user's home directory where public HTML documents may be found. This feature can be disabled by specifying the disabled option to the directive. If omitted, it defaults to

UserDir public_html

Although this may be a useful directive to allow users in a UNIX environment to specify their own home pages, some users may not be aware of this fact, resulting in the possibility of them creating a directory named public_html that contains private files. Additionally, depending on the kind of users in your system, this can create some security problems.

Apache 1.1 enhances this module to redirect home page requests to a different directory, removing the security concerns previously raised. By specifying an absolute path such as the following:

UserDir /Users/homepages

The server will look for a directory matching the request in /Users/homepages. Requests for http://www.somedomain.com/~x will be retrieved from /Users/homepages/x.

---

If you have enabled Options FollowSymLinks or AllowOverrides Options for the directory containing your users' home directories, any users could attach, via a link, any portion of your filesystem to their public_html directory. This, in effect, would make private materials from your organization available to anyone outside of your organization. This might not be what you want, and might be a good reason to scan logs frequently.

---

Here's an example of the UserDir directive:

UserDir public_html

A request for http://www.somedomain.com/~user will return the file http://www.somedomain.com/~user/index.html.

Summary

This chapter serves as a reference guide for Apache modules. In the next chapters, you will learn about system administration, including the basics, Web server performance tuning, and Web accounting.