This chapter is from the book
This chapter is from the book
This chapter is from the book
Apache Configuration File Structure
Apache keeps all 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, to a directory, or to 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.
The Apache server documentation offers a quick reference for directives at http://httpd.apache.org/docs/2.0/mod/quickreference.html. You'll soon learn about some of the basic directives, but you should supplement your knowledge using the online documentation.
The Apache documentation for directives typically follows this model:
- 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.
- 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.
- 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.
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 websites with a single Apache installation. Directives inside this container apply to a particular website. This directive accepts a domain name or IP address and an optional port as arguments. You will learn more about virtual hosts in Chapter 29, "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 (0906 for September 2006):
<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.
Example 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 /some/directory and its subdirectories. SomeDirective3 will apply to URLs referring to pages with the .html extension under the /downloads/ 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 is 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 also allow the argument to be negated. That is, directives inside a <IfDefine !MyModule> section—notice the exclamation point before the MyModule name—will be processed only if no -DMyModule parameter is passed as a command-line argument.
- <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 into Apache 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.
Example 3.2. IfDefine Example
1: <IfDefine MyModule> 2: LoadModule my_module modules/libmymodule.so 3: </IfDefine>
Example 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>
The ServerRoot Directive
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. The ServerRoot for Mac OS X users 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 filesystem. 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.
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 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 for the Override field are as follows:
- 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 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.
Example 3.4. Disabling Per-Directory Configuration Files
1: <Directory /> 2: AllowOverride none 3: </Directory>