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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>core - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.1</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Core Features</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
  25 <a href="../en/mod/core.html" title="English">&nbsp;en&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Core Apache HTTP Server features that are always
  28 available</td></tr>
  29 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Core</td></tr></table>
  30 </div>
  31 <div id="quickview"><h3 class="directives">Directives</h3>
  32 <ul id="toc">
  33 <li><img alt="" src="../images/down.gif" /> <a href="#acceptpathinfo">AcceptPathInfo</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#accessfilename">AccessFileName</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#adddefaultcharset">AddDefaultCharset</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#addoutputfilterbytype">AddOutputFilterByType</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#allowencodedslashes">AllowEncodedSlashes</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#allowoverride">AllowOverride</a></li>
  39 <li><img alt="" src="../images/down.gif" /> <a href="#authname">AuthName</a></li>
  40 <li><img alt="" src="../images/down.gif" /> <a href="#authtype">AuthType</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#cgimapextension">CGIMapExtension</a></li>
  42 <li><img alt="" src="../images/down.gif" /> <a href="#contentdigest">ContentDigest</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#defaulttype">DefaultType</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#directory">&lt;Directory&gt;</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#directorymatch">&lt;DirectoryMatch&gt;</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#documentroot">DocumentRoot</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#enablemmap">EnableMMAP</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#enablesendfile">EnableSendfile</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#errordocument">ErrorDocument</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#errorlog">ErrorLog</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#fileetag">FileETag</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#files">&lt;Files&gt;</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#filesmatch">&lt;FilesMatch&gt;</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#forcetype">ForceType</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#hostnamelookups">HostnameLookups</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#ifdefine">&lt;IfDefine&gt;</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#ifmodule">&lt;IfModule&gt;</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#include">Include</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#keepalive">KeepAlive</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#keepalivetimeout">KeepAliveTimeout</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#limit">&lt;Limit&gt;</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#limitexcept">&lt;LimitExcept&gt;</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#limitinternalrecursion">LimitInternalRecursion</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestbody">LimitRequestBody</a></li>
  65 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestfields">LimitRequestFields</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestfieldsize">LimitRequestFieldSize</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestline">LimitRequestLine</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#limitxmlrequestbody">LimitXMLRequestBody</a></li>
  69 <li><img alt="" src="../images/down.gif" /> <a href="#location">&lt;Location&gt;</a></li>
  70 <li><img alt="" src="../images/down.gif" /> <a href="#locationmatch">&lt;LocationMatch&gt;</a></li>
  71 <li><img alt="" src="../images/down.gif" /> <a href="#loglevel">LogLevel</a></li>
  72 <li><img alt="" src="../images/down.gif" /> <a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></li>
  73 <li><img alt="" src="../images/down.gif" /> <a href="#namevirtualhost">NameVirtualHost</a></li>
  74 <li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#require">Require</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitcpu">RLimitCPU</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitmem">RLimitMEM</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitnproc">RLimitNPROC</a></li>
  79 <li><img alt="" src="../images/down.gif" /> <a href="#satisfy">Satisfy</a></li>
  80 <li><img alt="" src="../images/down.gif" /> <a href="#scriptinterpretersource">ScriptInterpreterSource</a></li>
  81 <li><img alt="" src="../images/down.gif" /> <a href="#serveradmin">ServerAdmin</a></li>
  82 <li><img alt="" src="../images/down.gif" /> <a href="#serveralias">ServerAlias</a></li>
  83 <li><img alt="" src="../images/down.gif" /> <a href="#servername">ServerName</a></li>
  84 <li><img alt="" src="../images/down.gif" /> <a href="#serverpath">ServerPath</a></li>
  85 <li><img alt="" src="../images/down.gif" /> <a href="#serverroot">ServerRoot</a></li>
  86 <li><img alt="" src="../images/down.gif" /> <a href="#serversignature">ServerSignature</a></li>
  87 <li><img alt="" src="../images/down.gif" /> <a href="#servertokens">ServerTokens</a></li>
  88 <li><img alt="" src="../images/down.gif" /> <a href="#sethandler">SetHandler</a></li>
  89 <li><img alt="" src="../images/down.gif" /> <a href="#setinputfilter">SetInputFilter</a></li>
  90 <li><img alt="" src="../images/down.gif" /> <a href="#setoutputfilter">SetOutputFilter</a></li>
  91 <li><img alt="" src="../images/down.gif" /> <a href="#timeout">TimeOut</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#usecanonicalname">UseCanonicalName</a></li>
  93 <li><img alt="" src="../images/down.gif" /> <a href="#virtualhost">&lt;VirtualHost&gt;</a></li>
  94 </ul>
  95 </div>
  96
  97 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  98 <div class="directive-section"><h2><a name="AcceptPathInfo" id="AcceptPathInfo">AcceptPathInfo</a> <a name="acceptpathinfo" id="acceptpathinfo">Directive</a></h2>
  99 <table class="directive">
 100 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Resources accept trailing pathname information</td></tr>
 101 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AcceptPathInfo On|Off|Default</code></td></tr>
 102 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AcceptPathInfo Default</code></td></tr>
 103 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 104 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 105 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 106 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 107 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.30 and later</td></tr>
 108 </table>
 109
 110     <p>This directive controls whether requests that contain trailing
 111     pathname information that follows an actual filename (or
 112     non-existent file in an existing directory) will be accepted or
 113     rejected.  The trailing pathname information can be made
 114     available to scripts in the <code>PATH_INFO</code> environment
 115     variable.</p>
 116
 117     <p>For example, assume the location <code>/test/</code> points to
 118     a directory that contains only the single file
 119     <code>here.html</code>.  Then requests for
 120     <code>/test/here.html/more</code> and
 121     <code>/test/nothere.html/more</code> both collect
 122     <code>/more</code> as <code>PATH_INFO</code>.</p>
 123
 124     <p>The three possible arguments for the
 125     <code class="directive">AcceptPathInfo</code> directive are:</p>
 126     <dl>
 127     <dt><code>Off</code></dt><dd>A request will only be accepted if it
 128     maps to a literal path that exists.  Therefore a request with
 129     trailing pathname information after the true filename such as
 130     <code>/test/here.html/more</code> in the above example will return
 131     a 404 NOT FOUND error.</dd>
 132
 133     <dt><code>On</code></dt><dd>A request will be accepted if a
 134     leading path component maps to a file that exists.  The above
 135     example <code>/test/here.html/more</code> will be accepted if
 136     <code>/test/here.html</code> maps to a valid file.</dd>
 137
 138     <dt><code>Default</code></dt><dd>The treatment of requests with
 139     trailing pathname information is determined by the <a href="../handler.html">handler</a> responsible for the request.
 140     The core handler for normal files defaults to rejecting
 141     <code>PATH_INFO</code> requests. Handlers that serve scripts, such as <a href="mod_cgi.html">cgi-script</a> and <a href="mod_isapi.html">isapi-isa</a>, generally accept
 142     <code>PATH_INFO</code> by default.</dd>
 143     </dl>
 144
 145     <p>The primary purpose of the <code>AcceptPathInfo</code>
 146     directive is to allow you to override the handler's choice of
 147     accepting or rejecting <code>PATH_INFO</code>. This override is required,
 148     for example, when you use a <a href="../filter.html">filter</a>, such
 149     as <a href="mod_include.html">INCLUDES</a>, to generate content
 150     based on <code>PATH_INFO</code>.  The core handler would usually reject
 151     the request, so you can use the following configuration to enable
 152     such a script:</p>
 153
 154     <div class="example"><p><code>
 155       &lt;Files "mypaths.shtml"&gt;<br />
 156       <span class="indent">
 157         Options +Includes<br />
 158         SetOutputFilter INCLUDES<br />
 159         AcceptPathInfo On<br />
 160       </span>
 161       &lt;/Files&gt;
 162     </code></p></div>
 163
 164
 165 </div>
 166 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 167 <div class="directive-section"><h2><a name="AccessFileName" id="AccessFileName">AccessFileName</a> <a name="accessfilename" id="accessfilename">Directive</a></h2>
 168 <table class="directive">
 169 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name of the distributed configuration file</td></tr>
 170 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AccessFileName <var>filename</var> [<var>filename</var>] ...</code></td></tr>
 171 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AccessFileName .htaccess</code></td></tr>
 172 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 173 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 174 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 175 </table>
 176     <p>While processing a request the server looks for
 177     the first existing configuration file from this list of names in
 178     every directory of the path to the document, if distributed
 179     configuration files are <a href="#allowoverride">enabled for that
 180     directory</a>. For example:</p>
 181
 182     <div class="example"><p><code>
 183       AccessFileName .acl
 184     </code></p></div>
 185
 186     <p>before returning the document
 187     <code>/usr/local/web/index.html</code>, the server will read
 188     <code>/.acl</code>, <code>/usr/.acl</code>,
 189     <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code>
 190     for directives, unless they have been disabled with</p>
 191
 192     <div class="example"><p><code>
 193       &lt;Directory /&gt;<br />
 194       <span class="indent">
 195         AllowOverride None<br />
 196       </span>
 197       &lt;/Directory&gt;
 198     </code></p></div>
 199
 200 <h3>See also</h3>
 201 <ul>
 202 <li><code class="directive"><a href="#allowoverride">AllowOverride</a></code></li>
 203 <li><a href="../configuring.html">Configuration Files</a></li>
 204 <li><a href="../howto/htaccess.html">.htaccess Files</a></li>
 205 </ul>
 206 </div>
 207 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 208 <div class="directive-section"><h2><a name="AddDefaultCharset" id="AddDefaultCharset">AddDefaultCharset</a> <a name="adddefaultcharset" id="adddefaultcharset">Directive</a></h2>
 209 <table class="directive">
 210 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default character set to be added for a
 211 response without an explicit character set</td></tr>
 212 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddDefaultCharset On|Off|<var>charset</var></code></td></tr>
 213 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AddDefaultCharset Off</code></td></tr>
 214 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 215 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 216 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 217 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 218 </table>
 219     <p>This directive specifies the name of the character set that
 220     will be added to any response that does not have any parameter on
 221     the content type in the HTTP headers. This will override any
 222     character set specified in the body of the document via a
 223     <code>META</code> tag. A setting of <code>AddDefaultCharset
 224     Off</code> disables this
 225     functionality. <code>AddDefaultCharset On</code> enables
 226     Apache's internal default charset of <code>iso-8859-1</code> as
 227     required by the directive. You can also specify an alternate
 228     <var>charset</var> to be used. For example:</p>
 229
 230     <div class="example"><p><code>
 231       AddDefaultCharset utf-8
 232     </code></p></div>
 233
 234 </div>
 235 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 236 <div class="directive-section"><h2><a name="AddOutputFilterByType" id="AddOutputFilterByType">AddOutputFilterByType</a> <a name="addoutputfilterbytype" id="addoutputfilterbytype">Directive</a></h2>
 237 <table class="directive">
 238 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>assigns an output filter to a particular MIME-type</td></tr>
 239 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...]
 240 <var>MIME-type</var> [<var>MIME-type</var>] ...</code></td></tr>
 241 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 242 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 243 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 244 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 245 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.33 and later</td></tr>
 246 </table>
 247     <p>This directive activates a particular output <a href="../filter.html">filter</a> for a request depending on the
 248     response MIME-type.</p>
 249
 250     <p>The following example uses the <code>DEFLATE</code> filter, which
 251     is provided by <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code>. It will compress all
 252     output (either static or dynamic) which is labeled as
 253     <code>text/html</code> or <code>text/plain</code> before it is sent
 254     to the client.</p>
 255
 256     <div class="example"><p><code>
 257       AddOutputFilterByType DEFLATE text/html text/plain
 258     </code></p></div>
 259
 260     <p>If you want the content to be processed by more than one filter, their
 261     names have to be separated by semicolons. It's also possible to use one
 262     <code class="directive">AddOutputFilterByType</code> directive for each of
 263     these filters.</p>
 264
 265     <p>The configuration below causes all script output labeled as
 266     <code>text/html</code> to be processed at first by the
 267     <code>INCLUDES</code> filter and then by the <code>DEFLATE</code>
 268     filter.</p>
 269
 270     <div class="example"><p><code>
 271     &lt;Location /cgi-bin/&gt;<br />
 272     <span class="indent">
 273       Options Includes<br />
 274       AddOutputFilterByType INCLUDES;DEFLATE text/html<br />
 275     </span>
 276     &lt;/Location&gt;
 277     </code></p></div>
 278
 279     <div class="warning"><h3>Note</h3>
 280       <p>Enabling filters with <code class="directive">AddOutputFilterByType</code>
 281       may fail partially or completely in some cases. For expample, no
 282       filters are applied if the MIME-type could not be determined  and falls
 283       back to the <code class="directive"><a href="#defaulttype">DefaultType</a></code> setting,
 284       even if the <code class="directive"><a href="#defaulttype">DefaultType</a></code> is the
 285       same.</p>
 286
 287       <p>However, if you want to make sure, that the filters will be
 288       applied, assign the content type to a resource explicitely, for
 289       example with <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> or
 290       <code class="directive"><a href="#forcetype">ForceType</a></code>. Setting the
 291       content type within a (non-nph) CGI script is also safe.</p>
 292
 293       <p>The by-type output filters are never applied on proxy requests.</p>
 294     </div>
 295
 296 <h3>See also</h3>
 297 <ul>
 298 <li><code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code></li>
 299 <li><code class="directive"><a href="#setoutputfilter">SetOutputFilter</a></code></li>
 300 <li><a href="../filter.html">filters</a></li>
 301 </ul>
 302 </div>
 303 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 304 <div class="directive-section"><h2><a name="AllowEncodedSlashes" id="AllowEncodedSlashes">AllowEncodedSlashes</a> <a name="allowencodedslashes" id="allowencodedslashes">Directive</a></h2>
 305 <table class="directive">
 306 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether encoded path separators in URLs are allowed to
 307 be passed through</td></tr>
 308 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowEncodedSlashes On|Off</code></td></tr>
 309 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowEncodedSlashes Off</code></td></tr>
 310 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 311 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 312 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 313 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.46 and later</td></tr>
 314 </table>
 315     <p>The <code class="directive">AllowEncodedSlashes</code> directive allows URLs
 316     which contain encoded path separators (<code>%2F</code> for <code>/</code>
 317     and additionally <code>%5C</code> for <code>\</code> on according systems)
 318     to be used. Normally such URLs are refused with a 404 (Not found) error.</p>
 319
 320     <p>Turning <code class="directive">AllowEncodedSlashes</code> <code>On</code> is
 321     mostly useful when used in conjunction with <code>PATH_INFO</code>.</p>
 322
 323     <div class="note"><h3>Note</h3>
 324       <p>Allowing encoded slashes does <em>not</em> imply <em>decoding</em>.
 325       Occurences of <code>%2F</code> or <code>%5C</code> (<em>only</em> on
 326       according systems) will be left as such in the otherwise decoded URL
 327       string.</p>
 328     </div>
 329
 330 <h3>See also</h3>
 331 <ul>
 332 <li><code class="directive"><a href="#acceptpathinfo">AcceptPathInfo</a></code></li>
 333 </ul>
 334 </div>
 335 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 336 <div class="directive-section"><h2><a name="AllowOverride" id="AllowOverride">AllowOverride</a> <a name="allowoverride" id="allowoverride">Directive</a></h2>
 337 <table class="directive">
 338 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Types of directives that are allowed in
 339 .htaccess files</td></tr>
 340 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowOverride All|None|<var>directive-type</var>
 341 [<var>directive-type</var>] ...</code></td></tr>
 342 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowOverride All</code></td></tr>
 343 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 344 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 345 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 346 </table>
 347     <p>When the server finds an <code>.htaccess</code> file (as
 348     specified by <code class="directive"><a href="#accessfilename">AccessFileName</a></code>)
 349     it needs to know which directives declared in that file can override
 350     earlier configuration directives.</p>
 351
 352     <div class="note"><h3>Only available in &lt;Directory&gt; sections</h3>
 353     <code class="directive">AllowOverride</code> is valid only in
 354     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
 355     sections, not in <code class="directive"><a href="#location">&lt;Location&gt;</a></code> or <code class="directive"><a href="#files">&lt;Files&gt;</a></code> sections.
 356     </div>
 357
 358     <p>When this directive is set to <code>None</code>, then
 359     <a href="#accessfilename">.htaccess</a> files are completely ignored.
 360     In this case, the server will not even attempt to read
 361     <code>.htaccess</code> files in the filesystem.</p>
 362
 363     <p>When this directive is set to <code>All</code>, then any
 364     directive which has the .htaccess <a href="directive-dict.html#Context">Context</a> is allowed in
 365     <code>.htaccess</code> files.</p>
 366
 367     <p>The <var>directive-type</var> can be one of the following
 368     groupings of directives.</p>
 369
 370     <dl>
 371       <dt>AuthConfig</dt>
 372
 373       <dd>
 374
 375       Allow use of the authorization directives (<code class="directive"><a href="../mod/mod_authn_dbm.html#authdbmgroupfile">AuthDBMGroupFile</a></code>,
 376       <code class="directive"><a href="../mod/mod_authn_dbm.html#authdbmuserfile">AuthDBMUserFile</a></code>,
 377       <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>,
 378       <code class="directive"><a href="#authname">AuthName</a></code>,
 379       <code class="directive"><a href="#authtype">AuthType</a></code>, <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code>, <code class="directive"><a href="#require">Require</a></code>, <em>etc.</em>).</dd>
 380
 381       <dt>FileInfo</dt>
 382
 383       <dd>
 384       Allow use of the directives controlling document types (<code class="directive"><a href="#defaulttype">DefaultType</a></code>, <code class="directive"><a href="#errordocument">ErrorDocument</a></code>, <code class="directive"><a href="#forcetype">ForceType</a></code>, <code class="directive"><a href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>,
 385       <code class="directive"><a href="#sethandler">SetHandler</a></code>, <code class="directive"><a href="#setinputfilter">SetInputFilter</a></code>, <code class="directive"><a href="#setoutputfilter">SetOutputFilter</a></code>, and
 386       <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> Add* and Remove*
 387       directives, <em>etc.</em>).</dd>
 388
 389       <dt>Indexes</dt>
 390
 391       <dd>
 392       Allow use of the directives controlling directory indexing
 393       (<code class="directive"><a href="../mod/mod_autoindex.html#adddescription">AddDescription</a></code>,
 394       <code class="directive"><a href="../mod/mod_autoindex.html#addicon">AddIcon</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#addiconbyencoding">AddIconByEncoding</a></code>,
 395       <code class="directive"><a href="../mod/mod_autoindex.html#addiconbytype">AddIconByType</a></code>,
 396       <code class="directive"><a href="../mod/mod_autoindex.html#defaulticon">DefaultIcon</a></code>, <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#fancyindexing">FancyIndexing</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#headername">HeaderName</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#indexignore">IndexIgnore</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#indexoptions">IndexOptions</a></code>, <code class="directive"><a href="../mod/mod_autoindex.html#readmename">ReadmeName</a></code>,
 397       <em>etc.</em>).</dd>
 398
 399       <dt>Limit</dt>
 400
 401       <dd>
 402       Allow use of the directives controlling host access (<code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code>, <code class="directive"><a href="../mod/mod_authz_host.html#deny">Deny</a></code> and <code class="directive"><a href="../mod/mod_authz_host.html#order">Order</a></code>).</dd>
 403
 404       <dt>Options</dt>
 405
 406       <dd>
 407       Allow use of the directives controlling specific directory
 408       features (<code class="directive"><a href="#options">Options</a></code> and
 409       <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code>).</dd>
 410     </dl>
 411
 412     <p>Example:</p>
 413
 414     <div class="example"><p><code>
 415       AllowOverride AuthConfig Indexes
 416     </code></p></div>
 417
 418 <h3>See also</h3>
 419 <ul>
 420 <li><code class="directive"><a href="#accessfilename">AccessFileName</a></code></li>
 421 <li><a href="../configuring.html">Configuration Files</a></li>
 422 <li><a href="../howto/htaccess.html">.htaccess Files</a></li>
 423 </ul>
 424 </div>
 425 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 426 <div class="directive-section"><h2><a name="AuthName" id="AuthName">AuthName</a> <a name="authname" id="authname">Directive</a></h2>
 427 <table class="directive">
 428 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Authorization realm for use in HTTP
 429 authentication</td></tr>
 430 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthName <var>auth-domain</var></code></td></tr>
 431 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 432 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 433 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 434 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 435 </table>
 436     <p>This directive sets the name of the authorization realm for a
 437     directory. This realm is given to the client so that the user
 438     knows which username and password to send.
 439     <code class="directive">AuthName</code> takes a single argument; if the
 440     realm name contains spaces, it must be enclosed in quotation
 441     marks.  It must be accompanied by <code class="directive"><a href="#authtype">AuthType</a></code> and <code class="directive"><a href="#require">Require</a></code> directives, and directives such
 442     as <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> and
 443     <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code> to
 444     work.</p>
 445
 446    <p>For example:</p>
 447
 448    <div class="example"><p><code>
 449      AuthName "Top Secret"
 450    </code></p></div>
 451
 452     <p>The string provided for the <code>AuthName</code> is what will
 453     appear in the password dialog provided by most browsers.</p>
 454
 455 <h3>See also</h3>
 456 <ul>
 457 <li><a href="../howto/auth.html">Authentication, Authorization, and
 458     Access Control</a></li>
 459 </ul>
 460 </div>
 461 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 462 <div class="directive-section"><h2><a name="AuthType" id="AuthType">AuthType</a> <a name="authtype" id="authtype">Directive</a></h2>
 463 <table class="directive">
 464 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of user authentication</td></tr>
 465 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthType Basic|Digest</code></td></tr>
 466 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 467 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 468 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 469 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 470 </table>
 471     <p>This directive selects the type of user authentication for a
 472     directory. Only <code>Basic</code> and <code>Digest</code> are
 473     currently implemented.
 474
 475      It must be accompanied by <code class="directive"><a href="#authname">AuthName</a></code> and <code class="directive"><a href="#require">Require</a></code> directives, and directives such
 476      as <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> and
 477      <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code> to
 478      work.</p>
 479
 480 <h3>See also</h3>
 481 <ul>
 482 <li><a href="../howto/auth.html">Authentication, Authorization,
 483 and Access Control</a></li>
 484 </ul>
 485 </div>
 486 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 487 <div class="directive-section"><h2><a name="CGIMapExtension" id="CGIMapExtension">CGIMapExtension</a> <a name="cgimapextension" id="cgimapextension">Directive</a></h2>
 488 <table class="directive">
 489 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI
 490 scripts</td></tr>
 491 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIMapExtension <var>cgi-path</var> <var>.extension</var></code></td></tr>
 492 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 493 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 494 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 495 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 496 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>NetWare only</td></tr>
 497 </table>
 498     <p>This directive is used to control how Apache finds the
 499     interpreter used to run CGI scripts. For example, setting
 500     <code>CGIMapExtension sys:\foo.nlm .foo</code> will
 501     cause all CGI script files with a <code>.foo</code> extension to
 502     be passed to the FOO interpreter.</p>
 503
 504 </div>
 505 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 506 <div class="directive-section"><h2><a name="ContentDigest" id="ContentDigest">ContentDigest</a> <a name="contentdigest" id="contentdigest">Directive</a></h2>
 507 <table class="directive">
 508 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables the generation of Content-MD5 HTTP Response
 509 headers</td></tr>
 510 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ContentDigest On|Off</code></td></tr>
 511 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ContentDigest Off</code></td></tr>
 512 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 513 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
 514 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 515 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 516 </table>
 517     <p>This directive enables the generation of
 518     <code>Content-MD5</code> headers as defined in RFC1864
 519     respectively RFC2068.</p>
 520
 521     <p>MD5 is an algorithm for computing a "message digest"
 522     (sometimes called "fingerprint") of arbitrary-length data, with
 523     a high degree of confidence that any alterations in the data
 524     will be reflected in alterations in the message digest.</p>
 525
 526     <p>The <code>Content-MD5</code> header provides an end-to-end
 527     message integrity check (MIC) of the entity-body. A proxy or
 528     client may check this header for detecting accidental
 529     modification of the entity-body in transit. Example header:</p>
 530
 531     <div class="example"><p><code>
 532       Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==
 533     </code></p></div>
 534
 535     <p>Note that this can cause performance problems on your server
 536     since the message digest is computed on every request (the
 537     values are not cached).</p>
 538
 539     <p><code>Content-MD5</code> is only sent for documents served
 540     by the <code class="module"><a href="../mod/core.html">core</a></code>, and not by any module. For example,
 541     SSI documents, output from CGI scripts, and byte range responses
 542     do not have this header.</p>
 543
 544 </div>
 545 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 546 <div class="directive-section"><h2><a name="DefaultType" id="DefaultType">DefaultType</a> <a name="defaulttype" id="defaulttype">Directive</a></h2>
 547 <table class="directive">
 548 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>MIME content-type that will be sent if the
 549 server cannot determine a type in any other way</td></tr>
 550 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultType <var>MIME-type</var></code></td></tr>
 551 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultType text/plain</code></td></tr>
 552 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 553 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 554 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 555 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 556 </table>
 557     <p>There will be times when the server is asked to provide a
 558     document whose type cannot be determined by its MIME types
 559     mappings.</p>
 560
 561     <p>The server must inform the client of the content-type of the
 562     document, so in the event of an unknown type it uses the
 563     <code>DefaultType</code>. For example:</p>
 564
 565     <div class="example"><p><code>
 566       DefaultType image/gif
 567     </code></p></div>
 568
 569     <p>would be appropriate for a directory which contained many GIF
 570     images with filenames missing the <code>.gif</code> extension.</p>
 571
 572     <p>Note that unlike <code class="directive"><a href="#forcetype">ForceType</a></code>, this directive only
 573     provides the default mime-type. All other mime-type definitions,
 574     including filename extensions, that might identify the media type
 575     will override this default.</p>
 576
 577 </div>
 578 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 579 <div class="directive-section"><h2><a name="Directory" id="Directory">&lt;Directory&gt;</a> <a name="directory" id="directory">Directive</a></h2>
 580 <table class="directive">
 581 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of directives that apply only to the
 582 named file-system directory and sub-directories</td></tr>
 583 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Directory <var>directory-path</var>&gt;
 584 ... &lt;/Directory&gt;</code></td></tr>
 585 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 586 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 587 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 588 </table>
 589     <p><code class="directive">&lt;Directory&gt;</code> and
 590     <code>&lt;/Directory&gt;</code> are used to enclose a group of
 591     directives that will apply only to the named directory and
 592     sub-directories of that directory. Any directive that is allowed
 593     in a directory context may be used. <var>Directory-path</var> is
 594     either the full path to a directory, or a wild-card string using
 595     Unix shell-style matching. In a wild-card string, <code>?</code> matches
 596     any single character, and <code>*</code> matches any sequences of
 597     characters. You may also use <code>[]</code> character ranges. None
 598     of the wildcards match a `/' character, so <code>&lt;Directory
 599     /*/public_html&gt;</code> will not match
 600     <code>/home/user/public_html</code>, but <code>&lt;Directory
 601     /home/*/public_html&gt;</code> will match. Example:</p>
 602
 603     <div class="example"><p><code>
 604       &lt;Directory /usr/local/httpd/htdocs&gt;<br />
 605       <span class="indent">
 606         Options Indexes FollowSymLinks<br />
 607       </span>
 608       &lt;/Directory&gt;
 609     </code></p></div>
 610
 611     <div class="note">
 612       <p>Be careful with the <var>directory-path</var> arguments:
 613       They have to literally match the filesystem path which Apache uses
 614       to access the files. Directives applied to a particular
 615       <code>&lt;Directory&gt;</code> will not apply to files accessed from
 616       that same directory via a different path, such as via different symbolic
 617       links.</p>
 618     </div>
 619
 620     <p>Extended regular
 621     expressions can also be used, with the addition of the
 622     <code>~</code> character. For example:</p>
 623
 624     <div class="example"><p><code>
 625       &lt;Directory ~ "^/www/.*/[0-9]{3}"&gt;
 626     </code></p></div>
 627
 628     <p>would match directories in <code>/www/</code> that consisted of
 629     three numbers.</p>
 630
 631     <p>If multiple (non-regular expression) <code class="directive">&lt;Directory&gt;</code> sections
 632     match the directory (or one of its parents) containing a document,
 633     then the directives are applied in the order of shortest match
 634     first, interspersed with the directives from the <a href="#accessfilename">.htaccess</a> files. For example,
 635     with</p>
 636
 637     <div class="example"><p><code>
 638       &lt;Directory /&gt;<br />
 639       <span class="indent">
 640         AllowOverride None<br />
 641       </span>
 642       &lt;/Directory&gt;<br />
 643       <br />
 644       &lt;Directory /home/&gt;<br />
 645       <span class="indent">
 646         AllowOverride FileInfo<br />
 647       </span>
 648       &lt;/Directory&gt;
 649     </code></p></div>
 650
 651     <p>for access to the document <code>/home/web/dir/doc.html</code>
 652     the steps are:</p>
 653
 654     <ul>
 655       <li>Apply directive <code>AllowOverride None</code>
 656       (disabling <code>.htaccess</code> files).</li>
 657
 658       <li>Apply directive <code>AllowOverride FileInfo</code> (for
 659       directory <code>/home</code>).</li>
 660
 661       <li>Apply any <code>FileInfo</code> directives in
 662       <code>/home/.htaccess</code>, <code>/home/web/.htaccess</code> and
 663       <code>/home/web/dir/.htaccess</code> in that order.</li>
 664     </ul>
 665
 666     <p>Regular expressions are not considered until after all of the
 667     normal sections have been applied. Then all of the regular
 668     expressions are tested in the order they appeared in the
 669     configuration file. For example, with</p>
 670
 671     <div class="example"><p><code>
 672       &lt;Directory ~ abc$&gt;<br />
 673       <span class="indent">
 674         # ... directives here ...<br />
 675       </span>
 676       &lt;/Directory&gt;
 677     </code></p></div>
 678
 679     <p>the regular expression section won't be considered until after
 680     all normal <code class="directive">&lt;Directory&gt;</code>s and
 681     <code>.htaccess</code> files have been applied. Then the regular
 682     expression will match on <code>/home/abc/public_html/abc</code> and
 683     the corresponding <code class="directive">&lt;Directory&gt;</code> will
 684     be applied.</p>
 685
 686    <p><strong>Note that the default Apache access for
 687     <code>&lt;Directory /&gt;</code> is <code>Allow from All</code>.
 688     This means that Apache will serve any file mapped from an URL. It is
 689     recommended that you change this with a block such
 690     as</strong></p>
 691
 692     <div class="example"><p><code>
 693       &lt;Directory /&gt;<br />
 694       <span class="indent">
 695         Order Deny,Allow<br />
 696         Deny from All<br />
 697       </span>
 698       &lt;/Directory&gt;
 699     </code></p></div>
 700
 701     <p><strong>and then override this for directories you
 702     <em>want</em> accessible. See the <a href="../misc/security_tips.html">Security Tips</a> page for more
 703     details.</strong></p>
 704
 705     <p>The directory sections occur in the <code>httpd.conf</code> file.
 706     <code class="directive">&lt;Directory&gt;</code> directives
 707     cannot nest, and cannot appear in a <code class="directive"><a href="#limit">&lt;Limit&gt;</a></code> or <code class="directive"><a href="#limitexcept">&lt;LimitExcept&gt;</a></code> section.</p>
 708
 709 <h3>See also</h3>
 710 <ul>
 711 <li><a href="../sections.html">How &lt;Directory&gt;,
 712     &lt;Location&gt; and &lt;Files&gt; sections work</a> for an
 713     explanation of how these different sections are combined when a
 714     request is received</li>
 715 </ul>
 716 </div>
 717 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 718 <div class="directive-section"><h2><a name="DirectoryMatch" id="DirectoryMatch">&lt;DirectoryMatch&gt;</a> <a name="directorymatch" id="directorymatch">Directive</a></h2>
 719 <table class="directive">
 720 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose directives that apply to
 721 file-system directories matching a regular expression and their
 722 subdirectories</td></tr>
 723 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;DirectoryMatch <var>regex</var>&gt;
 724 ... &lt;/DirectoryMatch&gt;</code></td></tr>
 725 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 726 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 727 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 728 </table>
 729     <p><code class="directive">&lt;DirectoryMatch&gt;</code> and
 730     <code>&lt;/DirectoryMatch&gt;</code> are used to enclose a group
 731     of directives which will apply only to the named directory and
 732     sub-directories of that directory, the same as <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>. However, it
 733     takes as an argument a regular expression. For example:</p>
 734
 735     <div class="example"><p><code>
 736       &lt;DirectoryMatch "^/www/.*/[0-9]{3}"&gt;
 737     </code></p></div>
 738
 739     <p>would match directories in <code>/www/</code> that consisted of three
 740     numbers.</p>
 741
 742 <h3>See also</h3>
 743 <ul>
 744 <li><code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> for
 745 a description of how regular expressions are mixed in with normal
 746 <code class="directive">&lt;Directory&gt;</code>s</li>
 747 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt; and
 748 &lt;Files&gt; sections work</a> for an explanation of how these different
 749 sections are combined when a request is received</li>
 750 </ul>
 751 </div>
 752 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 753 <div class="directive-section"><h2><a name="DocumentRoot" id="DocumentRoot">DocumentRoot</a> <a name="documentroot" id="documentroot">Directive</a></h2>
 754 <table class="directive">
 755 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory that forms the main document tree visible
 756 from the web</td></tr>
 757 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DocumentRoot <var>directory-path</var></code></td></tr>
 758 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DocumentRoot /usr/local/apache/htdocs</code></td></tr>
 759 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 760 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 761 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 762 </table>
 763     <p>This directive sets the directory from which <code>httpd</code>
 764     will serve files. Unless matched by a directive like <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, the server appends the
 765     path from the requested URL to the document root to make the
 766     path to the document. Example:</p>
 767
 768     <div class="example"><p><code>
 769       DocumentRoot /usr/web
 770     </code></p></div>
 771
 772     <p>then an access to
 773     <code>http://www.my.host.com/index.html</code> refers to
 774     <code>/usr/web/index.html</code>. If the <var>directory-path</var> is
 775     not absolute then it is assumed to be relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p>
 776
 777     <p>The <code class="directive">DocumentRoot</code> should be specified without
 778     a trailing slash.</p>
 779
 780 <h3>See also</h3>
 781 <ul>
 782 <li><a href="../urlmapping.html">Mapping URLs to Filesystem
 783 Location</a></li>
 784 </ul>
 785 </div>
 786 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 787 <div class="directive-section"><h2><a name="EnableMMAP" id="EnableMMAP">EnableMMAP</a> <a name="enablemmap" id="enablemmap">Directive</a></h2>
 788 <table class="directive">
 789 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use memory-mapping to read files during delivery</td></tr>
 790 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableMMAP On|Off</code></td></tr>
 791 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableMMAP On</code></td></tr>
 792 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 793 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 794 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 795 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 796 </table>
 797     <p>This directive controls whether the <code>httpd</code> may use
 798     memory-mapping if it needs to read the contents of a file during
 799     delivery.  By default, when the handling of a request requires
 800     access to the data within a file -- for example, when delivering a
 801     server-parsed file using <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> -- Apache
 802     memory-maps the file if the OS supports it.</p>
 803
 804     <p>This memory-mapping sometimes yields a performance improvement.
 805     But in some environments, it is better to disable the memory-mapping
 806     to prevent operational problems:</p>
 807
 808     <ul>
 809     <li>On some multiprocessor systems, memory-mapping can reduce the
 810     performance of the <code>httpd</code>.</li>
 811     <li>With an NFS-mounted <code class="directive"><a href="#documentroot">DocumentRoot</a></code>,
 812     the <code>httpd</code> may crash due to a segmentation fault if a file
 813     is deleted or truncated while the <code>httpd</code> has it
 814     memory-mapped.</li>
 815     </ul>
 816
 817     <p>For server configurations that are vulnerable to these problems,
 818     you should disable memory-mapping of delivered files by specifying:</p>
 819
 820     <div class="example"><p><code>
 821       EnableMMAP Off
 822     </code></p></div>
 823
 824     <p>For NFS mounted files, this feature may be disabled explicitly for
 825     the offending files by specifying:</p>
 826
 827     <div class="example"><p><code>
 828       &lt;Directory "/path-to-nfs-files"&gt;
 829       <span class="indent">
 830         EnableMMAP Off
 831       </span>
 832       &lt;/Directory&gt;
 833     </code></p></div>
 834
 835 </div>
 836 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 837 <div class="directive-section"><h2><a name="EnableSendfile" id="EnableSendfile">EnableSendfile</a> <a name="enablesendfile" id="enablesendfile">Directive</a></h2>
 838 <table class="directive">
 839 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the kernel sendfile support to deliver files to the client</td></tr>
 840 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableSendfile On|Off</code></td></tr>
 841 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableSendfile On</code></td></tr>
 842 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 843 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 844 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 845 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 846 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.44 and later</td></tr>
 847 </table>
 848     <p>This directive controls whether <code>httpd</code> may use the sendfile
 849     support from the kernel to transmit file contents to the client.
 850     By default, when the handling of a request requires no access
 851     to the data within a file -- for example, when delivering a
 852     static file -- Apache uses sendfile to deliver the file contents
 853     without ever reading the file if the OS supports it.</p>
 854
 855     <p>This sendfile mechanism avoids seperate read and send operations,
 856     and buffer allocations. But on some platforms or within some
 857     filesystems, it is better to disable this feature to avoid
 858     operational problems:</p>
 859
 860     <ul>
 861     <li>Some platforms may have broken sendfile support that the build
 862     system did not detect, especially if the binaries were built on
 863     another box and moved to such a machine with broken sendfile
 864     support.</li>
 865     <li>With a network-mounted <code class="directive"><a href="#documentroot">DocumentRoot</a></code> (e.g., NFS or SMB),
 866     the kernel may be unable to serve the network file through
 867     its own cache.</li>
 868     </ul>
 869
 870     <p>For server configurations that are vulnerable to these problems,
 871     you should disable this feature by specifying:</p>
 872
 873     <div class="example"><p><code>
 874       EnableSendfile Off
 875     </code></p></div>
 876
 877     <p>For NFS or SMB mounted files, this feature may be disabled explicitly
 878     for the offending files by specifying:</p>
 879
 880     <div class="example"><p><code>
 881       &lt;Directory "/path-to-nfs-files"&gt;
 882       <span class="indent">
 883         EnableSendfile Off
 884       </span>
 885       &lt;/Directory&gt;
 886     </code></p></div>
 887
 888 </div>
 889 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 890 <div class="directive-section"><h2><a name="ErrorDocument" id="ErrorDocument">ErrorDocument</a> <a name="errordocument" id="errordocument">Directive</a></h2>
 891 <table class="directive">
 892 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>What the server will return to the client
 893 in case of an error</td></tr>
 894 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ErrorDocument <var>error-code</var> <var>document</var></code></td></tr>
 895 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 896 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 897 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 898 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 899 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Quoting syntax for text messages is different in Apache
 900 2.0</td></tr>
 901 </table>
 902     <p>In the event of a problem or error, Apache can be configured
 903     to do one of four things,</p>
 904
 905     <ol>
 906       <li>output a simple hardcoded error message</li>
 907
 908       <li>output a customized message</li>
 909
 910       <li>redirect to a local <var>URL-path</var> to handle the
 911       problem/error</li>
 912
 913       <li>redirect to an external <var>URL</var> to handle the
 914       problem/error</li>
 915     </ol>
 916
 917     <p>The first option is the default, while options 2-4 are
 918     configured using the <code class="directive">ErrorDocument</code>
 919     directive, which is followed by the HTTP response code and a URL
 920     or a message. Apache will sometimes offer additional information
 921     regarding the problem/error.</p>
 922
 923     <p>URLs can begin with a slash (/) for local URLs, or be a full
 924     URL which the client can resolve. Alternatively, a message can
 925     be provided to be displayed by the browser. Examples:</p>
 926
 927     <div class="example"><p><code>
 928       ErrorDocument 500 http://foo.example.com/cgi-bin/tester<br />
 929       ErrorDocument 404 /cgi-bin/bad_urls.pl<br />
 930       ErrorDocument 401 /subscription_info.html<br />
 931       ErrorDocument 403 "Sorry can't allow you access today"
 932     </code></p></div>
 933
 934     <p>Note that when you specify an <code class="directive">ErrorDocument</code>
 935     that points to a remote URL (ie. anything with a method such as
 936     <code>http</code> in front of it), Apache will send a redirect to the
 937     client to tell it where to find the document, even if the
 938     document ends up being on the same server. This has several
 939     implications, the most important being that the client will not
 940     receive the original error status code, but instead will
 941     receive a redirect status code. This in turn can confuse web
 942     robots and other clients which try to determine if a URL is
 943     valid using the status code. In addition, if you use a remote
 944     URL in an <code>ErrorDocument 401</code>, the client will not
 945     know to prompt the user for a password since it will not
 946     receive the 401 status code. Therefore, <strong>if you use an
 947     <code>ErrorDocument 401</code> directive then it must refer to a local
 948     document.</strong></p>
 949
 950     <p>Microsoft Internet Explorer (MSIE) will by default ignore
 951     server-generated error messages when they are "too small" and substitute
 952     its own "friendly" error messages. The size threshold varies depending on
 953     the type of error, but in general, if you make your error document
 954     greater than 512 bytes, then MSIE will show the server-generated
 955     error rather than masking it.  More information is available in
 956     Microsoft Knowledgebase article <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q294807">Q294807</a>.</p>
 957
 958     <p>Prior to version 2.0, messages were indicated by prefixing
 959     them with a single unmatched double quote character.</p>
 960
 961 <h3>See also</h3>
 962 <ul>
 963 <li><a href="../custom-error.html">documentation of
 964     customizable responses</a></li>
 965 </ul>
 966 </div>
 967 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 968 <div class="directive-section"><h2><a name="ErrorLog" id="ErrorLog">ErrorLog</a> <a name="errorlog" id="errorlog">Directive</a></h2>
 969 <table class="directive">
 970 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location where the server will log errors</td></tr>
 971 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> ErrorLog <var>file-path</var>|syslog[:<var>facility</var>]</code></td></tr>
 972 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)</code></td></tr>
 973 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 974 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 975 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 976 </table>
 977     <p>The <code class="directive">ErrorLog</code> directive sets the name of
 978     the file to which the server will log any errors it encounters. If
 979     the <var>file-path</var> is not absolute then it is assumed to be
 980     relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p>
 981
 982     <div class="example"><h3>Example</h3><p><code>
 983     ErrorLog /var/log/httpd/error_log
 984     </code></p></div>
 985
 986     <p>If the <var>file-path</var>
 987     begins with a pipe (|) then it is assumed to be a command to spawn
 988     to handle the error log.</p>
 989
 990     <div class="example"><h3>Example</h3><p><code>
 991     ErrorLog "|/usr/local/bin/httpd_errors"
 992     </code></p></div>
 993
 994     <p>Using <code>syslog</code> instead of a filename enables logging
 995     via syslogd(8) if the system supports it. The default is to use
 996     syslog facility <code>local7</code>, but you can override this by
 997     using the <code>syslog:<var>facility</var></code> syntax where
 998     <var>facility</var> can be one of the names usually documented in
 999     syslog(1).</p>
1000
1001     <div class="example"><h3>Example</h3><p><code>
1002     ErrorLog syslog:user
1003     </code></p></div>
1004
1005     <p>SECURITY: See the <a href="../misc/security_tips.html#serverroot">security tips</a>
1006     document for details on why your security could be compromised
1007     if the directory where logfiles are stored is writable by
1008     anyone other than the user that starts the server.</p>
1009     <div class="warning"><h3>Note</h3>
1010       <p>When entering a file path on non-Unix platforms, care should be taken
1011       to make sure that only forward slashed are used even though the platform
1012       may allow the use of back slashes. In general it is a good idea to always
1013       use forward slashes throughout the configuration files.</p>
1014     </div>
1015
1016 <h3>See also</h3>
1017 <ul>
1018 <li><code class="directive"><a href="#loglevel">LogLevel</a></code></li>
1019 <li><a href="../logs.html">Apache Log Files</a></li>
1020 </ul>
1021 </div>
1022 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1023 <div class="directive-section"><h2><a name="FileETag" id="FileETag">FileETag</a> <a name="fileetag" id="fileetag">Directive</a></h2>
1024 <table class="directive">
1025 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File attributes used to create the ETag
1026 HTTP response header</td></tr>
1027 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FileETag <var>component</var> ...</code></td></tr>
1028 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>FileETag INode MTime Size</code></td></tr>
1029 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1030 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1031 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1032 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1033 </table>
1034     <p>
1035     The <code class="directive">FileETag</code> directive configures the file
1036     attributes that are used to create the <code>ETag</code> (entity
1037     tag) response header field when the document is based on a file.
1038     (The <code>ETag</code> value is used in cache management to save
1039     network bandwidth.) In Apache 1.3.22 and earlier, the
1040     <code>ETag</code> value was <em>always</em> formed
1041     from the file's inode, size, and last-modified time (mtime). The
1042     <code class="directive">FileETag</code> directive allows you to choose
1043     which of these -- if any -- should be used. The recognized keywords are:
1044     </p>
1045
1046     <dl>
1047      <dt><strong>INode</strong></dt>
1048      <dd>The file's i-node number will be included in the calculation</dd>
1049      <dt><strong>MTime</strong></dt>
1050      <dd>The date and time the file was last modified will be included</dd>
1051      <dt><strong>Size</strong></dt>
1052      <dd>The number of bytes in the file will be included</dd>
1053      <dt><strong>All</strong></dt>
1054      <dd>All available fields will be used. This is equivalent to:
1055          <div class="example"><p><code>FileETag INode MTime Size</code></p></div></dd>
1056      <dt><strong>None</strong></dt>
1057      <dd>If a document is file-based, no <code>ETag</code> field will be
1058        included in the response</dd>
1059     </dl>
1060
1061     <p>The <code>INode</code>, <code>MTime</code>, and <code>Size</code>
1062     keywords may be prefixed with either <code>+</code> or <code>-</code>,
1063     which allow changes to be made to the default setting inherited
1064     from a broader scope. Any keyword appearing without such a prefix
1065     immediately and completely cancels the inherited setting.</p>
1066
1067     <p>If a directory's configuration includes
1068     <code>FileETag&nbsp;INode&nbsp;MTime&nbsp;Size</code>, and a
1069     subdirectory's includes <code>FileETag&nbsp;-INode</code>,
1070     the setting for that subdirectory (which will be inherited by
1071     any sub-subdirectories that don't override it) will be equivalent to
1072     <code>FileETag&nbsp;MTime&nbsp;Size</code>.</p>
1073
1074 </div>
1075 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1076 <div class="directive-section"><h2><a name="Files" id="Files">&lt;Files&gt;</a> <a name="files" id="files">Directive</a></h2>
1077 <table class="directive">
1078 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to matched
1079 filenames</td></tr>
1080 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Files <var>filename</var>&gt; ... &lt;/Files&gt;</code></td></tr>
1081 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1082 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1083 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1084 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1085 </table>
1086     <p>The <code class="directive">&lt;Files&gt;</code> directive
1087     limits the scope of the enclosed directives by filename. It is comparable
1088     to the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
1089     and <code class="directive"><a href="#location">&lt;Location&gt;</a></code>
1090     directives. It should be matched with a <code>&lt;/Files&gt;</code>
1091     directive. The directives given within this section will be applied to
1092     any object with a basename (last component of filename) matching the
1093     specified filename. <code class="directive">&lt;Files&gt;</code>
1094     sections are processed in the order they appear in the
1095     configuration file, after the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections and
1096     <code>.htaccess</code> files are read, but before <code class="directive"><a href="#location">&lt;Location&gt;</a></code> sections. Note
1097     that <code class="directive">&lt;Files&gt;</code> can be nested
1098     inside <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections to restrict the
1099     portion of the filesystem they apply to.</p>
1100
1101     <p>The <var>filename</var> argument should include a filename, or
1102     a wild-card string, where <code>?</code> matches any single character,
1103     and <code>*</code> matches any sequences of characters. Extended regular
1104     expressions can also be used, with the addition of the
1105     <code>~</code> character. For example:</p>
1106
1107     <div class="example"><p><code>
1108       &lt;Files ~ "\.(gif|jpe?g|png)$"&gt;
1109     </code></p></div>
1110
1111     <p>would match most common Internet graphics formats. <code class="directive"><a href="#filesmatch">&lt;FilesMatch&gt;</a></code> is preferred,
1112     however.</p>
1113
1114     <p>Note that unlike <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> and <code class="directive"><a href="#location">&lt;Location&gt;</a></code> sections, <code class="directive">&lt;Files&gt;</code> sections can be used inside
1115     <code>.htaccess</code> files. This allows users to control access to
1116     their own files, at a file-by-file level.</p>
1117
1118
1119 <h3>See also</h3>
1120 <ul>
1121 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1122     and &lt;Files&gt; sections work</a> for an explanation of how these
1123     different sections are combined when a request is received</li>
1124 </ul>
1125 </div>
1126 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1127 <div class="directive-section"><h2><a name="FilesMatch" id="FilesMatch">&lt;FilesMatch&gt;</a> <a name="filesmatch" id="filesmatch">Directive</a></h2>
1128 <table class="directive">
1129 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to regular-expression matched
1130 filenames</td></tr>
1131 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;FilesMatch <var>regex</var>&gt; ... &lt;/FilesMatch&gt;</code></td></tr>
1132 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1133 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1134 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1135 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1136 </table>
1137     <p>The <code class="directive">&lt;FilesMatch&gt;</code> directive
1138     limits the scope of the enclosed directives by filename, just as the
1139     <code class="directive"><a href="#files">&lt;Files&gt;</a></code> directive
1140     does. However, it accepts a regular expression. For example:</p>
1141
1142     <div class="example"><p><code>
1143       &lt;FilesMatch "\.(gif|jpe?g|png)$"&gt;
1144     </code></p></div>
1145
1146     <p>would match most common Internet graphics formats.</p>
1147
1148 <h3>See also</h3>
1149 <ul>
1150 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1151     and &lt;Files&gt; sections work</a> for an explanation of how these
1152     different sections are combined when a request is received</li>
1153 </ul>
1154 </div>
1155 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1156 <div class="directive-section"><h2><a name="ForceType" id="ForceType">ForceType</a> <a name="forcetype" id="forcetype">Directive</a></h2>
1157 <table class="directive">
1158 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be served with the specified
1159 MIME content-type</td></tr>
1160 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceType <var>MIME-type</var>|None</code></td></tr>
1161 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
1162 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1163 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1164 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1165 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Moved to the core in Apache 2.0</td></tr>
1166 </table>
1167     <p>When placed into an <code>.htaccess</code> file or a
1168     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>, or
1169     <code class="directive"><a href="#location">&lt;Location&gt;</a></code> or
1170     <code class="directive"><a href="#files">&lt;Files&gt;</a></code>
1171     section, this directive forces all matching files to be served
1172     with the content type identification given by
1173     <var>MIME-type</var>. For example, if you had a directory full of
1174     GIF files, but did not want to label them all with <code>.gif</code>,
1175     you might want to use:</p>
1176
1177     <div class="example"><p><code>
1178       ForceType image/gif
1179     </code></p></div>
1180
1181     <p>Note that unlike <code class="directive"><a href="#defaulttype">DefaultType</a></code>,
1182     this directive overrides all mime-type associations, including
1183     filename extensions, that might identify the media type.</p>
1184
1185     <p>You can override any <code class="directive">ForceType</code> setting
1186     by using the value of <code>None</code>:</p>
1187
1188     <div class="example"><p><code>
1189       # force all files to be image/gif:<br />
1190       &lt;Location /images&gt;<br />
1191         <span class="indent">
1192           ForceType image/gif<br />
1193         </span>
1194       &lt;/Location&gt;<br />
1195       <br />
1196       # but normal mime-type associations here:<br />
1197       &lt;Location /images/mixed&gt;<br />
1198       <span class="indent">
1199         ForceType None<br />
1200       </span>
1201       &lt;/Location&gt;
1202     </code></p></div>
1203
1204 </div>
1205 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1206 <div class="directive-section"><h2><a name="HostnameLookups" id="HostnameLookups">HostnameLookups</a> <a name="hostnamelookups" id="hostnamelookups">Directive</a></h2>
1207 <table class="directive">
1208 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables DNS lookups on client IP addresses</td></tr>
1209 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HostnameLookups On|Off|Double</code></td></tr>
1210 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>HostnameLookups Off</code></td></tr>
1211 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1212 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1213 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1214 </table>
1215     <p>This directive enables DNS lookups so that host names can be
1216     logged (and passed to CGIs/SSIs in <code>REMOTE_HOST</code>).
1217     The value <code>Double</code> refers to doing double-reverse
1218     DNS lookup. That is, after a reverse lookup is performed, a forward
1219     lookup is then performed on that result. At least one of the ip
1220     addresses in the forward lookup must match the original
1221     address. (In "tcpwrappers" terminology this is called
1222     <code>PARANOID</code>.)</p>
1223
1224     <p>Regardless of the setting, when <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code> is
1225     used for controlling access by hostname, a double reverse lookup
1226     will be performed.  This is necessary for security. Note that the
1227     result of this double-reverse isn't generally available unless you
1228     set <code>HostnameLookups Double</code>. For example, if only
1229     <code>HostnameLookups On</code> and a request is made to an object
1230     that is protected by hostname restrictions, regardless of whether
1231     the double-reverse fails or not, CGIs will still be passed the
1232     single-reverse result in <code>REMOTE_HOST</code>.</p>
1233
1234     <p>The default is <code>Off</code> in order to save the network
1235     traffic for those sites that don't truly need the reverse
1236     lookups done. It is also better for the end users because they
1237     don't have to suffer the extra latency that a lookup entails.
1238     Heavily loaded sites should leave this directive
1239     <code>Off</code>, since DNS lookups can take considerable
1240     amounts of time. The utility <a href="../programs/logresolve.html">logresolve</a>, compiled by default
1241     to the <code>bin</code> subdirectory of your installation directory, can
1242     be used to look up host names from logged IP addresses offline.</p>
1243
1244 </div>
1245 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1246 <div class="directive-section"><h2><a name="IfDefine" id="IfDefine">&lt;IfDefine&gt;</a> <a name="ifdefine" id="ifdefine">Directive</a></h2>
1247 <table class="directive">
1248 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that will be processed only
1249 if a test is true at startup</td></tr>
1250 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfDefine [!]<var>parameter-name</var>&gt; ...
1251     &lt;/IfDefine&gt;</code></td></tr>
1252 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1253 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1254 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1255 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1256 </table>
1257     <p>The <code>&lt;IfDefine <var>test</var>&gt;...&lt;/IfDefine&gt;
1258     </code> section is used to mark directives that are conditional. The
1259     directives within an <code class="directive">&lt;IfDefine&gt;</code>
1260     section are only processed if the <var>test</var> is true. If <var>
1261     test</var> is false, everything between the start and end markers is
1262     ignored.</p>
1263
1264     <p>The <var>test</var> in the <code class="directive">&lt;IfDefine&gt;</code> section directive can be one of two forms:</p>
1265
1266     <ul>
1267       <li><var>parameter-name</var></li>
1268
1269       <li><code>!</code><var>parameter-name</var></li>
1270     </ul>
1271
1272     <p>In the former case, the directives between the start and end
1273     markers are only processed if the parameter named
1274     <var>parameter-name</var> is defined. The second format reverses
1275     the test, and only processes the directives if
1276     <var>parameter-name</var> is <strong>not</strong> defined.</p>
1277
1278     <p>The <var>parameter-name</var> argument is a define as given on
1279     the <code>httpd</code> command line via <code>-D<var>parameter-</var>
1280     </code>, at the time the server was started.</p>
1281
1282     <p><code class="directive">&lt;IfDefine&gt;</code> sections are
1283     nest-able, which can be used to implement simple
1284     multiple-parameter tests. Example:</p>
1285
1286     <div class="example"><p><code>
1287       httpd -DReverseProxy ...<br />
1288       <br />
1289       # httpd.conf<br />
1290       &lt;IfDefine ReverseProxy&gt;<br />
1291       <span class="indent">
1292         LoadModule rewrite_module modules/mod_rewrite.so<br />
1293         LoadModule proxy_module   modules/libproxy.so<br />
1294       </span>
1295       &lt;/IfDefine&gt;
1296     </code></p></div>
1297
1298 </div>
1299 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1300 <div class="directive-section"><h2><a name="IfModule" id="IfModule">&lt;IfModule&gt;</a> <a name="ifmodule" id="ifmodule">Directive</a></h2>
1301 <table class="directive">
1302 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that are processed conditional on the
1303 presence or absence of a specific module</td></tr>
1304 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfModule [!]<var>module-name</var>&gt; ...
1305     &lt;/IfModule&gt;</code></td></tr>
1306 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1307 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1308 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1309 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1310 </table>
1311     <p>The <code>&lt;IfModule <var>test</var>&gt;...&lt;/IfModule&gt;</code>
1312     section is used to mark directives that are conditional on the presence of
1313     a specific module. The directives within an <code class="directive">&lt;IfModule&gt;</code> section are only processed if the <var>test</var>
1314     is true. If <var>test</var> is false, everything between the start and
1315     end markers is ignored.</p>
1316
1317     <p>The <var>test</var> in the <code class="directive">&lt;IfModule&gt;</code> section directive can be one of two forms:</p>
1318
1319     <ul>
1320       <li><var>module name</var></li>
1321
1322       <li>!<var>module name</var></li>
1323     </ul>
1324
1325     <p>In the former case, the directives between the start and end
1326     markers are only processed if the module named <var>module
1327     name</var> is included in Apache -- either compiled in or
1328     dynamically loaded using <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>. The second format reverses the test,
1329     and only processes the directives if <var>module name</var> is
1330     <strong>not</strong> included.</p>
1331
1332     <p>The <var>module name</var> argument is the file name of the
1333     module, at the time it was compiled.  For example,
1334     <code>mod_rewrite.c</code>.  If a module consists of several
1335     source files, use the name of the file containing the string
1336     <code>STANDARD20_MODULE_STUFF</code>.</p>
1337
1338     <p><code class="directive">&lt;IfModule&gt;</code> sections are
1339     nest-able, which can be used to implement simple multiple-module
1340     tests.</p>
1341
1342     <div class="note">This section should only be used if you need to have one
1343     configuration file that works whether or not a specific module
1344     is available. In normal operation, directives need not be
1345     placed in <code class="directive">&lt;IfModule&gt;</code>
1346     sections.</div>
1347
1348 </div>
1349 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1350 <div class="directive-section"><h2><a name="Include" id="Include">Include</a> <a name="include" id="include">Directive</a></h2>
1351 <table class="directive">
1352 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Includes other configuration files from within
1353 the server configuration files</td></tr>
1354 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Include <var>file-path</var>|<var>directory-path</var></code></td></tr>
1355 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1356 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1357 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1358 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Wildcard matching available in 2.0.41 and later</td></tr>
1359 </table>
1360     <p>This directive allows inclusion of other configuration files
1361     from within the server configuration files.</p>
1362
1363     <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used to
1364     include several files at once, in alphabetical order. In
1365     addition, if <code class="directive">Include</code> points to a directory,
1366     rather than a file, Apache will read all files in that directory
1367     and any subdirectory.  But including entire directories is not
1368     recommended, because it is easy to accidentally leave temporary
1369     files in a directory that can cause <code>httpd</code> to
1370     fail.</p>
1371
1372     <p>The file path specified may be an absolute path, or may be relative
1373     to the <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory.</p>
1374
1375     <p>Examples:</p>
1376
1377     <div class="example"><p><code>
1378       Include /usr/local/apache2/conf/ssl.conf<br />
1379       Include /usr/local/apache2/conf/vhosts/*.conf
1380     </code></p></div>
1381
1382     <p>Or, providing paths relative to your <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory:</p>
1383
1384     <div class="example"><p><code>
1385       Include conf/ssl.conf<br />
1386       Include conf/vhosts/*.conf
1387     </code></p></div>
1388
1389     <p>Running <code>apachectl configtest</code> will give you a list
1390     of the files that are being processed during the configuration
1391     check:</p>
1392
1393     <div class="example"><p><code>
1394       root@host# apachectl configtest<br />
1395       Processing config file: /usr/local/apache2/conf/ssl.conf<br />
1396       Processing config file: /usr/local/apache2/conf/vhosts/vhost1.conf<br />
1397       Processing config file: /usr/local/apache2/conf/vhosts/vhost2.conf<br />
1398       Syntax OK
1399     </code></p></div>
1400
1401 <h3>See also</h3>
1402 <ul>
1403 <li><a href="../programs/apachectl.html">apachectl</a></li>
1404 </ul>
1405 </div>
1406 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1407 <div class="directive-section"><h2><a name="KeepAlive" id="KeepAlive">KeepAlive</a> <a name="keepalive" id="keepalive">Directive</a></h2>
1408 <table class="directive">
1409 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables HTTP persistent connections</td></tr>
1410 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAlive On|Off</code></td></tr>
1411 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAlive On</code></td></tr>
1412 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1413 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1414 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1415 </table>
1416     <p>The Keep-Alive extension to HTTP/1.0 and the persistent
1417     connection feature of HTTP/1.1 provide long-lived HTTP sessions
1418     which allow multiple requests to be sent over the same TCP
1419     connection. In some cases this has been shown to result in an
1420     almost 50% speedup in latency times for HTML documents with
1421     many images. To enable Keep-Alive connections, set
1422     <code>KeepAlive On</code>.</p>
1423
1424     <p>For HTTP/1.0 clients, Keep-Alive connections will only be
1425     used if they are specifically requested by a client. In
1426     addition, a Keep-Alive connection with an HTTP/1.0 client can
1427     only be used when the length of the content is known in
1428     advance. This implies that dynamic content such as CGI output,
1429     SSI pages, and server-generated directory listings will
1430     generally not use Keep-Alive connections to HTTP/1.0 clients.
1431     For HTTP/1.1 clients, persistent connections are the default
1432     unless otherwise specified. If the client requests it, chunked
1433     encoding will be used in order to send content of unknown
1434     length over persistent connections.</p>
1435
1436 <h3>See also</h3>
1437 <ul>
1438 <li><code class="directive"><a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></code></li>
1439 </ul>
1440 </div>
1441 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1442 <div class="directive-section"><h2><a name="KeepAliveTimeout" id="KeepAliveTimeout">KeepAliveTimeout</a> <a name="keepalivetimeout" id="keepalivetimeout">Directive</a></h2>
1443 <table class="directive">
1444 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for subsequent
1445 requests on a persistent connection</td></tr>
1446 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAliveTimeout <var>seconds</var></code></td></tr>
1447 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAliveTimeout 15</code></td></tr>
1448 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1449 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1450 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1451 </table>
1452     <p>The number of seconds Apache will wait for a subsequent
1453     request before closing the connection. Once a request has been
1454     received, the timeout value specified by the
1455     <code class="directive"><a href="#timeout">Timeout</a></code> directive applies.</p>
1456
1457     <p>Setting <code class="directive">KeepAliveTimeout</code> to a high value
1458     may cause performance problems in heavily loaded servers. The
1459     higher the timeout, the more server processes will be kept
1460     occupied waiting on connections with idle clients.</p>
1461
1462 </div>
1463 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1464 <div class="directive-section"><h2><a name="Limit" id="Limit">&lt;Limit&gt;</a> <a name="limit" id="limit">Directive</a></h2>
1465 <table class="directive">
1466 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict enclosed access controls to only certain HTTP
1467 methods</td></tr>
1468 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Limit <var>method</var> [<var>method</var>] ... &gt; ...
1469     &lt;/Limit&gt;</code></td></tr>
1470 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1471 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1472 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1473 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1474 </table>
1475     <p>Access controls are normally effective for
1476     <strong>all</strong> access methods, and this is the usual
1477     desired behavior. <strong>In the general case, access control
1478     directives should not be placed within a
1479     <code class="directive">&lt;Limit&gt;</code> section.</strong></p>
1480
1481     <p>The purpose of the <code class="directive">&lt;Limit&gt;</code>
1482     directive is to restrict the effect of the access controls to the
1483     nominated HTTP methods. For all other methods, the access
1484     restrictions that are enclosed in the <code class="directive">&lt;Limit&gt;</code> bracket <strong>will have no
1485     effect</strong>. The following example applies the access control
1486     only to the methods <code>POST</code>, <code>PUT</code>, and
1487     <code>DELETE</code>, leaving all other methods unprotected:</p>
1488
1489     <div class="example"><p><code>
1490       &lt;Limit POST PUT DELETE&gt;<br />
1491       <span class="indent">
1492         Require valid-user<br />
1493       </span>
1494       &lt;/Limit&gt;
1495     </code></p></div>
1496
1497     <p>The method names listed can be one or more of: <code>GET</code>,
1498     <code>POST</code>, <code>PUT</code>, <code>DELETE</code>,
1499     <code>CONNECT</code>, <code>OPTIONS</code>,
1500     <code>PATCH</code>, <code>PROPFIND</code>, <code>PROPPATCH</code>,
1501     <code>MKCOL</code>, <code>COPY</code>, <code>MOVE</code>,
1502     <code>LOCK</code>, and <code>UNLOCK</code>. <strong>The method name is
1503     case-sensitive.</strong> If <code>GET</code> is used it will also
1504     restrict <code>HEAD</code> requests. The <code>TRACE</code> method
1505     cannot be limited.</p>
1506
1507 </div>
1508 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1509 <div class="directive-section"><h2><a name="LimitExcept" id="LimitExcept">&lt;LimitExcept&gt;</a> <a name="limitexcept" id="limitexcept">Directive</a></h2>
1510 <table class="directive">
1511 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict access controls to all HTTP methods
1512 except the named ones</td></tr>
1513 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;LimitExcept <var>method</var> [<var>method</var>] ... &gt; ...
1514     &lt;/LimitExcept&gt;</code></td></tr>
1515 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1516 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1517 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1518 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1519 </table>
1520     <p><code class="directive">&lt;LimitExcept&gt;</code> and
1521     <code>&lt;/LimitExcept&gt;</code> are used to enclose
1522     a group of access control directives which will then apply to any
1523     HTTP access method <strong>not</strong> listed in the arguments;
1524     i.e., it is the opposite of a <code class="directive"><a href="#limit">&lt;Limit&gt;</a></code> section and can be used to control
1525     both standard and nonstandard/unrecognized methods. See the
1526     documentation for <code class="directive"><a href="#limit">&lt;Limit&gt;</a></code> for more details.</p>
1527
1528     <p>For example:</p>
1529
1530     <div class="example"><p><code>
1531       &lt;LimitExcept POST GET&gt;<br />
1532       <span class="indent">
1533         Require valid-user<br />
1534       </span>
1535       &lt;LimitExcept&gt;
1536     </code></p></div>
1537
1538
1539 </div>
1540 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1541 <div class="directive-section"><h2><a name="LimitInternalRecursion" id="LimitInternalRecursion">LimitInternalRecursion</a> <a name="limitinternalrecursion" id="limitinternalrecursion">Directive</a></h2>
1542 <table class="directive">
1543 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine maximum number of internal redirects and nested
1544 subrequests</td></tr>
1545 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitInternalRecursion <var>number</var> [<var>number</var>]</code></td></tr>
1546 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitInternalRecursion 10</code></td></tr>
1547 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1548 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1549 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1550 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later</td></tr>
1551 </table>
1552     <p>An internal redirect happens, for example, when using the <code class="directive"><a href="../mod/mod_actions.html#action">Action</a></code> directive, which internally
1553     redirects the original request to a CGI script. A subrequest is Apache's
1554     mechanism to find out what would happen for some URI if it were requested.
1555     For example, <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> uses subrequests to look for the
1556     files listed in the <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
1557     directive.</p>
1558
1559     <p><code class="directive">LimitInternalRecursion</code> prevents the server
1560     from crashing when entering an infinite loop of internal redirects or
1561     subrequests. Such loops are usually caused by misconfigurations.</p>
1562
1563     <p>The directive stores two different limits, which are evaluated on
1564     per-request basis. The first <var>number</var> is the maximum number of
1565     internal redirects, that may follow each other. The second <var>number</var>
1566     determines, how deep subrequests may be nested. If you specify only one
1567     <var>number</var>, it will be assigned to both limits.</p>
1568
1569     <div class="example"><h3>Example</h3><p><code>
1570       LimitInternalRecursion 5
1571     </code></p></div>
1572
1573 </div>
1574 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1575 <div class="directive-section"><h2><a name="LimitRequestBody" id="LimitRequestBody">LimitRequestBody</a> <a name="limitrequestbody" id="limitrequestbody">Directive</a></h2>
1576 <table class="directive">
1577 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restricts the total size of the HTTP request body sent
1578 from the client</td></tr>
1579 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestBody <var>bytes</var></code></td></tr>
1580 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestBody 0</code></td></tr>
1581 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1582 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1583 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1584 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1585 </table>
1586     <p>This directive specifies the number of <var>bytes</var> from 0
1587     (meaning unlimited) to 2147483647 (2GB) that are allowed in a
1588     request body. The default value is defined by the compile-time
1589     constant <code>DEFAULT_LIMIT_REQUEST_BODY</code> (0 as
1590     distributed).</p>
1591
1592     <p>The <code class="directive">LimitRequestBody</code> directive allows
1593     the user to set a limit on the allowed size of an HTTP request
1594     message body within the context in which the directive is given
1595     (server, per-directory, per-file or per-location). If the client
1596     request exceeds that limit, the server will return an error
1597     response instead of servicing the request. The size of a normal
1598     request message body will vary greatly depending on the nature of
1599     the resource and the methods allowed on that resource. CGI scripts
1600     typically use the message body for retrieving form information.
1601     Implementations of the <code>PUT</code> method will require
1602     a value at least as large as any representation that the server
1603     wishes to accept for that resource.</p>
1604
1605     <p>This directive gives the server administrator greater
1606     control over abnormal client request behavior, which may be
1607     useful for avoiding some forms of denial-of-service
1608     attacks.</p>
1609
1610     <p>If, for example, you are permitting file upload to a particular
1611     location, and wish to limit the size of the uploaded file to 100K,
1612     you might use the following directive:</p>
1613
1614     <div class="example"><p><code>
1615       LimitRequestBody 102400
1616     </code></p></div>
1617
1618
1619 </div>
1620 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1621 <div class="directive-section"><h2><a name="LimitRequestFields" id="LimitRequestFields">LimitRequestFields</a> <a name="limitrequestfields" id="limitrequestfields">Directive</a></h2>
1622 <table class="directive">
1623 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of HTTP request header fields that
1624 will be accepted from the client</td></tr>
1625 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFields <var>number</var></code></td></tr>
1626 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFields 100</code></td></tr>
1627 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1628 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1629 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1630 </table>
1631     <p><var>Number</var> is an integer from 0 (meaning unlimited) to
1632     32767. The default value is defined by the compile-time
1633     constant <code>DEFAULT_LIMIT_REQUEST_FIELDS</code> (100 as
1634     distributed).</p>
1635
1636     <p>The <code class="directive">LimitRequestFields</code> directive allows
1637     the server administrator to modify the limit on the number of
1638     request header fields allowed in an HTTP request. A server needs
1639     this value to be larger than the number of fields that a normal
1640     client request might include. The number of request header fields
1641     used by a client rarely exceeds 20, but this may vary among
1642     different client implementations, often depending upon the extent
1643     to which a user has configured their browser to support detailed
1644     content negotiation. Optional HTTP extensions are often expressed
1645     using request header fields.</p>
1646
1647     <p>This directive gives the server administrator greater
1648     control over abnormal client request behavior, which may be
1649     useful for avoiding some forms of denial-of-service attacks.
1650     The value should be increased if normal clients see an error
1651     response from the server that indicates too many fields were
1652     sent in the request.</p>
1653
1654     <p>For example:</p>
1655
1656     <div class="example"><p><code>
1657       LimitRequestFields 50
1658     </code></p></div>
1659
1660
1661 </div>
1662 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1663 <div class="directive-section"><h2><a name="LimitRequestFieldSize" id="LimitRequestFieldSize">LimitRequestFieldSize</a> <a name="limitrequestfieldsize" id="limitrequestfieldsize">Directive</a></h2>
1664 <table class="directive">
1665 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of the HTTP request header allowed from the
1666 client</td></tr>
1667 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFieldsize <var>bytes</var></code></td></tr>
1668 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFieldsize 8190</code></td></tr>
1669 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1670 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1671 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1672 </table>
1673     <p>This directive specifies the number of <var>bytes</var> from 0
1674     to the value of the compile-time constant
1675     <code>DEFAULT_LIMIT_REQUEST_FIELDSIZE</code> (8190 as
1676     distributed) that will be allowed in an HTTP request
1677     header.</p>
1678
1679     <p>The <code class="directive">LimitRequestFieldSize</code> directive
1680     allows the server administrator to reduce the limit on the allowed
1681     size of an HTTP request header field below the normal input buffer
1682     size compiled with the server. A server needs this value to be
1683     large enough to hold any one header field from a normal client
1684     request. The size of a normal request header field will vary
1685     greatly among different client implementations, often depending
1686     upon the extent to which a user has configured their browser to
1687     support detailed content negotiation.</p>
1688
1689     <p>This directive gives the server administrator greater
1690     control over abnormal client request behavior, which may be
1691     useful for avoiding some forms of denial-of-service attacks.</p>
1692
1693     <p>For example:</p>
1694
1695     <div class="example"><p><code>
1696       LimitRequestFieldSize 4094
1697     </code></p></div>
1698
1699     <div class="note">Under normal conditions, the value should not be changed from
1700     the default.</div>
1701
1702
1703 </div>
1704 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1705 <div class="directive-section"><h2><a name="LimitRequestLine" id="LimitRequestLine">LimitRequestLine</a> <a name="limitrequestline" id="limitrequestline">Directive</a></h2>
1706 <table class="directive">
1707 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit the size of the HTTP request line that will be accepted
1708 from the client</td></tr>
1709 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestLine <var>bytes</var></code></td></tr>
1710 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestLine 8190</code></td></tr>
1711 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1712 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1713 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1714 </table>
1715     <p>This directive sets the number of <var>bytes</var> from 0 to
1716     the value of the compile-time constant
1717     <code>DEFAULT_LIMIT_REQUEST_LINE</code> (8190 as distributed)
1718     that will be allowed on the HTTP request-line.</p>
1719
1720     <p>The <code class="directive">LimitRequestLine</code> directive allows
1721     the server administrator to reduce the limit on the allowed size
1722     of a client's HTTP request-line below the normal input buffer size
1723     compiled with the server. Since the request-line consists of the
1724     HTTP method, URI, and protocol version, the
1725     <code class="directive">LimitRequestLine</code> directive places a
1726     restriction on the length of a request-URI allowed for a request
1727     on the server. A server needs this value to be large enough to
1728     hold any of its resource names, including any information that
1729     might be passed in the query part of a <code>GET</code> request.</p>
1730
1731     <p>This directive gives the server administrator greater
1732     control over abnormal client request behavior, which may be
1733     useful for avoiding some forms of denial-of-service attacks.</p>
1734
1735     <p>For example:</p>
1736
1737     <div class="example"><p><code>
1738       LimitRequestLine 4094
1739     </code></p></div>
1740
1741     <div class="note">Under normal conditions, the value should not be changed from
1742     the default.</div>
1743
1744 </div>
1745 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1746 <div class="directive-section"><h2><a name="LimitXMLRequestBody" id="LimitXMLRequestBody">LimitXMLRequestBody</a> <a name="limitxmlrequestbody" id="limitxmlrequestbody">Directive</a></h2>
1747 <table class="directive">
1748 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of an XML-based request body</td></tr>
1749 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitXMLRequestBody <var>bytes</var></code></td></tr>
1750 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitXMLRequestBody 1000000</code></td></tr>
1751 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1752 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1753 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1754 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1755 </table>
1756     <p>Limit (in bytes) on maximum size of an XML-based request
1757     body. A value of <code>0</code> will disable any checking.</p>
1758
1759     <p>Example:</p>
1760
1761     <div class="example"><p><code>
1762       LimitXMLRequestBody 0
1763     </code></p></div>
1764
1765
1766 </div>
1767 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1768 <div class="directive-section"><h2><a name="Location" id="Location">&lt;Location&gt;</a> <a name="location" id="location">Directive</a></h2>
1769 <table class="directive">
1770 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to matching
1771 URLs</td></tr>
1772 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Location
1773     <var>URL-path</var>|<var>URL</var>&gt; ... &lt;/Location&gt;</code></td></tr>
1774 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1775 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1776 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1777 </table>
1778     <p>The <code class="directive">&lt;Location&gt;</code> directive
1779     limits the scope of the enclosed directives by URL. It is similar to the
1780     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
1781     directive, and starts a subsection which is terminated with a
1782     <code>&lt;/Location&gt;</code> directive.  <code class="directive">&lt;Location&gt;</code> sections are processed in the
1783     order they appear in the configuration file, after the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections and
1784     <code>.htaccess</code> files are read, and after the <code class="directive"><a href="#files">&lt;Files&gt;</a></code> sections.</p>
1785
1786     <p><code class="directive">&lt;Location&gt;</code> sections operate
1787     completely outside the filesystem.  This has several consequences.
1788     Most importantly, <code class="directive">&lt;Location&gt;</code>
1789     directives should not be used to control access to filesystem
1790     locations.  Since several different URLs may map to the same
1791     filesystem location, such access controls may by circumvented.</p>
1792
1793     <div class="note"><h3>When to use <code class="directive">&lt;Location&gt;</code></h3>
1794
1795     <p>Use <code class="directive">&lt;Location&gt;</code> to apply
1796     directives to content that lives outside the filesystem.  For
1797     content that lives in the filesystem, use <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> and <code class="directive"><a href="#files">&lt;Files&gt;</a></code>.  An exception is
1798     <code>&lt;Location /&gt;</code>, which is an easy way to
1799     apply a configuration to the entire server.</p>
1800     </div>
1801
1802     <p>For all origin (non-proxy) requests, the URL to be matched is a
1803     URL-path of the form <code>/path/</code>.  No scheme, hostname,
1804     port, or query string may be included.  For proxy requests, the
1805     URL to be matched is of the form
1806     <code>scheme://servername/path</code>, and you must include the
1807     prefix.</p>
1808
1809     <p>The URL may use wildcards. In a wild-card string, <code>?</code> matches
1810     any single character, and <code>*</code> matches any sequences of
1811     characters.</p>
1812
1813     <p>Extended regular
1814     expressions can also be used, with the addition of the
1815     <code>~</code> character. For example:</p>
1816
1817     <div class="example"><p><code>
1818       &lt;Location ~ "/(extra|special)/data"&gt;
1819     </code></p></div>
1820
1821     <p>would match URLs that contained the substring <code>/extra/data</code>
1822     or <code>/special/data</code>. The directive <code class="directive"><a href="#locationmatch">&lt;LocationMatch&gt;</a></code> behaves
1823     identical to the regex version of <code class="directive">&lt;Location&gt;</code>.</p>
1824
1825     <p>The <code class="directive">&lt;Location&gt;</code>
1826     functionality is especially useful when combined with the
1827     <code class="directive"><a href="#sethandler">SetHandler</a></code>
1828     directive. For example, to enable status requests, but allow them
1829     only from browsers at <code>foo.com</code>, you might use:</p>
1830
1831     <div class="example"><p><code>
1832       &lt;Location /status&gt;<br />
1833       <span class="indent">
1834         SetHandler server-status<br />
1835         Order Deny,Allow<br />
1836         Deny from all<br />
1837         Allow from .foo.com<br />
1838       </span>
1839       &lt;/Location&gt;
1840     </code></p></div>
1841
1842     <div class="note"><h3>Note about / (slash)</h3>
1843       <p>The slash character has special meaning depending on where in a
1844       URL it appears. People may be used to its behavior in the filesystem
1845       where multiple adjacent slashes are frequently collapsed to a single
1846       slash (<em>i.e.</em>, <code>/home///foo</code> is the same as
1847       <code>/home/foo</code>). In URL-space this is not necessarily true.
1848       The <code class="directive"><a href="#locationmatch">&lt;LocationMatch&gt;</a></code>
1849       directive and the regex version of <code class="directive">&lt;Location&gt;</code> require you to explicitly specify multiple
1850       slashes if that is your intention.</p>
1851
1852       <p>For example, <code>&lt;LocationMatch ^/abc&gt;</code> would match
1853       the request URL <code>/abc</code> but not the request URL <code>
1854       //abc</code>. The (non-regex) <code class="directive">&lt;Location&gt;</code> directive behaves similarly when used for
1855       proxy requests. But when (non-regex) <code class="directive">&lt;Location&gt;</code> is used for non-proxy requests it will
1856       implicitly match multiple slashes with a single slash. For example,
1857       if you specify <code>&lt;Location /abc/def&gt;</code> and the
1858       request is to <code>/abc//def</code> then it will match.</p>
1859     </div>
1860
1861 <h3>See also</h3>
1862 <ul>
1863 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1864     and &lt;Files&gt; sections work</a> for an explanation of how these
1865     different sections are combined when a request is received</li>
1866 </ul>
1867 </div>
1868 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1869 <div class="directive-section"><h2><a name="LocationMatch" id="LocationMatch">&lt;LocationMatch&gt;</a> <a name="locationmatch" id="locationmatch">Directive</a></h2>
1870 <table class="directive">
1871 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to regular-expression
1872 matching URLs</td></tr>
1873 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;LocationMatch
1874     <var>regex</var>&gt; ... &lt;/LocationMatch&gt;</code></td></tr>
1875 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1876 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1877 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1878 </table>
1879     <p>The <code class="directive">&lt;LocationMatch&gt;</code> directive
1880     limits the scope of the enclosed directives by URL, in an identical manner
1881     to <code class="directive"><a href="#location">&lt;Location&gt;</a></code>. However,
1882     it takes a regular expression as an argument instead of a simple
1883     string. For example:</p>
1884
1885     <div class="example"><p><code>
1886       &lt;LocationMatch "/(extra|special)/data"&gt;
1887     </code></p></div>
1888
1889     <p>would match URLs that contained the substring <code>/extra/data</code>
1890     or <code>/special/data</code>.</p>
1891
1892 <h3>See also</h3>
1893 <ul>
1894 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1895     and &lt;Files&gt; sections work</a> for an explanation of how these
1896     different sections are combined when a request is received</li>
1897 </ul>
1898 </div>
1899 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1900 <div class="directive-section"><h2><a name="LogLevel" id="LogLevel">LogLevel</a> <a name="loglevel" id="loglevel">Directive</a></h2>
1901 <table class="directive">
1902 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls the verbosity of the ErrorLog</td></tr>
1903 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogLevel <var>level</var></code></td></tr>
1904 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LogLevel warn</code></td></tr>
1905 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1906 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1907 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1908 </table>
1909     <p><code class="directive">LogLevel</code> adjusts the verbosity of the
1910     messages recorded in the error logs (see <code class="directive"><a href="#errorlog">ErrorLog</a></code> directive). The following
1911     <var>level</var>s are available, in order of decreasing
1912     significance:</p>
1913
1914     <table class="bordered">
1915       <tr>
1916         <th><strong>Level</strong> </th>
1917
1918         <th><strong>Description</strong> </th>
1919
1920         <th><strong>Example</strong> </th>
1921       </tr>
1922
1923       <tr>
1924         <td><code>emerg</code> </td>
1925
1926         <td>Emergencies - system is unusable.</td>
1927
1928         <td>"Child cannot open lock file. Exiting"</td>
1929       </tr>
1930
1931       <tr>
1932         <td><code>alert</code> </td>
1933
1934         <td>Action must be taken immediately.</td>
1935
1936         <td>"getpwuid: couldn't determine user name from uid"</td>
1937       </tr>
1938
1939       <tr>
1940         <td><code>crit</code> </td>
1941
1942         <td>Critical Conditions.</td>
1943
1944         <td>"socket: Failed to get a socket, exiting child"</td>
1945       </tr>
1946
1947       <tr>
1948         <td><code>error</code> </td>
1949
1950         <td>Error conditions.</td>
1951
1952         <td>"Premature end of script headers"</td>
1953       </tr>
1954
1955       <tr>
1956         <td><code>warn</code> </td>
1957
1958         <td>Warning conditions.</td>
1959
1960         <td>"child process 1234 did not exit, sending another
1961         SIGHUP"</td>
1962       </tr>
1963
1964       <tr>
1965         <td><code>notice</code> </td>
1966
1967         <td>Normal but significant condition.</td>
1968
1969         <td>"httpd: caught SIGBUS, attempting to dump core in
1970         ..."</td>
1971       </tr>
1972
1973       <tr>
1974         <td><code>info</code> </td>
1975
1976         <td>Informational.</td>
1977
1978         <td>"Server seems busy, (you may need to increase
1979         StartServers, or Min/MaxSpareServers)..."</td>
1980       </tr>
1981
1982       <tr>
1983         <td><code>debug</code> </td>
1984
1985         <td>Debug-level messages</td>
1986
1987         <td>"Opening config file ..."</td>
1988       </tr>
1989     </table>
1990
1991     <p>When a particular level is specified, messages from all
1992     other levels of higher significance will be reported as well.
1993     <em>E.g.</em>, when <code>LogLevel info</code> is specified,
1994     then messages with log levels of <code>notice</code> and
1995     <code>warn</code> will also be posted.</p>
1996
1997     <p>Using a level of at least <code>crit</code> is
1998     recommended.</p>
1999
2000     <p>For example:</p>
2001
2002     <div class="example"><p><code>
2003       LogLevel notice
2004     </code></p></div>
2005
2006 </div>
2007 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2008 <div class="directive-section"><h2><a name="MaxKeepAliveRequests" id="MaxKeepAliveRequests">MaxKeepAliveRequests</a> <a name="maxkeepaliverequests" id="maxkeepaliverequests">Directive</a></h2>
2009 <table class="directive">
2010 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of requests allowed on a persistent
2011 connection</td></tr>
2012 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxKeepAliveRequests <var>number</var></code></td></tr>
2013 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxKeepAliveRequests 100</code></td></tr>
2014 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2015 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2016 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2017 </table>
2018     <p>The <code class="directive">MaxKeepAliveRequests</code> directive
2019     limits the number of requests allowed per connection when
2020     <code class="directive"><a href="#keepalive">KeepAlive</a></code> is on. If it is
2021     set to <code>0</code>, unlimited requests will be allowed. We
2022     recommend that this setting be kept to a high value for maximum
2023     server performance.</p>
2024
2025     <p>For example:</p>
2026
2027     <div class="example"><p><code>
2028       MaxKeepAliveRequests 500
2029     </code></p></div>
2030
2031 </div>
2032 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2033 <div class="directive-section"><h2><a name="NameVirtualHost" id="NameVirtualHost">NameVirtualHost</a> <a name="namevirtualhost" id="namevirtualhost">Directive</a></h2>
2034 <table class="directive">
2035 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Designates an IP address for name-virtual
2036 hosting</td></tr>
2037 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NameVirtualHost <var>addr</var>[:<var>port</var>]</code></td></tr>
2038 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2039 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2040 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2041 </table>
2042     <p>The <code class="directive">NameVirtualHost</code> directive is a
2043     required directive if you want to configure <a href="../vhosts/">name-based virtual hosts</a>.</p>
2044
2045     <p>Although <var>addr</var> can be hostname it is recommended
2046     that you always use an IP address, e.g.</p>
2047
2048     <div class="example"><p><code>
2049       NameVirtualHost 111.22.33.44
2050     </code></p></div>
2051
2052     <p>With the <code class="directive">NameVirtualHost</code> directive you
2053     specify the IP address on which the server will receive requests
2054     for the name-based virtual hosts. This will usually be the address
2055     to which your name-based virtual host names resolve. In cases
2056     where a firewall or other proxy receives the requests and forwards
2057     them on a different IP address to the server, you must specify the
2058     IP address of the physical interface on the machine which will be
2059     servicing the requests. If you have multiple name-based hosts on
2060     multiple addresses, repeat the directive for each address.</p>
2061
2062     <div class="note"><h3>Note</h3>
2063       <p>Note, that the "main server" and any <code>_default_</code> servers
2064       will <strong>never</strong> be served for a request to a
2065       <code class="directive">NameVirtualHost</code> IP Address (unless for some
2066       reason you specify <code class="directive">NameVirtualHost</code> but then
2067       don't define any <code class="directive">VirtualHost</code>s for that
2068       address).</p>
2069     </div>
2070
2071     <p>Optionally you can specify a port number on which the
2072     name-based virtual hosts should be used, e.g.</p>
2073
2074     <div class="example"><p><code>
2075       NameVirtualHost 111.22.33.44:8080
2076     </code></p></div>
2077
2078     <p>IPv6 addresses must be enclosed in square brackets, as shown
2079     in the following example:</p>
2080
2081     <div class="example"><p><code>
2082       NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080
2083     </code></p></div>
2084
2085     <p>To receive requests on all interfaces, you can use an argument of
2086     <code>*</code></p>
2087
2088     <div class="example"><p><code>
2089       NameVirtualHost *
2090     </code></p></div>
2091
2092     <div class="note"><h3>Argument to <code class="directive">&lt;VirtualHost&gt;</code>
2093       directive</h3>
2094       <p>Note that the argument to the <code class="directive">&lt;VirtualHost&gt;</code> directive must
2095       exactly match the argument to the <code class="directive">NameVirtualHost</code> directive.</p>
2096
2097       <div class="example"><p><code>
2098         NameVirtualHost 1.2.3.4<br />
2099         &lt;VirtualHost 1.2.3.4&gt;<br />
2100         # ...<br />
2101         &lt;/VirtualHost&gt;<br />
2102       </code></p></div>
2103     </div>
2104
2105 <h3>See also</h3>
2106 <ul>
2107 <li><a href="../vhosts/">Virtual Hosts
2108 documentation</a></li>
2109 </ul>
2110 </div>
2111 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2112 <div class="directive-section"><h2><a name="Options" id="Options">Options</a> <a name="options" id="options">Directive</a></h2>
2113 <table class="directive">
2114 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures what features are available in a particular
2115 directory</td></tr>
2116 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Options
2117     [+|-]<var>option</var> [[+|-]<var>option</var>] ...</code></td></tr>
2118 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Options All</code></td></tr>
2119 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2120 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
2121 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2122 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2123 </table>
2124     <p>The <code class="directive">Options</code> directive controls which
2125     server features are available in a particular directory.</p>
2126
2127     <p><var>option</var> can be set to <code>None</code>, in which
2128     case none of the extra features are enabled, or one or more of
2129     the following:</p>
2130
2131     <dl>
2132       <dt><code>All</code></dt>
2133
2134       <dd>All options except for <code>MultiViews</code>. This is the default
2135       setting.</dd>
2136
2137       <dt><code>ExecCGI</code></dt>
2138
2139       <dd>
2140       Execution of CGI scripts using <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>
2141       is permitted.</dd>
2142
2143       <dt><code>FollowSymLinks</code></dt>
2144
2145       <dd>
2146
2147       The server will follow symbolic links in this directory.
2148       <div class="note">
2149       <p>Even though the server follows the symlink it does <em>not</em>
2150       change the pathname used to match against <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections.</p>
2151       <p>Note also, that this option <strong>gets ignored</strong> if set
2152       inside a <code class="directive"><a href="#location">&lt;Location&gt;</a></code>
2153       section.</p>
2154       </div></dd>
2155
2156       <dt><code>Includes</code></dt>
2157
2158       <dd>
2159       Server-side includes provided by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
2160       are permitted.</dd>
2161
2162       <dt><code>IncludesNOEXEC</code></dt>
2163
2164       <dd>
2165
2166       Server-side includes are permitted, but the <code>#exec
2167       cmd</code> and <code>#exec cgi</code> are disabled. It is still
2168       possible to <code>#include virtual</code> CGI scripts from
2169       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed
2170       directories.</dd>
2171
2172       <dt><code>Indexes</code></dt>
2173
2174       <dd>
2175       If a URL which maps to a directory is requested, and there
2176       is no <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
2177       (<em>e.g.</em>, <code>index.html</code>) in that directory, then
2178       <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code> will return a formatted listing
2179       of the directory.</dd>
2180
2181       <dt><code>MultiViews</code></dt>
2182
2183       <dd>
2184       <a href="../content-negotiation.html">Content negotiated</a>
2185       "MultiViews" are allowed using
2186       <code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code>.</dd>
2187
2188       <dt><code>SymLinksIfOwnerMatch</code></dt>
2189
2190       <dd>The server will only follow symbolic links for which the
2191       target file or directory is owned by the same user id as the
2192       link.
2193
2194       <div class="note"><h3>Note</h3> This option gets ignored if
2195       set inside a <code class="directive"><a href="#location">&lt;Location&gt;</a></code> section.</div>
2196       </dd>
2197     </dl>
2198
2199     <p>Normally, if multiple <code class="directive">Options</code> could
2200     apply to a directory, then the most specific one is used and
2201     others are ignored; the options are not merged. (See <a href="../sections.html#mergin">how sections are merged</a>.)
2202     However if <em>all</em> the options on the
2203     <code class="directive">Options</code> directive are preceded by a
2204     <code>+</code> or <code>-</code> symbol, the options are
2205     merged. Any options preceded by a <code>+</code> are added to the
2206     options currently in force, and any options preceded by a
2207     <code>-</code> are removed from the options currently in
2208     force. </p>
2209
2210     <p>For example, without any <code>+</code> and <code>-</code> symbols:</p>
2211
2212     <div class="example"><p><code>
2213       &lt;Directory /web/docs&gt;<br />
2214       <span class="indent">
2215         Options Indexes FollowSymLinks<br />
2216       </span>
2217       &lt;/Directory&gt;<br />
2218       <br />
2219       &lt;Directory /web/docs/spec&gt;<br />
2220       <span class="indent">
2221         Options Includes<br />
2222       </span>
2223       &lt;/Directory&gt;
2224     </code></p></div>
2225
2226     <p>then only <code>Includes</code> will be set for the
2227     <code>/web/docs/spec</code> directory. However if the second
2228     <code class="directive">Options</code> directive uses the <code>+</code> and
2229     <code>-</code> symbols:</p>
2230
2231     <div class="example"><p><code>
2232       &lt;Directory /web/docs&gt;<br />
2233       <span class="indent">
2234         Options Indexes FollowSymLinks<br />
2235       </span>
2236       &lt;/Directory&gt;<br />
2237       <br />
2238       &lt;Directory /web/docs/spec&gt;<br />
2239       <span class="indent">
2240         Options +Includes -Indexes<br />
2241       </span>
2242       &lt;/Directory&gt;
2243     </code></p></div>
2244
2245     <p>then the options <code>FollowSymLinks</code> and
2246     <code>Includes</code> are set for the <code>/web/docs/spec</code>
2247     directory.</p>
2248
2249     <div class="note"><h3>Note</h3>
2250       <p>Using <code>-IncludesNOEXEC</code> or
2251       <code>-Includes</code> disables server-side includes completely
2252       regardless of the previous setting.</p>
2253     </div>
2254
2255     <p>The default in the absence of any other settings is
2256     <code>All</code>.</p>
2257
2258 </div>
2259 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2260 <div class="directive-section"><h2><a name="Require" id="Require">Require</a> <a name="require" id="require">Directive</a></h2>
2261 <table class="directive">
2262 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Selects which authenticated users can access
2263 a resource</td></tr>
2264 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Require <var>entity-name</var> [<var>entity-name</var>] ...</code></td></tr>
2265 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
2266 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
2267 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2268 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2269 </table>
2270     <p>This directive selects which authenticated users can access
2271     a directory. The allowed syntaxes are:</p>
2272
2273     <dl>
2274       <dt><code>Require user <var>userid</var> [<var>userid</var>]
2275       ...</code></dt>
2276       <dd>Only the named users can access the resource.</dd>
2277
2278       <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
2279       ...</code></dt>
2280       <dd>Only users in the named groups can access the resource.</dd>
2281
2282       <dt><code>Require valid-user</code></dt>
2283       <dd>All valid users can access the resource.</dd>
2284     </dl>
2285
2286     <p><code class="directive">Require</code> must be accompanied by
2287     <code class="directive"><a href="#authname">AuthName</a></code> and <code class="directive"><a href="#authtype">AuthType</a></code> directives, and directives such
2288     as <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code>
2289     and <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code> (to
2290     define users and groups) in order to work correctly. Example:</p>
2291
2292     <div class="example"><p><code>
2293        AuthType Basic<br />
2294        AuthName "Restricted Directory"<br />
2295        AuthUserFile /web/users<br />
2296        AuthGroupFile /web/groups<br />
2297        Require group admin
2298     </code></p></div>
2299
2300     <p>Access controls which are applied in this way are effective for
2301     <strong>all</strong> methods. <strong>This is what is normally
2302     desired.</strong> If you wish to apply access controls only to
2303     specific methods, while leaving other methods unprotected, then
2304     place the <code class="directive">Require</code> statement into a
2305     <code class="directive"><a href="#limit">&lt;Limit&gt;</a></code>
2306     section.</p>
2307
2308 <h3>See also</h3>
2309 <ul>
2310 <li><code class="directive"><a href="#satisfy">Satisfy</a></code></li>
2311 <li><code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></li>
2312 </ul>
2313 </div>
2314 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2315 <div class="directive-section"><h2><a name="RLimitCPU" id="RLimitCPU">RLimitCPU</a> <a name="rlimitcpu" id="rlimitcpu">Directive</a></h2>
2316 <table class="directive">
2317 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the CPU consumption of processes launched
2318 by Apache children</td></tr>
2319 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RLimitCPU <var>seconds</var>|max [<var>seconds</var>|max]</code></td></tr>
2320 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
2321 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2322 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2323 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2324 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2325 </table>
2326     <p>Takes 1 or 2 parameters. The first parameter sets the soft
2327     resource limit for all processes and the second parameter sets
2328     the maximum resource limit. Either parameter can be a number,
2329     or <code>max</code> to indicate to the server that the limit should
2330     be set to the maximum allowed by the operating system
2331     configuration. Raising the maximum resource limit requires that
2332     the server is running as <code>root</code>, or in the initial startup
2333     phase.</p>
2334
2335     <p>This applies to processes forked off from Apache children
2336     servicing requests, not the Apache children themselves. This
2337     includes CGI scripts and SSI exec commands, but not any
2338     processes forked off from the Apache parent such as piped
2339     logs.</p>
2340
2341     <p>CPU resource limits are expressed in seconds per
2342     process.</p>
2343
2344 <h3>See also</h3>
2345 <ul>
2346 <li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li>
2347 <li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li>
2348 </ul>
2349 </div>
2350 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2351 <div class="directive-section"><h2><a name="RLimitMEM" id="RLimitMEM">RLimitMEM</a> <a name="rlimitmem" id="rlimitmem">Directive</a></h2>
2352 <table class="directive">
2353 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the memory consumption of processes launched
2354 by Apache children</td></tr>
2355 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RLimitMEM <var>bytes</var>|max [<var>bytes</var>|max]</code></td></tr>
2356 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
2357 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2358 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2359 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2360 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2361 </table>
2362     <p>Takes 1 or 2 parameters. The first parameter sets the soft
2363     resource limit for all processes and the second parameter sets
2364     the maximum resource limit. Either parameter can be a number,
2365     or <code>max</code> to indicate to the server that the limit should
2366     be set to the maximum allowed by the operating system
2367     configuration. Raising the maximum resource limit requires that
2368     the server is running as <code>root</code>, or in the initial startup
2369     phase.</p>
2370
2371     <p>This applies to processes forked off from Apache children
2372     servicing requests, not the Apache children themselves. This
2373     includes CGI scripts and SSI exec commands, but not any
2374     processes forked off from the Apache parent such as piped
2375     logs.</p>
2376
2377     <p>Memory resource limits are expressed in bytes per
2378     process.</p>
2379
2380 <h3>See also</h3>
2381 <ul>
2382 <li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li>
2383 <li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li>
2384 </ul>
2385 </div>
2386 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2387 <div class="directive-section"><h2><a name="RLimitNPROC" id="RLimitNPROC">RLimitNPROC</a> <a name="rlimitnproc" id="rlimitnproc">Directive</a></h2>
2388 <table class="directive">
2389 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of processes that can be launched by
2390 processes launched by Apache children</td></tr>
2391 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RLimitNPROC <var>number</var>|max [<var>number</var>|max]</code></td></tr>
2392 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
2393 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2394 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2395 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2396 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2397 </table>
2398     <p>Takes 1 or 2 parameters. The first parameter sets the soft
2399     resource limit for all processes and the second parameter sets
2400     the maximum resource limit. Either parameter can be a number,
2401     or <code>max</code> to indicate to the server that the limit
2402     should be set to the maximum allowed by the operating system
2403     configuration. Raising the maximum resource limit requires that
2404     the server is running as <code>root</code>, or in the initial startup
2405     phase.</p>
2406
2407     <p>This applies to processes forked off from Apache children
2408     servicing requests, not the Apache children themselves. This
2409     includes CGI scripts and SSI exec commands, but not any
2410     processes forked off from the Apache parent such as piped
2411     logs.</p>
2412
2413     <p>Process limits control the number of processes per user.</p>
2414
2415     <div class="note"><h3>Note</h3>
2416       <p>If CGI processes are <strong>not</strong> running
2417       under userids other than the web server userid, this directive
2418       will limit the number of processes that the server itself can
2419       create. Evidence of this situation will be indicated by
2420       <strong><code>cannot fork</code></strong> messages in the
2421       <code>error_log</code>.</p>
2422     </div>
2423
2424 <h3>See also</h3>
2425 <ul>
2426 <li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li>
2427 <li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li>
2428 </ul>
2429 </div>
2430 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2431 <div class="directive-section"><h2><a name="Satisfy" id="Satisfy">Satisfy</a> <a name="satisfy" id="satisfy">Directive</a></h2>
2432 <table class="directive">
2433 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Interaction between host-level access control and
2434 user authentication</td></tr>
2435 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Satisfy Any|All</code></td></tr>
2436 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Satisfy All</code></td></tr>
2437 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
2438 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
2439 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2440 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2441 </table>
2442     <p>Access policy if both <code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code> and <code class="directive"><a href="#require">Require</a></code> used. The parameter can be
2443     either <code>All</code> or <code>Any</code>. This directive is only
2444     useful if access to a particular area is being restricted by both
2445     username/password <em>and</em> client host address. In this case
2446     the default behavior (<code>All</code>) is to require that the client
2447     passes the address access restriction <em>and</em> enters a valid
2448     username and password. With the <code>Any</code> option the client will be
2449     granted access if they either pass the host restriction or enter a
2450     valid username and password. This can be used to password restrict
2451     an area, but to let clients from particular addresses in without
2452     prompting for a password.</p>
2453
2454     <p>For example, if you wanted to let people on your network have
2455     unrestricted access to a portion of your website, but require that
2456     people outside of your network provide a password, you could use a
2457     configuration similar to the following:</p>
2458
2459     <div class="example"><p><code>
2460       Require valid-user<br />
2461       Allow from 192.168.1<br />
2462       Satisfy Any
2463     </code></p></div>
2464
2465
2466 <h3>See also</h3>
2467 <ul>
2468 <li><code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code></li>
2469 <li><code class="directive"><a href="#require">Require</a></code></li>
2470 </ul>
2471 </div>
2472 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2473 <div class="directive-section"><h2><a name="ScriptInterpreterSource" id="ScriptInterpreterSource">ScriptInterpreterSource</a> <a name="scriptinterpretersource" id="scriptinterpretersource">Directive</a></h2>
2474 <table class="directive">
2475 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI
2476 scripts</td></tr>
2477 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptInterpreterSource Registry|Registry-Strict|Script</code></td></tr>
2478 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptInterpreterSource Script</code></td></tr>
2479 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2480 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
2481 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2482 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2483 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Win32 only;
2484 option <code>Registry-Strict</code> is available in Apache 2.0 and
2485 later</td></tr>
2486 </table>
2487     <p>This directive is used to control how Apache finds the
2488     interpreter used to run CGI scripts. The default setting is
2489     <code>Script</code>. This causes Apache to use the interpreter pointed to
2490     by the shebang line (first line, starting with <code>#!</code>) in the
2491     script. On Win32 systems this line usually looks like:</p>
2492
2493     <div class="example"><p><code>
2494       #!C:/Perl/bin/perl.exe
2495     </code></p></div>
2496
2497     <p>or, if perl is in <code>PATH</code>, simply:</p>
2498
2499     <div class="example"><p><code>
2500       #!perl
2501     </code></p></div>
2502
2503     <p>Setting <code>ScriptInterpreterSource Registry</code> will
2504     cause the Windows Registry tree <code>HKEY_CLASSES_ROOT</code> to be
2505     searched using the script file extension (e.g., <code>.pl</code>) as a
2506     search key. The command defined by the registry subkey
2507     <code>Shell\ExecCGI\Command</code> or if not exists by the subkey
2508     <code>Shell\Open\Command</code> is used to open the script file. In absence
2509     of the file extension key or both subkeys Apache uses the
2510     <code>Script</code> option.</p>
2511
2512     <div class="warning"><h3>Security</h3>
2513       <p>Be careful to use <code>ScriptInterpreterSource Registry</code> with
2514       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>'ed directories,
2515       because Apache is trying to execute <strong>every</strong> file within
2516       this directory. The <code>Registry</code> setting may cause undesired
2517       program calls on files, which are usually not executed. For example, the
2518       default open command on <code>.htm</code> files on most Windows systems is
2519       executing the Microsoft Internet Explorer, so any HTTP request for an
2520       <code>.htm</code> file existing within the script directory would start
2521       the browser in background. This is an effective method to crash your
2522       system within a minute or so.</p>
2523     </div>
2524
2525     <p>The option <code>Registry-Strict</code> which is new in Apache 2.0
2526       does the same as <code>Registry</code> but uses only the subkey
2527       <code>Shell\ExecCGI\Command</code>. The <code>ExecCGI</code> key
2528       is not a common one. It has to be configured manually and prevents your
2529       system from accidental program calls.</p>
2530
2531 </div>
2532 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2533 <div class="directive-section"><h2><a name="ServerAdmin" id="ServerAdmin">ServerAdmin</a> <a name="serveradmin" id="serveradmin">Directive</a></h2>
2534 <table class="directive">
2535 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Email address that the server includes in error
2536 messages sent to the client</td></tr>
2537 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAdmin <var>email-address</var></code></td></tr>
2538 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2539 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2540 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2541 </table>
2542     <p>The <code class="directive">ServerAdmin</code> sets the e-mail address
2543     that the server includes in any error messages it returns to the
2544     client.</p>
2545
2546     <p>It may be worth setting up a dedicated address for this, e.g.</p>
2547
2548     <div class="example"><p><code>
2549       ServerAdmin www-admin@foo.example.com
2550     </code></p></div>
2551     <p>as users do not always mention that they are talking about the
2552     server!</p>
2553
2554 </div>
2555 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2556 <div class="directive-section"><h2><a name="ServerAlias" id="ServerAlias">ServerAlias</a> <a name="serveralias" id="serveralias">Directive</a></h2>
2557 <table class="directive">
2558 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Alternate names for a host used when matching requests
2559 to name-virtual hosts</td></tr>
2560 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAlias <var>hostname</var> [<var>hostname</var>] ...</code></td></tr>
2561 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr>
2562 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2563 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2564 </table>
2565     <p>The <code class="directive">ServerAlias</code> directive sets the
2566     alternate names for a host, for use with <a href="../vhosts/name-based.html">name-based virtual hosts</a>.</p>
2567
2568     <div class="example"><p><code>
2569       &lt;VirtualHost *&gt;<br />
2570       ServerName server.domain.com<br />
2571       ServerAlias server server2.domain.com server2<br />
2572       # ...<br />
2573       &lt;/VirtualHost&gt;
2574     </code></p></div>
2575
2576 <h3>See also</h3>
2577 <ul>
2578 <li><a href="../vhosts/">Apache Virtual Host documentation</a></li>
2579 </ul>
2580 </div>
2581 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2582 <div class="directive-section"><h2><a name="ServerName" id="ServerName">ServerName</a> <a name="servername" id="servername">Directive</a></h2>
2583 <table class="directive">
2584 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hostname and port that the server uses to identify
2585 itself</td></tr>
2586 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerName <var>fully-qualified-domain-name</var>[:<var>port</var>]</code></td></tr>
2587 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2588 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2589 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2590 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>In version 2.0, this
2591      directive supersedes the functionality of the <code class="directive">Port</code>
2592      directive from version 1.3.</td></tr>
2593 </table>
2594     <p>The <code class="directive">ServerName</code> directive sets the hostname and
2595     port that the server uses to identify itself.  This is used when
2596     creating redirection URLs. For example, if the name of the
2597     machine hosting the webserver is <code>simple.example.com</code>,
2598     but the machine also has the DNS alias <code>www.example.com</code>
2599     and you wish the webserver to be so identified, the following
2600     directive should be used:</p>
2601
2602     <div class="example"><p><code>
2603       ServerName www.example.com:80
2604     </code></p></div>
2605
2606     <p>If no <code class="directive">ServerName</code> is specified, then the
2607     server attempts to deduce the hostname by performing a reverse
2608     lookup on the IP address. If no port is specified in the
2609     servername, then the server will use the port from the incoming
2610     request. For optimal reliability and predictability, you should
2611     specify an explicit hostname and port using the
2612     <code class="directive">ServerName</code> directive.</p>
2613
2614     <p>If you are using <a href="../vhosts/name-based.html">name-based virtual hosts</a>,
2615     the <code class="directive">ServerName</code> inside a
2616     <code class="directive"><a href="#virtualhost">&lt;VirtualHost&gt;</a></code>
2617     section specifies what hostname must appear in the request's
2618     <code>Host:</code> header to match this virtual host.</p>
2619
2620     <p>See the description of the
2621     <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> directive for
2622     settings which determine whether self-referential URL's (e.g., by the
2623     <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> module) will refer to the
2624     specified port, or to the port number given in the client's request.
2625     </p>
2626
2627 <h3>See also</h3>
2628 <ul>
2629 <li><a href="../dns-caveats.html">Issues Regarding DNS and
2630     Apache</a></li>
2631 <li><a href="../vhosts/">Apache virtual host
2632     documentation</a></li>
2633 <li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li>
2634 <li><code class="directive"><a href="#namevirtualhost">NameVirtualHost</a></code></li>
2635 <li><code class="directive"><a href="#serveralias">ServerAlias</a></code></li>
2636 </ul>
2637 </div>
2638 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2639 <div class="directive-section"><h2><a name="ServerPath" id="ServerPath">ServerPath</a> <a name="serverpath" id="serverpath">Directive</a></h2>
2640 <table class="directive">
2641 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Legacy URL pathname for a name-based virtual host that
2642 is accessed by an incompatible browser</td></tr>
2643 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerPath <var>URL-path</var></code></td></tr>
2644 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr>
2645 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2646 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2647 </table>
2648     <p>The <code class="directive">ServerPath</code> directive sets the legacy
2649     URL pathname for a host, for use with <a href="../vhosts/">name-based virtual hosts</a>.</p>
2650
2651 <h3>See also</h3>
2652 <ul>
2653 <li><a href="../vhosts/">Apache Virtual Host documentation</a></li>
2654 </ul>
2655 </div>
2656 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2657 <div class="directive-section"><h2><a name="ServerRoot" id="ServerRoot">ServerRoot</a> <a name="serverroot" id="serverroot">Directive</a></h2>
2658 <table class="directive">
2659 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the server installation</td></tr>
2660 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerRoot <var>directory-path</var></code></td></tr>
2661 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerRoot /usr/local/apache</code></td></tr>
2662 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2663 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2664 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2665 </table>
2666     <p>The <code class="directive">ServerRoot</code> directive sets the
2667     directory in which the server lives. Typically it will contain the
2668     subdirectories <code>conf/</code> and <code>logs/</code>. Relative
2669     paths for other configuration files are taken as relative to this
2670     directory.</p>
2671
2672     <div class="example"><h3>Example</h3><p><code>
2673       ServerRoot /home/httpd
2674     </code></p></div>
2675
2676
2677 <h3>See also</h3>
2678 <ul>
2679 <li><a href="../invoking.html">the <code>-d</code>
2680     option to <code>httpd</code></a></li>
2681 <li><a href="../misc/security_tips.html#serverroot">the
2682     security tips</a> for information on how to properly set
2683     permissions on the <code class="directive">ServerRoot</code></li>
2684 </ul>
2685 </div>
2686 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2687 <div class="directive-section"><h2><a name="ServerSignature" id="ServerSignature">ServerSignature</a> <a name="serversignature" id="serversignature">Directive</a></h2>
2688 <table class="directive">
2689 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the footer on server-generated documents</td></tr>
2690 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerSignature On|Off|EMail</code></td></tr>
2691 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerSignature Off</code></td></tr>
2692 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2693 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2694 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2695 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2696 </table>
2697     <p>The <code class="directive">ServerSignature</code> directive allows the
2698     configuration of a trailing footer line under server-generated
2699     documents (error messages, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> ftp directory
2700     listings, <code class="module"><a href="../mod/mod_info.html">mod_info</a></code> output, ...). The reason why you
2701     would want to enable such a footer line is that in a chain of proxies,
2702     the user often has no possibility to tell which of the chained servers
2703     actually produced a returned error message.</p>
2704
2705     <p>The <code>Off</code>
2706     setting, which is the default, suppresses the footer line (and is
2707     therefore compatible with the behavior of Apache-1.2 and
2708     below). The <code>On</code> setting simply adds a line with the
2709     server version number and <code class="directive"><a href="#servername">ServerName</a></code> of the serving virtual host,
2710     and the <code>EMail</code> setting additionally creates a
2711     "mailto:" reference to the <code class="directive"><a href="#serveradmin">ServerAdmin</a></code> of the referenced
2712     document.</p>
2713
2714     <p>After version 2.0.44, the details of the server version number
2715     presented are controlled by the <code class="directive"><a href="#servertokens">ServerTokens</a></code> directive.</p>
2716
2717 <h3>See also</h3>
2718 <ul>
2719 <li><code class="directive"><a href="#servertokens">ServerTokens</a></code></li>
2720 </ul>
2721 </div>
2722 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2723 <div class="directive-section"><h2><a name="ServerTokens" id="ServerTokens">ServerTokens</a> <a name="servertokens" id="servertokens">Directive</a></h2>
2724 <table class="directive">
2725 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the Server HTTP response
2726 header</td></tr>
2727 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full</code></td></tr>
2728 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerTokens Full</code></td></tr>
2729 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2730 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2731 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2732 </table>
2733     <p>This directive controls whether <code>Server</code> response
2734     header field which is sent back to clients includes a
2735     description of the generic OS-type of the server as well as
2736     information about compiled-in modules.</p>
2737
2738     <dl>
2739       <dt><code>ServerTokens Prod[uctOnly]</code></dt>
2740
2741       <dd>Server sends (<em>e.g.</em>): <code>Server:
2742       Apache</code></dd>
2743
2744       <dt><code>ServerTokens Major</code></dt>
2745
2746       <dd>Server sends (<em>e.g.</em>): <code>Server:
2747       Apache/2</code></dd>
2748
2749       <dt><code>ServerTokens Minor</code></dt>
2750
2751       <dd>Server sends (<em>e.g.</em>): <code>Server:
2752       Apache/2.0</code></dd>
2753
2754       <dt><code>ServerTokens Min[imal]</code></dt>
2755
2756       <dd>Server sends (<em>e.g.</em>): <code>Server:
2757       Apache/2.0.41</code></dd>
2758
2759       <dt><code>ServerTokens OS</code></dt>
2760
2761       <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.0.41
2762       (Unix)</code></dd>
2763
2764       <dt><code>ServerTokens Full</code> (or not specified)</dt>
2765
2766       <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.0.41
2767       (Unix) PHP/4.2.2 MyMod/1.2</code></dd>
2768     </dl>
2769
2770     <p>This setting applies to the entire server, and cannot be
2771     enabled or disabled on a virtualhost-by-virtualhost basis.</p>
2772
2773     <p>After version 2.0.44, this directive also controls the
2774     information presented by the <code class="directive"><a href="#serversignature">ServerSignature</a></code> directive.</p>
2775
2776 <h3>See also</h3>
2777 <ul>
2778 <li><code class="directive"><a href="#serversignature">ServerSignature</a></code></li>
2779 </ul>
2780 </div>
2781 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2782 <div class="directive-section"><h2><a name="SetHandler" id="SetHandler">SetHandler</a> <a name="sethandler" id="sethandler">Directive</a></h2>
2783 <table class="directive">
2784 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be processed by a
2785 handler</td></tr>
2786 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetHandler <var>handler-name</var>|None</code></td></tr>
2787 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2788 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
2789 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2790 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2791 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Moved into the core in Apache 2.0</td></tr>
2792 </table>
2793     <p>When placed into an <code>.htaccess</code> file or a
2794     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> or
2795     <code class="directive"><a href="#location">&lt;Location&gt;</a></code>
2796     section, this directive forces all matching files to be parsed
2797     through the <a href="../handler.html">handler</a> given by
2798     <var>handler-name</var>. For example, if you had a directory you
2799     wanted to be parsed entirely as imagemap rule files, regardless
2800     of extension, you might put the following into an
2801     <code>.htaccess</code> file in that directory:</p>
2802
2803     <div class="example"><p><code>
2804       SetHandler imap-file
2805     </code></p></div>
2806
2807     <p>Another example: if you wanted to have the server display a
2808     status report whenever a URL of
2809     <code>http://servername/status</code> was called, you might put
2810     the following into <code>httpd.conf</code>:</p>
2811
2812     <div class="example"><p><code>
2813       &lt;Location /status&gt;<br />
2814       <span class="indent">
2815         SetHandler server-status<br />
2816       </span>
2817       &lt;/Location&gt;
2818     </code></p></div>
2819
2820     <p>You can override an earlier defined <code class="directive">SetHandler</code>
2821     directive by using the value <code>None</code>.</p>
2822
2823 <h3>See also</h3>
2824 <ul>
2825 <li><code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code></li>
2826 </ul>
2827 </div>
2828 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2829 <div class="directive-section"><h2><a name="SetInputFilter" id="SetInputFilter">SetInputFilter</a> <a name="setinputfilter" id="setinputfilter">Directive</a></h2>
2830 <table class="directive">
2831 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process client requests and POST
2832 input</td></tr>
2833 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetInputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr>
2834 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2835 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
2836 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2837 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2838 </table>
2839     <p>The <code class="directive">SetInputFilter</code> directive sets the
2840     filter or filters which will process client requests and POST
2841     input when they are received by the server. This is in addition to
2842     any filters defined elsewhere, including the
2843     <code class="directive"><a href="../mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>
2844     directive.</p>
2845
2846     <p>If more than one filter is specified, they must be separated
2847     by semicolons in the order in which they should process the
2848     content.</p>
2849
2850 <h3>See also</h3>
2851 <ul>
2852 <li><a href="../filter.html">Filters</a> documentation</li>
2853 </ul>
2854 </div>
2855 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2856 <div class="directive-section"><h2><a name="SetOutputFilter" id="SetOutputFilter">SetOutputFilter</a> <a name="setoutputfilter" id="setoutputfilter">Directive</a></h2>
2857 <table class="directive">
2858 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process responses from the
2859 server</td></tr>
2860 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetOutputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr>
2861 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2862 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
2863 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2864 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2865 </table>
2866     <p>The <code class="directive">SetOutputFilter</code> directive sets the filters
2867     which will process responses from the server before they are
2868     sent to the client. This is in addition to any filters defined
2869     elsewhere, including the
2870     <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code>
2871     directive.</p>
2872
2873     <p>For example, the following configuration will process all files
2874     in the <code>/www/data/</code> directory for server-side
2875     includes.</p>
2876
2877     <div class="example"><p><code>
2878       &lt;Directory /www/data/&gt;<br />
2879       <span class="indent">
2880         SetOutputFilter INCLUDES<br />
2881       </span>
2882       &lt;/Directory&gt;
2883     </code></p></div>
2884
2885     <p>If more than one filter is specified, they must be separated
2886     by semicolons in the order in which they should process the
2887     content.</p>
2888
2889 <h3>See also</h3>
2890 <ul>
2891 <li><a href="../filter.html">Filters</a> documentation</li>
2892 </ul>
2893 </div>
2894 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2895 <div class="directive-section"><h2><a name="TimeOut" id="TimeOut">TimeOut</a> <a name="timeout" id="timeout">Directive</a></h2>
2896 <table class="directive">
2897 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for
2898 certain events before failing a request</td></tr>
2899 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TimeOut <var>seconds</var></code></td></tr>
2900 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>TimeOut 300</code></td></tr>
2901 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2902 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2903 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2904 </table>
2905     <p>The <code class="directive">TimeOut</code> directive currently defines
2906     the amount of time Apache will wait for three things:</p>
2907
2908     <ol>
2909       <li>The total amount of time it takes to receive a GET
2910       request.</li>
2911
2912       <li>The amount of time between receipt of TCP packets on a
2913       POST or PUT request.</li>
2914
2915       <li>The amount of time between ACKs on transmissions of TCP
2916       packets in responses.</li>
2917     </ol>
2918
2919     <p>We plan on making these separately configurable at some point
2920     down the road. The timer used to default to 1200 before 1.2,
2921     but has been lowered to 300 which is still far more than
2922     necessary in most situations. It is not set any lower by
2923     default because there may still be odd places in the code where
2924     the timer is not reset when a packet is sent. </p>
2925
2926 </div>
2927 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2928 <div class="directive-section"><h2><a name="UseCanonicalName" id="UseCanonicalName">UseCanonicalName</a> <a name="usecanonicalname" id="usecanonicalname">Directive</a></h2>
2929 <table class="directive">
2930 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures how the server determines its own name and
2931 port</td></tr>
2932 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UseCanonicalName On|Off|DNS</code></td></tr>
2933 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>UseCanonicalName On</code></td></tr>
2934 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
2935 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2936 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2937 </table>
2938     <p>In many situations Apache must construct a <em>self-referential</em>
2939     URL -- that is, a URL that refers back to the same server. With
2940     <code>UseCanonicalName On</code> Apache will use the hostname and port
2941     specified in the <code class="directive"><a href="#servername">ServerName</a></code>
2942     directive to construct the canonical name for the server. This name
2943     is used in all self-referential URLs, and for the values of
2944     <code>SERVER_NAME</code> and <code>SERVER_PORT</code> in CGIs.</p>
2945
2946     <p>With <code>UseCanonicalName Off</code> Apache will form
2947     self-referential URLs using the hostname and port supplied by
2948     the client if any are supplied (otherwise it will use the
2949     canonical name, as defined above). These values are the same
2950     that are used to implement <a href="../vhosts/name-based.html">name based virtual hosts</a>,
2951     and are available with the same clients. The CGI variables
2952     <code>SERVER_NAME</code> and <code>SERVER_PORT</code> will be
2953     constructed from the client supplied values as well.</p>
2954
2955     <p>An example where this may be useful is on an intranet server
2956     where you have users connecting to the machine using short
2957     names such as <code>www</code>. You'll notice that if the users
2958     type a shortname, and a URL which is a directory, such as
2959     <code>http://www/splat</code>, <em>without the trailing
2960     slash</em> then Apache will redirect them to
2961     <code>http://www.domain.com/splat/</code>. If you have
2962     authentication enabled, this will cause the user to have to
2963     authenticate twice (once for <code>www</code> and once again
2964     for <code>www.domain.com</code> -- see <a href="http://httpd.apache.org/docs/misc/FAQ.html#prompted-twice">the
2965     FAQ on this subject for more information</a>). But if
2966     <code class="directive">UseCanonicalName</code> is set <code>Off</code>, then
2967     Apache will redirect to <code>http://www/splat/</code>.</p>
2968
2969     <p>There is a third option, <code>UseCanonicalName DNS</code>,
2970     which is intended for use with mass IP-based virtual hosting to
2971     support ancient clients that do not provide a
2972     <code>Host:</code> header. With this option Apache does a
2973     reverse DNS lookup on the server IP address that the client
2974     connected to in order to work out self-referential URLs.</p>
2975
2976     <div class="warning"><h3>Warning</h3>
2977     <p>If CGIs make assumptions about the values of <code>SERVER_NAME</code>
2978     they may be broken by this option. The client is essentially free
2979     to give whatever value they want as a hostname. But if the CGI is
2980     only using <code>SERVER_NAME</code> to construct self-referential URLs
2981     then it should be just fine.</p>
2982     </div>
2983
2984 <h3>See also</h3>
2985 <ul>
2986 <li><code class="directive"><a href="#servername">ServerName</a></code></li>
2987 <li><code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code></li>
2988 </ul>
2989 </div>
2990 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2991 <div class="directive-section"><h2><a name="VirtualHost" id="VirtualHost">&lt;VirtualHost&gt;</a> <a name="virtualhost" id="virtualhost">Directive</a></h2>
2992 <table class="directive">
2993 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only to a specific
2994 hostname or IP address</td></tr>
2995 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;VirtualHost
2996     <var>addr</var>[:<var>port</var>] [<var>addr</var>[:<var>port</var>]]
2997     ...&gt; ... &lt;/VirtualHost&gt;</code></td></tr>
2998 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2999 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3000 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3001 </table>
3002     <p><code class="directive">&lt;VirtualHost&gt;</code> and
3003     <code>&lt;/VirtualHost&gt;</code> are used to enclose a group of
3004     directives that will apply only to a particular virtual host. Any
3005     directive that is allowed in a virtual host context may be
3006     used. When the server receives a request for a document on a
3007     particular virtual host, it uses the configuration directives
3008     enclosed in the <code class="directive">&lt;VirtualHost&gt;</code>
3009     section. <var>Addr</var> can be:</p>
3010
3011     <ul>
3012       <li>The IP address of the virtual host;</li>
3013
3014       <li>A fully qualified domain name for the IP address of the
3015       virtual host;</li>
3016
3017       <li>The character <code>*</code>, which is used only in combination with
3018       <code>NameVirtualHost *</code> to match all IP addresses; or</li>
3019
3020       <li>The string <code>_default_</code>, which is used only
3021       with IP virtual hosting to catch unmatched IP addresses.</li>
3022     </ul>
3023
3024     <div class="example"><h3>Example</h3><p><code>
3025       &lt;VirtualHost 10.1.2.3&gt;<br />
3026       <span class="indent">
3027         ServerAdmin webmaster@host.foo.com<br />
3028         DocumentRoot /www/docs/host.foo.com<br />
3029         ServerName host.foo.com<br />
3030         ErrorLog logs/host.foo.com-error_log<br />
3031         TransferLog logs/host.foo.com-access_log<br />
3032       </span>
3033       &lt;/VirtualHost&gt;
3034     </code></p></div>
3035
3036
3037     <p>IPv6 addresses must be specified in square brackets because
3038     the optional port number could not be determined otherwise.  An
3039     IPv6 example is shown below:</p>
3040
3041     <div class="example"><p><code>
3042       &lt;VirtualHost [fe80::a00:20ff:fea7:ccea]&gt;<br />
3043       <span class="indent">
3044         ServerAdmin webmaster@host.example.com<br />
3045         DocumentRoot /www/docs/host.example.com<br />
3046         ServerName host.example.com<br />
3047         ErrorLog logs/host.example.com-error_log<br />
3048         TransferLog logs/host.example.com-access_log<br />
3049       </span>
3050       &lt;/VirtualHost&gt;
3051     </code></p></div>
3052
3053     <p>Each Virtual Host must correspond to a different IP address,
3054     different port number or a different host name for the server,
3055     in the former case the server machine must be configured to
3056     accept IP packets for multiple addresses. (If the machine does
3057     not have multiple network interfaces, then this can be
3058     accomplished with the <code>ifconfig alias</code> command -- if
3059     your OS supports it).</p>
3060
3061     <div class="note"><h3>Note</h3>
3062     <p>The use of <code class="directive">&lt;VirtualHost&gt;</code> does
3063     <strong>not</strong> affect what addresses Apache listens on. You
3064     may need to ensure that Apache is listening on the correct addresses
3065     using <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>.</p>
3066     </div>
3067
3068     <p>When using IP-based virtual hosting, the special name
3069     <code>_default_</code> can be specified in
3070     which case this virtual host will match any IP address that is
3071     not explicitly listed in another virtual host. In the absence
3072     of any <code>_default_</code> virtual host the "main" server config,
3073     consisting of all those definitions outside any VirtualHost
3074     section, is used when no IP-match occurs.  (But note that any IP
3075     address that matches a <code class="directive"><a href="#namevirtualhost">NameVirtualHost</a></code> directive will use neither
3076     the "main" server config nor the <code>_default_</code> virtual host.
3077     See the <a href="../vhosts/name-based.html">name-based virtual hosting</a>
3078     documentation for further details.)</p>
3079
3080     <p>You can specify a <code>:port</code> to change the port that is
3081     matched. If unspecified then it defaults to the same port as the
3082     most recent <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>
3083     statement of the main server. You may also specify <code>:*</code>
3084     to match all ports on that address. (This is recommended when used
3085     with <code>_default_</code>.)</p>
3086
3087     <div class="warning"><h3>Security</h3>
3088     <p>See the <a href="../misc/security_tips.html">security tips</a>
3089     document for details on why your security could be compromised if the
3090     directory where logfiles are stored is writable by anyone other
3091     than the user that starts the server.</p>
3092     </div>
3093
3094 <h3>See also</h3>
3095 <ul>
3096 <li><a href="../vhosts/">Apache Virtual Host documentation</a></li>
3097 <li><a href="../dns-caveats.html">Issues Regarding DNS and
3098      Apache</a></li>
3099 <li><a href="../bind.html">Setting
3100     which addresses and ports Apache uses</a></li>
3101 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
3102     and &lt;Files&gt; sections work</a> for an explanation of how these
3103     different sections are combined when a request is received</li>
3104 </ul>
3105 </div>
3106 </div>
3107 <div class="bottomlang">
3108 <p><span>Available Languages: </span><a href="../de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
3109 <a href="../en/mod/core.html" title="English">&nbsp;en&nbsp;</a></p>
3110 </div><div id="footer">
3111 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
3112 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
3113 </body></html>