The Apache HTTP Server configuration file is /etc/httpd/conf/httpd.conf. The httpd.conf file is well-commented and mostly self-explanatory. Its default configuration works for most situations; however, it is a good idea to become familiar some of the more important configuration options.
With the release of Apache HTTP Server 2.0, many configuration options have changed. If migrating a version 1.3 configuration file to the 2.0 format, refer to Section 10.2 Migrating Apache HTTP Server 1.3 Configuration Files.
If configuring the Apache HTTP Server, edit /etc/httpd/conf/httpd.conf and then either reload, restart, or stop and start the httpd process as outlined in Section 10.4 Starting and Stopping httpd.
Before editing httpd.conf, first make a copy the original file. Creating a backup makes it easier to recover from mistakes made while editing the configuration file.
If a mistake is made and the Web server does not work correctly, first review recently edited passages in httpd.conf to verify there are no typos.
Next look in the Web server's error log, /var/log/httpd/error_log. The error log may not be easy to interpret, depending on the level of experience. If experiencing problems, however, the last entries in the error log should provide useful information about what happened.
Next are a list of short descriptions for many of the directives included in httpd.conf. These descriptions are not exhaustive. For more information, refer to the Apache documentation provided in HTML format at http://localhost/manual/ or online at the following URL: http://httpd.apache.org/docs-2.0/.
For more information about mod_ssl directives, refer to the documentation included in HTML format at http://localhost/mod/mod_ssl.html or online at the following URL: http://httpd.apache.org/docs-2.0/mod/mod_ssl.html.
The ServerRoot is the top-level directory which contains the server's files. Both the secure server and the non-secure server set the ServerRoot directive is set to "/etc/httpd".
The ScoreBoardFile stores internal server process information, which is used for communication between the parent server process and its child processes. Red Hat Linux uses shared memory to store the ScoreBoardFile, the default of /etc/httpd/logs/apache_runtime_status is only used as a fall back.
PidFile names the file where the server records its process ID (PID). By default the PID is set in /var/run/httpd.pid.
Timeout defines, in seconds, the amount of time that the server will wait for receipts and transmissions during communications. Specifically, Timeout defines how long the server will wait to receive a GET request, how long it will wait to receive TCP packets on a POST or PUT request, and how long it will wait between ACKs responding to TCP packets. Timeout is set to 300 seconds by default, which is appropriate for most situations.
KeepAlive sets whether the server will allow more than one request per connection and can be used to prevent any one client from consuming too much of the server's resources.
By default Keepalive is set to off. If Keepalive is set to on and the server becomes very busy, the server can quickly spawn the maximum number of child processes. In this situation, the server will slow down significantly. If Keepalive is enabled, it is a good idea to set the the KeepAliveTimeout low (refer to Section 10.5.8 KeepAliveTimeout for more information about the KeepAliveTimeout directive) and monitor the /var/log/httpd/error_log log file on the server. This log reports when the server is running out of child processes.
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.
KeepAliveTimeout sets the number of seconds the server will wait after a request has been served before it closes the connection. Once the server receives a request, the Timeout directive applies instead. KeepAliveTimeout is set to 15 seconds by default.
The Apache HTTP Server dynamically adapts to the perceived load by maintaining an appropriate number of spare server processes based on the traffic. The server checks the number of servers waiting for a request and kills some if there are more than MaxSpareServers or creates some if the number of servers is less than MinSpareServers.
The default MinSpareServers value is 5; the default MaxSpareServers value is 20. These default settings should be appropriate in most situations. Be careful not to increase the MinSpareServers to a large number as doing so will create a heavy processing load on the server even when traffic is light.
StartServers sets how many server processes are created upon startup. Since the Web server dynamically kills and creates server processes based on traffic load, it is not necessary to change this parameter. The Web server is set to start eight server processes at startup.
MaxClients sets a limit on the total number of server processes, or simultaneously connected clients, that can run at one time. The main purpose of this directive is to keep a runaway Apache HTTP Server from crashing the operating system. For busy servers this value should be set to a high value. The server's default is set to 150. It is not recommended this the value for the MaxClients exceed 256.
MaxRequestsPerChild sets the total number of requests each child server process serves before the child dies. The main reason for setting MaxRequestsPerChild is to avoid long-lived process induced memory leaks. The default MaxRequestsPerChild for the server is 1000.
The Listen command identifies the ports on which the Web server will accept 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 which defines any secure servers) to port 443 for secure Web communications.
If the Apache HTTP Server is configured to listen to a port under 1024, the root user to start it. For port 1024 and above, httpd can be started as a regular user.
The Listen directive can also be used to specify particular IP addresses over which the server will accept connections.
Include allows other configuration files to be included at runtime.
The path to these configuration files can be absolute or relative to the ServerRoot.
For the server to use individually packaged modules, such as mod_ssl, mod_perl, and php, the following directive must be in Section 1: Global Environment of httpd.conf:
LoadModule is used to load in Dynamic Shared Object (DSO) modules. More information on the Apache HTTP Server's DSO support, including exactly how to use the LoadModule directive, can be found in Section 10.7 Adding Modules. Note, the load order of the modules is no longer important with Apache HTTP Server 2.0. See Section 10.2.1.3 Dynamic Shared Object (DSO) Support for more information about Apache HTTP Server 2.0 DSO support.
The 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 Section 10.5.63 Location.
The <IfDefine> and </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.
The test in the <IfDefine> tags 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 IfDefine tags are applied.
By default, <IfDefine HAVE_SSL> tags surround the virtual host tags for the secure server. <IfDefine HAVE_SSL> tags also surround the LoadModule and AddModule directives for the ssl_module.
The User directive sets the user name 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.
By default User is set to apache.
For security reasons, the Apache HTTP Server will refuse to run as the root user.
Specifies the group name of the Apache HTTP Server processes.
By default Group is set to apache.
Set the ServerAdmin directive to the email address of the Web server administrator. This email address will show up in error messages on server-generated Web pages, so users can report a problem by sending email to the server administrator.
By default, ServerAdmin is set to root@localhost.
A common way to set up ServerAdmin is to set it to firstname.lastname@example.org. Then alias webmaster to the person responsible for the Web server in /etc/aliases and run /usr/bin/newaliases.
Use ServerName to set 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.
The following is a sample ServerName directive:
When specifying a ServerName, be sure the IP address and server name pair are included in the /etc/hosts file.
When set to on, this directive configures the Apache HTTP Server to references itself using the value specified in the ServerName and Port directives. When UseCanonicalName is set to off, the server will instead use the value used by the requesting client when referring to itself.
UseCanonicalName is set to off by default.
The DocumentRoot is the directory which contains most of the HTML files which is 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:
The server looks for the following file in the default directory:
To change the DocumentRoot so that it is not shared by the secure and the non-secure Web servers, see Section 10.8 Virtual Hosts.
<Directory /path/to/directory> and </Directory> tags create what is referred to as a container and are used to enclose a group of configuration directives meant to apply only to a particular directory and its subdirectories. Any directive which is applicable to a directory may be used within <Directory> tags.
By default, very restrictive parameters are applied to the root directory (/), using the Options (see Section 10.5.25 Options) and AllowOverride (see Section 10.5.26 AllowOverride) directives. Under this configuration, any directory on the system which needs more permissive settings has to be explicitly given those settings.
In the default configuration, another Directory container is configured for the DocumentRoot which assigns less rigid parameters to the directory tree so that the Apache HTTP Server can access the files residing there.
The Directory container can be also be used to configure additional cgi-bin directories for server-side applications outside of the directory specified in the ScriptAlias directive (refer to Section 10.5.44 ScriptAlias for more information about the ScriptAlias directive).
To accomplish this, the Directory container must set the ExecCGI option for that directory.
For example, if CGI scripts are located in /home/my_cgi_directory, add the following Directory container to the httpd.conf file:
<Directory /home/my_cgi_directory> Options +ExecCGI </Directory>
Next, the AddHandler directive must be uncommented to identify files with the .cgi extension as CGI scripts. See Section 10.5.59 AddHandler for instructions on setting AddHandler.
For this to work, permissions for CGI scripts, and the entire path to the scripts, must be set to 0755.
The 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 set to only FollowSymLinks. No features are enabled, except that the server is allowed to follow symbolic links in the root directory.
By default, in the DocumentRoot directory, Options is set to include Indexes and FollowSymLinks. Indexes permits the server to generate a directory listing for a directory if no DirectoryIndex (for example, index.html) is specified. FollowSymLinks allows the server to follow symbolic links in that directory.
Options statements from the main server configuration section needs to be replicated to each VirtualHost containers individually. Refer to Section 10.5.69 VirtualHost for more information about VirtualHost containers.
The AllowOverride directive sets whether or not 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 .htaccess overrides.
The Order directive controls the order in which allow and deny directives are evaluated. The server is configured to evaluate the Allow directives before the Deny directives for the DocumentRoot directory.
Allow specifies which requester can access a given directory. The requester 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.
Deny works just like Allow, except it specifies who is denied access. The DocumentRoot is not configured to Deny requests from anyone by default.
UserDir is the name of 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.
The name for the subdirectory is set to public_html in the default configuration. For example, the server might receive the following request:
The server would look for the file:
In the above example, /home/username/ is the user's home directory (note that the default path to users' home directories may vary).
Make sure that the permissions on the users' home directories are set correctly. Users' home directories must be set to 0711. The read (r) and execute (x) bits must be set on the users' public_html directories (0755 will also work). Files that will be served in users' public_html directories must be set to at least 0644.
The 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.
When a user requests the page http://example/this_directory/, they get either the DirectoryIndex page if it exists or a server-generated directory list. The default for DirectoryIndex is index.html and the index.html.var type map. The server tries to find any one of these files, and returns the first one it finds. If it does not find any of these files and Options Indexes is 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.
AccessFileName names the file which the server should use for access control information in each directory. The default is .htaccess.
Immediately after the AccessFileName directive, a set of Files tags apply access control to any file beginning with a .ht. These directives deny Web access to any .htaccess files (or other files which begin with .ht) for security reasons.
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, disables the function and allowing proxy servers to cache documents.
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 directive.
For more information about AddType, refer to Section 10.5.58 AddType.
DefaultType sets a default content type for the Web server to use for documents whose MIME types cannot be determined. The default is text/plain.
</IfModule> tags create a conditional
container which are only activated if the specified module is
loaded. Directives contained within the IfModule
tags 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
For more information about Apache HTTP Server modules, refer to Section 10.7 Adding Modules.
HostnameLookups can be set to on, off or double. If HostnameLookups 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.
To conserve resources on the server, HostnameLookups set to off by default.
If hostnames are required in server log files, consider running one of the many log analyzer tools that perform the DNS lookups more efficiently and in bulk when rotating the Web server log files.
ErrorLog specifies the file where server errors are logged. By default, this directive is set to /var/log/httpd/error_log.
LogLevel sets how verbose the error messages in the error logs are. LogLevel can be set (from least verbose to most verbose) to emerg, alert, crit, error, warn, notice, info or debug. The default LogLevel is warn.
The 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 (see Section 10.5.41 CustomLog).
The following are the format options if the CustomLog directive is set to combined:
Lists the remote IP address of the requesting client. If HostnameLookups is set to on, the client hostname is recorded unless it is not available from DNS.
Not used. A hyphen
If authentication was required, lists the user name of the
user is recorded. Usually, this is not used, so a hyphen
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.
CustomLog identifies the log file and the log file format. By default, the log is recorded to the /var/log/httpd/access_log file.
The default CustomLog format is combined. The following illustrates the combined log file format:
remotehost rfc931 user date "request" status bytes referrer user-agent
The 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.
It to also be set to off or to EMail. EMail, adds a mailto:ServerAdmin HTML tag to the signature line of auto-generated responses.
The 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 DocumentRoot.
The 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 set to /var/www/cgi-bin/ by default.
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>
In this example, replace <old-path> with the old path information for <file-name> and <current-domain> and <current-path> with the current domain and path information for <file-name>.
In this example, any requests for <file-name> at the old location is automatically redirected to the new location.
For more advanced redirection techniques, use the mod_rewrite module included with the Apache HTTP Server. For more information about configuring the mod_rewrite module, refer to the Apache Software Foundation documentation online at http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html.
IndexOptions controls the appearance of server generated directing listings, by adding icons, file descriptions, and so on. If Options Indexes is set (see Section 10.5.25 Options), the Web server generates a directory listing when the Web server receives an HTTP request for a directory without an index.
First, the Web server looks in the requested directory for a file matching the names listed in the DirectoryIndex directive (usually, index.html). If an index.html file 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 IndexOptions directive.
The default configuration turns on FancyIndexing. This means that a user can re-sort a directory listing by clicking on column headers. Another click on the same header will switch from ascending to descending order. FancyIndexing also shows different icons for different files, based upon file extensions.
The AddDescription option, when used in conjunction with FancyIndexing, presents a short description for the file in server generated directory listings.
IndexOptions has a number of other parameters which can be set to control the appearance of server generated directories. Parameters include IconHeight and IconWidth, to make the server include HTML HEIGHT and WIDTH tags for the icons in server generated webpages; IconsAreLinks, for making the icons act as part of the HTML link anchor along with the filename and others.
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.
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 .bin or .exe extensions.
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.
When using 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 listings. The AddDescription directive supports listing specific files, wildcard expressions, or file extensions.
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 try to include it as plain text. By default, ReadmeName is set to README.html.
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.
IndexIgnore lists file extensions, partial file names, wildcard expressions or full filenames. The Web server will not include any files which match any of those parameters in server generated directory listings.
AddEncoding names filename 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.
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.
LanguagePriority sets precedence for different languages in case the client Web browser has no language preference set.
Use the AddType directive to define MIME type and file extension pairs. For example, using PHP4, use the AddType directive to make the Web server recognize with PHP file extensions (.php4, .php3 .phtml .php) as PHP MIME types. The following directive tells the Apache HTTP Server to recognize the .shtml file extension:
AddType text/html .shtml AddHandler server-parsed .shtml
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 .cgi extension.
AddHandler cgi-script .cgi
This directive enables CGIs outside of the cgi-bin to function in any directory on the server which has the ExecCGI option within the directories container. Refer to Section 10.5.24 Directory for more information about setting the ExecCGI option for a directory.
In addition to CGI scripts, the AddHandler directive is used to process server-parsed HTML and image-map files.
Action specifies a MIME content type and CGI script pair, so that whenever a file of that media type is requested, a particular CGI script is executed.
The 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 redirects the client to a local or external URL.
In order to be valid, the message must be enclosed in a pair of
The 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.
The <Location> and </Location> tags create a container in which access control based on URL can be specified.
For instance, to allow people connecting from within the server's domain to see status reports, use the following directives:
<Location /server-status> SetHandler server-status Order deny,allow Deny from all Allow from <.example.com> </Location>
Replace <.example.com> with the second-level domain name for the Web server.
To provide server configuration reports (including installed modules and configuration directives) to requests from inside the domain, use the following directives:
<Location /server-info> SetHandler server-info Order deny,allow Deny from all Allow from <.example.com> </Location>
Again, replace <.example.com> with the second-level domain name for the Web server.
To configure the Apache HTTP Server to function as a proxy server, remove the hash marks from the beginning of the <IfModule mod_proxy.c> line to load the mod_proxy module and set the ProxyRequests directive to On.
<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 applicable to a directory may be used within <Proxy> tags.
The ProxyVia command controls whether or not an HTTP Via: header line is sent along with requests or replies which go through the Apache proxy server. The Via: header shows the hostname if ProxyVia is set to On, shows the hostname and the Apache HTTP Server version for Full, passes along any Via: lines unchanged for Off, and Via: lines are removed for Block.
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
CacheRoot — Specifies the name of the directory containing cached files. The default CacheRoot is the /var/httpd/proxy/ directory.
CacheSize — Specifies how much space the cache can use in kilobytes. The default CacheSize is 5 KB.
CacheGcInterval — Specifies the number of hours which must pass before files in the cache are deleted. The default for CacheGcInterval is 4 hours.
CacheMaxExpire — Specifies how long HTML documents are retained (without a reload from the originating Web server) in the cache. The default is 24 hours.
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 CacheLastModifiedFactor is 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 1 hour.
NoCache — Specifies a list of hosts whose content is not cached.
The 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.
Name-based virtual hosts only work with non-secure HTTP connections. If using virtual hosts with a secure server, use IP address-based virtual hosts instead.
To enable name-based virtual hosting, uncomment the NameVirtualHost configuration directive and add the correct IP address. Then add more VirtualHost containers for each virtual host.
<VirtualHost> and </VirtualHost> tags create a container outlining the characteristics of a virtual host. The <VirtualHost> container accepts most configuration directives.
A set of commented VirtualHost container is provided in httpd.conf, which illustrates the minimum set of configuration directives necessary for each virtual host. Refer to Section 10.8 Virtual Hosts for more information about virtual hosts.
All SSL virtual host containers have been moved into the file /etc/httpd/conf.d/ssl.conf.
The SSL directives in /etc/httpd/conf.d/ssl.conf file can be configured to enable secure Web communications using SSL and TLS.
SetEnvIf sets environment variables based on the headers of incoming secure connections. In the supplied /etc/httpd/conf.d/ssl.conf file, it is used to disable HTTP keepalive and to allow SSL to close the connection without a close notify alert from the client browser. This setting is necessary for certain browsers that do not reliably shut down the SSL connection.
For more information on SSL directives, direct a Web browser to either of the following addresses:
For information about setting up an Apache HTTP Secure Server see the chapter titled Apache HTTP Secure Server Configuration in the Red Hat Linux Customization Guide.
In most cases, the SSL directives are configured appropriately as installed. Be cautious when altering Apache HTTP Secure Server directives as misconfiguration can lead to security vulnerabilities.