granicus.if.org Git - apache/blob - docs/manual/mod/core.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Apache Core Features</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16
  17 <H1 ALIGN="CENTER">Apache Core Features</h1>
  18 <P>
  19 These configuration parameters control the core Apache features, and are
  20 always available.
  21 </P>
  22 <H2>Directives</H2>
  23 <ul>
  24 <li><A HREF="#accessconfig">AccessConfig</A>
  25 <li><A HREF="#accessfilename">AccessFileName</A>
  26 <li><A HREF="#addmodule">AddModule</A>
  27 <li><A HREF="#allowoverride">AllowOverride</A>
  28 <li><A HREF="#authname">AuthName</A>
  29 <li><A HREF="#authtype">AuthType</A>
  30 <li><A HREF="#bindaddress">BindAddress</A>
  31 <li><A HREF="#clearmodulelist">ClearModuleList</A>
  32 <li><A HREF="#contentdigest">ContentDigest</A>
  33 <li><A HREF="#coredumpdirectory">CoreDumpDirectory</A>
  34 <li><A HREF="#defaulttype">DefaultType</A>
  35 <li><A HREF="#directory">&lt;Directory&gt;</A>
  36 <li><A HREF="#directorymatch">&lt;DirectoryMatch&gt;</A>
  37 <li><A HREF="#documentroot">DocumentRoot</A>
  38 <li><A HREF="#errordocument">ErrorDocument</A>
  39 <li><A HREF="#errorlog">ErrorLog</A>
  40 <li><A HREF="#files">&lt;Files&gt;</A>
  41 <li><A HREF="#filesmatch">&lt;FilesMatch&gt;</A>
  42 <li><A HREF="#group">Group</A>
  43 <li><A HREF="#hostnamelookups">HostNameLookups</A>
  44 <li><A HREF="#identitycheck">IdentityCheck</A>
  45 <li><A HREF="#ifmodule">&lt;IfModule&gt;</A>
  46 <li><A HREF="#include">&lt;Include&gt;</A>
  47 <li><A HREF="#keepalive">KeepAlive</A>
  48 <li><A HREF="#keepalivetimeout">KeepAliveTimeout</A>
  49 <li><A HREF="#limit">&lt;Limit&gt;</A>
  50 <li><A HREF="#listen">Listen</A>
  51 <li><A HREF="#listenbacklog">ListenBacklog</A>
  52 <li><A HREF="#location">&lt;Location&gt;</A>
  53 <li><A HREF="#locationmatch">&lt;LocationMatch&gt;</A>
  54 <li><A HREF="#lockfile">LockFile</A>
  55 <li><A HREF="#maxclients">MaxClients</A>
  56 <li><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</a>
  57 <li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A>
  58 <li><A HREF="#maxspareservers">MaxSpareServers</A>
  59 <li><A HREF="#minspareservers">MinSpareServers</A>
  60 <li><A HREF="#options">Options</A>
  61 <li><A HREF="#pidfile">PidFile</A>
  62 <li><A HREF="#port">Port</A>
  63 <li><A HREF="#require">require</A>
  64 <li><A HREF="#resourceconfig">ResourceConfig</A>
  65 <li><A HREF="#rlimitcpu">RLimitCPU</A>
  66 <li><A HREF="#rlimitmem">RLimitMEM</A>
  67 <li><A HREF="#rlimitnproc">RLimitNPROC</A>
  68 <li><A HREF="#satisfy">Satisfy</A>
  69 <li><A HREF="#scoreboardfile">ScoreBoardFile</A>
  70 <li><A HREF="#sendbuffersize">SendBufferSize</A>
  71 <li><A HREF="#serveradmin">ServerAdmin</A>
  72 <li><A HREF="#serveralias">ServerAlias</A>
  73 <li><A HREF="#servername">ServerName</A>
  74 <li><A HREF="#serverpath">ServerPath</A>
  75 <li><A HREF="#serverroot">ServerRoot</A>
  76 <li><A HREF="#servertype">ServerType</A>
  77 <li><A HREF="#startservers">StartServers</A>
  78 <li><A HREF="#threadsperchild">ThreadsPerChild</a>
  79 <li><A HREF="#timeout">TimeOut</A>
  80 <li><A HREF="#user">User</A>
  81 <li><A HREF="#virtualhost">&lt;VirtualHost&gt;</A>
  82 </ul>
  83 <hr>
  84
  85 <h2><A name="accessconfig">AccessConfig directive</A></h2>
  86 <!--%plaintext &lt;?INDEX {\tt AccessConfig} directive&gt; -->
  87 <strong>Syntax:</strong> AccessConfig <em>filename</em><br>
  88 <strong>Default:</strong> <code>AccessConfig conf/access.conf</code><br>
  89 <strong>Context:</strong> server config, virtual host<br>
  90 <strong>Status:</strong> core<p>
  91
  92 The server will read this file for more directives after reading the
  93 <A HREF="#resourceconfig">ResourceConfig</A> file. <em>Filename</em> is
  94 relative to the <A HREF="#serverroot">ServerRoot</A>.
  95 This feature can be disabled using:
  96 <blockquote><code>AccessConfig /dev/null</code></blockquote>
  97 Historically, this file only contained
  98 <A HREF="#directory">&lt;Directory&gt;</A> sections; in fact it can now
  99 contain any server directive allowed in the <em>server config</em> context.
 100 <p><hr>
 101
 102 <h2><A name="accessfilename">AccessFileName directive</A></h2>
 103 <!--%plaintext &lt;?INDEX {\tt AccessFileName} directive&gt; -->
 104 <strong>Syntax:</strong> AccessFileName <em>filename filename ...</em><br>
 105 <strong>Default:</strong> <code>AccessFileName .htaccess</code><br>
 106 <strong>Context:</strong> server config, virtual host<br>
 107 <strong>Status:</strong> core<br>
 108 <strong>Compatibility:</strong> AccessFileName can accept more than one filename only in Apache 1.3 and later<p>
 109
 110 When returning a document to the client the server looks for the first existing
 111 access control file from this list of names in every directory of the path to
 112 the document, if access control files are enabled for that directory.
 113
 114 For example:
 115 <blockquote><code>AccessFileName .acl</code></blockquote>
 116 before returning the document /usr/local/web/index.html, the
 117 server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl
 118 for directives, unless they have been disabled with
 119 <blockquote><code>
 120 &lt;Directory /&gt;<br>
 121 AllowOverride None<br>
 122 &lt;/Directory&gt;</code></blockquote><p><hr>
 123
 124 <h2><A name="addmodule">AddModule directive</A></h2>
 125 <!--%plaintext &lt;?INDEX {\tt AddModule} directive&gt; -->
 126 <strong>Syntax:</strong> AddModule <em>module module ...</em><br>
 127 <strong>Context:</strong> server config <br>
 128 <strong>Status:</strong> core<br>
 129 <strong>Compatibility:</strong> AddModule is only available in Apache 1.2 and later<p>
 130
 131 The server can have modules compiled in which are not actively in use.
 132 This directive can be used to enable the use of those modules.  The
 133 server comes with a pre-loaded list of active modules; this list can
 134 be cleared with the <A HREF="#clearmodulelist">ClearModuleList</A>
 135 directive.<p><hr>
 136
 137 <h2><A name="allowoverride">AllowOverride directive</A></h2>
 138 <!--%plaintext &lt;?INDEX {\tt AllowOverride} directive&gt; -->
 139 <strong>Syntax:</strong> AllowOverride <em>override override ...</em><br>
 140 <strong>Default:</strong> <code>AllowOverride All</code><br>
 141 <strong>Context:</strong> directory<br>
 142 <strong>Status:</strong> core<p>
 143
 144 When the server finds an .htaccess file (as specified by
 145 <A HREF="#accessfilename">AccessFileName</A>) it needs to know which
 146 directives declared in that file can override earlier access information.<p>
 147
 148 <em>Override</em> can be set to <code>None</code>, in which case the server
 149 will not read the file, <code>All</code> in which case the server will
 150 allow all the directives, or one or more of the following:
 151 <dl>
 152 <dt>AuthConfig
 153 <dd>
 154 <!--%plaintext &lt;?INDEX {\tt AuthConfig} override&gt; -->
 155 Allow use of the authorization directives
 156 (<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>,
 157 <A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>,
 158 <A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>,
 159 <A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>,
 160 <A HREF="mod_auth.html#authuserfile">AuthUserFile</A>,
 161 <A HREF="#require">require</A>, etc.).
 162 <dt>FileInfo
 163 <dd>
 164 <!--%plaintext &lt;?INDEX {\tt FileInfo} override&gt; -->
 165 Allow use of the directives controlling document types
 166 (<A HREF="mod_mime.html#addencoding">AddEncoding</A>,
 167 <A HREF="mod_mime.html#addlanguage">AddLanguage</A>,
 168 <A HREF="mod_mime.html#addtype">AddType</A>,
 169 <A HREF="#defaulttype">DefaultType</A>,
 170 <A HREF="#errordocument">ErrorDocument</A>,
 171 <A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>, etc.).
 172 <dt>Indexes
 173 <dd>
 174 <!--%plaintext &lt;?INDEX {\tt Indexes} override&gt; -->
 175 Allow use of the directives controlling directory indexing
 176 (<A HREF="mod_autoindex.html#adddescription">AddDescription</A>,
 177 <A HREF="mod_autoindex.html#addicon">AddIcon</A>,
 178 <A HREF="mod_autoindex.html#addiconbyencoding">AddIconByEncoding</A>,
 179 <A HREF="mod_autoindex.html#addiconbytype">AddIconByType</A>,
 180 <A HREF="mod_autoindex.html#defaulticon">DefaultIcon</A>,
 181 <A HREF="mod_dir.html#directoryindex">DirectoryIndex</A>,
 182 <A HREF="mod_autoindex.html#fancyindexing">FancyIndexing</A>,
 183 <A HREF="mod_autoindex.html#headername">HeaderName</A>,
 184 <A HREF="mod_autoindex.html#indexignore">IndexIgnore</A>,
 185 <A HREF="mod_autoindex.html#indexoptions">IndexOptions</A>,
 186 <A HREF="mod_autoindex.html#readmename">ReadmeName</A>, etc.).
 187 <dt>Limit
 188 <dd>
 189 <!--%plaintext &lt;?INDEX {\tt Limit} override&gt; -->
 190 Allow use of the directives controlling host access (allow, deny and order).
 191 <dt>Options
 192 <dd>
 193 <!--%plaintext &lt;?INDEX {\tt Options} override&gt; -->
 194 Allow use of the directives controlling specific directory features
 195 (<A HREF="#options">Options</A> and
 196 <A HREF="mod_include.html#xbithack">XBitHack</A>).
 197 </dl><p><hr>
 198
 199 <h2><A name="authname">AuthName directive</A></h2>
 200 <!--%plaintext &lt;?INDEX {\tt AuthName} directive&gt; -->
 201 <strong>Syntax:</strong> AuthName <em>auth-domain</em><br>
 202 <strong>Context:</strong> directory, .htaccess<br>
 203 <strong>Override:</strong> AuthConfig<br>
 204 <strong>Status:</strong> core<p>
 205
 206 This directive sets the name of the authorization realm for a directory.
 207 This realm is given to the client so that the user knows which username and
 208 password to send.
 209 It must be accompanied by <A HREF="#authtype">AuthType</A> and
 210 <A HREF="#require">require</A> directives, and directives such as
 211 <A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and
 212 <A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr>
 213
 214 <h2><A name="authtype">AuthType directive</A></h2>
 215 <!--%plaintext &lt;?INDEX {\tt AuthType} directive&gt; -->
 216 <strong>Syntax:</strong> AuthType <em>type</em><br>
 217 <strong>Context:</strong> directory, .htaccess<br>
 218 <strong>Override:</strong> AuthConfig<br>
 219 <strong>Status:</strong> core<p>
 220
 221 This directive selects the type of user authentication for a directory.
 222 Only <code>Basic</code> is currently implemented.
 223 <!--%plaintext &lt;?INDEX {\tt Basic} authentication scheme&gt; -->
 224 It must be accompanied by <A HREF="#authname">AuthName</A> and
 225 <A HREF="#require">require</A> directives, and directives such as
 226 <A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and
 227 <A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr>
 228
 229 <h2><A name="bindaddress">BindAddress directive</A></h2>
 230 <!--%plaintext &lt;?INDEX {\tt BindAddress} directive&gt; -->
 231 <strong>Syntax:</strong> BindAddress <em>saddr</em><br>
 232 <strong>Default:</strong> <code>BindAddress *</code><br>
 233 <strong>Context:</strong> server config<br>
 234 <strong>Status:</strong> core<p>
 235
 236 A Unix&#174; http server can either listen for connections to every
 237 IP address of the server machine, or just one IP address of the server
 238 machine. <em>Saddr</em> can be
 239
 240 <menu>
 241 <li>*
 242 <li>An IP address
 243 <li>A fully-qualified Internet domain name
 244 </menu>
 245 If the value is *, then the server will listen for connections on
 246 every IP address, otherwise it will only listen on the IP address
 247 specified. <p>
 248
 249 Only one <code>BindAddress</code> directive can be used. For more
 250 control over which address and ports Apache listens to, use the
 251 <code><a href="#listen">Listen</a></code> directive instead of
 252 <code>BindAddress</code>.<p>
 253
 254 <code>BindAddress</code> can be used as an alternative method for
 255 supporting <A HREF="../virtual-host.html">virtual hosts</A> using
 256 multiple independent servers, instead of using <code><A
 257 HREF="#virtualhost">&lt;VirtualHost&gt;</A></code> sections.
 258
 259 <p><strong>See Also:</strong>
 260 <a href="../dns-caveats.html">DNS Issues</a><br>
 261 <strong>See Also:</strong>
 262 <a href="../bind.html">Setting which addresses and ports Apache uses</a></p>
 263
 264 <hr>
 265
 266 <h2><A name="clearmodulelist">ClearModuleList directive</A></h2>
 267 <!--%plaintext &lt;?INDEX {\tt ClearModuleList} directive&gt; -->
 268 <strong>Syntax:</strong> ClearModuleList<br>
 269 <strong>Context:</strong> server config<br>
 270 <strong>Status:</strong> core<br>
 271 <strong>Compatibility:</strong> ClearModuleList is only available in Apache 1.2 and later<p>
 272
 273 The server comes with a built-in list of active modules.  This
 274 directive clears the list.  It is assumed that the list will then be
 275 re-populated using the <A HREF="#addmodule">AddModule</A> directive.<p><hr>
 276
 277 <h2><A name="contentdigest">ContentDigest directive</A></h2>
 278 <!--%plaintext &lt;?INDEX {\tt ContentDigest} directive&gt; -->
 279 <strong>Syntax:</strong> ContentDigest <em>on|off</em><br>
 280 <strong>Default:</strong> <code>ContentDigest off</code><br>
 281 <strong>Context:</strong> any<br>
 282 <strong>Override:</strong> AuthConfig<br>
 283 <strong>Status:</strong> experimental<p>
 284 <strong>Compatibility:</strong> ContentDigest is only available in Apache 1.1 and later<p>
 285
 286 This directive enables the generation of <code>Content-MD5</code> headers
 287 as defined in RFC1864 respectively RFC2068.<P>
 288
 289 MD5 is an algorithm for computing a "message digest" (sometimes called
 290 "fingerprint") of arbitrary-length data, with a high degree of confidence
 291 that any alterations in the data will be reflected in alterations in the
 292 message digest.<P>
 293
 294 The <code>Content-MD5</code> header provides an end-to-end message
 295 integrity check (MIC) of the entity-body. A proxy or client may check this
 296 header for detecting accidental modification of the entity-body
 297 in transit.
 298 Example header:
 299 <pre>   Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==</pre><P>
 300
 301 Note that this can cause performance problems on your server
 302 since the message digest is computed on every request
 303 (the values are not cached).<P>
 304
 305 <code>Content-MD5</code> is only sent for documents served by the
 306 core, and not by any module.  For example, SSI documents, output from
 307 CGI scripts, and byte range responses do not have this header.
 308
 309 <hr>
 310
 311 <h2><A name="coredumpdirectory">CoreDumpDirectory directive</A></h2>
 312 <!--%plaintext &lt;?INDEX {\tt CoreDumpDirectory} directive&gt; -->
 313 <strong>Syntax:</strong> CoreDumpDirectory <em>directory</em><br>
 314 <strong>Default:</strong> the same location as ServerRoot<br>
 315 <strong>Context:</strong> server config<br>
 316 <strong>Status:</strong> core<p>
 317
 318 This controls the directory to which Apache attempts to switch before
 319 dumping core.  The default is in the <A HREF="#serverroot">ServerRoot</A>
 320 directory, however since this should not be writable by the user
 321 the server runs as, core dumps won't normally get written.  If you
 322 want a core dump for debugging, you can use this directive to place
 323 it in a different location.<p><hr>
 324
 325 <h2><A name="defaulttype">DefaultType directive</A></h2>
 326 <!--%plaintext &lt;?INDEX {\tt DefaultType} directive&gt; -->
 327 <strong>Syntax:</strong> DefaultType <em>mime-type</em><br>
 328 <strong>Default:</strong> <code>DefaultType text/html</code><br>
 329 <strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
 330 <strong>Override:</strong> FileInfo<br>
 331 <strong>Status:</strong> core<p>
 332
 333 There will be times when the server is asked to provide a document
 334 whose type cannot be determined by its MIME types mappings.<p>
 335
 336 The server must inform the client of the content-type of the document, so in
 337 the event of an unknown type it uses the <CODE>DefaultType</CODE>. For
 338 example:
 339 <blockquote><code>DefaultType image/gif</code></blockquote>
 340 would be appropriate for a directory which contained many gif images
 341 with filenames missing the .gif extension.<p><hr>
 342
 343 <h2><A name="directory">&lt;Directory&gt; directive</A></h2>
 344 <!--%plaintext &lt;?INDEX {\tt Directory} section directive&gt; -->
 345 <strong>Syntax:</strong> &lt;Directory <em>directory</em>&gt; ... &lt;/Directory&gt; <br>
 346 <strong>Context:</strong> server config, virtual host<br>
 347 <strong>Status:</strong> Core. <p>
 348
 349 &lt;Directory&gt; and &lt;/Directory&gt; are used to enclose a group of
 350 directives which will apply only to the named directory and sub-directories
 351 of that directory. Any directive which is allowed in a directory
 352 context may be used. <em>Directory</em> is either the full path to a directory,
 353 or a wild-card string. In a wild-card string, `?' matches any single character,
 354 and `*' matches any sequences of characters.  As of Apache 1.3, you
 355 may also use `[]' character ranges like in the shell.  Also as of Apache 1.3
 356 none of the wildcards match a `/' character, which more closely mimics the
 357 behaviour of Unix shells.
 358 Example:
 359 <pre>
 360    &lt;Directory /usr/local/httpd/htdocs&gt;
 361    Options Indexes FollowSymLinks
 362    &lt;/Directory&gt;
 363 </pre>
 364
 365 <p><strong>Apache 1.2 and above:</strong>
 366 Extended regular expressions can also be used, with the addition of the
 367 <code>~</code> character. For example:</p>
 368
 369 <pre>
 370    &lt;Directory ~ &quot;^/www/.*/[0-9]{3}&quot;&gt;
 371 </pre>
 372
 373 would match directories in /www/ that consisted of three numbers.</p>
 374
 375 <p>If multiple (non-regular expression) directory sections match the
 376 directory (or its parents) containing
 377 a document, then the directives are applied in the order of shortest match
 378 first, interspersed with the directives from the
 379 <A HREF="#accessfilename">.htaccess</A> files. For example, with
 380 <blockquote><code>
 381 &lt;Directory /&gt;<br>
 382 AllowOverride None<br>
 383 &lt;/Directory&gt;<br><br>
 384 &lt;Directory /home/*&gt;<br>
 385 AllowOverride FileInfo<br>
 386 &lt;/Directory&gt;</code></blockquote>
 387 for access to the document <code>/home/web/dir/doc.html</code> the
 388 steps are:
 389 <menu>
 390 <li>Apply directive <code>AllowOverride None</code> (disabling
 391 <code>.htaccess</code> files).
 392 <li>Apply directive <code>AllowOverride FileInfo</code> (for directory
 393 <code>/home/web</code>).
 394 <li>Apply any FileInfo directives in <code>/home/web/.htaccess</code>
 395 </menu>
 396
 397 <P>
 398 Regular expression directory sections are handled slightly differently
 399 by Apache 1.2 and 1.3.  In Apache 1.2 they are interspersed with the normal
 400 directory sections and applied in the order they appear in the configuration
 401 file.  They are applied only once, and apply when the shortest match
 402 possible occurs.  In Apache 1.3 regular expressions are not considered
 403 until after all of the normal sections have been applied.  Then all of
 404 the regular expressions are tested in the order they appeared in the
 405 configuration file.  For example, with
 406 <blockquote><code>
 407 &lt;Directory ~ abc$&gt;<br>
 408 ... directives here ...<br>
 409 &lt;/Directory&gt;<br>
 410 </code></blockquote>
 411 Suppose that the filename being accessed is
 412 <code>/home/abc/public_html/abc/index.html</code>.  The server
 413 considers each of <code>/</code>, <code>/home</code>, <code>/home/abc</code>,
 414 <code>/home/abc/public_html</code>, and <code>/home/abc/public_html/abc</code>
 415 in that order.   In Apache 1.2, when
 416 <code>/home/abc</code> is considered, the regular expression will match
 417 and be applied.  In Apache 1.3 the regular expression isn't considered
 418 at all at that point in the tree.  It won't be considered until after
 419 all normal &lt;Directory&gt;s and <code>.htaccess</code> files have
 420 been applied.  Then the regular expression will
 421 match on <code>/home/abc/public_html/abc</code> and be applied.
 422
 423 <P>
 424
 425 <STRONG>
 426 Note that the default Apache access for &lt;Directory /&gt; is
 427 <SAMP>Allow from All</SAMP>.  This means that Apache will serve any file
 428 mapped from an URL.  It is recommended that you change this with a block
 429 such as
 430 </STRONG>
 431 <PRE>
 432  &lt;Directory /&gt;
 433      Order Deny,Allow
 434      Deny from All
 435  &lt;/Directory&gt;
 436 </PRE>
 437 <P>
 438 <STRONG>
 439 and then override this for directories you <EM>want</EM> accessible.
 440 See the
 441 <A
 442  HREF="../misc/security_tips.html"
 443 >Security Tips</A>
 444 page for more details.
 445 </STRONG>
 446 </P>
 447
 448 The directory sections typically occur in the access.conf file, but they
 449 may appear in any configuration file. &lt;Directory&gt; directives cannot
 450 nest, and cannot appear in a <A HREF="#limit">&lt;Limit&gt;</A> section.
 451 <p>
 452
 453 <strong>See also</strong>: <a href="../sections.html">How Directory,
 454 Location and Files sections work</a> for an explanation of how these
 455 different sections are combined when a request is received
 456
 457 <hr>
 458
 459 <h2><A name="directorymatch">&lt;DirectoryMatch&gt;</A></h2>
 460 <strong>Syntax:</strong> &lt;DirectoryMatch <em>regex</em>&gt; ... &lt;/DirectoryMatch&gt; <br>
 461 <strong>Context:</strong> server config, virtual host<br>
 462 <strong>Status:</strong> Core.<br>
 463 <strong>Compatibility:</strong> Available in Apache 1.3 and later
 464
 465 <p>&lt;DirectoryMatch&gt; and &lt;/DirectoryMatch&gt; are used to enclose a group of
 466 directives which will apply only to the named directory and sub-directories
 467 of that directory, the same as <a
 468 href="#directory">&lt;Directory&gt;</a>. However, it takes as an
 469 argument a regular expression. For example:</p>
 470
 471 <pre>
 472    &lt;DirectoryMatch &quot;^/www/.*/[0-9]{3}&quot;&gt;
 473 </pre>
 474
 475 <p>would match directories in /www/ that consisted of three numbers.</p>
 476
 477 <p><strong>See Also:</strong>
 478 <a href="#directory">&lt;Directory&gt;</a> for a description of how
 479 regular expressions are mixed in with normal &lt;Directory&gt;s.
 480 <br>
 481 <strong>See also</strong>: <a href="../sections.html">How Directory,
 482 Location and Files sections work</a> for an explanation of how these
 483 different sections are combined when a request is received
 484
 485 <hr>
 486
 487 <h2><A NAME="documentroot">DocumentRoot directive</A></h2>
 488 <!--%plaintext &lt;?INDEX {\tt DocumentRoot} directive&gt; -->
 489 <strong>Syntax:</strong> DocumentRoot <em>directory-filename</em><br>
 490 <strong>Default:</strong> <code>DocumentRoot
 491 /usr/local/etc/httpd/htdocs</code><br>
 492 <strong>Context:</strong> server config, virtual host<br>
 493 <strong>Status:</strong> core<p>
 494
 495 This directive sets the directory from which httpd will serve files.
 496 Unless matched by a directive like Alias, the server appends the path
 497 from the requested URL to the document root to make the path to the
 498 document. Example:
 499 <blockquote><code>DocumentRoot /usr/web</code></blockquote>
 500 then an access to <code>http://www.my.host.com/index.html</code> refers
 501 to <code>/usr/web/index.html</code>.
 502
 503 <P>There appears to be a bug in mod_dir which causes problems when the
 504 DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so
 505 please avoid that.
 506
 507 <p><hr>
 508
 509 <h2><A name="errordocument">ErrorDocument directive</A></h2>
 510 <!--%plaintext &lt;?INDEX {\tt ErrorDocument} directive&gt; -->
 511 <strong>Syntax:</strong> ErrorDocument <em>error-code document</em><br>
 512 <strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
 513 <strong>Status:</strong> core<br>
 514 <strong>Override:</strong> FileInfo<br>
 515 <strong>Compatibility:</strong> The directory and .htaccess contexts
 516 are only available in Apache 1.1 and later.<p>
 517
 518 In the event of a problem or error, Apache can be configured to do
 519 one of four things,
 520
 521 <OL>
 522 <LI>output a simple hardcoded error message
 523 <LI>output a customized message
 524 <LI>redirect to a local URL to handle the problem/error
 525 <LI>redirect to an external URL to handle the problem/error
 526 </OL>
 527
 528 <P>The first option is the default, while options 2-4 are configured
 529 using the <CODE>ErrorDocument</CODE> directive, which is followed by
 530 the HTTP response code and a message or URL.
 531
 532 <P><em>Messages</em> in this context begin with a single quote
 533 (<code>"</code>), which does not form part of the message itself.
 534 Apache will sometimes offer additional information regarding the
 535 problem/error.
 536
 537 <P>URLs can begin with a slash (/) for local URLs, or be a full
 538 URL which the client can resolve. Examples:
 539 <blockquote><code>
 540 ErrorDocument 500 http://foo.example.com/cgi-bin/tester<br>
 541 ErrorDocument 404 /cgi-bin/bad_urls.pl<br>
 542 ErrorDocument 401 /subscription_info.html<br>
 543 ErrorDocument 403 "Sorry can't allow you access today
 544 </code></blockquote>
 545
 546 <P>Note that when you specify an <CODE>ErrorDocument</CODE> that
 547 points to a remote URL (ie. anything with a method such as "http" in
 548 front of it) Apache will send a redirect to the client to tell it
 549 where to find the document, even if the document ends up being
 550 on the same server..  This has several implications, the
 551 most important being that <STRONG>if you use an "ErrorDocument 401"
 552 directive then it must refer to a local document.</STRONG>  This results
 553 from the nature of the HTTP basic authentication scheme.
 554
 555 <P>See Also: <A HREF="../custom-error.html">documentation of customizable
 556 responses.</A><p><hr>
 557
 558 <h2><A name="errorlog">ErrorLog directive</A></h2>
 559 <!--%plaintext &lt;?INDEX {\tt ErrorLog} directive&gt; -->
 560 <strong>Syntax:</strong> ErrorLog <em>filename</em><br>
 561 <strong>Default:</strong> <code>ErrorLog logs/error_log</code><br>
 562 <strong>Context:</strong> server config, virtual host<br>
 563 <strong>Status:</strong> core<p>
 564
 565 The error log directive sets the name of the file to which the server will log
 566 any errors it encounters. If the filename does not begin with a slash (/)
 567 then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>.
 568 Example:
 569 <blockquote><code>ErrorLog /dev/null</code></blockquote>
 570 This effectively turns off error logging.<p>
 571
 572 SECURITY: See the <A HREF="../misc/security_tips.html">security tips</A>
 573 document for details on why your security could be compromised if
 574 the directory where logfiles are stored is writable by anyone other
 575 than the user that starts the server.
 576
 577 <p><hr>
 578
 579 <h2><A name="files">&lt;Files&gt; directive</A></h2>
 580 <strong>Syntax:</strong> &lt;Files <em>filename</em>&gt;
 581 ... &lt;/Files&gt;<br>
 582 <strong>Context:</strong> server config, virtual host, .htaccess<br>
 583 <strong>Status:</strong> core<br>
 584 <strong>Compatibility:</strong> only available in Apache
 585 1.2 and above.<p>
 586
 587 <p>The &lt;Files&gt; directive provides for access control by
 588 filename. It is comparable to the <a
 589 href="#directory">&lt;Directory&gt;</a> directive and
 590 <a href="#location">&lt;Location&gt;</a> directives. It
 591 should be matched with a &lt;/Files&gt; directive. Directives that
 592 apply to the filename given should be listed
 593 within. <code>&lt;Files&gt;</code> sections are processed in the
 594 order they appear in the configuration file, after the
 595 &lt;Directory&gt; sections and <code>.htaccess</code> files are
 596 read, but before &lt;Location&gt; sections.</p>
 597
 598 <p>The <em>filename</em> argument should include a filename, or a
 599 wild-card string, where `?' matches any single character, and `*' matches any
 600 sequences of characters. Extended regular expressions can also be used,
 601 with the addition of
 602 the <code>~</code> character. For example:</p>
 603
 604 <pre>
 605    &lt;Files ~ &quot;\.(gif|jpe?g|png)$&quot;&gt;
 606 </pre>
 607
 608 would match most common Internet graphics formats. In Apache 1.3 and
 609 later, <a href="#filesmatch">&lt;FilesMatch&gt;</a> is preferred,
 610 however.
 611
 612 <p>Note that unlike <a
 613 href="#directory"><code>&lt;Directory&gt;</code></a> and <a
 614 href="#location"><code>&lt;Location&gt;</code></a> sections,
 615 <code>&lt;Files&gt;</code> sections can be used inside .htaccess
 616 files. This allows users to control access to their own files, at a
 617 file-by-file level. When used in an .htaccess file, if the
 618 <em>filename</em> does not begin with a <code>/</code> character,
 619 the directory being applied will be prefixed automatically.
 620
 621 <p>
 622
 623 <strong>See also</strong>: <a href="../sections.html">How Directory,
 624 Location and Files sections work</a> for an explanation of how these
 625 different sections are combined when a request is received
 626
 627 <hr>
 628
 629 <h2><A name="filesmatch">&lt;FilesMatch&gt;</A></h2>
 630 <strong>Syntax:</strong> &lt;FilesMatch <em>regex</em>&gt;
 631 ... &lt;/Files&gt;<br>
 632 <strong>Context:</strong> server config, virtual host, .htaccess<br>
 633 <strong>Status:</strong> core<br>
 634 <strong>Compatibility:</strong> only available in Apache
 635 1.3 and above.<p>
 636
 637 <p>The &lt;FilesMatch&gt; directive provides for access control by
 638 filename, just as the <a href="#files">&lt;Files&gt;</a> directive
 639 does. However, it accepts a regular expression. For example:</p>
 640
 641 <pre>
 642    &lt;FilesMatch &quot;\.(gif|jpe?g|png)$&quot;&gt;
 643 </pre>
 644
 645 <p>would match most common Internet graphics formats.</p>
 646
 647 <strong>See also</strong>: <a href="../sections.html">How Directory,
 648 Location and Files sections work</a> for an explanation of how these
 649 different sections are combined when a request is received
 650
 651 <hr>
 652
 653 <h2><A name="group">Group directive</A></h2>
 654 <!--%plaintext &lt;?INDEX {\tt Group} directive&gt; -->
 655 <strong>Syntax:</strong> Group <em>unix-group</em><br>
 656 <strong>Default:</strong> <code>Group #-1</code><br>
 657 <strong>Context:</strong> server config, virtual host<br>
 658 <strong>Status:</strong> core<p>
 659
 660 The Group directive sets the group under which the server will answer requests.
 661 In order to use this directive, the stand-alone server must be run initially
 662 as root. <em>Unix-group</em> is one of:
 663 <dl>
 664 <dt>A group name
 665 <dd>Refers to the given group by name.
 666 <dt># followed by a group number.
 667 <dd>Refers to a group by its number.
 668 </dl>
 669
 670 It is recommended that you set up a new group specifically for running the
 671 server. Some admins use user <code>nobody</code>, but this is not always
 672 possible or desirable.<p>
 673
 674 Note: if you start the server as a non-root user, it will fail to change
 675 to the specified group, and will instead continue to run as the group of the
 676 original user. <p>
 677
 678 Special note: Use of this directive in &lt;VirtualHost&gt; requires a
 679 properly configured <A HREF="../suexec.html">suEXEC wrapper</A>.
 680 When used inside a &lt;VirtualHost&gt; in this manner, only the group
 681 that CGIs are run as is affected.  Non-CGI requests are still processed
 682 as the group specified in the main Group directive.<p>
 683
 684 SECURITY: See <A HREF="#user">User</A> for a discussion of the security
 685 considerations.<p><hr>
 686
 687 <h2><A name="hostnamelookups">HostNameLookups directive</A></h2>
 688 <!--%plaintext &lt;?INDEX {\tt HostNameLookups} directive&gt; -->
 689 <strong>Syntax:</strong> HostNameLookups <em>on | off | double</em><br>
 690 <strong>Default:</strong> <code>HostNameLookups off</code><br>
 691 <strong>Context:</strong> server config, virtual host<br>
 692 <strong>Status:</strong> core<br>
 693 <strong>Compatibility:</strong> <code>double</code> available only in Apache
 694 1.3 and above.<br>
 695 <strong>Compatibility:</strong> Default was <code>on</code> prior to Apache
 696 1.3.<p>
 697
 698 This directive enables DNS lookups so that host names can be logged (and
 699 passed to CGIs/SSIs in <code>REMOTE_HOST</code>).
 700 The value <code>double</code> refers to doing double-reverse DNS.
 701 That is, after a reverse lookup is performed, a forward lookup is then
 702 performed on that result.  At least one of the ip addresses in the forward
 703 lookup must match the original address.  (In "tcpwrappers" terminology
 704 this is called <code>PARANOID</code>.)<p>
 705
 706 Regardless of the setting, when <a href="mod_access.html">mod_access</a>
 707 is used for controlling access by hostname, a double reverse lookup
 708 will be performed.  This is necessary for security.  Note that the
 709 result of this double-reverse isn't generally available unless
 710 you set <code>HostnameLookups double</code>.  For example, if only
 711 <code>HostnameLookups on</code> and a request is made to an object that
 712 is protected by hostname restrictions, regardless of whether the
 713 double-reverse fails or not, CGIs will still be passed the single-reverse
 714 result in <code>REMOTE_HOST</code>.<p>
 715
 716 The default for this directive was previously <code>on</code> in
 717 versions of Apache prior to 1.3.  It was changed to <code>off</code>
 718 in order to save the network traffic for those sites that don't truly
 719 need the reverse lookups done.  It is also better for the end users
 720 because they don't have to suffer the extra latency that a lookup
 721 entails.
 722 Heavily loaded sites should leave this directive <code>off</code>, since DNS
 723 lookups can take considerable amounts of time. The utility <i>logresolve</i>,
 724 provided in the <i>/support</i> directory, can be used to look up host names
 725 from logged IP addresses offline.<p><hr>
 726
 727 <h2><A name="identitycheck">IdentityCheck directive</A></h2>
 728 <!--%plaintext &lt;?INDEX {\tt IdentityCheck} directive&gt; -->
 729 <strong>Syntax:</strong> IdentityCheck <em>boolean</em><br>
 730 <strong>Default:</strong> <code>IdentityCheck off</code><br>
 731 <strong>Context:</strong> server config, virtual host<br>
 732 <strong>Status:</strong> core<p>
 733
 734 This directive enables RFC1413-compliant logging of the remote user name
 735 for each connection, where the client machine runs identd or something similar.
 736 This information is logged in the access log. <em>Boolean</em> is either
 737 <code>on</code> or <code>off</code>.<p>
 738
 739 The information should not be trusted in any way except for rudimentary usage
 740 tracking.<p>
 741
 742 Note that this can cause serious latency problems accessing your server
 743 since every request requires one of these lookups to be performed.  When
 744 firewalls are involved each lookup might possibly fail and add 30 seconds
 745 of latency to each hit.  So in general this is not very useful on public
 746 servers accessible from the Internet.
 747 <p><hr>
 748
 749 <H2><A NAME="ifmodule">&lt;IfModule&gt; directive</A></H2>
 750 <b>Syntax:</b> &lt;IfModule [!]<i>module-name</i>&gt; <i>...</i>
 751 &lt;/IfModule&gt;<br>
 752 <b>Default:</b> None<br>
 753 <b>Context:</b> all<br>
 754 <b>Status:</b> Core<br>
 755 <strong>Compatibility:</strong> IfModule is only available in 1.2 and
 756 later.<P>
 757
 758 <p>
 759
 760 The &lt;IfModule <i>test</i>&gt;...&lt;/IfModule&gt;
 761 section is used to mark directives that are conditional. The
 762 directives within an IfModule section are only
 763 processed if the <i>test</i> is true. If <i>test</i>
 764 is false, everything between the start and end markers
 765 is ignored.<p>
 766
 767 The <i>test</i> in the &lt;IfModule&gt; section directive
 768 can be one of two forms:
 769
 770 <ul>
 771 <li><i>module name</i>
 772 <li>!<i>module name</i>
 773 </ul>
 774
 775 <p>In the former case, the directives between the start and end markers
 776 are only processed if the module named <i>module name</i> is compiled
 777 in to Apache. The second format reverses the test, and only processes
 778 the directives if <i>module name</i> is <b>not</b> compiled in.
 779
 780 <p>The <i>module name</i> argument is a module name as given as the file
 781 name of the module, at the time it was compiled. For example,
 782 <code>mod_rewrite.c</code>.
 783
 784 <p>&lt;IfModule&gt; sections are nest-able, which can be used to implement
 785 simple multiple-module tests.
 786
 787 <P> <hr>
 788
 789 <h2><a name="include">Include directive</a></h2>
 790 <strong>Syntax: (Apache 1.2)</strong> Include <em>filename</em><br>
 791 <strong>Context:</strong> server config<br>
 792 <strong>Status:</strong> Core<br>
 793 <strong>Compatibility:</strong> Include is only available in Apache 1.3 and later.
 794 <P>
 795 This directive allows inclusion of other configuration files from within the server configuration files.
 796
 797 <P> <hr>
 798
 799 <h2><a name="keepalive">KeepAlive directive</a></h2>
 800 <strong>Syntax: (Apache 1.1)</strong> KeepAlive <em>max-requests</em><br>
 801 <strong>Default: (Apache 1.1)</strong> <code>KeepAlive 5</code><br>
 802 <strong>Syntax: (Apache 1.2)</strong> KeepAlive <em>on/off</em><br>
 803 <strong>Default: (Apache 1.2)</strong> <code>KeepAlive On</code><br>
 804 <strong>Context:</strong> server config<br>
 805 <strong>Status:</strong> Core<br>
 806 <strong>Compatibility:</strong> KeepAlive is only available in Apache
 807 1.1 and later.<p>
 808
 809 This directive enables
 810 <a href="../keepalive.html">Keep-Alive</a>
 811 support.
 812
 813 <p><strong>Apache 1.1</strong>: Set <em>max-requests</em>
 814 to the maximum number of requests you want Apache to entertain per
 815 request. A limit is imposed to prevent a client from hogging your
 816 server resources. Set this to <code>0</code> to disable support.
 817
 818 <p><strong>Apache 1.2 and later</strong>: Set to "On" to enable
 819 persistent connections, "Off" to disable. See also the <a
 820 href="#maxkeepaliverequests">MaxKeepAliveRequests</a> directive.</p><hr>
 821
 822 <h2><a name="keepalivetimeout">KeepAliveTimeout directive</a></h2>
 823 <strong>Syntax:</strong> KeepAliveTimeout <em>seconds</em><br>
 824 <strong>Default:</strong> <code>KeepAliveTimeout 15</code><br>
 825 <strong>Context:</strong> server config<br>
 826 <strong>Status:</strong> Core<br>
 827 <strong>Compatibility:</strong> KeepAliveTimeout is only available in Apache
 828 1.1 and later.<p>
 829
 830 The number of seconds Apache will wait for a subsequent request before
 831 closing the connection. Once a request has been received, the timeout
 832 value specified by the <a
 833 href="#timeout"><code>Timeout</code></a> directive
 834 applies.
 835 <hr>
 836
 837 <h2><A name="limit">&lt;Limit&gt; directive</A></h2>
 838 <!--%plaintext &lt;?INDEX {\tt Limit} section directive&gt; -->
 839 <strong>Syntax:</strong>
 840  &lt;Limit <em>method method</em> ... &gt; ... &lt;/Limit&gt;<br>
 841 <strong>Context:</strong> any<br>
 842 <strong>Status:</strong> core<p>
 843
 844 &lt;Limit&gt; and &lt;/Limit&gt; are used to enclose a group of
 845 access control directives which will then apply only to the specified
 846 access methods, where <em>method</em> is any valid HTTP method.
 847 Any directive except another &lt;Limit&gt; or
 848 <A HREF="#directory">&lt;Directory&gt;</A> may be used; the majority will be
 849 unaffected by the &lt;Limit&gt;. Example:
 850 <blockquote><code>
 851 &lt;Limit GET POST&gt;<br>
 852 require valid-user<br>
 853 &lt;/Limit&gt;</code></blockquote>
 854
 855 If an access control directive appears outside a &lt;Limit&gt;
 856 directive, then it applies to all access methods. The method names
 857 listed can be one or more of: GET, POST, PUT, DELETE, CONNECT or
 858 OPTIONS. If GET is used it will also restrict HEAD requests.
 859 <STRONG>If you wish to limit all methods, do not include any
 860 &lt;Limit&gt; directive at all.</STRONG> <p><hr>
 861
 862 <h2><A name="listen">Listen directive</A></h2>
 863 <strong>Syntax:</strong>
 864 Listen [<em>IP address</em>:]<em>port number</em><br>
 865 <strong>Context:</strong> server config<br>
 866 <strong>Status:</strong> core<br>
 867 <strong>Compatibility:</strong> Listen is only available in Apache
 868 1.1 and later.<p>
 869
 870 <p>The Listen directive instructs Apache to listen to more than one IP
 871 address or port; by default it responds to requests on all IP
 872 interfaces, but only on the port given by the <code><a
 873 href="#port">Port</a></code> directive.</p>
 874
 875 <tt>Listen</tt> can be used instead of <tt><a
 876 href="bindaddress">BindAddress</a></tt> and <tt>Port</tt>. It tells
 877 the server to accept incoming requests on the specified port or
 878 address-and-port combination. If the first format is used, with a port
 879 number only, the server listens to the given port on all interfaces,
 880 instead of the port given by the <tt>Port</tt> directive. If an IP
 881 address is given as well as a port, the server will listen on the
 882 given port and interface.  <p>
 883
 884 Note that you may still require a <tt>Port</tt> directive so
 885 that URLs that Apache generates that point to your server still
 886 work.<p>
 887
 888 Multiple Listen directives may be used
 889 to specify a number of addresses and ports to listen to. The server
 890 will respond to requests from any of the listed addresses and
 891 ports.
 892 <p>
 893
 894 For example, to make the server accept connections on both port
 895 80 and port 8000, use:
 896 <pre>
 897    Listen 80
 898    Listen 8000
 899 </pre>
 900
 901 To make the server accept connections on two specified
 902 interfaces and port numbers, use
 903 <pre>
 904    Listen 192.170.2.1:80
 905    Listen 192.170.2.5:8000
 906 </pre>
 907
 908 <p><strong>See Also:</strong>
 909 <a href="../dns-caveats.html">DNS Issues</a><br>
 910 <strong>See Also:</strong>
 911 <a href="../bind.html">Setting which addresses and ports Apache uses</a><br>
 912 <strong>See Also:</strong>
 913 <a href="../misc/known_bugs.html#listenbug">Known Bugs</a></p>
 914 <hr>
 915
 916 <H2><A NAME="listenbacklog">ListenBacklog directive</A></H2>
 917 <strong>Syntax:</strong> ListenBacklog <em>backlog</em><br>
 918 <strong>Default:</strong> <code>ListenBacklog 511</code><br>
 919 <strong>Context:</strong> server config<br>
 920 <strong>Status:</strong> Core<br>
 921 <strong>Compatibility:</strong> ListenBacklog is only available in Apache
 922 versions after 1.2.0.<p>
 923
 924 The maximum length of the queue of pending connections.  Generally no
 925 tuning is needed or desired, however on some systems it is desirable
 926 to increase this when under a TCP SYN flood attack.  See
 927 the backlog parameter to the <code>listen(2)</code> system call.</p><hr>
 928
 929 <h2><a name="location">&lt;Location&gt; directive</a></h2>
 930
 931 <strong>Syntax:</strong> &lt;Location <em>URL</em>&gt;
 932 ... &lt;/Location&gt;<br>
 933 <strong>Context:</strong> server config, virtual host<br>
 934 <strong>Status:</strong> core<br>
 935 <strong>Compatibility:</strong> Location is only available in Apache
 936 1.1 and later.<p>
 937
 938 <p>The &lt;Location&gt; directive provides for access control by
 939 URL. It is comparable to the <a
 940 href="#directory">&lt;Directory&gt;</a> directive, and
 941 should be matched with a &lt;/Location&gt; directive. Directives that
 942 apply to the URL given should be listed
 943 within. <code>&lt;Location&gt;</code> sections are processed in the
 944 order they appear in the configuration file, after the
 945 &lt;Directory&gt; sections and <code>.htaccess</code> files are
 946 read.</p>
 947
 948 <p>Note that, due to the way HTTP functions, <em>URL prefix</em>
 949 should, save for proxy requests, be of the form <code>/path/</code>,
 950 and should not include the <code>http://servername</code>. It doesn't
 951 necessarily have to protect a directory (it can be an individual
 952 file, or a number of files), and can include wild-cards.  In a wild-card
 953 string, `?' matches any single character, and `*' matches any
 954 sequences of characters.
 955
 956 <p><strong>Apache 1.2 and above:</strong>
 957 Extended regular expressions can also be used, with the addition of
 958 the
 959 <code>~</code> character. For example:</p>
 960
 961 <pre>
 962    &lt;Location ~ &quot;/(extra|special)/data&quot;&gt;
 963 </pre>
 964
 965 <p>would match URLs that contained the substring "/extra/data" or
 966 "/special/data". However, in Apache 1.3 and above, use of <a
 967 href="#locationmatch">&lt;LocationMatch&gt;</a> is preferred.</p>
 968
 969 <p>The <code>Location</code> functionality is especially useful when
 970 combined with the <code><a
 971 href="mod_mime.html#sethandler">SetHandler</a></code> directive. For example, to enable status requests, but allow them only
 972 from browsers at foo.com, you might use:
 973
 974 <pre>
 975     &lt;Location /status&gt;
 976     SetHandler server-status
 977     order deny,allow
 978     deny from all
 979     allow from .foo.com
 980     &lt;/Location&gt;
 981 </pre>
 982
 983 <p>
 984 <strong>See also</strong>: <a href="../sections.html">How Directory,
 985 Location and Files sections work</a> for an explanation of how these
 986 different sections are combined when a request is received
 987
 988 <hr>
 989
 990 <h2><a name="locationmatch">&lt;LocationMatch&gt;</a></h2>
 991
 992 <strong>Syntax:</strong> &lt;LocationMatch <em>regex</em>&gt;
 993 ... &lt;/LocationMatch&gt;<br>
 994 <strong>Context:</strong> server config, virtual host<br>
 995 <strong>Status:</strong> core<br>
 996 <strong>Compatibility:</strong> Location is only available in Apache
 997 1.3 and later.<p>
 998
 999 <p>The &lt;LocationMatch&gt; directive provides for access control by
1000 URL, in an identical manner to <a
1001 href="#location">&lt;Location&gt;</a>. However, it takes a regular
1002 expression as an argument instead of a simple string. For example:</p>
1003
1004 <pre>
1005    &lt;LocationMatch &quot;/(extra|special)/data&quot;&gt;
1006 </pre>
1007
1008 <p>would match URLs that contained the substring "/extra/data" or
1009 "/special/data".</p>
1010
1011 <strong>See also</strong>: <a href="../sections.html">How Directory,
1012 Location and Files sections work</a> for an explanation of how these
1013 different sections are combined when a request is received
1014
1015 <hr>
1016
1017 <H2><A NAME="lockfile">LockFile directive</A></H2>
1018 <strong>Syntax:</strong> LockFile <em>filename</em><BR>
1019 <strong>Default:</strong> <code>LockFile logs/accept.lock</code><BR>
1020 <strong>Context:</strong> server config<BR>
1021 <strong>Status:</strong> core<P>
1022
1023 The LockFile directive sets the path to the lockfile used when
1024 Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or
1025 USE_FLOCK_SERIALIZED_ACCEPT.  This directive should normally be
1026 left at its default value.  The main reason for changing it is if
1027 the <code>logs</code> directory is NFS mounted, since the lockfile
1028 should be stored on a local disk if possible.  The PID of the main
1029 server process is automatically appended to the filename.
1030
1031 <P><HR>
1032
1033 <h2><A name="maxclients">MaxClients directive</A></h2>
1034 <!--%plaintext &lt;?INDEX {\tt MaxClients} directive&gt; -->
1035 <strong>Syntax:</strong> MaxClients <em>number</em><br>
1036 <strong>Default:</strong> <code>MaxClients 256</code><br>
1037 <strong>Context:</strong> server config<br>
1038 <strong>Status:</strong> core<p>
1039
1040 The MaxClients directive sets the limit on the number of simultaneous
1041 requests that can be supported; not more than this number of child server
1042 processes will be created.<p><hr>
1043
1044 <h2><A name="maxkeepaliverequests">MaxKeepAliveRequests directive</A></h2>
1045 <strong>Syntax:</strong> MaxKeepAliveRequests <em>number</em><br>
1046 <strong>Default:</strong> <code>MaxKeepAliveRequests 100</code><br>
1047 <strong>Context:</strong> server config<br>
1048 <strong>Status:</strong> core<br>
1049 <strong>Compatibility:</strong> Only available in Apache
1050 1.2 and later.
1051
1052 <p>The MaxKeepAliveRequests directive limits the number of requests
1053 allowed per connection when <a href="#keepalive">KeepAlive</a> is
1054 on. If it is set to "<code>0</code>", unlimited requests will be
1055 allowed. We recommend that this setting be kept to a high value for
1056 maximum server performance.</p><hr>
1057
1058 <h2><A name="maxrequestsperchild">MaxRequestsPerChild directive</A></h2>
1059 <!--%plaintext &lt;?INDEX {\tt MaxRequestsPerChild} directive&gt; -->
1060 <strong>Syntax:</strong> MaxRequestsPerChild <em>number</em><br>
1061 <strong>Default:</strong> <code>MaxRequestsPerChild 0</code><br>
1062 <strong>Context:</strong> server config<br>
1063 <strong>Status:</strong> core<p>
1064
1065 The MaxRequestsPerChild directive sets the limit on the number of requests
1066 that an individual child server process will handle. After MaxRequestsPerChild
1067 requests, the child process will die. If MaxRequestsPerChild is 0, then
1068 the process will never expire.<p>
1069
1070 Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects:
1071 <ul>
1072 <li>it limits the amount of memory that process can consume by (accidental)
1073 memory leakage;
1074 <li> by giving processes a finite lifetime, it helps reduce the
1075 number of processes when the server load reduces.
1076 </ul><p><hr>
1077
1078 <h2><A name="maxspareservers">MaxSpareServers directive</A></h2>
1079 <!--%plaintext &lt;?INDEX {\tt MaxSpareServers} directive&gt; -->
1080 <strong>Syntax:</strong> MaxSpareServers <em>number</em><br>
1081 <strong>Default:</strong> <code>MaxSpareServers 10</code><br>
1082 <strong>Context:</strong> server config<br>
1083 <strong>Status:</strong> core<p>
1084
1085 The MaxSpareServers directive sets the desired maximum number of <em>idle</em>
1086 child server processes. An idle process is one which is not handling
1087 a request. If there are more than MaxSpareServers idle, then the parent
1088 process will kill off the excess processes.<p>
1089
1090 Tuning of this parameter should only be necessary on very busy sites.
1091 Setting this parameter to a large number is almost always a bad idea.<p>
1092
1093 See also <A HREF="#minspareservers">MinSpareServers</A> and
1094 <A HREF="#startservers">StartServers</A>.<p><hr>
1095
1096 <h2><A name="minspareservers">MinSpareServers directive</A></h2>
1097 <!--%plaintext &lt;?INDEX {\tt MinSpareServers} directive&gt; -->
1098 <strong>Syntax:</strong> MinSpareServers <em>number</em><br>
1099 <strong>Default:</strong> <code>MinSpareServers 5</code><br>
1100 <strong>Context:</strong> server config<br>
1101 <strong>Status:</strong> core<p>
1102
1103 The MinSpareServers directive sets the desired minimum number of <em>idle</em>
1104 child server processes. An idle process is one which is not handling
1105 a request. If there are fewer than MinSpareServers idle, then the parent
1106 process creates new children at a maximum rate of 1 per second.<p>
1107
1108 Tuning of this parameter should only be necessary on very busy sites.
1109 Setting this parameter to a large number is almost always a bad idea.<p>
1110
1111 See also <A HREF="#maxspareservers">MaxSpareServers</A> and
1112 <A HREF="#startservers">StartServers</A>.<p><hr>
1113
1114 <h2><A name="options">Options directive</A></h2>
1115 <!--%plaintext &lt;?INDEX {\tt Options} directive&gt; -->
1116 <strong>Syntax:</strong> Options <em>[+|-]option [+|-]option ...</em><br>
1117 <strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
1118 <strong>Override:</strong> Options<br>
1119 <strong>Status:</strong> core<p>
1120
1121 The Options directive controls which server features are available in
1122 a particular directory.
1123 <p>
1124 <em>option</em> can be set to <code>None</code>, in which case none of
1125 the extra features are enabled, or one or more of the following:
1126 <dl>
1127 <dt>All
1128 <dd>All options except for MultiViews.
1129 <dt>ExecCGI
1130 <dd>
1131 <!--%plaintext &lt;?INDEX {\tt ExecCGI} option&gt; -->
1132 Execution of CGI scripts is permitted.
1133 <dt>FollowSymLinks
1134 <dd>
1135 <!--%plaintext &lt;?INDEX {\tt FollowSymLinks} option&gt; -->
1136 The server will follow symbolic links in this directory.
1137 <b>Note</b>: even though the server follows the symlink it does <i>not</i>
1138 change the pathname used to match against <code>&lt;Directory&gt;</code>
1139 sections.
1140 <dt>Includes
1141 <dd>
1142 <!--%plaintext &lt;?INDEX {\tt Includes} option&gt; -->
1143 Server-side includes are permitted.
1144 <dt>IncludesNOEXEC
1145 <dd>
1146 <!--%plaintext &lt;?INDEX {\tt IncludesNOEXEC} option&gt; -->
1147 Server-side includes are permitted, but the #exec command and
1148 #include of CGI scripts are disabled.
1149 <dt>Indexes
1150 <dd>
1151 <!--%plaintext &lt;?INDEX {\tt Indexes} option&gt; -->
1152 If a URL which maps to a directory is requested, and the there is no
1153 DirectoryIndex (e.g. index.html) in that directory, then the server will
1154 return a formatted listing of the directory.
1155 <dt>MultiViews
1156 <dd>
1157 <!--%plaintext &lt;?INDEX {\tt MultiViews} option&gt; -->
1158 <A HREF="../content-negotiation.html">Content negotiated</A> MultiViews are
1159 allowed.
1160 <dt>SymLinksIfOwnerMatch
1161 <dd>
1162 <!--%plaintext &lt;?INDEX {\tt SymLinksIfOwnerMatch} option&gt; -->
1163 The server will only follow symbolic links for which the target
1164 file or directory is owned by the same user id as the link.
1165 </dl>
1166
1167 Normally, if multiple <code>Options</code> could apply to a directory,
1168 then the most specific one is taken complete; the options are not
1169 merged. However if <i>all</i> the options on the <code>Options</code>
1170 directive are preceded by a + or - symbol, the options are
1171 merged. Any options preceded by a + are added to the options
1172 currently in force, and any options preceded by a - are removed from
1173 the options currently in force.  <P>
1174
1175 For example, without any + and - symbols:
1176
1177 <blockquote><code>
1178 &lt;Directory /web/docs&gt; <br>
1179 Options Indexes FollowSymLinks<br>
1180 &lt;/Directory&gt;<br>
1181 &lt;Directory /web/docs/spec&gt; <br>
1182 Options Includes<br>
1183 &lt;/Directory&gt;
1184 </code></blockquote>
1185 then only <code>Includes</code> will be set for the /web/docs/spec
1186 directory. However if the second <code>Options</code> directive uses the +
1187 and - symbols:<p>
1188
1189 <blockquote><code>
1190 &lt;Directory /web/docs&gt; <br>
1191 Options Indexes FollowSymLinks<br>
1192 &lt;/Directory&gt;<br>
1193 &lt;Directory /web/docs/spec&gt; <br>
1194 Options +Includes -Indexes<br>
1195 &lt;/Directory&gt;
1196 </code></blockquote>
1197 then the options <code>FollowSymLinks</code> and <code>Includes</code>
1198 are set for the /web/docs/spec directory.
1199 <hr>
1200
1201 <h2><A name="pidfile">PidFile directive</A></h2>
1202 <!--%plaintext &lt;?INDEX {\tt PidFile} directive&gt; -->
1203 <strong>Syntax:</strong> PidFile <em>filename</em><br>
1204 <strong>Default:</strong> <code>PidFile logs/httpd.pid</code><br>
1205 <strong>Context:</strong> server config<br>
1206 <strong>Status:</strong> core<p>
1207
1208 The PidFile directive sets the file to which the server records the
1209 process id of the daemon. If the filename does not begin with a slash (/)
1210 then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>.
1211 The PidFile is only used in <A HREF="#servertype">standalone</A> mode.<p>
1212
1213 It is often useful to be able to send the server a signal, so that it closes
1214 and then reopens its <A HREF="#errorlog">ErrorLog</A> and TransferLog, and
1215 re-reads its configuration files. This is done by sending a SIGHUP (kill -1)
1216 signal to the process id listed in the PidFile.<p>
1217
1218 The PidFile is subject to the same warnings about log file placement and
1219 <a href="../misc/security_tips.html">security</a>.
1220
1221 <p><hr>
1222
1223 <h2><A name="port">Port directive</A></h2>
1224 <!--%plaintext &lt;?INDEX {\tt Port} directive&gt; -->
1225 <strong>Syntax:</strong> Port <em>number</em><br>
1226 <strong>Default:</strong> <code>Port 80</code><br>
1227 <strong>Context:</strong> server config<br>
1228 <strong>Status:</strong> core<p>
1229
1230 <em>Number</em> is a number from 0 to 65535; some port numbers (especially below
1231 1024) are reserved for particular protocols. See <code>/etc/services</code>
1232 for a list of some defined ports; the standard port for the http protocol
1233 is 80.<p>
1234
1235 The Port directive has two behaviors, the first of which is necessary for
1236 NCSA backwards compatibility (and which is confusing in the context of
1237 Apache).<p>
1238
1239 <ul>
1240 <li>
1241 In the absence of any <a href="#listen">Listen</a> or
1242 <a href="#bindaddress">BindAddress</a> directives specifying a port number,
1243 the Port directive sets the network port on which the server listens.
1244 If there are any Listen or BindAddress directives specifying
1245 <code>:number</code> then Port has no effect on what address the server
1246 listens at.
1247
1248 <li>The Port directive
1249 sets the <code>SERVER_PORT</code> environment variable (for
1250 <a href="mod_cgi.html">CGI</a> and <a href="mod_include.html">SSI</a>),
1251 and is used when the server must generate a URL that refers to itself
1252 (for example when creating an external redirect to itself).
1253 </ul>
1254
1255 In no event does a Port setting affect
1256 what ports a <a href="#virtualhost">VirtualHost</a> responds on, the
1257 VirtualHost directive itself is used for that.<p>
1258
1259 The primary behaviour of Port should be considered to be similar to that of
1260 the <a href="#servername">ServerName</a> directive.  The ServerName
1261 and Port together specify what you consider to be the <i>canonical</i>
1262 address of the server.<p>
1263
1264 Port 80 is one of Unix's special ports. All ports numbered
1265 below 1024 are reserved for system use, i.e. regular (non-root) users cannot
1266 make use of them; instead they can only use higher port numbers.
1267 To use port 80, you must start the server from the root account.
1268 After binding to the port and before accepting requests, Apache will change
1269 to a low privileged user as set by the <A HREF="#user">User directive</A>.<p>
1270
1271 If you cannot use port 80, choose any other unused port. Non-root users
1272 will have to choose a port number higher than 1023, such as 8000.<p>
1273
1274 SECURITY: if you do start the server as root, be sure
1275 not to set <A HREF="#user">User</A> to root. If you run the server as
1276 root whilst handling connections, your site may be open to a major security
1277 attack.<p><hr>
1278
1279 <h2><A name="require">require directive</A></h2>
1280 <!--%plaintext &lt;?INDEX {\tt require} directive&gt; -->
1281 <strong>Syntax:</strong> require <em>entity-name entity entity...</em><br>
1282 <strong>Context:</strong> directory, .htaccess<br>
1283 <strong>Override:</strong> AuthConfig<br>
1284 <strong>Status:</strong> core<p>
1285
1286 This directive selects which authenticated users can access a directory.
1287 The allowed syntaxes are:
1288 <ul>
1289 <li>require user <em>userid userid ...</em><p>
1290 Only the named users can access the directory.<p>
1291 <li>require group <em>group-name group-name ...</em><p>
1292 Only users in the named groups can access the directory.<p>
1293 <li>require valid-user<p>
1294 All valid users can access the directory.
1295 </ul>
1296 <p>
1297 If <code>require</code> appears in a <A HREF="#limit">&lt;Limit&gt;</A>
1298 section, then it restricts access to the named methods, otherwise
1299 it restricts access for all methods. Example:
1300 <blockquote><code>
1301 AuthType Basic<br>
1302 AuthName somedomain<br>
1303 AuthUserFile /web/users<br>
1304 AuthGroupFile /web/groups<br>
1305 &lt;Limit GET POST&gt;<br>
1306 require group admin<br>
1307 &lt;/Limit&gt;
1308 </code></blockquote>
1309
1310 Require must be accompanied by <A HREF="#authname">AuthName</A> and
1311 <A HREF="#authtype">AuthType</A> directives, and directives such as
1312 <A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and
1313 <A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> (to define users and
1314 groups) in order to work correctly.<p><hr>
1315
1316 <h2><A name="resourceconfig">ResourceConfig directive</A></h2>
1317 <!--%plaintext &lt;?INDEX {\tt ResourceConfig} directive&gt; -->
1318 <strong>Syntax:</strong> ResourceConfig <em>filename</em><br>
1319 <strong>Default:</strong> <code>ResourceConfig conf/srm.conf</code><br>
1320 <strong>Context:</strong> server config, virtual host<br>
1321 <strong>Status:</strong> core<p>
1322
1323 The server will read this file for more directives after reading the
1324 httpd.conf file. <em>Filename</em> is relative to the
1325 <A HREF="#serverroot">ServerRoot</A>.
1326 This feature can be disabled using:
1327 <blockquote><code>ResourceConfig /dev/null</code></blockquote>
1328 Historically, this file contained most directives except for server
1329 configuration directives and <A HREF="#directory">&lt;Directory&gt;</A>
1330 sections; in fact it can now contain any server directive allowed in the
1331 <em>server config</em> context.<p>
1332
1333 See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr>
1334
1335 <H2><A name="rlimit">RLimitCPU</A> <A NAME="rlimitcpu">directive</A></H2>
1336 <!--%plaintext &lt;?INDEX {\tt RLimitCPU} directive&gt; -->
1337 <strong>Syntax:</strong> RLimitCPU <em># or 'max'</em> <em>[# or 'max']</em><br>
1338 <strong>Default:</strong> <e>Unset; uses operating system defaults</e><br>
1339 <strong>Context:</strong> server config, virtual host<br>
1340 <strong>Status:</strong> core<br>
1341 <strong>Compatibility:</strong> RLimitCPU is only available in Apache 1.2 and later<p>
1342
1343 Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all
1344 processes and the second parameter sets the maximum resource limit. Either parameter
1345 can be a number, or <em>max</em> to indicate to the server that the limit should
1346 be set to the maximum allowed by the operating system configuration. Raising the
1347 maximum resource limit requires that the server is running as root, or in the initial
1348 startup phase.<p>
1349
1350 CPU resource limits are expressed in seconds per process.<p>
1351
1352 See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr>
1353
1354 <h2><A name="rlimitmem">RLimitMEM directive</A></h2>
1355 <!--%plaintext &lt;?INDEX {\tt RLimitMEM} directive&gt; -->
1356 <strong>Syntax:</strong> RLimitMEM <em># or 'max'</em> <em>[# or 'max']</em><br>
1357 <strong>Default:</strong> <e>Unset; uses operating system defaults</e><br>
1358 <strong>Context:</strong> server config, virtual host<br>
1359 <strong>Status:</strong> core<br>
1360 <strong>Compatibility:</strong> RLimitMEM is only available in Apache 1.2 and later<p>
1361
1362 Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all
1363 processes and the second parameter sets the maximum resource limit. Either parameter
1364 can be a number, or <em>max</em> to indicate to the server that the limit should
1365 be set to the maximum allowed by the operating system configuration. Raising the
1366 maximum resource limit requires that the server is running as root, or in the initial
1367 startup phase.<p>
1368
1369 Memory resource limits are expressed in bytes per process.<p>
1370
1371 See also <A HREF="#rlimitcpu">RLimitCPU</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr>
1372
1373 <h2><A name="rlimitnproc">RLimitNPROC directive</A></h2>
1374 <!--%plaintext &lt;?INDEX {\tt RLimitNPROC} directive&gt; -->
1375 <strong>Syntax:</strong> RLimitNPROC <em># or 'max'</em> <em>[# or 'max']</em><br>
1376 <strong>Default:</strong> <e>Unset; uses operating system defaults</e><br>
1377 <strong>Context:</strong> server config, virtual host<br>
1378 <strong>Status:</strong> core<br>
1379 <strong>Compatibility:</strong> RLimitNPROC is only available in Apache 1.2 and later<p>
1380
1381 Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all
1382 processes and the second parameter sets the maximum resource limit. Either parameter
1383 can be a number, or <em>max</em> to indicate to the server that the limit should
1384 be set to the maximum allowed by the operating system configuration. Raising the
1385 maximum resource limit requires that the server is running as root, or in the initial
1386 startup phase.<p>
1387
1388 Process limits control the number of processes per user.<p>
1389
1390 Note: If CGI processes are <b>not</b> running under userids other than the
1391 web server userid, this directive will limit the number of processes that the
1392 server itself can create. Evidence of this situation will be indicated by
1393 <b><em>cannot fork</em></b> messages in the error_log.<p>
1394
1395 See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitcpu">RLimitCPU</A>.
1396
1397 <p><hr>
1398
1399 <h2><A name="satisfy">Satisfy directive</A></h2>
1400 <!--%plaintext &lt;?INDEX {\tt Satisfy} directive&gt; -->
1401 <strong>Syntax:</strong> Satisfy <em>'any' or 'all'</em><br>
1402 <strong>Default:</strong> Satisfy all<br>
1403 <strong>Context:</strong> directory, .htaccess<br>
1404 <strong>Status:</strong> core<br>
1405 <strong>Compatibility:</strong> Satisfy is only available in Apache 1.2 and later<p>
1406
1407 Access policy if both allow and require used. The parameter can be
1408 either <em>'all'</em> or <em>'any'</em>. This directive is only useful
1409 if access to a particular area is being restricted by both
1410 username/password <i>and</i> client host address. In this case the
1411 default behavior ("all") is to require that the client passes the
1412 address access restriction <i>and</i> enters a valid username and
1413 password. With the "any" option the client will be granted access if
1414 they either pass the host restriction or enter a valid username and
1415 password. This can be used to password restrict an area, but to let
1416 clients from particular addresses in without prompting for a password.
1417
1418
1419 <p><hr>
1420
1421 <h2><A name="scoreboardfile">ScoreBoardFile directive</A></h2>
1422 <!--%plaintext &lt;?INDEX {\tt ScoreBoardFile} directive&gt; -->
1423 <strong>Syntax:</strong> ScoreBoardFile <em>filename</em><br>
1424 <strong>Default:</strong> <code>ScoreBoardFile logs/apache_status</code><br>
1425 <strong>Context:</strong> server config<br>
1426 <strong>Status:</strong> core<p>
1427
1428 The ScoreBoardFile directive is required on some architectures to place
1429 a file that the server will use to communicate between its children and
1430 the parent.  The easiest way to find out if your architecture requires
1431 a scoreboard file is to run Apache and see if it creates the file named
1432 by the directive.  If your architecture requires it then you must ensure
1433 that this file is not used at the same time by more than one invocation
1434 of Apache.<p>
1435
1436 If you have to use a ScoreBoardFile then you may see improved speed by
1437 placing it on a RAM disk.  But be careful that you heed the same warnings
1438 about log file placement and
1439 <a href="../misc/security_tips.html">security</a>.<p>
1440
1441 Apache 1.2 and above:<p>
1442
1443 Linux 1.x users might be able to add <code>-DHAVE_SHMGET</code> to
1444 the <code>EXTRA_CFLAGS</code> in your <code>Configuration</code>.  This
1445 might work with some 1.x installations, but won't work with all of
1446 them.<p>
1447
1448 SVR4 users should consider adding <code>-DHAVE_SHMGET</code> to the
1449 <code>EXTRA_CFLAGS</code> in your <code>Configuration</code>.  This
1450 is believed to work, but we were unable to test it in time for 1.2
1451 release.<p>
1452
1453 <strong>See Also</strong>:
1454 <a href="../stopping.html">Stopping and Restarting Apache</a></p>
1455
1456 <p><hr>
1457
1458 <h2><A name="sendbuffersize">SendBufferSize directive</A></h2>
1459 <!--%plaintext &lt;?INDEX {\tt SendBufferSize} directive&gt; -->
1460 <strong>Syntax:</strong> SendBufferSize <em>bytes</em><br>
1461 <strong>Context:</strong> server config<br>
1462 <strong>Status:</strong> core<p>
1463
1464 The server will set the TCP buffer size to the number of bytes
1465 specified. Very useful to increase past standard OS defaults on high
1466 speed high latency (i.e. 100ms or so, such as transcontinental
1467 fast pipes)
1468 <p><hr>
1469
1470 <h2><A name="serveradmin">ServerAdmin directive</A></h2>
1471 <!--%plaintext &lt;?INDEX {\tt ServerAdmin} directive&gt; -->
1472 <strong>Syntax:</strong> ServerAdmin <em>email-address</em><br>
1473 <strong>Context:</strong> server config, virtual host<br>
1474 <strong>Status:</strong> core<p>
1475
1476 The ServerAdmin sets the e-mail address that the server includes in any
1477 error messages it returns to the client.<p>
1478
1479 It may be worth setting up a dedicated address for this, e.g.
1480 <blockquote><code>ServerAdmin www-admin@foo.bar.com</code></blockquote>
1481 as users do not always mention that they are talking about the server!<p><hr>
1482
1483 <h2><A name="serveralias">ServerAlias directive</A></h2>
1484
1485 <strong>Syntax:</strong> ServerAlias <em>host1 host2 ...</em><br>
1486 <strong>Context:</strong> virtual host<br>
1487 <strong>Status:</strong> core<br>
1488 <strong>Compatibility:</strong> ServerAlias is only available in Apache
1489 1.1 and later.<p>
1490
1491 The ServerAlias directive sets the alternate names for a host, for use
1492 with
1493 <a href="../host.html">Host-header based virtual hosts</a>.
1494 <p><strong>See Also</strong>:
1495 <a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p>
1496
1497 <hr>
1498
1499 <h2><A name="servername">ServerName directive</A></h2>
1500 <!--%plaintext &lt;?INDEX {\tt ServerName} directive&gt; -->
1501 <strong>Syntax:</strong> ServerName <em>fully-qualified domain name</em><br>
1502 <strong>Context:</strong> server config, virtual host<br>
1503 <strong>Status:</strong> core<p>
1504
1505 The ServerName directive sets the hostname of the server; this is only
1506 used when creating redirection URLs. If it is not specified, then the
1507 server attempts to deduce it from its own IP address; however this may
1508 not work reliably, or may not return the preferred hostname. For example:
1509 <blockquote><code>ServerName www.wibble.com</code></blockquote>
1510 would be used if the canonical (main) name of the actual machine
1511 were <code>monster.wibble.com</code>.<p>
1512 <p><strong>See Also</strong>:
1513 <a href="../dns-caveats.html">DNS Issues</a></p>
1514 <hr>
1515
1516 <h2><A name="serverpath">ServerPath directive</A></h2>
1517
1518 <strong>Syntax:</strong> ServerPath <em>pathname</em><br>
1519 <strong>Context:</strong> virtual host<br>
1520 <strong>Status:</strong> core<br>
1521 <strong>Compatibility:</strong> ServerPath is only available in Apache
1522 1.1 and later.<p>
1523
1524 The ServerPath directive sets the legacy URL pathname for a host, for
1525 use with <a href="../host.html">Host-header based virtual hosts</a>.
1526 <p><strong>See Also</strong>:
1527 <a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p>
1528 <hr>
1529
1530 <h2><A name="serverroot">ServerRoot directive</A></h2>
1531 <!--%plaintext &lt;?INDEX {\tt ServerRoot} directive&gt; -->
1532 <strong>Syntax:</strong> ServerRoot <em>directory-filename</em><br>
1533 <strong>Default:</strong> <code>ServerRoot /usr/local/etc/httpd</code><br>
1534 <strong>Context:</strong> server config<br>
1535 <strong>Status:</strong> core<p>
1536
1537 The ServerRoot directive sets the directory in which the server lives.
1538 Typically it will contain the subdirectories <code>conf/</code> and
1539 <code>logs/</code>. Relative paths for other configuration files are taken
1540 as relative to this directory.<br>
1541 See also <a href="../invoking.html">the <code>-d</code> option to httpd</a>.<p><hr>
1542
1543 <h2><A name="servertype">ServerType directive</A></h2>
1544 <!--%plaintext &lt;?INDEX {\tt ServerType} directive&gt; -->
1545 <strong>Syntax:</strong> ServerType <em>type</em><br>
1546 <strong>Default:</strong> <code>ServerType standalone</code><br>
1547 <strong>Context:</strong> server config<br>
1548 <strong>Status:</strong> core<p>
1549
1550 The ServerType directive sets how the server is executed by the system.
1551 <em>Type</em> is one of
1552 <dl>
1553 <dt>inetd
1554 <dd>The server will be run from the system process inetd; the command to start
1555 the server is added to <code>/etc/inetd.conf</code>
1556 <dt>standalone
1557 <dd>The server will run as a daemon process; the command to start the server
1558 is added to the system startup scripts. (<code>/etc/rc.local</code> or
1559 <code>/etc/rc3.d/...</code>.)
1560 </dl>
1561
1562 Inetd is the lesser used of the two options. For each http
1563 connection received, a new copy of the server is started from scratch;
1564 after the connection is complete, this program exits. There is a high price to
1565 pay per connection, but for security reasons, some admins prefer this option.
1566 <p>
1567
1568 Standalone is the most common setting for ServerType since
1569 it is far more efficient. The server is started once, and services all
1570 subsequent connections. If you intend running Apache to serve a busy site,
1571 standalone will probably be your only option.<p>
1572
1573 SECURITY: if you are paranoid about security, run in inetd mode. Security
1574 cannot be guaranteed in either, but whilst most people are happy to use
1575 standalone, inetd is probably least prone to attack.<p><hr>
1576
1577 <h2><A name="startservers">StartServers directive</A></h2>
1578 <!--%plaintext &lt;?INDEX {\tt StartServers} directive&gt; -->
1579 <strong>Syntax:</strong> StartServers <em>number</em><br>
1580 <strong>Default:</strong> <code>StartServers 5</code><br>
1581 <strong>Context:</strong> server config<br>
1582 <strong>Status:</strong> core<p>
1583
1584 The StartServers directive sets the number of child server processes created
1585 on startup. As the number of processes is dynamically controlled depending
1586 on the load, there is usually little reason to adjust this parameter.<p>
1587
1588 <p>When running with Microsoft Windows, this directive sets the total
1589    number of child processes running. Since the Windows version of Apache
1590    is multithreaded, one processes handles all the requests. The rest are
1591    held in reserve until the main processes dies.
1592
1593 See also <A HREF="#minspareservers">MinSpareServers</A> and
1594 <A HREF="#maxspareservers">MaxSpareServers</A>.<p><hr>
1595
1596 <h2><A name="threadsperchild">ThreadsPerChild</A></h2>
1597 <strong>Syntax:</strong> ThreadsPerChild <em>number</em><br>
1598 <strong>Default:</strong> <code>ThreadsPerChild 50</code><br>
1599 <strong>Context:</strong> server config<br>
1600 <strong>Status:</strong> core (Windows)<br>
1601 <strong>Compatbility:</strong> Available only with Apache 1.3 and later
1602 with Windows
1603
1604 <p>This directive tells the server how many threads it should use. This
1605    is the maximum number of connections the server can handle at once; be
1606    sure and set this number high enough for your site if you get a lot of
1607    hits.
1608
1609 <p>See also <A HREF="#startservers">StartServers</A> and <A
1610    HREF="#maxrequestsperchild">MaxRequestsPerChild</A>.</p>
1611
1612 <hr>
1613
1614 <h2><A name="timeout">TimeOut directive</A></h2>
1615 <!--%plaintext &lt;?INDEX {\tt TimeOut} directive&gt; -->
1616 <strong>Syntax:</strong> TimeOut <em>number</em><br>
1617 <strong>Default:</strong> <code>TimeOut 300</code><br>
1618 <strong>Context:</strong> server config<br>
1619 <strong>Status:</strong> core<p>
1620
1621 The TimeOut directive currently defines the amount of time Apache will
1622 wait for three things:
1623
1624 <OL>
1625   <LI>The total amount of time it takes to receive a GET request.
1626   <LI>The amount of time between receipt of TCP packets on a POST or
1627       PUT request.
1628   <LI>The amount of time between ACKs on transmissions of TCP packets
1629       in responses.
1630 </OL>
1631
1632 We plan on making these separately configurable at some point down the
1633 road.  The timer used to default to 1200 before 1.2, but has been
1634 lowered to 300 which is still far more than necessary in most
1635 situations.  It is not set any lower by default because there may
1636 still be odd places in the code where the timer is not reset when
1637 a packet is sent.
1638
1639 <p><hr>
1640
1641 <h2><A name="user">User directive</A></h2>
1642 <!--%plaintext &lt;?INDEX {\tt User} directive&gt; -->
1643 <strong>Syntax:</strong> User <em>unix-userid</em><br>
1644 <strong>Default:</strong> <code>User #-1</code><br>
1645 <strong>Context:</strong> server config, virtual host<br>
1646 <strong>Status:</strong> core<p>
1647
1648 The User directive sets the userid as which the server will answer requests.
1649 In order to use this directive, the standalone server must be run initially
1650 as root. <em>Unix-userid</em> is one of:
1651 <dl>
1652 <dt>A username
1653 <dd>Refers to the given user by name.
1654 <dt># followed by a user number.
1655 <dd>Refers to a user by their number.
1656 </dl>
1657
1658 The user should have no privileges which result in it being able to access
1659 files which are not intended to be visible to the outside world, and
1660 similarly, the user should not be able to execute code which is not
1661 meant for httpd requests. It is recommended that you set up a new user and
1662 group specifically for running the server. Some admins use user
1663 <code>nobody</code>, but this is not always possible or desirable.<p>
1664
1665 Notes: If you start the server as a non-root user, it will fail to change
1666 to the lesser privileged user, and will instead continue to run as
1667 that original user. If you do start the server as root, then it is normal
1668 for the parent process to remain running as root.<p>
1669
1670 Special note: Use of this directive in &lt;VirtualHost&gt; requires a
1671 properly configured <A HREF="../suexec.html">suEXEC wrapper</A>.
1672 When used inside a &lt;VirtualHost&gt; in this manner, only the user
1673 that CGIs are run as is affected.  Non-CGI requests are still processed
1674 with the user specified in the main User directive.<p>
1675
1676 SECURITY: Don't set User (or <A HREF="#group">Group</A>) to
1677 <code>root</code> unless you know exactly what you are doing, and what the
1678 dangers are.<p><hr>
1679
1680 <h2><A name="virtualhost">&lt;VirtualHost&gt; directive</A></h2>
1681 <!--%plaintext &lt;?INDEX {\tt VirtualHost} section directive&gt; -->
1682 <strong>Syntax:</strong> &lt;VirtualHost <em>addr</em>[:<em>port</em>] ...&gt; ...
1683 &lt;/VirtualHost&gt; <br>
1684 <strong>Context:</strong> server config<br>
1685 <strong>Status:</strong> Core.<br>
1686 <strong>Compatibility:</strong> Non-IP address-based Virtual Hosting only
1687 available in Apache 1.1 and later.<br>
1688 <strong>Compatibility:</strong> Multiple address support only available in
1689 Apache 1.2 and later.<p>
1690
1691 &lt;VirtualHost&gt; and &lt;/VirtualHost&gt; are used to enclose a group of
1692 directives which will apply only to a particular virtual host.
1693 Any directive which is allowed in a virtual host context may be used.
1694 When the server receives a request for a document on a particular virtual
1695 host, it uses the configuration directives enclosed in the &lt;VirtualHost&gt;
1696 section. <em>Addr</em> can be
1697 <menu>
1698 <li>The IP address of the virtual host
1699 <li>A fully qualified domain name for the IP address of the virtual host.
1700 </menu> Example:
1701 <blockquote>
1702 <code>
1703 &lt;VirtualHost 10.1.2.3&gt; <br>
1704 ServerAdmin webmaster@host.foo.com <br>
1705 DocumentRoot /www/docs/host.foo.com <br>
1706 ServerName host.foo.com <br>
1707 ErrorLog logs/host.foo.com-error_log <br>
1708 TransferLog logs/host.foo.com-access_log <br>
1709 &lt;/VirtualHost&gt;
1710 </code></blockquote>
1711
1712 Each VirtualHost must correspond to a different IP address, different port number or a
1713 different host name for the server, in the latter case the server
1714 machine must be configured to accept IP packets for multiple
1715 addresses. (If the machine does not have multiple network interfaces,
1716 then this can be accomplished with the <code>ifconfig alias</code>
1717 command (if your OS supports it), or with kernel patches like <A
1718 HREF="../misc/vif-info.html">VIF</A> (for SunOS(TM) 4.1.x)).<p>
1719
1720 The special name <code>_default_</code> can be specified in which case
1721 this virtual host will match any IP address that is not explicitly listed
1722 in another virtual host.  In the absence of any _default_ virtual host
1723 the "main" server config, consisting of all those definitions outside
1724 any VirtualHost section, is used when no match occurs.<p>
1725
1726 You can specify a <code>:port</code> to change the port that is matched.
1727 If unspecified then it defaults to the same port as the most recent
1728 <code><a href="#port">Port</a></code> statement of the main server.  You
1729 may also specify <code>:*</code> to match all ports on that address.
1730 (This is recommended when used with <code>_default_</code>.)<p>
1731
1732 <strong>SECURITY</strong>: See the
1733 <A HREF="../misc/security_tips.html">security tips</A>
1734 document for details on why your security could be compromised if
1735 the directory where logfiles are stored is writable by anyone other
1736 than the user that starts the server.
1737
1738 <p><strong>NOTE</strong>: The use of &lt;VirtualHost&gt; does
1739 <strong>not</strong> affect what addresses Apache listens on. You may
1740 need to ensure that Apache is listening on the correct addresses using
1741 either <a href="#bindaddress">BindAddress</a> or <a
1742 href="#listen">Listen</a>.
1743
1744 <p><strong>See also:</strong>
1745 <A HREF="../dns-caveats.html">Warnings about DNS and Apache</a><br>
1746 <strong>See also:</strong>
1747 <A HREF="../virtual-host.html">Information on Virtual Hosts.
1748 (multihome)</A><br>
1749 <strong>See also:</strong>
1750 <a href="../host.html">Non-IP address-based Virtual Hosts</a><br>
1751 <strong>See also:</strong>
1752 <a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a><br>
1753 <strong>See also:</strong>
1754 <a href="../bind.html">Setting which addresses and ports Apache uses</a><br>
1755 <strong>See also</strong>: <a href="../sections.html">How Directory,
1756 Location and Files sections work</a> for an explanation of how these
1757 different sections are combined when a request is received
1758 </p>
1759
1760 <!--#include virtual="footer.html" -->
1761 </BODY>
1762 </HTML>
1763