Common Directives

Common Directives

This section discusses the meanings and possible values of some of the more important configuration directives.

graphics/tip.gif

Generally these directives are found in the httpd.conf file. In order for any new values to take effect, you must restart the httpd daemon. (See the section on the apachectl script for instructions.)

 

ServerType

This value may be either "inetd" or "standalone." A value of inetd means that individual instances of the httpd executable will be started on an as-needed basis by the inetd internet services daemon.

Apache will always give you better performance when run in standalone mode. The tradeoff is that inetd provides some security mechanisms that you may want. In the absence of a burning need for inetd security (in particular, see your UNIX system documentation on the tcpd wrapper for more information), you should configure Apache to run in standalone mode.

Example: To configure Apache to run in standalone mode, use

ServerType standalone

Port

An IP connection is defined by the IP address of the server to which you are connecting (e.g., 192.168.1.10), plus the port that the server is monitoring for connections. On UNIX machines, ports are associated with a service name in the text file /etc/services. Obviously, in order for any two machines to have a meaningful connection, they must agree on what data will be passed through which port. For the most part, the port numbers were carved in stone long ago and are now referred to as "well-known port numbers."[1]

[1] This strikes me as somewhat disingenuous. A more appropriate term might be "Industry Standard Port Numbers" or "Unshakably Entrenched Port Numbers." On the other hand, the term was probably coined by the same batch of folks who decided to group all the truly useful protocols that make up the backbone of modern telcommunications under the lighthearted euphemism "Request For Comment," or "RFC" for short. There's an RFC for the TCP standard (RFC 793), another for telnet (RFC 854), and if you're so inclined, you can get a copy, read over it, and suggest changes. If you come up with something good, it might even get adopted most of them haven't changed in decades, but it is possible. Contrast this to the dizzying assortment of self-declared industry standards proposed and reproposed on an almost daily basis by the commercial software companies. The moral here is that in the computer industry, as in almost all other endeavors of life, self-promotion is suspect (e.g., if something calls itself "The Definitive Guide," it probably isn't).

As it happens, the port for client server web connections is number eighty.

Example: To configure Apache to monitor IP port 80, use

Port 80

Example: If you are planning to use Secure Socket Layer (SSL) communication you will also want to enable TCP port 443, which can be accomplished by typing

Port 443

HostnameLookups

When logging the clients who access your server, you may opt to enter either the numeric IP address (e.g., 204.62.129.132) or the symbolic hostname associated with that address (e.g., www.apache.org). Obviously, storing the symbolic name will make your log files more readable. However, doing DNS lookups on each and every client who accesses your site is almost guaranteed to slow performance to a crawl.

Example: In the absence of a pressing need for fully resolved names, it is strongly recommended that you turn HostnameLookups off. To do so, please use

HostnameLookups off

User & Group

It is recommended that you create a UNIX system user specifically for Apache. This sidesteps a wide variety of potential security problems created when Apache runs with the authority of the root user.

In the following example, the user is specified by its human readable symbolic name (Apache), while the group is specified using the number associated with the Apache group. For readability it's probably best to use symbolic names, but Apache doesn't care either way.

Example: To configure Apache to run as a UNIX user named Apache, use

User apache

Example: To configure Apache to run with a UNIX group identity of 506, use

Group 506

BrowserMatch

Use this directive to set environment variables based on the type of client browser that is attempting to access you, as indicated by the User-Agent HTTP request header. The idea here is to provide a mechanism that will enable you to adapt the behavior of your site(s) to the differences between the various browsers. For example, you may have some whizbang feature that looks great under Netscape, but blows up under Internet Explorer. This directive allows you to set an environment variable that your CGI scripts (or other scripts) can use to customize their output, based on the type of browser accessing them.

Example: The following directive sets the nokeepalive variable when the client is using Netscape 2.x browsers:

BrowserMatch Mozilla /2 nokeepalive

ServerAdmin

ServerAdmin is the email address to which the users will send emails when the users run into problems. (It is displayed automatically in some error screens.)

Example: To configure Apache to send email to you@yoursite.org, use

ServerAdmin you@yoursite.org

ServerRoot

The ServerRoot directory is the directory location relative to which everything else is specified. The ServerRoot directive is key because most of the directives that take files or directories as parameters allow you to specify either absolute paths or paths relative to ServerRoot.

Example: To configure Apache with a ServerRoot directory of /opt/apache, use

ServerRoot /opt/apache

BindAddress

Use this directive to tell Apache about an IP address on the local machine it should pay attention to. If you've only got one network interface on this machine, don't bother with this directive. By default, Apache will listen to all the connection interfaces on the host, which, if you only have one interface, is undoubtedly what you want it to do.

The practical value of this directive only comes into play when you have multiple network interfaces.[2]

[2] Use the command netstat -i to display your network interfaces on UNIX machines. For Windows, go to Start > Settings > Control Panel > Network.

Example: To force Apache to monitor only the IP addresss 192.168.1.10, use the following directive:

BindAddress 192.168.1.10

graphics/tip.gif

To get Apache to ignore requests emanating from anywhere other than the local machine while you're in the process of getting things up and running, you can specify the loopback address as your BindAddress:

 

BindAddress 127.0.0.1

The BindAddress value may be specified as a * (indicating all network interfaces on the local machine), an actual numeric IP address, or a fully qualified domain name. Recall that the use of domain names in configuration files requires an nslookup and is thus bad for performance.

Example: To monitor all available IP connections on your machine (the default behavior), use the following directive:

BindAddress *

If you wish to monitor two or more distinct IP addresses on your machine, but not all the addresses on your machine, you will need to use the Listen directive. BindAddress cannot be meaningfully used multiple times within the same configuration file.

ErrorLog

This directive specifies the path to the log file in which Apache will write error messages. The path may be either absolute or relative to ServerRoot. If the path specified does not start with the forward slash character ('/'), indicating an absolute path from the root directory of the filesystem,[3] the path specified will be assumed to be relative to the ServerRoot directory.

[3] This is true for both Windows and UNIX implementations. Despite the fact that Windows machines use the backslash "\" rather than forward slash "/" as a delimiter directory paths, the configuration files of Windows implementations of Apache use the UNIX delimiters in file specifications.

Example: Say that your ServerRoot directory is /opt/apache. If so, the directive

ErrorLog logs/error_log

indicates an error file located at

/opt/apache/logs/error_log.

Example: On the other hand, the following directive

ErrorLog /var/logs/apache

would cause all error messages to be written to the file

/var/logs/apache.

Make sure that whatever user identity apache runs under has write permissions for your error log file.

TransferLog

This directive specifies a file in which records of information transferred into and out of the server are stored. The path specified may be either absolute or relative. (See the discussion of the ErrorLog directive for more information about the difference.)

Example: To configure Apache to store records of the information it transfers in a file named access_log in the logs directory under ServerRoot, use

TransferLog logs/access_log

PidFile

This directive specifies a file in which the UNIX process id is stored. Briefly, the process id is a unique number, which the UNIX kernel uses to keep track of all the processes it is running. This number is stored as the first Apache (httpd) process is started, primarily so that the system will have some way of killing it and its children off later. The path specified may be either absolute or relative.

Example: To configure Apache to store the PID number of the root httpd process in a file named http.pid in the logs directory under ServerRoot, use

PidFile logs/httpd.pid

CacheNegotiatedDocs

The HTTP 1.1 standard defines a group of headers that Apache sends to clients and proxies (at least, those paying attention to the HTTP 1.1 protocols) to let them know what content can be stored in a cache and what should not be. By default, all negotiated content is marked as noncacheable.

Example: To override the default behavior and enable proxies to cache, use

CacheNegotiatedDocs

Timeout

This directive specifies the number of seconds a given connection may be inactive before Apache kills it off. The definition of inactivity is rather imprecise. It is the specified number of seconds since one of the following things happened:

         A connection was established or a GET request was received.

         In the case of incomplete transmissions, the last acknowledgement of receipt.

         A packet of data was received via a PUSH or PUT HTTP request.

Note that 300 seconds (the default) is an awfully long time. You may well wish to set it lower, which will improve performance by terminating dead connections (as well as a few that are merely slow).

Example: To set a timeout value of 2.5 minutes, use

Timeout 150

KeepAlive

When set on, this directive enables the server to take advantage of a browser's ability to maintain a persistent connection. A persistent connection allows the client to request more than one chunk of data at a time. It is in everyone's interest to enable the KeepAlive option as it removes the overhead required in initiating and closing an IP connection from all but the first and last requests, thus improving overall performance.

Example: To enable keepalives, use

KeepAlive On

MaxKeepAliveRequests

This directive specifies the maximum number of requests allowed during a single persistent connection (see the section on KeepAlive for more information). To improve performance, the directive's number should be set high. A value of 0 means "unlimited."

Example: To enable unlimited keepalive requests, use

MaxKeepAliveRequests 0

KeepAliveTimeout

Use this directive to specify the number of seconds that Apache will wait for the next request during a persistent connection session.

Example: To set a timeout value of 15 seconds for keepalive requests, use

KeepAliveTimeout 15

MinSpareServers

For optimum performance, it is a good idea to have a few instances of the Apache server just hanging around waiting for requests. When there are spares available you don't have to wait for a new instance to be copied into memory from disk before a request can be served. The MinSpareServers directive tells Apache how many copies of itself it needs to keep available to handle surprise jumps in the load. Use in conjunction with the MaxSpareServers directive to tune system performance.

Example: To tell the server to keep a minimum of 5 spare executables, use

MinSpareServers 5

MaxSpareServers

Use this directive to specify the maximum number of spare servers standing around waiting to handle load spikes. (See MinSpareServers for more explanation.)

Example: To tell the server to keep a minimum of 10 spare executables, use

MaxSpareServers 10

StartServers

This directive specifies the number of httpd instances that will be created upon startup. Note that it does not override the MinSpareServers directive and that other servers will be created on an as needed basis in any case. Pretty much any value even remotely in the ball park will be fine.

Example: To tell the server to create 5 httpd instances at startup time, use

StartServers 5

MaxClients

This directive sets a hard upper limit on the number of server processes running simultaneously. It is effectively a limit on the number of simultaneously connected clients, so it is important that you not set the value too low. A reasonable estimate for the value can be calculated by dividing the amount of available RAM by the size of the servers and subtracting some site-specific value for other programs that you may wish to keep resident.

graphics/note.gif

The number of server processes running is also limited by the HARD_SERVER_LIMIT variable that is compiled into the binary. By default, the HARD_SERVER_LIMIT is set to 256.

 

Example: To set an upper limit of 150 simultaneous connections, use

MaxClients 150

MaxRequestsPerChild

This directive sets an upper limit on the number of requests a particular child can process before it dies off. Why does this exist? Hypothetically, if the executable or any of its supporting libraries contained a memory leak, it could conceivably suck up all the system resources and choke or crash the machine.

Example: To force child servers to die off after servicing 30 client requests, use

MaxRequestsPerChild 30

<Directory>

The directives that actually control access to a collection of Web pages (e.g., Options, AllowOverride) are generally encased in another pair of directives that limit their scope (e.g., <Directory>).

Example: Anything contained in the following pair of directives would apply only to the files found in /opt/apache/htdocs:

<Directory /opt/apache/htdocs>

</Directory>

graphics/note.gif

Unless overridden by a configuration directive in one of its subdirectories, the access controls that apply to a directory apply to all of its subdirectories as well.

 

Location

Alternatively, the scope of a set of privileges may be restricted to a particular URI location within your site.

Example: To instruct Apache to deny all access to the URI secure_stuff from anyone but users on the local host, use


<Location /secure_stuff>

    order deny, allow

    deny from all

    allow from 127.0.0.1

</Location>

Options

This directive is used in conjunction with the .htaccess file, the <Directory> directive, or the <Location> directive to specify the sort of access that may be granted to a user process for that directory. The syntax is the word Options followed by one or more options from the following list:

All

Enable all options except MultiViews.

ExecCGI

Enable the execution of CGI scripts.

FollowSymLinks

Allow the server to follow symbolic links in this directory. (Be advised that even though the server follows the symlink, it does not change the pathname used to match against <Directory> sections.)

Includes

Enable the use of server-side includes.

IncludesNOEXEC

Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled.

Indexes

When this option is enabled, if a URL that maps to a directory is requested and there is no DirectoryIndex file (usually index.html) in that directory, then the server will return a formatted listing of the contents of that directory.

MultiViews

Allow content-negotiated MultiViews.

SymLinksIfOwnerMatch

Follow symbolic links only in the case where the owner of the target file or directory is the same as the owner of the link.

In the case where multiple options might apply to a single directory, the most specific overrides all the others. The options are not merged. However, if all the options on the Options directive are preceded by a + or symbol, the options are merged as follows: Those preceded by a '+' are added to the list of currently active options, and those preceded by a '-' are removed from the currently active list.

AllowOverride

One mechanism for controlling access is to include a file named .htaccess in each directory. As the directives contained in this file may conflict with the directives specified by the Options directive (see previous subsection), the AllowOverride directive has been provided to specify which of the two is in charge. The possible values are "All," "None," or any combination of "Options," "FileInfo," "AuthConfig," and "Limit."

Example: To specify that there will be no per-directory configuration files (and thereby improve performance), use

AllowOverride None

If you wish to specify override values in a file other than .htacces, you may specify that file name by using the AccessFileName directive. Note that setting AllowOverride to on causes Apache to search the entire directory tree ancestry (e.g., when accessing /apache/htdocs/index.html it must look in /, /apache, and /apache/htdocs for configuration files) of a given file for configuration files, and thus is not good for performance.

order

This directive is part of the mod_access default. The order directive specifies whether allow or deny directives will be considered first. To decide which order to choose, just answer the question of whether you intend to grant access to more hosts than you deny. If so, use

order allow,deny

otherwise

order deny,allow

allow

The allow directive specifies a host or domain that will be allowed access to server resources. The value may specified numerically (e.g., 192.168.20) or as a symbolic name (righthere.net). Be advised, however, that specifying access with a symbolic host or domain name will require a name lookup and thus hurt performance. If you choose to specify entire domains symbolically, be sure to use a leading dot (e.g., .sample.org, rather than sample.org).

Example: To allow any client access to server resources, use

allow from all

deny

The deny directive specifies a host or domain that will be denied access to server resources. The value may be specified numerically (192.168.20) or as a symbolic name. If you choose to specify entire domains symbolically, be sure to use a leading dot (e.g., .sample.org rather than sample.org).

Example: To deny all clients access to server resources, use

deny from all

DocumentRoot

This directive specifies the path to a directory from which (by default) all requested documents will be retrieved. Note that symbolic links and aliases may effectively allow users to access other directories. Be advised that a poor choice for this directive (e.g., setting it to the root directory of your machine, "/") may create vast and unnecessary security holes. It is far better to create a chunk of disk space for Apache and make the DocumentRoot directory a part of that chunk.

Example: To specify a root directory of /opt/apache/htdocs, use

DocumentRoot /opt/apache/htdocs

UserDir

This directive specifies the name of the subdirectory under a user's home directory that is referred to when a request for a user home page (e.g., ~userguy) as opposed to a registered Web site (e.g., www.userguy.com) is received.

Example: To tell the server to look in a file named "public_html" under the user's home directory when receiving a request for a user home page, use

UserDir public_html

DirectoryIndex

When Apache resolves a URL into a directory, it will return the file or files specified by this directory. By convention this is the file index.html, but it can be anything you like. If you specify a list of file names, Apache will return the first member of the list that it finds in the directory for example,

DirectoryIndex index.html index.htm index.cgi index.shtml

If nothing in the list matches, Apache will generate an actual listing of the contents of the directory and return that to the user. From a security standpoint this is not good, so you may wish to include an absolute path to a default file containing the message "Not found" or some such message at the tail end of your list.

FancyIndexing

When set to on, FancyIndexing generates a table of files containing the following columns: Icon, Name, Last Modified, Size, and Description.

Example: To enable fancy indexing, use

FancyIndexing on

AddDescription

Use this directive when you want to include a short description with a file on server-generated indices.

Example: To provide the description "Access Policy" next to the listing for README.HTML on server-generated indices, use

AddDescription "Access Policy" README.HTML

ReadmeName

Use this directive to specify the name of the README file for the mod_autoindex module to include in automatically generated directory indices.

Example: To tell the server that README files will be named README.html, use

ReadmeName README.html

HeaderName

This directive specifies the name of a file that will be prepended to the automatically generated directory indices.

Example: To tell the server to prepend a file named HEADER.html to automatically generated directory indices, use

HeaderName HEADER.html

IndexIgnore

Use this directive to specify a set of files that will not be included in automatically generated directory indexes.

Example: To tell the server to skip special files when generating directory indexes, use

IndexIgnore */.??* *~ *# */HEADER* */README* */RCS

AccessFileName

This directive specifies the name of the file that, if found in a particular directory, will be read for access control directives.

Example: To tell the server to look for files named .htaccess containing access control information in each directory (and thereby create a nasty performance problem), use

AccessFileName .htaccess

DefaultType

This directive tells the server what MIME type to default to when the actual type cannot be determined from the filename extensions. (Text is usually a good choice.)

Example: To tell the server to treat any file whose type it cannot determine to be a text file, use

DefaultType text/plain

AddLanguage

This directive makes the server aware of the language of a particular document based on the inclusion of the specified suffix in the name of the document. For example, if you were to use the directive

AddLanguage en .en .english

the browser would conclude that each of the following files contained an English text: filename.html.en, filename.html.english.

This information is of course of little use to the browser unless the client specifes the language type that it prefers.

LanguagePriority

This directive is provided to break ties that may occur when negotiating content. It lists the languages in decreasing order of preference.

Example: To specify a language preference (in decreasing order) of English, French, and German, use

LanguagePriority en fr de

ScriptAlias

This directive specifies which directories contain server scripts. The format is ScriptAlias fakename realname.

Example: To refer client requests from the nonexistent directory cgi-bin to the actual location in the directory tree where cgi files are stored, use

ScriptAlias /cgi-bin/ /usr/local/etc/httpd/cgi-bin/

AddHandler

The default configuration of Apache includes seven different content handlers for UNIX platforms plus another one for Windows. The AddHandler directive is used to associate a handler with a file type or types. The built-in handlers are

cgi-script

Execute the URL as a CGI script.

imap-file

Assume specified URL contains displayable image.

isapi-isa

Windows only. Load ISA format DLLs when URL is accessed.

server-info

Generate page containing server configuration information.

server-parsed

Parse any such files looking for server-side includes.

server-status

Generate page containing server status information.

type-map

Treat specified URL as a map of types.

Example: The following directive associates the cgi-script handler with the .pl and .ksh file extensions:

AddHandler cgi-script .pl .ksh

Example: Alternatively, handlers may be associated with a specific location, such as

<Location /cgi>

AddHandler cgi-script

</Location>

 



Linux Desk Reference
Linux Desk Reference (2nd Edition)
ISBN: 0130619892
EAN: 2147483647
Year: 2000
Pages: 174
Authors: Scott Hawkins

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net