Chapter 9: Apache Server Core Directives

• AccessConfig
• AccessFileName
• AllowOverride
• AuthName
• AuthType
• BindAddress
• DefaultType
• DocumentRoot
• ErrorDocument
• ErrorLog
• Group
• IdentityCheck
• KeepAlive
• KeepAliveTimeout
• Listen
• MaxClients
• MaxRequestPerChild
• MaxSpareServers
• MinSpareServers
• Options
• PidFile
• Port
• require
• ResourceConfig
• ServerAdmin
• ServerAlias
• ServerName
• ServerPath
• ServerRoot
• ServerType
• StartServers
• TimeOut
• User
• <Directory>
• <File>
• <Limit>
• <Location>
• <VirtualHost>

Apache Server Core Directives

The main server module is called the core. It implements what the Apache on-line server documentation describes as a "barely functional HTTP server." The core implements the basic support for the HTTP protocol as well as the foundation framework that allows for Apache's modular design.

AccessConfig

The AccessConfig directive defines the location of the global access control file. A filename can be specified relative to the ServerRoot pathname or as a full pathname. Traditionally, this file contained <Directory> sections and other directives that affected access control and user authentication; today, however, you can put any server-configuration directives allowed in the server configuration context.

If not defined, the default is

AccessConfig conf/access.conf

The AccessConfig directive can also be specified inside a <VirtualHost> section. Only one AccessConfig directive is allowed in the http.conf file unless the additional directives are part of a <VirtualHost> section, and then only a single AccessConfig directive is allowed per <VirtualHost> section.

To disable reading configuration settings from conf/access.conf set /dev/null as the filename parameter. The file specified by AccessConfig is read after the file specified by ResourceConfig.

AccessFileName

The AccessFileName directive allow you to change the default name Apache uses for per-directory access control files.

If not defined, the default is

AccessFileName .htaccess

Before returning a document to the client, Apache looks for additional per-directory access control files (ACF) in all directories in the path of the request.

The effects of any access control directive specified by an ACF can be disabled with an AllowOverride None directive specified in a <Directory> section on the global ACF (conf/access.conf).

AllowOverride

The AllowOverride directive specifies the extent to which a per-directory access control file can override defaults set in the global ACF conf/access.conf. If security is a concern, you will probably want to specify a setting of None.

This directive is specified inside a <Directory> section in the global ACF. The various options are as follows:

All	Allows all overrides.
AuthConfig	Allows use of the directives used to control user authentication and access control: AuthName, AuthType, AuthGroupFile, AuthUserFile, AuthDBMGroupFile, AuthDBMUserFile, and require.
	Apache 1.1 adds several additional AuthConfig directives: AuthDBGroupFile, AuthDBUserFile, Auth_MSQL.pwd_table, Auth_MSQL_Authorative, Auth_MSQL_EncryptedPasswords, Auth_MSQL_nopasswd, Auth_MSQLdatabase, Auth_MSQLgrp_field, Auth_MSQLgrp_table, Auth_MSQLhost, Auth_MSQLpwd_field, and Auth_MSQLuid_field
FileInfo	Allows you to use the directives that control document types: AddEncoding, AddLanguage, AddType, DefaultType, and LanguagePriority.
Indexes	Allows you to use the directives that control directory indexing: AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, and ReadmeName.
Limit	Allows you to use the directives that control host access: allow, deny, and order.
None	Disables all override directives for the directory.
Options	Allows you to use the directives that control specific directory features: Options and XBitHack.

AuthName

The AuthName directive allows you to label an access-controlled resource. label is displayed in the user authentication panel (login) that is displayed to the user when he is trying to access a controlled resource. If label is omitted, there is no default.

label can contain spaces:

AuthName This is a secured resource, please login first.

This directive requires the use of the AuthType and require directives, and requires that directives such as AuthUserFile and AuthGroupFile or any of their derivatives work properly.

AuthType

The AuthType directive controls the type of authentication used. Basic authentication provides no encryption to the authentication session. Password information is transmitted in code form but not encrypted, making it quite simple to decode.

---

Digest authentication uses RSA MD5 encryption, which makes the authentication process more secure because the authentication session is encrypted. The login and password entered by the user are also encoded so that they are only good for retrieving the requested URL. On requesting a different URL within the authentication realm, the browser will encode a new key (password) to retrieve those materials.

---

These directives require the use of the AuthName and require directives. In addition, if you using Basic authentication, you need to use directives such as AuthUserFile and AuthGroupFile or any of their derivatives work properly. When using Digest authentication, you'll need to use AuthDigestFile.

BindAddress

The httpd server can listen for connections to the host's IP address or to multiple IP addresses if the server is multihomed. If given a BindAddress, the httpd server will only listen for connections to the IP address specified by this directive. BindAddress can be specified by IP, such as

BindAddress 204.12.123.123

or by the fully qualified name of the machine, such as

BindAddress www.foo.com

To have the server listen to all IP addresses accepted by the host, use

BindAddress *

This is also the default value if not specified.

DefaultType

When a client requests a document, the server is responsible for setting the document type of the requested document in the HTTP header. If a client asks for a document type that the server does not recognize (either because the extension of the document is missing or because the extension is not registered as a valid MIME type) the server returns the mime-type defined by DefaultType.

If you have a directory that contains many Graphical Interchange Format (GIF) files that are not properly named with a .gif extension, an entry in an .htaccess such as

DefaultType image/gif

would ensure that the client browser would handle unknown files as GIFs. Some browsers are fairly smart and actually identify a type based on the encoding and format of the file.

DocumentRoot

The DocumentRoot directive specifies the server's document root. The server will append path to all requests prior to executing them, unless the paths are matched by an Alias directive. Do not terminate the path with a trailing slash (/).

DocumentRoot /usr/local/etc/httpd/htdocs

A request for http://www.foo.com/index.html will translate into /usr/local/etc/htdocs/index.html.

ErrorDocument

This is one of the great features of Apache. Instead of returning the standard error responses, Apache can be configured to return customized error messages or to redirect the request to a local or external URL that can handle the request.

You can specify that a file be retrieved by putting in the complete pathname to the file:

# Error code 404 - file not found
ErrorDocument 404 /error/filenotfound.html

Or you can specify a message on-the-fly:

ErrorDocument 404 "This file is not on this server. Go away.
ErrorDocument 500 "Your request failed, because: %s. Oh well 

If you provide the characters %s in message string, Apache inserts further information about the error if available.

You can also force the client to redirect to an external site by specifying a complete URL:

ErrorDocument 404 http://www.server.com/filex.html

---

Redirecting is especially useful for debugging CGI. If you code your CGI so that debugging and error output are stored in one file, you can have the server return the error file whenever your program fails. This saves you the step of manually testing for error responses.

---

---

With Apache 1.1 you can place ErrorDocument directives in per-directory access control files (.htaccess). This setting is toggled with the FileInfo option in AllowOverrides.

---

ErrorLog

This directive specifies the location of the error-log file. The error log is, not surprisingly, the file where the httpd server logs errors. An error can be any request that timed out, or any request that the server could not fulfill because of an access- or resource-availability error. As system administrator, you should check error logs often, especially after upgrading or adding a new CGI program. Many problems of which you may be unaware get logged here, and checking the error log may be the only way to see if someone is trying to attack your server.

If the filename specified in this directive is not an absolute path (a path starting with a /), the filename location is assumed to be relative to the path indicated by ServerRoot.

To turn off error logging, execute

ErrorLog /dev/null

Group

The Group directive sets the group ID (GID) that the server will use to answer any requests. In order to use this directive, the standalone server needs to be started as root because only the superuser is able to change the real and effective GID of a process.

When started by root, the parent httpd process will have root GID (usually wheel). However, httpd requests are served by child processes that use the GID assigned by the Group directive. If started by a user other than root, the GID is inherited from the user that started the httpd process.

---

If root doesn't start the httpd daemon, the Group directive will fail to change the GID of the child processes, leaving you with a potential security problem.
The GID under which you run the server is a very important security-configuration setting. The server should execute under a GID that has very low UNIX privileges. Also, to avoid potential security problems, the server should not be able to execute any programs not intended for use over the Web.

---

You can supply the GID in number format by preceding it with a #, like this:

Group #-1

You can also specify a valid group name as an argument:

Group nogroup

On my system, nogroup has a GID of -2. On many systems, however, nogroup has a GID of -1, which is the default setting for Apache.

---

When assigning a GID by number, you should examine the /etc/group file for the proper GID of the group under which you want the httpd daemon to run. On most systems, the GID you want is listed in the third field. The field delimiter for the group file is a colon (:).

---

---

If the server is started by root, you should make sure that neither the User directive nor the Group directive is set to root. Otherwise, you'll be seriously compromising security.

---

IdentityCheck

The IdentityCheck directive determines whether the user name of the remote user is logged to the transfer log. For this feature to work, the remote machine must be running an RFC931-compliant identity daemon. It should be obvious that this information should not be trusted outside of your network. The transferlog file is defined by the TransferLog directive.

This directive creates an additional server load because the server tries to determine the identity of each user making a request.

Only one IdentityCheck directive is allowed in your server-configuration file. If omitted, the default is

IdentityCheck off

Apache 1.1 enhances the IdentityCheck directive. It can now be used on a per-directory basis. The new version of IdentityCheck is RFC1413-compliant.

KeepAlive

The KeepAlive directive enables multiple transactions to be sent by the server over a single TCP connection, otherwise known as a persistent connection. Persistent connections greatly enhance the performance of the transaction because the overhead of establishing a new connection for each request is reduced or eliminated. The numrequests limit is imposed to prevent a client from grabbing all the server resources.

The following criteria must be met in order for this feature to work:

• [lb] The client must support this feature. All leading browsers, including Netscape Navigator and Microsoft Internet Explorer, support this feature.
  
  
• [lb] The length of the resources being transmitted must be known beforehand. That means that most CGI scripts, Server Side Includes files, and directory listings won't be able to take advantage of this protocol.
  
  

KeepAliveTimeout

This directive sets the maximum amount of time, in seconds, that the server will wait for subsequent requests before closing the connection. The time-out period starts the moment a request is received by the server. (See KeepAlive.)

Listen

This directive is similar to the BindAddress directive. The Listen directive instructs Apache to listen to more than one IP address or port; by default it listens in for requests on all interfaces, but only on the port given by the Port directive (Port is by default set to 80, the standard HTTP port). New versions of Stronghold (see Chapter 14, "Secure Web Servers") will use this feature to implement both SSL and standard servers in a single process. (Currently, you need two servers running: one for standard requests and another for SSL requests).

MaxClients

This directive specifies the maximum number of connections that the httpd server will handle. Connections beyond number get put on a wait state until the server gets freed. number should be changed with care, because setting it too low will place new connections on a wait state, and setting it too high will rapidly exhaust server resources. The default setting is probably fine for the typical server. High-performance servers may benefit from setting number higher, as long as the hardware resources are able to cope with the additional load.

MaxRequestPerChild

This directive specifies how many requests an individual child httpd process will handle before getting terminated. MaxRequestPerChild was initially developed to autokill processes that had aged longer than a certain number of requests with the intention of limiting the number of memory leaks that the process could consume. This option is still valuable on many systems such as Solaris where memory leaks in the libraries still exist.

MaxSpareServers

The MaxSpareServers directive sets the maximum number of idle child processes. Idle processes are httpd server processes not currently fulfilling HTTP requests.

Should the number of idle processes increase above what is specified by number, the parent process will terminate the excess processes.

Extremely busy sites can benefit from increasing the default setting of 10, in case there's a drop in usage for a few seconds. If usage drops, idle processes will go up, which the server will then kill. When usage resumes, the system will be scrambling to find resources to fulfill the requests. Unless you have a very good reason for altering it, don't change the default setting.

(See MinSpareServers and StartServers.)

MinSpareServers

The MinSpareServers directive controls the minimum number of idle child server processes that are available at any one time. Idle processes are server processes not currently handling HTTP requests. If the idle-process count should decrease below the amount designated by MinSpareServers, the parent process will create new child processes. New processes are created at one-second intervals.

This setting should not be changed from the default value unless you have a very good reason for the change.

(See MaxSpareServers and StartServers.)

Options

The Options directive controls which server options are available in a particular directory:

All	Enables all options except MultiViews.
ExecCGI	Execution of CGI programs is allowed.
FollowSymLinks	Following of symbolic links is allowed.
Includes	Use of Server Side Includes (SSI) is allowed
IncludesNOEXEC	SSI is allowed with the following restrictions: the #exec and #include commands are disabled.
Indexes	Enables return of directory listings in cases where a client requests a directory for which there is no DirectoryIndex file (index.html).
MultiViews	Enables content negotiation based on document language. See LanguagePriority.
SymLinksIfOwnerMatch	Following of symbolic links is allowed if the target file or directory is owned by the same user as the link. This setting offers better security than the FollowSymLinks option.

When multiple <Directory> sections that contain Options directives match a request, the Options in the best match are applied. As the following script shows, Option settings are not cumulative:

<Directory /usr/local/etc/htdocs/miscfiles>
Options Indexes
</Directory>
<Directory /usr/local/etc/htdocs>
Options MultiViews
</Directory>

For requests in the /usr/local/etc/htdocs/miscfiles tree, the only option enforced is MultiViews.

PidFile

This directive specifies the location of a file that contains the process ID of the main httpd process on a standalone configuration. The contents of this file are very useful if you need to stop or start the server. A convenient way to restart the server is to run

# kill -HUP 'cat pathToPidFile'

If you are running your server using inetd instead of standalone, the contents of this file are bogus.

A filename is set to be relative to ServerRoot if it's not an absolute path specification (begins with a slash).

Port

The Port directive sets the port where a standalone server listens for requests. The standard port for the HTTP protocol is 80.

The number is a TCP port, and as such it has certain restrictions. Ports numbered below 1024 are reserved for the system. Nonroot users cannot bind to reserved ports. If you want to use the default HTTP port (80), httpd must be started by root.

require

This directive sets the selection criteria used to determine which authenticated users may access a restricted resource.

require also selects which authenticated users can access a directory. The allowed options are as follows:

user	Only users named in the list can access the resource:
	require user1 user2 ...
group	Only users that are members of the groups specified in the list can access the resource:
	require group1 group2 ...
valid-user	Any valid user can access the resource:
	require valid-user

If the require directive appears inside a <Limit> section, it restricts access to the named HTTP methods; otherwise, access is restricted for all methods:

AuthType Basic
AuthName somedomain
AuthUserFile /web/users
AuthGroupFile /web/groups
Limit <GET POST>
require group admin
</Limit>

This directive requires the use of the AuthName and AuthType directives, and directives such as AuthUserFile and AuthGroupFile or any of their derivatives, to work properly.

ResourceConfig

The ResourceConfig directive defines the location of a secondary configuration file. Filename can be specified relative to the ServerRoot or as a full pathname. Traditionally, this file contained most configuration directives with the exception of the server configuration and <Directory> sections. This file can contain any directive with a context of server configuration.

If not defined, the default is

ResourceConfig conf/srm.conf

The ResourceConfig directive can also be specified inside a <VirtualHost> section. Only one ResourceConfig directive is allowed in the server configuration file unless the additional directives are part of a <VirtualHost> section, and then only a single ResourceConfig directive is allowed per <VirtualHost> section.

To ignore the default setting for the ResourceConfig, define /dev/null as the filename parameter. The file specified by ResourceConfig is read after the server configuration file.

ServerAdmin

The ServerAdmin directive sets the e-mail address of the webmaster that will be returned to a client in case of an error.

If you are hosting virtual domains, this directive gives you an opportunity to effectively add information; in some cases, it may be valuable to set up more elaborate aliases (such as ServerAdmin webmaster-smartsoft@accesslink.com) so that you know which server caused the problem. When you receive e-mail addressed to webmaster-smartsoft@accesslink.com, you know immediately that the sender was at SmartSoft's Web site.

For a more sophisticated method of handling e-mail aliases, please see Appendix B, "Managing Virtual Domains with sendmail V8."

ServerAlias

The ServerAlias directive sets additional names the server will respond to for requests. This directive is intended for use with non-IP intensive virtual hosts. For more information, please refer to Chapter 4, "Virtual Hosts," for the section titled, "Non-IP Virtual Hosts."

ServerName

This directive sets the name returned by your server. hostname should be a fully qualified domain name. hostname should be a valid DNS name.

ServerPath

The ServerPath directive is used as a workaround for browsers that don't support non-IP virtual hosts. Non-IP virtual hosts are supported by a browser by including an extra HTTP header, HTTP_HOST, that contains the name of the server requested. Because older browsers don't include this information, requests for a non-IP virtual host will end up in your real server's home page, which the virtual host shares its IP address.

ServerPath provides you with a mechanism to redirect requests to the proper place by using additional path information. Please refer to Chapter 4 for additional information on how to use and implement non-IP intensive virtual hosts.

ServerRoot

The ServerRoot directive specifies where the server directory tree lives. Path is appended to all relative path definitions. Many of the server resources are expected to be found in this tree.

The location of this tree can also be specified by using the -d option to the httpd executable.

ServerType

The ServerType directive sets how the HTTP server is run by UNIX. The server can be run from inetd (which listens for socket connections to the Internet ports and then passes the request to the appropriate software) or in standalone mode (where the server itself listens and handles requests to its port).

inetd runs a new copy of the server per request. After the request is processed, the server exits. Standalone servers fork several server processes that handle several connections before being disposed of by the main server process. This reuse of existing processes provides for increased efficiency.

inetd-run servers are considered by many administrators to be more secure and less prone to attack than standalone servers.

To have inetd start the Web server, you need to edit /etc/inetd.conf and /etc/services. For more information, please refer to Chapter 2, "Installing and Configuring an Apache Server."

StartServers

The StartServers directive specifies the number of child server processes that are forked at server startup. The actual number of server processes at any one time is dynamically controlled by the server load and the MaxSpareServers, MinSpareServers, and MaxClients directives.

There's no need to change this parameter from its default setting.

TimeOut

This directive sets the maximum amount of time, in seconds, that the server will wait for a request to be completed. If it is set too low, the server will terminate the connection before a large transfer is completed. Note that unless you are downloading huge pages, the default is set to 20 minutes. If you notice problems with many stuck-open connections, reducing this number will increase performance of your site.

User

The User directive sets the user ID (UID) the server will use to answer requests. In order for the server to change UIDs, the server needs to be started as root, because only the superuser is able to change the real and effective UID of a process.

When started as root, the owner of the parent server will remain as root. However, requests are handled by child processes will run under the UID assigned by this directive.

---

If root doesn't start the server, the User directive will have no effect, leaving the server running under the UID of the user that started the server process.

---

To set the user ID of httpd to nobody, use

User nobody

or

User #-1

where # is followed by the UID. You may find nobody to have a UID of -1 on many systems. The default for the User directive is -1. On my system, nobody has an UID of -2.

When specifying UIDs by number, verify the /etc/passwd file for the proper UID of the user under which you want the httpd daemon run. On most systems, the format of the passwd file is

login:encryptedPassword:UID:GID:realname and other info:home directory:shell program

As seen in the preceding /etc/passwd sample entry, UID is the third field. All fields on the passwd file are separated by colons (:).

---

If the server is started by root, ensure that the UID is NOT set to root.

---

<Directory>

A <Directory> section is a group of control directives enclosed by a <Directory dir> and </Directory> tag pair. Control directives inside a <Directory> section only apply to the document tree specified by dir. The effects of a <Directory> section apply to any subdirectories in the tree.

You can use any directive in a <Directory> section that is allowed in a directory context. dir is specified either as a full path or as a wildcard string. Wildcard strings can use ? and * characters, with results similar to a shell; ? matches any single character, whereas * matches any sequence of characters.

Because a directory may match various <Directory> sections, the directives are applied in the order of the shortest match first:

<Directory /usr/local/etc/htdocs>
AllowOverride None
</Directory>


<Directory /usr/local/etc/htdocs/public/*>
AllowOverride AuthConfig Limit
</Directory>

For a request to /usr/local/etc/htdocs/public/project/foo.html, the preceding directives get applied in the following order:

• Apply AllowOverride None, which disables per-directory access control files.
  
  
• Apply AllowOverride and AuthConfig Limit directives to /usr/local/etc/htdocs/public/project, which enables the use of the user authentication and host access control directives.
  
  
• Apply any AuthConfig and Limit directives found on the /usr/local/etc/htdocs/public/project/.htaccess file.
  
  

<Directory> sections are usually found in the global ACF conf/access.conf, or inside a <VirtualHost> section. However, you can put them in any configuration file, with the exception of per-directory ACFs (.htaccess). <Directory> sections cannot nest or appear inside a <Limit> section.

You can specify dir, using a regular expression. For information on creating regular expressions, please see Table 6.1.

<File>

The <File> section provides for access control on a per-file basis. It functions exactly like the <Directory> section; however, instead of using a directory specification, it specifies a file in a directory.

You can specify filepath, using a regular expression. For information on creating regular expressions, please see Table 6.1.

<Limit>

A <Limit> section is a group of access control directives, enclosed by a <Limit> and </Limit> tag pair, which applies only to listed HTTP access methods such as GET, POST, HEAD, and so on.

Typically, you use a require directive nested by limit tags to specify authentication requirements before the request is served:

...
 <Limit Get>
 require valid-user
 order deny,allow
 deny from all
 allow from domain
 </Limit>
...

Any HTTP request that uses the GET or POST method will be processed by the server only if the user authenticates (other authentication directives are not shown) and is a member of the group groupname. For the sake of completeness:

<Location>

The <Location> section provides for access control on a per-file or per-URL basis. It functions exactly like the <Directory> section, but instead of using a filepath specification, it uses an URI for its target.

URI is a URL without the http://servername portion. URI is specified either as a full path or a wildcard string. Wildcard strings can use ? and * characters, with results similar to a shell. ? matches any single character; * matches any sequence of characters.

<Location> sections are evaluated in the order listed after <Directory> sections and .htaccess files have been evaluated.

You can specify URI, using a regular expression. For information on creating regular expressions, please see Table 6.1.

(See <Directory>.)

<VirtualHost>

The <VirtualHost> and </VirtualHost> section tags are used to group directives that only apply to a particular host. Any directive that is allowed in a virtual host context can be used. The server receives a request directed toward a virtual host; the configuration directives enclosed in the <VirtualHost> and </VirtualHost> section tags override directives found elsewhere.

You can specify the host to which the section applies by specifying the IP address of the virtual host, or by specifying a fully qualified domain name (fqdn). In addition, you can specify the TCP port for the configuration. This way virtual hosts can return different content solely on the basis of the port used to access it.

<VirtualHost www.company.com>
ServerAdmin webmaster@company.com
DocumentRoot /www/docs/company
ServerName www.company.com
ErrorLog logs/company.error_log
TransferLog logs/company.transfer_log
</VirtualHost>

New in Apache 1.1 is support for non-IP intensive virtual hosts. The declaration of the directive is identical to the original IP-intensive version. The difference in implementation is that the IP of the virtual host must be the same as that of the main host. This new functionality works in conjunction with an HTTP/1.1 protocol, which requires the browser sends the name used for addressing the server.

For IP-intensive virtual hosts, each host IP-identified by the VirtualHost directive must be unique; in order for the host to work, the computer must be configured to accept multiple IP addresses. This configuration, unlike the new non-IP virtual hosts, works regardless of the browser.

For more information on how to build virtual hosts, refer to Chapter 4.