Apache Configuration File Structure

Apache keeps all of its configuration information in text files. The main file is called httpd.conf. This file contains directives and containers, which enable you to customize your Apache installation. Directives configure specific settings of Apache, such as authorization, performance, and network parameters. Containers specify the context to which those settings refer. For example, authorization configuration can refer to the server as a whole, a directory, or a single file.

Directives

The following rules apply for Apache directive syntax:

• The directive arguments follow the directive name.

• Directive arguments are separated by spaces.

• The number and type of arguments vary from directive to directive; some have no arguments.

• A directive occupies a single line, but you can continue it on a different line by ending the previous line with a backslash character (\).

• The pound sign (#) should precede the directive, and must appear on its own line.

In the Apache server documentation, found online at http://httpd.apache.org/docs-2.0/, you can browse the directives in alphabetical order or by the module to which they belong. You'll soon learn about some of the basic directives, but you should supplement your knowledge using the online documentation.

Figure 3.5 shows an entry from the documentation for the ServerName directive description. You can read this description in the online documentation at http://httpd.apache.org/docs-2.0/mod/core.html#servername.

The schema, as detailed in the documentation at http://httpd.apache.org/docs-2.0/mod/directive-dict.html, is the same for all directives:

• Description This entry provides a brief description of the directive.

• Syntax This entry explains the format of the directive options. Compulsory parameters appear in italics, optional parameters appear in italics and brackets.

• Default If the directive has a default value, it will appear here.

• Context This entry details the containers or sections in which the directive can appear. Containers are explained in the next section. The possible values are server config, virtual host, directory, and .htaccess.

• Status This entry indicates whether the directive is built in Apache (core), belongs to one of the bundled modules (base or extension, depending on whether they are compiled by default), is part of a Multi-Processing Module (MPM), or is bundled with Apache but not ready for use in a production server (experimental).

• Module This entry indicates the module to which the directive belongs.

• Compatibility This entry contains information about which versions of Apache support the directive.

• Override Apache directives belong to different categories. The override field is used to specify which directive categories can appear in .htaccess per-directory configuration files.

Further explanation of the directive follows these entries in the documentation, and a reference to related directives or documentation might appear at the end.

Containers

Directive containers, also called sections, limit the scope for which directives apply. If directives are not inside a container, they belong to the default server scope (server config) and apply to the server as a whole.

These are the default Apache directive containers:

• <VirtualHost> A VirtualHost directive specifies a virtual server. Apache enables you to host different Web sites with a single Apache installation. Directives inside this container apply to a particular Web site. This directive accepts a domain name or IP address and an optional port as arguments. You will learn more about virtual hosts in Chapter 27, "Apache Performance Tuning and Virtual Hosting."

• <Directory>, <DirectoryMatch> These containers allow directives to apply to a certain directory or group of directories in the file system. Directory containers take a directory or directory pattern argument. Enclosed directives apply to the specified directories and their subdirectories. The DirectoryMatch container allows regular expression patterns to be specified as an argument. For example, the following allows a match of all second-level subdirectories of the www directory that are made up of four numbers, such as a directory named after a year and month (0904 for September 2004):

  <DirectoryMatch "^/www/.*/[0-9]{4}">
  

  
  

• <Location>, <LocationMatch> These containers allow directives to apply to certain requested URLs or URL patterns. They are similar to their Directory counterparts. LocationMatch takes a regular expression as an argument. For example, the following matches directories containing either "/my/data" or "/your/data":

  <LocationMatch "/(my|your)/data">
  

  
  

• <Files>, <FilesMatch> Similar to Directory and Location containers, Files sections allow directives to apply to certain files or file patterns.

Containers surround directives, as shown in Listing 3.1.

Listing 3.1. Sample Container Directives

 1: <Directory "/some/directory">
 2: SomeDirective1
 3: SomeDirective2
 4: </Directory>
 5: <Location "/downloads/*.html">
 6: SomeDirective3
 7: </Location>
 8: <Files "\.(gif|jpg)">
 9: SomeDirective4
10: </Files>

Sample directives SomeDirective1 and SomeDirective2 will apply to the directory /www/docs and its subdirectories. SomeDirective3 will apply to URLs referring to pages with the .html extension under the /download/ URL. SomeDirective4 will apply to all files with .gif or .jpg extensions.

Conditional Evaluation

Apache provides support for conditional containers. Directives enclosed in these containers will be processed only if certain conditions are met.

• <IfDefine> Directives in this container will be processed if a specific command-line switch is passed to the Apache executable. The directive in Listing 3.2 will be processed only if the -DMyModule switch was passed to the Apache binary being executed. You can pass this directly or by modifying the apachectl script, as described in the "Apache-Related Commands" section later in this chapter.

  IfDefine containers allow the argument to be negated. That is, directives inside a <IfDefine ! MyModule> section will be processed only if no -DMyModule parameter was passed as a command-line argument. For example, if -DSSL is not passed, listening on the SSL port (usually 443) will not occur.

• <IfModule> Directives in an IfModule section will be processed only if the module passed as an argument is present in the Web server. For example, Apache ships with a default httpd.conf configuration file that provides support for different MPMs. Only the configuration belonging to the MPM compiled in will be processed, as you can see in Listing 3.3. The purpose of the example is to illustrate that only one of the directive groups will be evaluated.

Listing 3.2. IfDefine Example

1: <IfDefine MyModule>
2: LoadModule my_module modules/libmymodule.so
3: </IfDefine>

Listing 3.3. IfModule Example

 1: <IfModule prefork.c>
 2: StartServers              5
 3: MinSpareServers           5
 4: MaxSpareServers          10
 5: MaxClients               20
 6: MaxRequestsPerChild       0
 7: </IfModule>
 8:
 9: <IfModule worker.c>
10: StartServers             3
11: MaxClients               8
12: MinSpareThreads          5
13: MaxSpareThreads         10
14: ThreadsPerChild         25
15: MaxRequestsPerChild      0
16: </IfModule>

ServerRoot

The ServerRoot directive takes a single argument: a directory path pointing to the directory where the server lives. All relative path references in other directives are relative to the value of ServerRoot. If you compiled Apache from source on Linux/Unix, as described earlier in this chapter, the default value of ServerRoot is /usr/local/apache2. Mac OS X users, your ServerRoot defaults to /Library/WebServer. If you used the Windows installer, the ServerRoot is c:\Program Files\Apache Group.

Per-Directory Configuration Files

Apache uses per-directory configuration files to allow directives to exist outside the main configuration file, httpd.conf. These special files can be placed in the file system. Apache will process the content of these files if a document is requested in a directory containing one of these files or any subdirectories under it. The contents of all the applicable per-directory configuration files are merged and processed. For example, if Apache receives a request for the /usr/local/apache2/htdocs/index.html file, it will look for per-directory configuration files in the /, /usr, /usr/local, /usr/local/apache2, and /usr/local/apache2/htdocs directories, in that order.

Enabling per-directory configuration files has a performance penalty. Apache must perform expensive disk operations looking for these files in every request, even if the files do not exist.

Per-directory configuration files are called .htaccess by default. This is for historical reasons; they were originally used to protect access to directories containing HTML files.

The directive AccessFileName enables you to change the name of the per-directory configuration files from .htaccess to something else. It accepts a list of filenames that Apache will use when looking for per-directory configuration files.

To determine whether a directive can be configuration files overridden in the per-directory configuration file, check whether the Context: field of the directive syntax definition contains .htaccess.

Apache directives belong to different groups, specified in the Override: field in the directive syntax description. Possible values are

• AuthConfig Authorization directives

• FileInfo Directives controlling document types

• Indexes Directives controlling directory indexing

• Limit Directives controlling host access

• Options Directives controlling specific directory features

You can control which of these directive groups configuration files can appear in per-directory configuration files by using the AllowOverride directive. AllowOverride can also take an All or a None argument. All means that directives belonging to all groups can appear in the configuration file. None disables per-directory files in a directory and any of its subdirectories. Listing 3.4 shows how to disable per-directory configuration files for the server as a whole. This improves performance and is the default Apache configuration.

Listing 3.4. Disabling Per-Directory Configuration Files

1: <Directory />
2: AllowOverride none
3: </Directory>