25.5. Configuration Directives in httpd.conf
httpd.conffile is well-commented and mostly self-explanatory. The default configuration works for most situations; however, it is a good idea to become familiar some of the more important configuration options.
25.5.1. General Configuration Tips
/etc/httpd/conf/httpd.confand then either reload, restart, or stop and start the
httpdprocess as outlined in Section 25.3, “Starting and Stopping
httpd.conf, make a copy the original file. Creating a backup makes it easier to recover from mistakes made while editing the configuration file.
httpd.confto verify there are no typos.
/var/log/httpd/error_log. The error log may not be easy to interpret, depending on your level of expertise. However, the last entries in the error log should provide useful information.
httpd.conf. These descriptions are not exhaustive. For more information, refer to the Apache documentation online at http://httpd.apache.org/docs/2.2/.
mod_ssldirectives, refer to the documentation online at http://httpd.apache.org/docs/2.2/mod/mod_ssl.html.
AccessFileName names the file which the server should use for access control information in each directory. The default is
AccessFileNamedirective, a set of
Filestags apply access control to any file beginning with a
.ht. These directives deny Web access to any
.htaccessfiles (or other files which begin with
.ht) for security reasons.
Action specifies a MIME content type and CGI script pair, so that when a file of that media type is requested, a particular CGI script is executed.
FancyIndexing as an
IndexOptions parameter, the
AddDescription directive can be used to display user-specified descriptions for certain files or file types in a server generated directory listing. The
AddDescription directive supports listing specific files, wildcard expressions, or file extensions.
AddEncoding names file name extensions which should specify a particular encoding type.
AddEncoding can also be used to instruct some browsers to uncompress certain files as they are downloaded.
AddHandler maps file extensions to specific handlers. For example, the
cgi-script handler can be matched with the extension
.cgi to automatically treat a file ending with
.cgi as a CGI script. The following is a sample
AddHandler directive for the
AddHandler cgi-script .cgi
cgi-binto function in any directory on the server which has the
ExecCGIoption within the directories container. Refer to Directory for more information about setting the
ExecCGIoption for a directory.
AddHandlerdirective is used to process server-parsed HTML and image-map files.
AddIcon specifies which icon to show in server generated directory listings for files with certain extensions. For example, the Web server is set to show the icon
binary.gif for files with
This directive names icons which are displayed by files with MIME encoding in server generated directory listings. For example, by default, the Web server shows the
compressed.gif icon next to MIME encoded x-compress and x-gzip files in server generated directory listings.
This directive names icons which are displayed next to files with MIME types in server generated directory listings. For example, the server shows the icon
text.gif next to files with a mime-type of
text, in server generated directory listings.
AddLanguage associates file name extensions with specific languages. This directive is useful for Apache HTTP Servers which serve content in multiple languages based on the client Web browser's language settings.
AddType directive to define or override a default MIME type and file extension pairs. The following example directive tells the Apache HTTP Server to recognize the
.tgz file extension:
AddType application/x-tar .tgz
Alias setting allows directories outside the
DocumentRoot directory to be accessible. Any URL ending in the alias automatically resolves to the alias' path. By default, one alias for an
icons/ directory is already set up. An
icons/ directory can be accessed by the Web server, but the directory is not in the
Allow specifies which client can access a given directory. The client can be
all, a domain name, an IP address, a partial IP address, a network/netmask pair, and so on. The
DocumentRoot directory is configured to
Allow requests from
all, meaning everyone has access.
AllowOverride directive sets whether any
Options can be overridden by the declarations in an
.htaccess file. By default, both the root directory and the
DocumentRoot are set to allow no
BrowserMatch directive allows the server to define environment variables and take appropriate actions based on the User-Agent HTTP header field — which identifies the client's Web browser type. By default, the Web server uses
BrowserMatch to deny connections to specific browsers with known problems and also to disable keepalives and HTTP header flushes for browsers that are known to have problems with those actions.
A number of commented cache directives are supplied by the default Apache HTTP Server configuration file. In most cases, uncommenting these lines by removing the hash mark (
#) from the beginning of the line is sufficient. The following, however, is a list of some of the more important cache-related directives.
CacheEnable— Specifies whether the cache is a disk, memory, or file descriptor cache. By default
CacheEnableconfigures a disk cache for URLs at or below
CacheRoot— Specifies the name of the directory containing cached files. The default
CacheSize— Specifies how much space the cache can use in kilobytes. The default
CacheMaxExpire— Specifies how long HTML documents are retained (without a reload from the originating Web server) in the cache. The default is
CacheLastModifiedFactor— Specifies the creation of an expiry (expiration) date for a document which did not come from its originating server with its own expiry set. The default
CacheLastModifiedFactoris set to
0.1, meaning that the expiry date for such documents equals one-tenth of the amount of time since the document was last modified.
CacheDefaultExpire— Specifies the expiry time in hours for a document that was received using a protocol that does not support expiry times. The default is set to
NoProxy— Specifies a space-separated list of subnets, IP addresses, domains, or hosts whose content is not cached. This setting is most useful for Intranet sites.
By default, the Web server asks proxy servers not to cache any documents which were negotiated on the basis of content (that is, they may change over time or because of the input from the requester). If
CacheNegotiatedDocs is set to
on, this function is disabled and proxy servers are allowed to cache such documents.
CustomLog identifies the log file and the log file format. By default, the access log is recorded to the
/var/log/httpd/access_log file while errors are recorded in the
CustomLogformat is the
combinedlog file format, as illustrated here:
remotehost rfc931 user date "request" status bytes referrer user-agent
DefaultIcon specifies the icon displayed in server generated directory listings for files which have no other icon specified. The
unknown.gif image file is the default.
DefaultType sets a default content type for the Web server to use for documents whose MIME types cannot be determined. The default is
Deny works similar to
Allow, except it specifies who is denied access. The
DocumentRoot is not configured to
Deny requests from anyone by default.
<Directory /path/to/directory> and
</Directory> tags create a container used to enclose a group of configuration directives which apply only to a specific directory and its subdirectories. Any directive which is applicable to a directory may be used within
/), using the
Options(refer to Options) and
AllowOverride(refer to AllowOverride) directives. Under this configuration, any directory on the system which needs more permissive settings has to be explicitly given those settings.
Directorycontainer is configured for the
DocumentRootwhich assigns less rigid parameters to the directory tree so that the Apache HTTP Server can access the files residing there.
Directorycontainer can be also be used to configure additional
cgi-bindirectories for server-side applications outside of the directory specified in the
ScriptAliasdirective (refer to ScriptAlias for more information).
Directorycontainer must set the
ExecCGIoption for that directory.
/home/my_cgi_directory, add the following
Directorycontainer to the
<Directory /home/my_cgi_directory> Options +ExecCGI </Directory>
AddHandlerdirective must be uncommented to identify files with the
.cgiextension as CGI scripts. Refer to AddHandler for instructions on setting
DirectoryIndex is the default page served by the server when a user requests an index of a directory by specifying a forward slash (/) at the end of the directory name.
DirectoryIndexpage, if it exists, or a server-generated directory list. The default for
index.html.vartype map. The server tries to find either of these files and returns the first one it finds. If it does not find one of these files and
Options Indexesis set for that directory, the server generates and returns a listing, in HTML format, of the subdirectories and files within the directory, unless the directory listing feature is turned off.
DocumentRoot is the directory which contains most of the HTML files which are served in response to requests. The default
DocumentRoot, for both the non-secure and secure Web servers, is the
/var/www/html directory. For example, the server might receive a request for the following document:
DocumentRootso that it is not shared by the secure and the non-secure Web servers, refer to Section 25.7, “Virtual Hosts”.
ErrorDocument directive associates an HTTP response code with a message or a URL to be sent back to the client. By default, the Web server outputs a simple and usually cryptic error message when an error occurs. The
ErrorDocument directive forces the Web server to instead output a customized message or page.
ErrorLog specifies the file where server errors are logged. By default, this directive is set to
ExtendedStatus directive controls whether Apache generates basic (
off) or detailed server status information (
on), when the
server-status handler is called. The
server-status handler is called using
Location tags. More information on calling
server-status is included in Location.
Groupis set to
HeaderName names the file which, if it exists in the directory, is prepended to the start of server generated directory listings. Like
ReadmeName, the server tries to include it as an HTML document if possible or in plain text if not.
HostnameLookups can be set to
HostnameLookups is set to
on, the server automatically resolves the IP address for each connection. Resolving the IP address means that the server makes one or more connections to a DNS server, adding processing overhead. If
HostnameLookups is set to
double, the server performs a double-reverse DNS look up adding even more processing overhead.
HostnameLookupsis set to
IfDefine tags surround configuration directives that are applied if the "test" stated in the
IfDefine tag is true. The directives are ignored if the test is false.
IfDefinetags is a parameter name (for example,
HAVE_PERL). If the parameter is defined, meaning that it is provided as an argument to the server's start-up command, then the test is true. In this case, when the Web server is started, the test is true and the directives contained in the
IfDefinetags are applied.
</IfModule> tags create a conditional container which are only activated if the specified module is loaded. Directives within the
IfModule container are processed under one of two conditions. The directives are processed if the module contained within the starting
<IfModule> tag is loaded. Or, if an exclamation point ! appears before the module name, the directives are processed only if the module specified in the
<IfModule> tag is not loaded.
php, the following directive must be included in
Section 1: Global Environmentof
IndexIgnore lists file extensions, partial file names, wildcard expressions, or full file names. The Web server does not include any files which match any of those parameters in server generated directory listings.
IndexOptions controls the appearance of server generated directing listings, by adding icons, file descriptions, and so on. If
Options Indexes is set (refer to Options), the Web server generates a directory listing when the Web server receives an HTTP request for a directory without an index.
index.html). If an
index.htmlfile is not found, Apache HTTP Server creates an HTML directory listing of the requested directory. The appearance of this directory listing is controlled, in part, by the
FancyIndexing. This means that a user can re-sort a directory listing by clicking on column headers. Another click on the same header switches from ascending to descending order.
FancyIndexingalso shows different icons for different files, based upon file extensions.
AddDescriptionoption, when used in conjunction with
FancyIndexing, presents a short description for the file in server generated directory listings.
IndexOptionshas a number of other parameters which can be set to control the appearance of server generated directories. The
IconWidthparameters require the server to include HTML
WIDTHtags for the icons in server generated webpages. The
IconsAreLinksparameter combines the graphical icon with the HTML link anchor, which contains the URL link target.
KeepAlive sets whether the server allows more than one request per connection and can be used to prevent any one client from consuming too much of the server's resources.
Keepaliveis set to
Keepaliveis set to
onand the server becomes very busy, the server can quickly spawn the maximum number of child processes. In this situation, the server slows down significantly. If
Keepaliveis enabled, it is a good idea to set the
KeepAliveTimeoutlow (refer to KeepAliveTimeout for more information about the
KeepAliveTimeoutdirective) and monitor the
/var/log/httpd/error_loglog file on the server. This log reports when the server is running out of child processes.
KeepAliveTimeout sets the number of seconds the server waits after a request has been served before it closes the connection. Once the server receives a request, the
Timeout directive applies instead. The
KeepAliveTimeout directive is set to 15 seconds by default.
LanguagePriority sets precedence for different languages in case the client Web browser has no language preference set.
Listen command identifies the ports on which the Web server accepts incoming requests. By default, the Apache HTTP Server is set to listen to port 80 for non-secure Web communications and (in the
/etc/httpd/conf.d/ssl.conf file which defines any secure servers) to port 443 for secure Web communications.
httpdcan be started as a regular user.
Listendirective can also be used to specify particular IP addresses over which the server accepts connections.
LoadModule is used to load Dynamic Shared Object (DSO) modules. More information on the Apache HTTP Server's DSO support, including instructions for using the
LoadModule directive, can be found in Section 25.6, “Adding Modules”. Note, the load order of the modules is no longer important with Apache HTTP Server 2.0. Refer to Section 126.96.36.199.3, “Dynamic Shared Object (DSO) Support” for more information about Apache HTTP Server 2.0 DSO support.
</Location> tags create a container in which access control based on URL can be specified.
<Location /server-status> SetHandler server-status Order deny,allow Deny from all Allow from <.example.com> </Location>
<Location /server-info> SetHandler server-info Order deny,allow Deny from all Allow from <.example.com> </Location>
LogFormat directive configures the format of the various Web server log files. The actual
LogFormat used depends on the settings given in the
CustomLog directive (refer to CustomLog).
CustomLogdirective is set to
%h(remote host's IP address or hostname)
- Lists the remote IP address of the requesting client. If
HostnameLookupsis set to
on, the client hostname is recorded unless it is not available from DNS.
- Not used. A hyphen - appears in the log file for this field.
- Lists the username of the user recorded if authentication was required. Usually, this is not used, so a hyphen - appears in the log file for this field.
- Lists the date and time of the request.
- Lists the request string exactly as it came from the browser or client.
- Lists the HTTP status code which was returned to the client host.
- Lists the size of the document.
- Lists the URL of the webpage which referred the client host to Web server.
- Lists the type of Web browser making the request.
LogLevel sets how verbose the error messages in the error logs are.
LogLevel can be set (from least verbose to most verbose) to
debug. The default
This directive sets the maximum number of requests allowed per persistent connection. The Apache Project recommends a high setting, which improves the server's performance.
MaxKeepAliveRequests is set to
100 by default, which should be appropriate for most situations.
NameVirtualHost directive associates an IP address and port number, if necessary, for any name-based virtual hosts. Name-based virtual hosting allows one Apache HTTP Server to serve different domains without using multiple IP addresses.
NameVirtualHostconfiguration directive and add the correct IP address. Then add additional
VirtualHostcontainers for each virtual host as is necessary for your configuration.
Options directive controls which server features are available in a particular directory. For example, under the restrictive parameters specified for the root directory,
Options is only set to the
FollowSymLinks directive. No features are enabled, except that the server is allowed to follow symbolic links in the root directory.
Optionsis set to include
Indexespermits the server to generate a directory listing for a directory if no
index.html) is specified.
FollowSymLinksallows the server to follow symbolic links in that directory.
Optionsstatements from the main server configuration section need to be replicated to each
VirtualHostcontainer individually. Refer to VirtualHost for more information.
Order directive controls the order in which
deny directives are evaluated. The server is configured to evaluate the
Allow directives before the
Deny directives for the
PidFile names the file where the server records its process ID (PID). By default the PID is listed in
<Proxy *> and
</Proxy> tags create a container which encloses a group of configuration directives meant to apply only to the proxy server. Many directives which are allowed within a
<Directory> container may also be used within
To configure the Apache HTTP Server to function as a proxy server, remove the hash mark (
#) from the beginning of the
<IfModule mod_proxy.c> line, the ProxyRequests, and each line in the
<Proxy> stanza. Set the
ProxyRequests directive to
On, and set which domains are allowed access to the server in the
Allow from directive of the
ReadmeName names the file which, if it exists in the directory, is appended to the end of server generated directory listings. The Web server first tries to include the file as an HTML document and then tries to include it as plain text. By default,
ReadmeName is set to
When a webpage is moved,
Redirect can be used to map the file location to a new URL. The format is as follows:
Redirect /<old-path>/<file-name> http://<current-domain>/<current-path>/<file-name>
mod_rewritemodule included with the Apache HTTP Server. For more information about configuring the
mod_rewritemodule, refer to the Apache Software Foundation documentation online at http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html.
ScriptAlias directive defines where CGI scripts are located. Generally, it is not good practice to leave CGI scripts within the
DocumentRoot, where they can potentially be viewed as text documents. For this reason, a special directory outside of the
DocumentRoot directory containing server-side executables and scripts is designated by the
ScriptAlias directive. This directory is known as a
cgi-bin and is set to
/var/www/cgi-bin/ by default.
cgi-bin/directory. For instructions on doing so, refer to AddHandler and Directory.
ServerAdmin directive to the email address of the Web server administrator. This email address shows up in error messages on server-generated Web pages, so users can report a problem by sending email to the server administrator.
ServerAdminis set to
ServerAdminis to set it to
email@example.com. Once set, alias
webmasterto the person responsible for the Web server in
ServerName specifies a hostname and port number (matching the
Listen directive) for the server. The
ServerName does not need to match the machine's actual hostname. For example, the Web server may be
www.example.com, but the server's hostname is actually
foo.example.com. The value specified in
ServerName must be a valid Domain Name Service (DNS) name that can be resolved by the system — do not make something up.
ServerName, be sure the IP address and server name pair are included in the
ServerRoot directive specifies the top-level directory containing website content. By default,
ServerRoot is set to
"/etc/httpd" for both secure and non-secure servers.
ServerSignature directive adds a line containing the Apache HTTP Server server version and the
ServerName to any server-generated documents, such as error messages sent back to clients.
ServerSignature is set to
on by default.
ServerSignaturecan be set to
mailto:ServerAdminHTML tag to the signature line of auto-generated responses.
ServerSignaturecan also be set to
Offto stop Apache from sending out its version number and module information. Please also check the
ServerTokens directive determines if the Server response header field sent back to clients should include details of the Operating System type and information about compiled-in modules. By default,
ServerTokens is set to
Full which sends information about the Operating System type and compiled-in modules. Setting the
Prod sends the product name only and is recommended as many hackers check information in the Server header when scanning for vulnerabilities. You can also set the
Min (minimal) or to
OS (operating system).
SuexecUserGroup directive, which originates from the
mod_suexec module, allows the specification of user and group execution privileges for CGI programs. Non-CGI requests are still processed with the user and group specified in the
SuexecUserGroupdirective replaced the Apache HTTP Server 1.3 configuration of using the
Groupdirectives inside the configuration of
Timeout defines, in seconds, the amount of time that the server waits for receipts and transmissions during communications.
Timeout is set to
300 seconds by default, which is appropriate for most situations.
TypesConfig names the file which sets the default list of MIME type mappings (file name extensions to content types). The default
TypesConfig file is
/etc/mime.types. Instead of editing
/etc/mime.types, the recommended way to add MIME type mappings is to use the
AddType, refer to AddType.
When set to
on, this directive configures the Apache HTTP Server to reference itself using the value specified in the
Port directives. When
UseCanonicalName is set to
off, the server instead uses the value used by the requesting client when referring to itself.
UseCanonicalNameis set to
User directive sets the username of the server process and determines what files the server is allowed to access. Any files inaccessible to this user are also inaccessible to clients connecting to the Apache HTTP Server.
Useris set to
UserDir is the subdirectory within each user's home directory where they should place personal HTML files which are served by the Web server. This directive is set to
disable by default.
public_htmlin the default configuration. For example, the server might receive the following request:
/home/username/is the user's home directory (note that the default path to users' home directories may vary).
public_htmldirectories (0755 also works). Files that are served in a users'
public_htmldirectories must be set to at least 0644.
</VirtualHost> tags create a container outlining the characteristics of a virtual host. The
VirtualHost container accepts most configuration directives.
VirtualHostcontainer is provided in
httpd.conf, which illustrates the minimum set of configuration directives necessary for each virtual host. Refer to Section 25.7, “Virtual Hosts” for more information about virtual hosts.