The directives discussed in this section are fundamental in nature and generally apply to both the primary server (server config context)and the virtual servers (virtual host context).
AccessFileName
The AccessFileNamedirective specifies the name of the per-directory access con-trol file. The default setting (.htaccess) makes Apache look for the .htaccessfile each time an access request is made by a client system.
Syntax: AccessFileName filename [filename ...]
Default setting: AccessFileName .htaccess Context: Server config, virtual host
For example, say that the DocumentRootdirective of an Apache-powered Web site called www.mycompany.comis set as DocumentRoot “/www/mycompany/public/
htdocs”and a Web browser requests http://www.mycompany.com/feedback.
html. This causes Apache to search for the following access control files:
✦/.htaccess
✦/www/.htaccess
✦/www/mycompany/.htaccess
✦/www/mycompany/public/.htaccess
✦/www/mycompany/public/htdocs/.htaccess
Only after Apache has checked for all of these files does it look for the
feedback.htmlfile. If this seems like a lot of disk I/O, it is! You can avoid all that nonsense by specifying the access filename with this directive.
Note
If you do not make use of the per-directory access control file and would like Apache to stop checking for it, simply use the <Directory>directive to disable privileges to override options as follows:
<Directory />
AllowOverride None
</Directory>
See the sections on the <Directory>container and the AllowOverride direc-tive in this chapter for more details.
AddDefaultCharset
The AddDefaultCharsetdirective sets the default character set for the Content-Type header sent to the browser by Apache.
Syntax: AddDefaultCharset On | Off | charset Default setting: AddDefaultCharset Off
Context:All
When this directive is turned on (using Onoption), Apache sends iso-8859-1 (Western European)as the default character set unless you specify a character set as the second option to this directive. For example, AddDefaultCharset On utf-8will send UTF-8as the default character set. Commonly used character sets include:
✦ISO-8859-1 — Western European
✦ISO-8859-15 — Western European with Euro currency symbol support
✦Windows-1252 — Western European
✦CP850 — Western European
✦UTF-8 — 8-bit Unicode
✦UTF-7 — 7-bit Unicode
If your HTML documents set the character set by using <META http-equiv=”Content-Type” content=”content_type; charset=charac-ter_set_name”> tag, the AddDefaultCharset directive enables you to override it.
ContentDigest
When the ContentDigestdirective is set, it generates a message digest (MD5) header for the entire content of the body, which enables the Web client to verify the integrity of the page. This is a major performance drag for the Web server because MD5 digests need to be computed on each static page served by the Web server.
Note Tip
Note that this digest is not generated for any output generated by any module other than the core. This means that Common Gateway Interface (CGI) output cannot use this feature. Because of the performance drain on the server, it is not a recommended feature unless you know your server has the power to spare.
Syntax: ContentDigest On | Off Default setting: ContentDigest Off Context: All
DefaultType
The DefaultTypedirective is used to establish a default content type, so when Apache receives a request for a document whose file type is unknown (in other words, it cannot be determined from the MIME-type map available to the server), it uses the predetermined default type.
Syntax: DefaultType mime-type
Default setting: DefaultType text/html Context: All
Override: FileInfo
For example, if you have a directory in which you keep a lot of text files with no extensions, you can use the DefaultTypedirective inside a <Directory>container that points to this directory. In this case, setting DefaultTypeto text/plain enables the server to tell the other side (the Web browser) that these are plain-text files. Here’s an example:
<Directory /www/mycompany/public/htdocs/plaindata>
DefaultType plain/text
</Directory>
Here, all the files in the /www/mycompany/public/htdocs/plaindata/directory are treated as plain-text files.
DocumentRoot
The DocumentRootdirectory specified by this directive becomes the top-level directory for all the documents serviced by Apache.
Syntax: DocumentRoot “directory_path”
Default setting: DocumentRoot “/usr/local/apache/htdocs”
Context: Server config, virtual host
For example, if
DocumentRoot “/www/mycompany/public/htdocs”
is set for the serverwww.mycompany.com, then an access request for www.mycompany.
com/corporate.htmlmakes the server look for the following file:
/www/mycompany/public/htdocs/corporate.html
If the file is found, it is returned to the client (that is, the Web browser).
A bug in the mod_dirmodule causes a problem when the DocumentRoothas a trailing slash (for example, DocumentRoot /usr/web/), so you should avoid entering a /character at the end of any path for any directive.
It is possible to have the server look for files in a directory outside the DocumentRoot directory. If you want to access some files outside the DocumentRoottree, you can use the Aliasdirective to create a virtual directory name that can point to a physical directory anywhere in your server’s file system.
ErrorDocument
When the server encounters a problem, it generates a standard error message with the error code in it. This is not very user-friendly for most people, however, so a more customized version of the error message, or possibly a recovery measure, is more desirable. If you need such customization, use the ErrorDocumentdirective to override standard error messages.
Syntax: ErrorDocument error_code [filename | error_message | URL]
Default setting: None Context: All
Override: FileInfo
The directive requires two arguments. The first argument is the standard HTTP error code, which you can find in Appendix A; the second argument is the action item for the error. Depending on your needs, you can define what action you want the server to take for a particular error condition.
For example, if you want to provide a custom message for all requests that result in a standard “file not found” message, all you have to do is find the server status code for that error condition and use the ErrorDocumentdirective. Because the server status code for missing files is 404, the following directive setting enables Apache to display a custom message:
ErrorDocument 404 “Sorry, this is an invalid request because %s “ Tip
Note
Notice that the entire message is quoted, and the server replaces %swith whatever information is available regarding the error. If you find this a bit limiting, however, you can use a file as your error message response. For example:
ErrorDocument 404 /errors/404.html
Whenever the missing file error occurs, the 404.htmlfile found in the errors direc-tory under the DocumentRootdirectory is returned to the client (the Web browser).
If you want to do more than just return a static page, you can use a CGI script to perform some specific action. In such a case, you replace the filename with a call to your CGI script:
ErrorDocument 404 /cgi-bin/missingurl.cgi
This calls a CGI script called missingurl.cgievery time a 404 error occurs. You can also redirect the client to another site using a URL instead of a filename:
ErrorDocument 404 http://www.newsite.com/we.moved.html This can be used when a page or an entire site has moved to another location.
You cannot point the client to a remote server if an error 401 (unauthorized) occurs. The value of this directive must be a local file or a message.
<IfDefine>
The IfDefinecontainer directive enables you to create a conditional configura-tion. The special_command_line_paramoption is specified by using the -Doption with the httpdprogram.
Syntax: <IfDefine [!]special_command_line_param> ... </IfDefine>
Default setting: None Context: All
For example, if you run the Apache server from the bindirectory as ./httpd -D somethingthen you can use:
<IfDefine something>
# #directives that should be executed only when
# -D something is specified
</IfDefine>
Placing a !character in front of the special_command_line_paramtells Apache to process the directives within the IfDefine container only when a -D somethingwas not found in the command-line. For example:
<IfDefine !something>
# directives that should be executed only when
# -D something is NOT specified
</IfDefine>
Note Note Tip
<IfModule>
Use the IfModulecontainer directive if you have directives that are available from a custom module that may not always be present in your Apache installation.
Syntax: <IfModule [!]module_name> ... </IfModule>
Default setting: None Context:All
For example, if you want to use certain directives only if a module is available, then you can use the following conditional construct:
<IfModule module_name>
# Assign the following directives their respective value
# if the module is part of Apache.
# Your directives go here.
</IfModule>
where the module_nameargument is the filename of the module at the time it was compiled (for example, mod_rewrite.c).
If you need a conditional statement that is the exact opposite of the above, all you need to do is insert a !(bang or exclamation point) before the module name.
<IfModule>sections are nestable; this is a method that can be used to implement simple multiple-module condition tests. For example:
<IfModule module_A>
# Process the directives here if module A is
# part of Apache
<IfModule module_B>
# Come here only if module A and B both
# are part of Apache
<IfModule ! module_C>
# Come here only if module A and B exists
# but not module C as part of Apache
</IfModule>
</IfModule>
</IfModule>
Include
The Include directive enables you to include an external file as a configuration file.
Syntax: Include filename Default setting: None Context: Server config
For example, if you want to load all your virtual host configurations using external files, you can have the following configuration in httpd.conf:
NameVirtualHost IP_Address Include virtual_host_1.conf Include virtual_host_2.conf Include virtual_host_3.conf ...
Include virtual_host_N.conf
In each of these files you can define a <VirtualHost>container specific to the host. This is a good way of organizing the httpd.conf file if you have a lot of virtual hosts.
Options
The Optionsdirective controls which server features are available in a particular directory.
Syntax: Options [+|-]option [+|-]option ...
Default setting: None Context: All
Override: Options (see Table 4-1)
When this directive is set to None, none of the extra features are enabled for the context in which the directive is used.
All the possible settings for this directive are listed in Table 4-1.
Note Tip