Basic Server Configuration: Core Directives (Webmaster in a Nutshell, 3rd Edition)

AccessConfig

AccessConfig filename

[server config or within <VirtualHost>]

Specifies the location of the access configuration file, either as an absolute path (with a beginning slash) or as a relative path from the ServerRoot directory. For example:

AccessConfig conf/access.conf

AccessFileName

AccessFileName filename filename ...

[server config or within <VirtualHost>]

Specifies the names of one or more per-directory access control files. The default is:

AccessFileName .htaccess

AllowOverride

AllowOverride options ...

[Within <Directory>]

Controls the extent to which local per-directory .htaccess files can override the defaults defined by access control files in higher directories. The directive takes one or more options, which can be:

None: Access control files are unrecognized in this directory.
All: Access control files are unrestricted in this directory.
Options: Allow use of the Options and XBitHack directives.
Indexes: Allow use of directory indexing directives (FancyIndexing, AddIcon, and AddDescription, etc.).
FileInfo: Allow use of the directive relating to document type: (AddType, AddEncoding, AddLanguage, etc.).
AuthConfig: Allow use of these directives: require, AuthName, AuthType, AuthUserFile, AuthGroupFile, or any other Auth* directives.
Limit: Allow use of the allow, deny, and order directives.

If omitted, the default is:

AllowOverride All

AuthName

AuthName name

[Within <Directory> or .htaccess]

Sets the name of the username/password authorization realm for this directory. The value is a short name describing this authorization realm; it can contain spaces.

AuthType

AuthType type

[Within <Directory> or .htaccess]

Sets the type of authorization used in this directory. Basic authorization is the most commonly used method. If used, this directive should be followed by AuthName, require, AuthGroupFile, and AuthUserFile directives, which better describe the authorization realm.

ContentDigest

ContentDigest on|off

Computes an MD5 (Message Digest 5) hash of the body content of core data sent to the client. This value is stored in a header that looks like:

Content-MD5: AyTr28784eSp2k67d98n28a=

The receiver can use this hash value to determine whether the contents of the page have been altered in transit. The hash values are not cached for each page sent; hence, they must be recalculated each time data is requested.

DefaultType

DefaultType mime_type

Establishes a default MIME type to be returned to a browser if mappings in the mime.types file fail to successfully identify a document or file type. The default is text/html.

<Directory>

<Directory>...</Directory>

[server config or within <VirtualHost>]

<Directory> is a sectioning directive that identifies the directory (and its subdirectories) to which contained access-control directives apply. This directive cannot be used in a per-directory .htaccess file. The start tag has this format:

<Directory dir>

where dir is the absolute pathname of the directory. You can include wildcard characters (such as * and ?) to designate a set of directories or even use regular expressions if preceded by a tilde (~).

<DirectoryMatch>

<DirectoryMatch>...</DirectoryMatch>

[server config or within <VirtualHost>]

<DirectoryMatch> is a sectioning directive that identifies the directory (and subdirectories) to which contained access-control directives apply. It cannot be used in a per-directory .htaccess file. The start tag has this format:

<DirectoryMatch regex>

where regex is a regular expression that designates one or more directories the enclosed directives apply to.

DocumentRoot

DocumentRoot directory_path

[server config or within <VirtualHost>]

Specifies the root of the server document tree. For example:

DocumentRoot /usr/local/etc/httpd/htdocs/

This specifies that HTML documents for this server will reside in the given directory and its subdirectories. The default is:

DocumentRoot /usr/local/apache/htdocs/

ErrorDocument

ErrorDocument code filename|string|URL

Allows you to customize the response sent by your server when an error is encountered. The error code is an HTTP status code as listed in Chapter 17. Possible values are:

filename .25i: A local file to return upon encountering this error
string .25i: A message to return upon encountering this error; the string must be surrounded by quotes
URL .25i: A local or remote document to redirect the user to upon encountering this error

Example usage:

ErrorDocument 404 /errors/notfound.html
ErrorDocument 408 "Sorry, the server timed out
 - try again later"
ErrorDocument 402 http://www.oreilly.com/payment/

ErrorLog

ErrorLog filename

[server config or within <VirtualHost>]

Specifies the location of the error log file, either an absolute path or relative path to the ServerRoot directory if an opening slash (/) is omitted. The default setting is:

ErrorLog logs/error_log

Beginning with Apache 1.3, you can specify syslog if the system supports logging via syslogd.

<Files>

<Files>...</Files>

The <Files> directive is a sectioning directive that identifies the file or files to which contained access-control directives apply. The start tag has this format:

<Files filename>

where filename is the name of any file that should have restrictions placed on it. Note that filename may include wildcard characters (such as * and ?) to designate a set of files. In addition, you may place it inside a <Directory> directive to further restrict which files are affected. You can also specify regular expressions by preceding them with a tilde (~).

<FilesMatch>

<FilesMatch>...</FilesMatch>

The <FilesMatch> directive is a sectioning directive that identifies the file or files to which contained access-control directives apply. The start tag has the following format:

<FilesMatch regex>

where regex is a regular expression that designates one or more files the enclosed directives apply to. Note that you may place this directive inside a <Directory> directive to further restrict which files are affected.

Group

Group groupname

[server config or within <VirtualHost>]

Specifies the group you want the server to process requests as. Either a group name or group ID can be specified; a group ID should be preceded by a hash mark (#). Setting this option to the same group as the superuser (i.e., root) is highly discouraged. Many administrators use the group nobody for the Apache server.

HostNameLookups

HostNameLookups on|off|double

[server config, within <VirtualHost> or <Directory>]

Enables whether the server should perform hostname lookups on clients instead of simply recording the IP address in the connection logs. If the double option is specified, the server performs a forward and reverse DNS lookup; this ensures the client hostname maps to its IP, as well as the IP mapping to the DNS name. The default is off.

IdentityCheck

IdentityCheck on|off

[server config, within <VirtualHost> or <Directory>]

Specifies whether the server should attempt to learn the user identity for each request by querying an identd process running on the user's machine. By default, identity checking is off.

<IfDefine>

<IfDefine>...</IfDefine>

A sectioning directive for specifying directives that apply if a given define is entered on the command line. For example:

<IfDefine MD5Digest>
LoadModule mod_digest libexec/moddigest.so
</IfDefine>

This directive is executed if the Apache server is started using the following command line parameter:

httpd -DMD5Digest ...

Note that you can place an exclamation mark in front of the <IfDefine> parameter to include such directives if a definition is not made on the command line.

<IfModule>

<IfModule>...</IfModule>

A sectioning directive for specifying directives that apply if a given module has been compiled into the Apache server. For example:

<IfModule mod_cgi>
LoadModule mod_speling libexec/modspelling.so
</IfModule>

This directive is executed if Apache is compiled with the mod_cgi module. Note that you can place an exclamation mark in front of the module name to include such directives if a module is not included in the Apache server build.

Include

Include filename

[server config, within <VirtualHost>, or <Directory>]

Tells the server to include a specified file as part of its configuration.

KeepAlive

KeepAlive on|off

[server config or within <VirtualHost>]

Tells the server to allow persistent connections using the same TCP connection. The default is on. See also KeepAliveTimeOut and MaxKeepAliveRequests.

KeepAliveTimeOut

KeepAliveTimeOut seconds

[server config or within <VirtualHost>]

Specifies the number of seconds to wait for the next request before closing a persistent connection. Used only when persistent connections are enabled with the KeepAlive On setting. The default is 15.

<Limit>

<Limit methods> ... </Limit>

<Limit> is a sectioning directive that applies to the specified access methods (GET, POST, etc.). This directive restricts the boundaries of the access methods specified; if you wish to apply restrictions globally, omit the Limit directive completely. The start tag has the following syntax:

<Limit method1 method2 ...>

where a method is one of the following:

GET: Allows clients to retrieve documents and execute scripts with the GET request method. The HEAD method is also restricted when you specify GET.
POST: Allows clients to use scripts and resources using the POST request method (mostly CGI programs).
PUT: Allows clients access to documents and resources using the PUT request method.
DELETE: Allows clients access to documents and resources using the DELETE request method.
CONNECT: Allows clients access to documents and resources using the CONNECT request method.
OPTIONS: Allows clients access to documents and resources using the OPTIONS request method.

The order, deny, allow, and require directives are the usual inhabitants of the Limit sectioning directive.

Listen

Listen [IP_address:]port

[server config]

Tells the server to listen for requests on the specified port for the specified IP address (if supplied), instead of that specified by the BindAddress and Port directives. Multiple Listen directives can be used to bind the server to more than one port or address/port combination.

ListenBacklog

ListenBacklog backlog

[server config]

Sets the length of the pending connection queue. Increasing this may be useful when the server is flooded with an unusually large number of pending connections. The default is 511.

<Location>

<Location urlpath>...</Location>

[server config or within <VirtualHost>]

A sectioning directive for specifying directives that apply to a given URL. Basically just a more specific version of <Directory>. Wildcards and regular expressions are allowed.

<LocationMatch>

<LocationMatch regexpr>...</LocationMatch>

[server config or within <VirtualHost>]

A sectioning directive for specifying directives that apply to a given URL. Basically, it's just a more specific version of <DirectoryMatch>.

LockFile

LockFile filename

[server config]

Sets the path to the lockfile Apache uses while running. The lockfile must be on the local disk and cannot be NFS-mounted. This file should never be placed in a world-writable directory.

LogLevel

LogLevel level

[server config or within <VirtualHost>]

This directive sets the verbosity of the Apache error logs. The level can be one of the following:

emerg: Logs errors that cause the server to fail.
alert: Reports alerts from program execution that had unexpected errors. The server may or may not perform correctly after such an error.
crit: Reports critical conditions from server execution.
error: Reports error conditions in Apache execution.
warn: Reports warnings in Apache execution.
notice: Reports common, noteworthy conditions.
info: Reports informational items.
debug: Reports simple debug-level items.

MaxClients

MaxClients number

[server config]

Specifies the maximum number of slave processes, and hence the number of client connections, the Apache server can support at a given time. The default is 256.

MaxKeepAliveRequests

MaxKeepAliveRequests number

[server config]

When persistent connections are enabled with KeepAlive On, the MaxKeepAliveRequests directive specifies the number of requests the server allows per persistent connection. If set to 0, the server allows unlimited connections. The default is 100.

MaxRequestsPerChild

MaxRequestsPerChild number

[server config]

Specifies how many requests a slave process may handle for a client during its life. If set to 0, the slave process may handle an unlimited number of connections; the default is 0. For example:

MaxRequestsPerChild 1000

This allows the slave process to handle up to 1000 requests per connection before the process dies, and the client is forced to reconnect to the server.

MaxSpareServers

MaxSpareServers number

[server config]

Specifies the upper range for how many idle slave processes the server should keep to handle requests. The default is 10.

MinSpareServers

MinSpareServers number

[server config]

Specifies the lower range for how many idle slave processes the server should keep around to handle requests. The default is 5.

NameVirtualHost

NameVirtualHost [IP_address:]port

[server config]

Specifies the name or address a virtual host on the server should resolve to. In addition to the address, you can also specify the port that should be used. For example, if you are accepting connections on the server under the IP 123.23.23.123, port 8001 (in addition to others), you would specify:

NameVirtualHost 123.23.23.123:8001

Options

Options options ...

[server config, or within <VirtualHost> or <Directory>, or .htaccess]

Controls the degree of advanced features that you wish to allow on your server. One or more options may be listed on the Options line, separated by spaces. Valid entries are:

None: No features are enabled in this directory.
Indexes: Allows clients to request a formatted index of this directory if no DirectoryIndex has been specified.
Includes: Server-side includes are enabled in this directory.
IncludesNoExec: Server-side includes (SSIs) are enabled in the directory, but the exec feature and the include of CGI scripts is disabled.
ExecCGI: Execution of CGI scripts is allowed in this directory.
MultiViews: Content-negotiated multiviews are allowed in this directory.
FollowSymLinks: The server follows symbolic links in this directory. The pathname is not altered to reflect to the new location.
SymLinksIfOwnerMatch: The server follows symbolic links only if the target file/directory is owned by the same user ID as the link.
All: All features are enabled in this directory.

The Options directive can be used in both the global access.conf and in per-directory .htaccess files. There can be only one Options directive per Directory segment. If omitted, the default is:

Options All

PidFile

PidFile filename

[server config]

Specifies the location of the file into which the server should place its process ID when running in standalone mode, either as an absolute path or as a relative path from the ServerRoot directory if an opening slash (/) has been omitted. The default is:

PidFile logs/httpd.pid

require

require entity names ...

[Within <Directory>, or .htaccess]

Specifies which authenticated users or groups can access a given directory, typically in a <Limit> section of an access control file. A require line requires that all of the appropriate Auth* directives are specified for the directory. entity is one of the following:

user: Only the named users can access this directory with the given methods. Each name is therefore a username that exists in the AuthUserFile (specified password file).
group: Only users in the named groups can access this directory with the given methods. Each name is therefore a group name that is listed in the specified group file.
valid-user: All users listed in the AuthUserFile (specified password file) are allowed access upon providing a valid password.

For example, the following restricts access to a directory to a few key users:

require user jdoe msmith

RLimitCPU

RLimitCPU limit [limit]

Specifies the soft resource limit and optionally the maximum resource limit of CPU time, in seconds per slave process.

RLimitCPU 5 5

In place of each parameter, you can also use the max keyword, which sets it to the maximum allowed by the host operating system.

RLimitMEM

RLimitMEM limit [limit]

Specifies the soft resource limit and optionally the maximum resource limit of memory usage, in bytes per process.

RLimitMEM 65535 65535

In place of each parameter, you can also use the max keyword, which sets it to the maximum allowed by the host operating system.

RLimitNPROC

RLimitNPROC limit [limit]

[server config, or within <VirtualHost>]

Specifies the soft resource limit and optionally the maximum resource limit of slave processes that the server can create.

RLimitNPROC 20 20

In place of each parameter, you can also use the max keyword, which sets it to the maximum allowed by the host operating system.

Satisfy

Satisfy any| all

[Within <Directory>, or .htaccess]

Specifies an access policy if access is restricted by both username-password and host address. The any parameter allows access if the client satisfies either the username-password or host address requirements. The all parameter requires that the client satisfy both.

ScoreBoardFile

ScoreBoardFile filename

[server config]

Specifies the location of the server status file, used by the server to communicate with slave processes. The location is specified as an absolute path, or as a relative path from the ServerRoot directory if the opening slash (/) is omitted. The default is:

ScoreBoardFile logs/apache_status

SendBufferSize

SendBufferSize bytes

[server config]

Resets the TCP buffer size, typically over the OS default.

ServerAdmin

ServerAdmin email_address

[server config, or within <VirtualHost>]

Specifies the email address to which complaints, suggestions, and questions regarding your server should be sent. Used when the server sends error messages in response to failed requests. This directive has no default. It may be specified as follows:

ServerAdmin webmaster@oreilly.com

ServerAlias

ServerAlias virtual_hostname real_hostname

[Within <VirtualHost>]

Specifies an alternate name for a server virtual host.

ServerName

ServerName hostname[:port]

[server config, or within <VirtualHost>]

Allows you to specify a preferred hostname for your server and its port address. (In 2.0, this directive replaces the functionality of the superseded Port directive.) This must be a valid, fully qualified DNS name for the server in question.

ServerPath

ServerPath pathname

[Within <VirtualHost>]

Specifies a pathname for a virtual host; that is, requests for this hostname are automatically routed to the specified pathname.

ServerRoot

ServerRoot directory_path

[server config]

Specifies the directory in which all the server's associated files reside. This path is used as the root directory when relative paths are specified with other directives. For example:

ServerRoot /etc/httpd/

ServerSignature

ServerSignature on|off|EMail

[server config, or within <VirtualHost> or <Directory>, or .htaccess]

Creates a footer line under all documents to identify the exact server this document originated from. This is useful in the event that there is a series of proxies, any one of which can return a specific document or error message. The default is off. If the on option is specified, the footer creates a line with the ServerName and version number. If the EMail option is used, the server creates a name and version number as well as a "mailto:" reference to the ServerAdmin.

ServerTokens

ServerTokens Minimal|OS|Full

[server config]

Specifies which type of header field is returned to clients when the information is requested. There are three options, listed with the appropriate formats:

ProductOnly (Prod): Server: Apache
Major: Server: Apache/2
Minor: Server: Apache/2.0
Minimal (Min): Server: Apache/2.0.41
OS: Server: Apache/2.0.41 (Unix)
Full: Server: Apache/2.0.41 (Unix) PHP/4.2.2 MyMod/1.2

ServerType

ServerType standalone|inetd

[server config]

Specifies whether your server is run standalone or from the inetd daemon. If the server is run from inetd, it's restarted each time a connection is made; hence, using this option is discouraged. The default is to run standalone.

StartServers

StartServers number

[server config]

Specifies the initial number of slave processes at server startup. The default is 5. This directive has no effect under the Windows platform.

TimeOut

TimeOut seconds

[server config]

Specifies the number of seconds to wait before closing a presumably defunct connection. The default is 300 seconds.

UseCanonicalName

UseCanonicalName on|off|dns

[server config, within <Directory>, or <VirtualHost>]

Used to build a self-referential URL. If on, Apache uses the <ServerName> directive to build a URL representing itself. If off, Apache attempts to construct its URL from the client parameters, which is typical when using the VirtualHost directive to represent different addresses. The dns value causes the server to use reverse DNS lookup to determine the self URL.

User

User username

[server config, or within <VirtualHost>]

Specifies the user you want the Apache server to process requests as. Either a username or user ID can be specified; a user ID should be preceded by a hash mark (#). Setting this to root is highly discouraged. Many administrators create a user nobody for Apache.

<VirtualHost>

<VirtualHost>...</VirtualHost>

[server config]

Used when the Apache server services multiple hostnames. Each hostname is given its own <VirtualHost> directive.

<VirtualHost> has a beginning and ending directive, with other configuration directives for the virtual host entered in between. Most directives are valid within <VirtualHost> except the following: BindAddress, GroupId, MaxRequestsPerChild, MaxSpareServers, MinSpareServers, Listen, NameVirtualHost, PidFile, ServerType, ServerRoot, StartServers, TypesConfig, and UserId. This is essentially a segmenting directive that applies directives solely to the virtual host specified. For example:

<VirtualHost sales.oreilly.com>
ServerAdmin webmaster@oreilly.com
DocumentRoot /ora/sales/www
ServerName sales.oreilly.com
ErrorLog /ora/sales/logs/error_log
TransferLog /ora/sales/logs/access_log
</VirtualHost>

18.2. Basic Server Configuration: Core Directives