configuring.html revision cc069b1cbd5d2acde579bc6e1877e833132ed763
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maeder<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder BGCOLOR="#FFFFFF"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder TEXT="#000000"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder LINK="#0000FF"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder VLINK="#000080"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder ALINK="#FF0000"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<!--#include virtual="header.html" -->
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>Apache is configured by placing <A HREF="mod/directives.html"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder>directives</A> in plain text configuration files. The main
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederconfiguration file is usually called <CODE>httpd.conf</CODE>. The
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederlocation of this file is set at compile-time, but may be overridden
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederwith the <CODE>-f</CODE> command line flag. Some sites also have
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE>srm.conf</CODE> and <CODE>access.conf</CODE> files for <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="http://www.apache.org/info/three-config-files.html">historical
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederreasons</A>. In addition, other configuration files may be added using
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederthe <CODE><A HREF="mod/core.html#include">Include</A></CODE>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdirective. Any directive may be placed in any of these configuration
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederfiles. Changes to the main configuration files are only recognized by
af1cb109bce240bcafe3823df022d6088cbfc438Christian MaederApache when it is started or restarted.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederThe server also reads a file containing mime document types; the
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederfilename is set by the <A HREF="mod/mod_mime.html#typesconfig"
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder>TypesConfig</A> directive, and is <CODE>mime.types</CODE> by default.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>Apache configuration files contain one directive per line. The
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederback-slash "\" may be used as the last character on a line to indicate
9d3c461220f8076ef80ca48f7b0574ded9b23e7aChristian Maederthat the directive continues onto the next line. There must be no
9d3c461220f8076ef80ca48f7b0574ded9b23e7aChristian Maederother characters or white space between the back-slash and the end of
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederthe line. To end a line with a literal back-slash, you can escape it
162a689da386fc8ddbbe47bcae83eaca4fc8dbc0Christian Maederby preceding it with a second back-slash "\\".
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maeder<P>Directives in the configuration files are case-insensitive, but
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederarguments to directives are often case sensitive. Lines which begin
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederwith the hash character "#" are considered comments, and are ignored.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederComments may <STRONG>not</STRONG> be included on a line after a
9d3c461220f8076ef80ca48f7b0574ded9b23e7aChristian Maederconfiguration directive. Blank lines and white space occurring before
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedera directive are ignored, so you may indent directives for clarity.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>You can check your configuration files for syntax errors without
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederstarting the server by using <CODE>apachectl configtest</CODE>
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maeder<P>Apache is a modular server. This implies that only the most basic
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederfunctionality is included in the core server. Extended features are
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederavailable through <A HREF="mod/index-bytype.html">modules</A> which can
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maederbe loaded into Apache. By default, a <A
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian MaederHREF="mod/directive-dict.html#Status">base</A> set of modules is
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederincluded in the server at compile-time. If the server is compiled to
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maederuse <A HREF="dso.html">dynamically loaded</A> modules, then modules
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedercan be compiled separately and added at any time using the <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="mod/mod_so.html#loadmodule">LoadModule</A> directive.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederOtherwise, Apache must be recompiled to add or remove modules.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>To see which modules are currently compiled into the server,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederyou can use the <CODE>-l</CODE> command line option.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>Directives placed in the main configuration files apply to the entire
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederserver. If you wish to change the configuration for only a part of
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederthe server, you can scope your directives by placing them in
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE><A HREF="mod/core.html#directory"><Directory></A>,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<A HREF="mod/core.html#directorymatch"><DirectoryMatch></A>,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<A HREF="mod/core.html#files"><Files></A>,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<A HREF="mod/core.html#filesmatch"><FilesMatch></A>,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<A HREF="mod/core.html#location"><Location></A>,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<A HREF="mod/core.html#locationmatch"><LocationMatch></A>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedersections. These sections limit the application of the directives
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederwhich they enclose to particular filesystem locations or URLs. They
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maedercan also be nested, allowing for very fine grained configuration.
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maeder<P>Apache has the capability to serve many different websites
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedersimultaneously. This is called <A HREF="vhosts/">Virtual Hosting</A>.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederDirectives can also be scoped by placing them inside
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE><A HREF="mod/core.html#virtualhost"><VirtualHost></A></CODE>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedersections, so that they will only apply to requests for a particular
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>Although most directives can be placed in any of these sections,
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedersome directives do not make sense in some contexts. For example,
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maederdirectives controlling process creation can only be placed in the main
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederserver context. To find which directives can be placed in which
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maedersections, check the <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="mod/directive-dict.html#Context">Context</A> of the directive.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederFor further information, we provide details on <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="sections.html">How Directory, Location and Files sections
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>Apache allows for decentralized management of configuration via
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederspecial files placed inside the web tree. The special files are
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederusually called <CODE>.htaccess</CODE>, but any name can be specified
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maederin the <A HREF="mod/core.html#accessfilename"><CODE
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maeder>AccessFileName</CODE></A> directive. Directives placed in
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE>.htaccess</CODE> files apply to the directory where you place
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maederthe file, and all sub-directories. The <CODE>.htaccess</CODE> files
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederfollow the same syntax as the main configuration files. Since
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE>.htaccess</CODE> files are read on every request, rather than
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederonly at server startup, changes made in these files take immediate
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<P>To find which directives can be placed in <CODE>.htaccess</CODE>
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maederfiles, check the <A HREF="mod/directive-dict.html#Context">Context</A>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederof the directive. The server administrator further controls what
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdirectives may be placed in <CODE>.htaccess</CODE> files by
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederconfiguring the <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="mod/core.html#allowoverride"><CODE>AllowOverride</CODE></A>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdirective in the main configuration files.
af1cb109bce240bcafe3823df022d6088cbfc438Christian MaederAnyone who can write to the directory where Apache is writing a
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederlog file can almost certainly gain access to the uid that the server is
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederstarted as, which is normally root. Do <EM>NOT</EM> give people write
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederaccess to the directory the logs are stored in without being aware of
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederthe consequences; see the <A HREF="misc/security_tips.html">security tips</A>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdocument for details.
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maeder<P>On startup, Apache saves the process id of the parent httpd process to
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederthe file <CODE>logs/httpd.pid</CODE>. This filename can be changed
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederwith the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maederprocess-id is for use by the administrator in restarting and
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederterminating the daemon: on Unix, a HUP or USR1 signal causes the
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdaemon to re-read its configuration files and a TERM signal causes it
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederto die gracefully; on Windows, use the -k command line option instead.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederFor more information see the <A HREF="stopping.html">Stopping and
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederRestarting</A> page.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederIf the process dies (or is killed) abnormally, then it will be necessary to
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maederkill the children httpd processes.
31c6978fd9066c9d2c3c98c950f7abbe89112522Christian Maeder<P>The server will log error messages to a log file, by default
31c6978fd9066c9d2c3c98c950f7abbe89112522Christian Maeder<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on
31c6978fd9066c9d2c3c98c950f7abbe89112522Christian MaederWindows and OS/2. The filename can be set using the <A
31c6978fd9066c9d2c3c98c950f7abbe89112522Christian MaederHREF="mod/core.html#errorlog">ErrorLog</A> directive; different error
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maederlogs can be set for different <A
af1cb109bce240bcafe3823df022d6088cbfc438Christian MaederHREF="mod/core.html#virtualhost">virtual hosts</A>.
798a3d6fdcb8c17b0bc3502a150be75c9ec8799bChristian Maeder<P>The server will typically log each request to a transfer file, by
af1cb109bce240bcafe3823df022d6088cbfc438Christian Maederdefault <CODE>logs/access_log</CODE> on Unix or
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederset using a <A HREF="mod/mod_log_config.html#customlog">CustomLog</A>
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maederdirective; different transfer logs can be set for different <A
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian MaederHREF="mod/core.html#virtualhost">virtual hosts</A>.
bd8ff5b5f66be563e5be9d3a0c069e32d06f331cChristian Maeder<!--#include virtual="footer.html" -->