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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>core - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <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/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Core Features</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
  30 <a href="../en/mod/core.html" title="English">&nbsp;en&nbsp;</a> |
  31 <a href="../es/mod/core.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  32 <a href="../fr/mod/core.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  33 <a href="../ja/mod/core.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  34 <a href="../tr/mod/core.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  35 </div>
  36 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Core Apache HTTP Server features that are always
  37 available</td></tr>
  38 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Core</td></tr></table>
  39 </div>
  40 <div id="quickview"><h3 class="directives">Directives</h3>
  41 <ul id="toc">
  42 <li><img alt="" src="../images/down.gif" /> <a href="#acceptfilter">AcceptFilter</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#acceptpathinfo">AcceptPathInfo</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#accessfilename">AccessFileName</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#adddefaultcharset">AddDefaultCharset</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#allowencodedslashes">AllowEncodedSlashes</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#allowoverride">AllowOverride</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#allowoverridelist">AllowOverrideList</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#asyncfilter">AsyncFilter</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#cgimapextension">CGIMapExtension</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#cgipassauth">CGIPassAuth</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#cgivar">CGIVar</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#contentdigest">ContentDigest</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#defaultruntimedir">DefaultRuntimeDir</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#defaultstatedir">DefaultStateDir</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#defaulttype">DefaultType</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#define">Define</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#directory">&lt;Directory&gt;</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#directorymatch">&lt;DirectoryMatch&gt;</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#documentroot">DocumentRoot</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#else">&lt;Else&gt;</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#elseif">&lt;ElseIf&gt;</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#enablemmap">EnableMMAP</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#enablesendfile">EnableSendfile</a></li>
  65 <li><img alt="" src="../images/down.gif" /> <a href="#error">Error</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#errordocument">ErrorDocument</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#errorlog">ErrorLog</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#errorlogformat">ErrorLogFormat</a></li>
  69 <li><img alt="" src="../images/down.gif" /> <a href="#extendedstatus">ExtendedStatus</a></li>
  70 <li><img alt="" src="../images/down.gif" /> <a href="#fileetag">FileETag</a></li>
  71 <li><img alt="" src="../images/down.gif" /> <a href="#files">&lt;Files&gt;</a></li>
  72 <li><img alt="" src="../images/down.gif" /> <a href="#filesmatch">&lt;FilesMatch&gt;</a></li>
  73 <li><img alt="" src="../images/down.gif" /> <a href="#forcetype">ForceType</a></li>
  74 <li><img alt="" src="../images/down.gif" /> <a href="#gprofdir">GprofDir</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#hostnamelookups">HostnameLookups</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#httpprotocoloptions">HttpProtocolOptions</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#if">&lt;If&gt;</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#ifdefine">&lt;IfDefine&gt;</a></li>
  79 <li><img alt="" src="../images/down.gif" /> <a href="#ifdirective">&lt;IfDirective&gt;</a></li>
  80 <li><img alt="" src="../images/down.gif" /> <a href="#iffile">&lt;IfFile&gt;</a></li>
  81 <li><img alt="" src="../images/down.gif" /> <a href="#ifmodule">&lt;IfModule&gt;</a></li>
  82 <li><img alt="" src="../images/down.gif" /> <a href="#ifsection">&lt;IfSection&gt;</a></li>
  83 <li><img alt="" src="../images/down.gif" /> <a href="#include">Include</a></li>
  84 <li><img alt="" src="../images/down.gif" /> <a href="#includeoptional">IncludeOptional</a></li>
  85 <li><img alt="" src="../images/down.gif" /> <a href="#keepalive">KeepAlive</a></li>
  86 <li><img alt="" src="../images/down.gif" /> <a href="#keepalivetimeout">KeepAliveTimeout</a></li>
  87 <li><img alt="" src="../images/down.gif" /> <a href="#limit">&lt;Limit&gt;</a></li>
  88 <li><img alt="" src="../images/down.gif" /> <a href="#limitexcept">&lt;LimitExcept&gt;</a></li>
  89 <li><img alt="" src="../images/down.gif" /> <a href="#limitinternalrecursion">LimitInternalRecursion</a></li>
  90 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestbody">LimitRequestBody</a></li>
  91 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestfields">LimitRequestFields</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestfieldsize">LimitRequestFieldSize</a></li>
  93 <li><img alt="" src="../images/down.gif" /> <a href="#limitrequestline">LimitRequestLine</a></li>
  94 <li><img alt="" src="../images/down.gif" /> <a href="#limitxmlrequestbody">LimitXMLRequestBody</a></li>
  95 <li><img alt="" src="../images/down.gif" /> <a href="#location">&lt;Location&gt;</a></li>
  96 <li><img alt="" src="../images/down.gif" /> <a href="#locationmatch">&lt;LocationMatch&gt;</a></li>
  97 <li><img alt="" src="../images/down.gif" /> <a href="#loglevel">LogLevel</a></li>
  98 <li><img alt="" src="../images/down.gif" /> <a href="#logleveloverride">LogLevelOverride</a></li>
  99 <li><img alt="" src="../images/down.gif" /> <a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></li>
 100 <li><img alt="" src="../images/down.gif" /> <a href="#maxrangeoverlaps">MaxRangeOverlaps</a></li>
 101 <li><img alt="" src="../images/down.gif" /> <a href="#maxrangereversals">MaxRangeReversals</a></li>
 102 <li><img alt="" src="../images/down.gif" /> <a href="#maxranges">MaxRanges</a></li>
 103 <li><img alt="" src="../images/down.gif" /> <a href="#mergetrailers">MergeTrailers</a></li>
 104 <li><img alt="" src="../images/down.gif" /> <a href="#mutex">Mutex</a></li>
 105 <li><img alt="" src="../images/down.gif" /> <a href="#namevirtualhost">NameVirtualHost</a></li>
 106 <li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
 107 <li><img alt="" src="../images/down.gif" /> <a href="#protocol">Protocol</a></li>
 108 <li><img alt="" src="../images/down.gif" /> <a href="#protocols">Protocols</a></li>
 109 <li><img alt="" src="../images/down.gif" /> <a href="#protocolshonororder">ProtocolsHonorOrder</a></li>
 110 <li><img alt="" src="../images/down.gif" /> <a href="#qualifyredirecturl">QualifyRedirectURL</a></li>
 111 <li><img alt="" src="../images/down.gif" /> <a href="#regexdefaultoptions">RegexDefaultOptions</a></li>
 112 <li><img alt="" src="../images/down.gif" /> <a href="#registerhttpmethod">RegisterHttpMethod</a></li>
 113 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitcpu">RLimitCPU</a></li>
 114 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitmem">RLimitMEM</a></li>
 115 <li><img alt="" src="../images/down.gif" /> <a href="#rlimitnproc">RLimitNPROC</a></li>
 116 <li><img alt="" src="../images/down.gif" /> <a href="#scriptinterpretersource">ScriptInterpreterSource</a></li>
 117 <li><img alt="" src="../images/down.gif" /> <a href="#seerequesttail">SeeRequestTail</a></li>
 118 <li><img alt="" src="../images/down.gif" /> <a href="#serveradmin">ServerAdmin</a></li>
 119 <li><img alt="" src="../images/down.gif" /> <a href="#serveralias">ServerAlias</a></li>
 120 <li><img alt="" src="../images/down.gif" /> <a href="#servername">ServerName</a></li>
 121 <li><img alt="" src="../images/down.gif" /> <a href="#serverpath">ServerPath</a></li>
 122 <li><img alt="" src="../images/down.gif" /> <a href="#serverroot">ServerRoot</a></li>
 123 <li><img alt="" src="../images/down.gif" /> <a href="#serversignature">ServerSignature</a></li>
 124 <li><img alt="" src="../images/down.gif" /> <a href="#servertokens">ServerTokens</a></li>
 125 <li><img alt="" src="../images/down.gif" /> <a href="#sethandler">SetHandler</a></li>
 126 <li><img alt="" src="../images/down.gif" /> <a href="#setinputfilter">SetInputFilter</a></li>
 127 <li><img alt="" src="../images/down.gif" /> <a href="#setoutputfilter">SetOutputFilter</a></li>
 128 <li><img alt="" src="../images/down.gif" /> <a href="#stricthostcheck">StrictHostCheck</a></li>
 129 <li><img alt="" src="../images/down.gif" /> <a href="#timeout">TimeOut</a></li>
 130 <li><img alt="" src="../images/down.gif" /> <a href="#traceenable">TraceEnable</a></li>
 131 <li><img alt="" src="../images/down.gif" /> <a href="#undefine">UnDefine</a></li>
 132 <li><img alt="" src="../images/down.gif" /> <a href="#usecanonicalname">UseCanonicalName</a></li>
 133 <li><img alt="" src="../images/down.gif" /> <a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></li>
 134 <li><img alt="" src="../images/down.gif" /> <a href="#virtualhost">&lt;VirtualHost&gt;</a></li>
 135 <li><img alt="" src="../images/down.gif" /> <a href="#warning">Warning</a></li>
 136 </ul>
 137 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=core">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=core">Report a bug</a></li></ul><h3>See also</h3>
 138 <ul class="seealso">
 139 <li><a href="#comments_section">Comments</a></li></ul></div>
 140
 141 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 142 <div class="directive-section"><h2><a name="AcceptFilter" id="AcceptFilter">AcceptFilter</a> <a name="acceptfilter" id="acceptfilter">Directive</a><a title="Permanent link" href="#acceptfilter" class="permalink">&para;</a></h2>
 143 <table class="directive">
 144 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures optimizations for a Protocol's Listener Sockets</td></tr>
 145 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AcceptFilter <var>protocol</var> <var>accept_filter</var></code></td></tr>
 146 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 147 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 148 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 149 </table>
 150     <p>This directive enables operating system specific optimizations for a
 151        listening socket by the <code class="directive">Protocol</code> type.
 152        The basic premise is for the kernel to not send a socket to the server
 153        process until either data is received or an entire HTTP Request is buffered.
 154        Only <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&amp;sektion=9">
 155        FreeBSD's Accept Filters</a>, Linux's more primitive
 156        <code>TCP_DEFER_ACCEPT</code>, and Windows' optimized AcceptEx()
 157        are currently supported.</p>
 158
 159     <p>Using <code>none</code> for an argument will disable any accept filters
 160        for that protocol.  This is useful for protocols that require a server
 161        send data first, such as <code>ftp:</code> or <code>nntp</code>:</p>
 162     <pre class="prettyprint lang-config">AcceptFilter nntp none</pre>
 163
 164
 165     <p>The default protocol names are <code>https</code> for port 443
 166        and <code>http</code> for all other ports.  To specify that another
 167        protocol is being used with a listening port, add the <var>protocol</var>
 168        argument to the <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>
 169        directive.</p>
 170
 171     <p>The default values on FreeBSD are:</p>
 172     <pre class="prettyprint lang-config">AcceptFilter http httpready
 173 AcceptFilter https dataready</pre>
 174
 175
 176     <p>The <code>httpready</code> accept filter buffers entire HTTP requests at
 177        the kernel level.  Once an entire request is received, the kernel then
 178        sends it to the server. See the
 179        <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_http&amp;sektion=9">
 180        accf_http(9)</a> man page for more details.  Since HTTPS requests are
 181        encrypted, only the <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_data&amp;sektion=9">
 182        accf_data(9)</a> filter is used.</p>
 183
 184     <p>The default values on Linux are:</p>
 185     <pre class="prettyprint lang-config">AcceptFilter http data
 186 AcceptFilter https data</pre>
 187
 188
 189     <p>Linux's <code>TCP_DEFER_ACCEPT</code> does not support buffering http
 190        requests.  Any value besides <code>none</code> will enable
 191        <code>TCP_DEFER_ACCEPT</code> on that listener. For more details
 192        see the Linux
 193        <a href="http://man7.org/linux/man-pages/man7/tcp.7.html">
 194        tcp(7)</a> man page.</p>
 195
 196     <p>The default values on Windows are:</p>
 197     <pre class="prettyprint lang-config">AcceptFilter http connect
 198 AcceptFilter https connect</pre>
 199
 200
 201     <p>Window's mpm_winnt interprets the AcceptFilter to toggle the AcceptEx()
 202        API, and does not support http protocol buffering. <code>connect</code>
 203        will use the AcceptEx() API, also retrieve the network endpoint
 204        addresses, but like <code>none</code> the <code>connect</code> option
 205        does not wait for the initial data transmission.</p>
 206
 207     <p>On Windows, <code>none</code> uses accept() rather than AcceptEx()
 208        and will not recycle sockets between connections.  This is useful for
 209        network adapters with broken driver support, as well as some virtual
 210        network providers such as vpn drivers, or spam, virus or spyware
 211        filters.</p>
 212
 213     <div class="warning">
 214       <h3>The <code>data</code> AcceptFilter (Windows)</h3>
 215
 216       <p>For versions 2.4.23 and prior, the Windows <code>data</code> accept
 217          filter waited until data had been transmitted and the initial data
 218          buffer and network endpoint addresses had been retrieved from the
 219          single AcceptEx() invocation. This implementation was subject to a
 220          denial of service attack and has been disabled.</p>
 221
 222       <p>Current releases of httpd default to the <code>connect</code> filter
 223          on Windows, and will fall back to <code>connect</code> if
 224          <code>data</code> is specified. Users of prior releases are encouraged
 225          to add an explicit setting of <code>connect</code> for their
 226          AcceptFilter, as shown above.</p>
 227     </div>
 228
 229
 230 <h3>See also</h3>
 231 <ul>
 232 <li><code class="directive"><a href="#protocol">Protocol</a></code></li>
 233 </ul>
 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="AcceptPathInfo" id="AcceptPathInfo">AcceptPathInfo</a> <a name="acceptpathinfo" id="acceptpathinfo">Directive</a><a title="Permanent link" href="#acceptpathinfo" class="permalink">&para;</a></h2>
 237 <table class="directive">
 238 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Resources accept trailing pathname information</td></tr>
 239 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AcceptPathInfo On|Off|Default</code></td></tr>
 240 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AcceptPathInfo Default</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 </table>
 246
 247     <p>This directive controls whether requests that contain trailing
 248     pathname information that follows an actual filename (or
 249     non-existent file in an existing directory) will be accepted or
 250     rejected.  The trailing pathname information can be made
 251     available to scripts in the <code>PATH_INFO</code> environment
 252     variable.</p>
 253
 254     <p>For example, assume the location <code>/test/</code> points to
 255     a directory that contains only the single file
 256     <code>here.html</code>.  Then requests for
 257     <code>/test/here.html/more</code> and
 258     <code>/test/nothere.html/more</code> both collect
 259     <code>/more</code> as <code>PATH_INFO</code>.</p>
 260
 261     <p>The three possible arguments for the
 262     <code class="directive">AcceptPathInfo</code> directive are:</p>
 263     <dl>
 264     <dt><code>Off</code></dt><dd>A request will only be accepted if it
 265     maps to a literal path that exists.  Therefore a request with
 266     trailing pathname information after the true filename such as
 267     <code>/test/here.html/more</code> in the above example will return
 268     a 404 NOT FOUND error.</dd>
 269
 270     <dt><code>On</code></dt><dd>A request will be accepted if a
 271     leading path component maps to a file that exists.  The above
 272     example <code>/test/here.html/more</code> will be accepted if
 273     <code>/test/here.html</code> maps to a valid file.</dd>
 274
 275     <dt><code>Default</code></dt><dd>The treatment of requests with
 276     trailing pathname information is determined by the <a href="../handler.html">handler</a> responsible for the request.
 277     The core handler for normal files defaults to rejecting
 278     <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-handler</a>, generally accept
 279     <code>PATH_INFO</code> by default.</dd>
 280     </dl>
 281
 282     <p>The primary purpose of the <code>AcceptPathInfo</code>
 283     directive is to allow you to override the handler's choice of
 284     accepting or rejecting <code>PATH_INFO</code>. This override is required,
 285     for example, when you use a <a href="../filter.html">filter</a>, such
 286     as <a href="mod_include.html">INCLUDES</a>, to generate content
 287     based on <code>PATH_INFO</code>.  The core handler would usually reject
 288     the request, so you can use the following configuration to enable
 289     such a script:</p>
 290
 291     <pre class="prettyprint lang-config">&lt;Files "mypaths.shtml"&gt;
 292   Options +Includes
 293   SetOutputFilter INCLUDES
 294   AcceptPathInfo On
 295 &lt;/Files&gt;</pre>
 296
 297
 298
 299 </div>
 300 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 301 <div class="directive-section"><h2><a name="AccessFileName" id="AccessFileName">AccessFileName</a> <a name="accessfilename" id="accessfilename">Directive</a><a title="Permanent link" href="#accessfilename" class="permalink">&para;</a></h2>
 302 <table class="directive">
 303 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name of the distributed configuration file</td></tr>
 304 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AccessFileName <var>filename</var> [<var>filename</var>] ...</code></td></tr>
 305 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AccessFileName .htaccess</code></td></tr>
 306 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 307 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 308 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 309 </table>
 310     <p>While processing a request, the server looks for
 311     the first existing configuration file from this list of names in
 312     every directory of the path to the document, if distributed
 313     configuration files are <a href="#allowoverride">enabled for that
 314     directory</a>. For example:</p>
 315
 316     <pre class="prettyprint lang-config">AccessFileName .acl</pre>
 317
 318
 319     <p>Before returning the document
 320     <code>/usr/local/web/index.html</code>, the server will read
 321     <code>/.acl</code>, <code>/usr/.acl</code>,
 322     <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code>
 323     for directives unless they have been disabled with:</p>
 324
 325     <pre class="prettyprint lang-config">&lt;Directory "/"&gt;
 326     AllowOverride None
 327 &lt;/Directory&gt;</pre>
 328
 329
 330 <h3>See also</h3>
 331 <ul>
 332 <li><code class="directive"><a href="#allowoverride">AllowOverride</a></code></li>
 333 <li><a href="../configuring.html">Configuration Files</a></li>
 334 <li><a href="../howto/htaccess.html">.htaccess Files</a></li>
 335 </ul>
 336 </div>
 337 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 338 <div class="directive-section"><h2><a name="AddDefaultCharset" id="AddDefaultCharset">AddDefaultCharset</a> <a name="adddefaultcharset" id="adddefaultcharset">Directive</a><a title="Permanent link" href="#adddefaultcharset" class="permalink">&para;</a></h2>
 339 <table class="directive">
 340 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default charset parameter to be added when a response
 341 content-type is <code>text/plain</code> or <code>text/html</code></td></tr>
 342 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddDefaultCharset On|Off|<var>charset</var></code></td></tr>
 343 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AddDefaultCharset Off</code></td></tr>
 344 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 345 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 346 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 347 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 348 </table>
 349     <p>This directive specifies a default value for the media type
 350     charset parameter (the name of a character encoding) to be added
 351     to a response if and only if the response's content-type is either
 352     <code>text/plain</code> or <code>text/html</code>.  This should override
 353     any charset specified in the body of the response via a <code>META</code>
 354     element, though the exact behavior is often dependent on the user's client
 355     configuration. A setting of <code>AddDefaultCharset Off</code>
 356     disables this functionality. <code>AddDefaultCharset On</code> enables
 357     a default charset of <code>iso-8859-1</code>. Any other value is assumed
 358     to be the <var>charset</var> to be used, which should be one of the
 359     <a href="http://www.iana.org/assignments/character-sets">IANA registered
 360     charset values</a> for use in Internet media types (MIME types).
 361     For example:</p>
 362
 363     <pre class="prettyprint lang-config">AddDefaultCharset utf-8</pre>
 364
 365
 366     <p><code class="directive">AddDefaultCharset</code> should only be used when all
 367     of the text resources to which it applies are known to be in that
 368     character encoding and it is too inconvenient to label their charset
 369     individually. One such example is to add the charset parameter
 370     to resources containing generated content, such as legacy CGI
 371     scripts, that might be vulnerable to cross-site scripting attacks
 372     due to user-provided data being included in the output.  Note, however,
 373     that a better solution is to just fix (or delete) those scripts, since
 374     setting a default charset does not protect users that have enabled
 375     the "auto-detect character encoding" feature on their browser.</p>
 376
 377 <h3>See also</h3>
 378 <ul>
 379 <li><code class="directive"><a href="../mod/mod_mime.html#addcharset">AddCharset</a></code></li>
 380 </ul>
 381 </div>
 382 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 383 <div class="directive-section"><h2><a name="AllowEncodedSlashes" id="AllowEncodedSlashes">AllowEncodedSlashes</a> <a name="allowencodedslashes" id="allowencodedslashes">Directive</a><a title="Permanent link" href="#allowencodedslashes" class="permalink">&para;</a></h2>
 384 <table class="directive">
 385 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether encoded path separators in URLs are allowed to
 386 be passed through</td></tr>
 387 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowEncodedSlashes On|Off|NoDecode</code></td></tr>
 388 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowEncodedSlashes Off</code></td></tr>
 389 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 390 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 391 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 392 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>
 393 NoDecode option available in 2.3.12 and later.</td></tr>
 394 </table>
 395     <p>The <code class="directive">AllowEncodedSlashes</code> directive allows URLs
 396     which contain encoded path separators (<code>%2F</code> for <code>/</code>
 397     and additionally <code>%5C</code> for <code>\</code> on accordant systems)
 398     to be used in the path info.</p>
 399
 400     <p>With the default value, <code>Off</code>, such URLs are refused
 401     with a 404 (Not found) error.</p>
 402
 403     <p>With the value <code>On</code>, such URLs are accepted, and encoded
 404       slashes are decoded like all other encoded characters.</p>
 405
 406     <p>With the value <code>NoDecode</code>, such URLs are accepted, but
 407       encoded slashes are not decoded but left in their encoded state.</p>
 408
 409     <p>Turning <code class="directive">AllowEncodedSlashes</code> <code>On</code> is
 410     mostly useful when used in conjunction with <code>PATH_INFO</code>.</p>
 411
 412     <div class="note"><h3>Note</h3>
 413       <p>If encoded slashes are needed in path info, use of <code>NoDecode</code> is
 414       strongly recommended as a security measure.  Allowing slashes
 415       to be decoded could potentially allow unsafe paths.</p>
 416     </div>
 417
 418 <h3>See also</h3>
 419 <ul>
 420 <li><code class="directive"><a href="#acceptpathinfo">AcceptPathInfo</a></code></li>
 421 </ul>
 422 </div>
 423 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 424 <div class="directive-section"><h2><a name="AllowOverride" id="AllowOverride">AllowOverride</a> <a name="allowoverride" id="allowoverride">Directive</a><a title="Permanent link" href="#allowoverride" class="permalink">&para;</a></h2>
 425 <table class="directive">
 426 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Types of directives that are allowed in
 427 <code>.htaccess</code> files</td></tr>
 428 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowOverride All|None|<var>directive-type</var>
 429 [<var>directive-type</var>] ...</code></td></tr>
 430 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowOverride None (2.3.9 and later), AllowOverride All (2.3.8 and earlier)</code></td></tr>
 431 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 432 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 433 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 434 </table>
 435     <p>When the server finds an <code>.htaccess</code> file (as
 436     specified by <code class="directive"><a href="#accessfilename">AccessFileName</a></code>),
 437     it needs to know which directives declared in that file can override
 438     earlier configuration directives.</p>
 439
 440     <div class="note"><h3>Only available in &lt;Directory&gt; sections</h3>
 441     <code class="directive">AllowOverride</code> is valid only in
 442     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
 443     sections specified without regular expressions, not in <code class="directive"><a href="#location">&lt;Location&gt;</a></code>, <code class="directive"><a href="#directorymatch">&lt;DirectoryMatch&gt;</a></code> or
 444     <code class="directive"><a href="#files">&lt;Files&gt;</a></code> sections.
 445     </div>
 446
 447     <p>When this directive is set to <code>None</code> and <code class="directive"><a href="#allowoverridelist">AllowOverrideList</a></code> is set to
 448     <code>None</code>, <a href="#accessfilename">.htaccess</a> files are
 449     completely ignored. In this case, the server will not even attempt
 450     to read <code>.htaccess</code> files in the filesystem.</p>
 451
 452     <p>When this directive is set to <code>All</code>, then any
 453     directive which has the .htaccess <a href="directive-dict.html#Context">Context</a> is allowed in
 454     <code>.htaccess</code> files.</p>
 455
 456     <p>The <var>directive-type</var> can be one of the following
 457     groupings of directives. (See the <a href="overrides.html">override class
 458     index</a> for an up-to-date listing of which directives are enabled by each
 459     <var>directive-type</var>.)</p>
 460
 461     <dl>
 462       <dt><a href="overrides.html#override-authconfig">AuthConfig</a></dt>
 463
 464       <dd>
 465
 466       Allow use of the authorization directives (<code class="directive"><a href="../mod/mod_authz_dbm.html#authdbmgroupfile">AuthDBMGroupFile</a></code>,
 467       <code class="directive"><a href="../mod/mod_authn_dbm.html#authdbmuserfile">AuthDBMUserFile</a></code>,
 468       <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>,
 469       <code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code>,
 470       <code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code>, <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code>, <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>, <em>etc.</em>).</dd>
 471
 472       <dt><a href="overrides.html#override-fileinfo">FileInfo</a></dt>
 473
 474       <dd>
 475       Allow use of the directives controlling document types
 476      (<code class="directive"><a href="#errordocument">ErrorDocument</a></code>,
 477       <code class="directive"><a href="#forcetype">ForceType</a></code>,
 478       <code class="directive"><a href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>,
 479       <code class="directive"><a href="#sethandler">SetHandler</a></code>,
 480       <code class="directive"><a href="#setinputfilter">SetInputFilter</a></code>,
 481       <code class="directive"><a href="#setoutputfilter">SetOutputFilter</a></code>, and
 482       <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> Add* and Remove* directives),
 483       document meta data (<code class="directive"><a href="../mod/mod_headers.html#header">Header</a></code>, <code class="directive"><a href="../mod/mod_headers.html#requestheader">RequestHeader</a></code>, <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>, <code class="directive"><a href="../mod/mod_setenvif.html#setenvifnocase">SetEnvIfNoCase</a></code>, <code class="directive"><a href="../mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code>, <code class="directive"><a href="../mod/mod_usertrack.html#cookieexpires">CookieExpires</a></code>, <code class="directive"><a href="../mod/mod_usertrack.html#cookiedomain">CookieDomain</a></code>, <code class="directive"><a href="../mod/mod_usertrack.html#cookiestyle">CookieStyle</a></code>, <code class="directive"><a href="../mod/mod_usertrack.html#cookietracking">CookieTracking</a></code>, <code class="directive"><a href="../mod/mod_usertrack.html#cookiename">CookieName</a></code>),
 484       <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> directives (<code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code>, <code class="directive"><a href="../mod/mod_rewrite.html#rewriteoptions">RewriteOptions</a></code>, <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code>, <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>, <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>),
 485       <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directives (<code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code>, <code class="directive"><a href="../mod/mod_alias.html#redirecttemp">RedirectTemp</a></code>, <code class="directive"><a href="../mod/mod_alias.html#redirectpermanent">RedirectPermanent</a></code>, <code class="directive"><a href="../mod/mod_alias.html#redirectmatch">RedirectMatch</a></code>), and
 486       <code class="directive"><a href="../mod/mod_actions.html#action">Action</a></code> from
 487       <code class="module"><a href="../mod/mod_actions.html">mod_actions</a></code>.
 488       </dd>
 489
 490       <dt><a href="overrides.html#override-indexes">Indexes</a></dt>
 491
 492       <dd>
 493       Allow use of the directives controlling directory indexing
 494       (<code class="directive"><a href="../mod/mod_autoindex.html#adddescription">AddDescription</a></code>,
 495       <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>,
 496       <code class="directive"><a href="../mod/mod_autoindex.html#addiconbytype">AddIconByType</a></code>,
 497       <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_dir.html#fallbackresource">FallbackResource</a></code>, <a href="mod_autoindex.html#indexoptions.fancyindexing"><code>FancyIndexing</code></a>, <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>,
 498       <em>etc.</em>).</dd>
 499
 500       <dt><a href="overrides.html#override-limit">Limit</a></dt>
 501
 502       <dd>
 503       Allow use of the directives controlling host access (<code class="directive"><a href="../mod/mod_access_compat.html#allow">Allow</a></code>, <code class="directive"><a href="../mod/mod_access_compat.html#deny">Deny</a></code> and <code class="directive"><a href="../mod/mod_access_compat.html#order">Order</a></code>).</dd>
 504
 505
 506
 507
 508       <dt>Nonfatal=[Override|Unknown|All]</dt>
 509
 510       <dd>
 511       Allow use of AllowOverride option to treat invalid (unrecognized
 512       or disallowed) directives in
 513       .htaccess as nonfatal. Instead of causing an Internal Server
 514       Error, disallowed or unrecognised directives will be ignored
 515       and a warning logged:
 516       <ul>
 517           <li><strong>Nonfatal=Override</strong> treats directives
 518               forbidden by AllowOverride as nonfatal.</li>
 519           <li><strong>Nonfatal=Unknown</strong> treats unknown directives
 520               as nonfatal.  This covers typos and directives implemented
 521               by a module that's not present.</li>
 522           <li><strong>Nonfatal=All</strong> treats both the above as nonfatal.</li>
 523       </ul>
 524       <p>Note that a syntax error in a valid directive will still cause
 525       an Internal Server Error.</p>
 526       <div class="warning"><h3>Security</h3>
 527           Nonfatal errors may have security implications for .htaccess users.
 528           For example, if AllowOverride disallows AuthConfig, users'
 529           configuration designed to restrict access to a site will be disabled.
 530       </div>
 531       </dd>
 532
 533       <dt><a href="overrides.html#override-options">Options</a>[=<var>Option</var>,...]</dt>
 534
 535       <dd>
 536       Allow use of the directives controlling specific directory
 537       features (<code class="directive"><a href="#options">Options</a></code> and
 538       <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code>).
 539       An equal sign may be given followed by a comma-separated list, without
 540       spaces, of options that may be set using the <code class="directive"><a href="#options">Options</a></code> command.
 541
 542       <div class="note"><h3>Implicit disabling of Options</h3>
 543       <p>Even though the list of options that may be used in .htaccess files
 544          can be limited with this directive, as long as any <code class="directive"><a href="#options">Options</a></code> directive is allowed any
 545          other inherited option can be disabled by using the non-relative
 546          syntax.  In other words, this mechanism cannot force a specific option
 547          to remain <em>set</em> while allowing any others to be set.
 548       </p></div>
 549
 550       <div class="example"><p><code>
 551       AllowOverride Options=Indexes,MultiViews
 552       </code></p></div>
 553       </dd>
 554     </dl>
 555
 556     <p>Example:</p>
 557
 558     <pre class="prettyprint lang-config">AllowOverride AuthConfig Indexes</pre>
 559
 560
 561     <p>In the example above, all directives that are neither in the group
 562     <code>AuthConfig</code> nor <code>Indexes</code> cause an internal
 563     server error.</p>
 564
 565     <div class="note"><p>For security and performance reasons, do not set
 566     <code>AllowOverride</code> to anything other than <code>None</code>
 567     in your <code>&lt;Directory "/"&gt;</code> block. Instead, find (or
 568     create) the <code>&lt;Directory&gt;</code> block that refers to the
 569     directory where you're actually planning to place a
 570     <code>.htaccess</code> file.</p>
 571     </div>
 572
 573 <h3>See also</h3>
 574 <ul>
 575 <li><code class="directive"><a href="#accessfilename">AccessFileName</a></code></li>
 576 <li><code class="directive"><a href="#allowoverridelist">AllowOverrideList</a></code></li>
 577 <li><a href="../configuring.html">Configuration Files</a></li>
 578 <li><a href="../howto/htaccess.html">.htaccess Files</a></li>
 579 <li><a href="overrides.html">Override Class Index for .htaccess</a></li>
 580 </ul>
 581 </div>
 582 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 583 <div class="directive-section"><h2><a name="AllowOverrideList" id="AllowOverrideList">AllowOverrideList</a> <a name="allowoverridelist" id="allowoverridelist">Directive</a><a title="Permanent link" href="#allowoverridelist" class="permalink">&para;</a></h2>
 584 <table class="directive">
 585 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Individual directives that are allowed in
 586 <code>.htaccess</code> files</td></tr>
 587 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowOverrideList None|<var>directive</var>
 588 [<var>directive-type</var>] ...</code></td></tr>
 589 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowOverrideList None</code></td></tr>
 590 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 591 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 592 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 593 </table>
 594     <p>When the server finds an <code>.htaccess</code> file (as
 595     specified by <code class="directive"><a href="#accessfilename">AccessFileName</a></code>),
 596     it needs to know which directives declared in that file can override
 597     earlier configuration directives.</p>
 598
 599     <div class="note"><h3>Only available in &lt;Directory&gt; sections</h3>
 600     <code class="directive">AllowOverrideList</code> is valid only in
 601     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
 602     sections specified without regular expressions, not in <code class="directive"><a href="#location">&lt;Location&gt;</a></code>, <code class="directive"><a href="#directorymatch">&lt;DirectoryMatch&gt;</a></code> or
 603     <code class="directive"><a href="#files">&lt;Files&gt;</a></code> sections.
 604     </div>
 605
 606     <p>When this directive is set to <code>None</code> and <code class="directive"><a href="#allowoverride">AllowOverride</a></code> is set to <code>None</code>,
 607     then <a href="#accessfilename">.htaccess</a> files are completely
 608     ignored.  In this case, the server will not even attempt to read
 609     <code>.htaccess</code> files in the filesystem.</p>
 610
 611     <p>Example:</p>
 612
 613     <pre class="prettyprint lang-config">AllowOverride None
 614 AllowOverrideList Redirect RedirectMatch</pre>
 615
 616
 617     <p>In the example above, only the <code>Redirect</code> and
 618     <code>RedirectMatch</code> directives are allowed. All others will
 619     cause an Internal Server Error.</p>
 620
 621     <p>Example:</p>
 622
 623     <pre class="prettyprint lang-config">AllowOverride AuthConfig
 624 AllowOverrideList CookieTracking CookieName</pre>
 625
 626
 627     <p>In the example above, <code class="directive"><a href="#allowoverride">AllowOverride</a></code>
 628     grants permission to the <code>AuthConfig</code>
 629     directive grouping and <code class="directive">AllowOverrideList</code> grants
 630     permission to only two directives from the <code>FileInfo</code> directive
 631     grouping. All others will cause an Internal Server Error.</p>
 632
 633 <h3>See also</h3>
 634 <ul>
 635 <li><code class="directive"><a href="#accessfilename">AccessFileName</a></code></li>
 636 <li><code class="directive"><a href="#allowoverride">AllowOverride</a></code></li>
 637 <li><a href="../configuring.html">Configuration Files</a></li>
 638 <li><a href="../howto/htaccess.html">.htaccess Files</a></li>
 639 </ul>
 640 </div>
 641 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 642 <div class="directive-section"><h2><a name="AsyncFilter" id="AsyncFilter">AsyncFilter</a> <a name="asyncfilter" id="asyncfilter">Directive</a><a title="Permanent link" href="#asyncfilter" class="permalink">&para;</a></h2>
 643 <table class="directive">
 644 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the minimum filter type eligible for asynchronous handling</td></tr>
 645 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AsyncFilter request|connection|network</code></td></tr>
 646 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AsyncFilter request</code></td></tr>
 647 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 648 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 649 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 650 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Only available from Apache 2.5.0 and later.</td></tr>
 651 </table>
 652         <p>This directive controls the minimum filter levels that are eligible
 653         for asynchronous handling. This may be necessary to support legacy external
 654         filters that did not handle meta buckets correctly.</p>
 655
 656         <p>If set to "network", asynchronous handling will be limited to the network
 657         filter only. If set to "connection", all connection and network filters
 658         will be eligible for asynchronous handling, including <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.
 659         If set to "request", all filters will be eligible for asynchronous handling.</p>
 660
 661 </div>
 662 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 663 <div class="directive-section"><h2><a name="CGIMapExtension" id="CGIMapExtension">CGIMapExtension</a> <a name="cgimapextension" id="cgimapextension">Directive</a><a title="Permanent link" href="#cgimapextension" class="permalink">&para;</a></h2>
 664 <table class="directive">
 665 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI
 666 scripts</td></tr>
 667 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIMapExtension <var>cgi-path</var> <var>.extension</var></code></td></tr>
 668 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 669 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 670 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 671 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 672 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>NetWare only</td></tr>
 673 </table>
 674     <p>This directive is used to control how Apache httpd finds the
 675     interpreter used to run CGI scripts. For example, setting
 676     <code>CGIMapExtension sys:\foo.nlm .foo</code> will
 677     cause all CGI script files with a <code>.foo</code> extension to
 678     be passed to the FOO interpreter.</p>
 679
 680 </div>
 681 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 682 <div class="directive-section"><h2><a name="CGIPassAuth" id="CGIPassAuth">CGIPassAuth</a> <a name="cgipassauth" id="cgipassauth">Directive</a><a title="Permanent link" href="#cgipassauth" class="permalink">&para;</a></h2>
 683 <table class="directive">
 684 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables passing HTTP authorization headers to scripts as CGI
 685 variables</td></tr>
 686 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIPassAuth On|Off</code></td></tr>
 687 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CGIPassAuth Off</code></td></tr>
 688 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 689 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 690 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 691 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 692 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.4.13 and later</td></tr>
 693 </table>
 694     <p><code class="directive">CGIPassAuth</code> allows scripts access to HTTP
 695     authorization headers such as <code>Authorization</code>, which is
 696     required for scripts that implement HTTP Basic authentication.
 697     Normally these HTTP headers are hidden from scripts. This is to disallow
 698     scripts from seeing user ids and passwords used to access the server when
 699     HTTP Basic authentication is enabled in the web server.  This directive
 700     should be used when scripts are allowed to implement HTTP Basic
 701     authentication.</p>
 702
 703     <p>This directive can be used instead of the compile-time setting
 704     <code>SECURITY_HOLE_PASS_AUTHORIZATION</code> which has been available
 705     in previous versions of Apache HTTP Server.</p>
 706
 707     <p>The setting is respected by any modules which use
 708     <code>ap_add_common_vars()</code>, such as <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>,
 709     <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code>, <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>,
 710     <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code>, and so on.  Notably, it affects
 711     modules which don't handle the request in the usual sense but
 712     still use this API; examples of this are <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 713     and <code class="module"><a href="../mod/mod_ext_filter.html">mod_ext_filter</a></code>.  Third-party modules that don't
 714     use <code>ap_add_common_vars()</code> may choose to respect the setting
 715     as well.</p>
 716
 717 </div>
 718 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 719 <div class="directive-section"><h2><a name="CGIVar" id="CGIVar">CGIVar</a> <a name="cgivar" id="cgivar">Directive</a><a title="Permanent link" href="#cgivar" class="permalink">&para;</a></h2>
 720 <table class="directive">
 721 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how some CGI variables are set</td></tr>
 722 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIVar <var>variable</var> <var>rule</var></code></td></tr>
 723 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 724 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 725 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 726 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 727 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.4.21 and later</td></tr>
 728 </table>
 729   <p>This directive controls how some CGI variables are set.</p>
 730
 731   <p><strong>REQUEST_URI</strong> rules:</p>
 732   <dl>
 733     <dt><code>original-uri</code> (default)</dt>
 734     <dd>The value is taken from the original request line, and will not
 735     reflect internal redirects or subrequests which change the requested
 736     resource.</dd>
 737     <dt><code>current-uri</code></dt>
 738     <dd>The value reflects the resource currently being processed,
 739     which may be different than the original request from the client
 740     due to internal redirects or subrequests.</dd>
 741   </dl>
 742
 743 </div>
 744 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 745 <div class="directive-section"><h2><a name="ContentDigest" id="ContentDigest">ContentDigest</a> <a name="contentdigest" id="contentdigest">Directive</a><a title="Permanent link" href="#contentdigest" class="permalink">&para;</a></h2>
 746 <table class="directive">
 747 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables the generation of <code>Content-MD5</code> HTTP Response
 748 headers</td></tr>
 749 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ContentDigest On|Off</code></td></tr>
 750 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ContentDigest Off</code></td></tr>
 751 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 752 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
 753 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 754 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 755 </table>
 756     <p>This directive enables the generation of
 757     <code>Content-MD5</code> headers as defined in RFC1864
 758     respectively RFC2616.</p>
 759
 760     <p>MD5 is an algorithm for computing a "message digest"
 761     (sometimes called "fingerprint") of arbitrary-length data, with
 762     a high degree of confidence that any alterations in the data
 763     will be reflected in alterations in the message digest.</p>
 764
 765     <p>The <code>Content-MD5</code> header provides an end-to-end
 766     message integrity check (MIC) of the entity-body. A proxy or
 767     client may check this header for detecting accidental
 768     modification of the entity-body in transit. Example header:</p>
 769
 770     <div class="example"><p><code>
 771       Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==
 772     </code></p></div>
 773
 774     <p>Note that this can cause performance problems on your server
 775     since the message digest is computed on every request (the
 776     values are not cached).</p>
 777
 778     <p><code>Content-MD5</code> is only sent for documents served
 779     by the <code class="module"><a href="../mod/core.html">core</a></code>, and not by any module. For example,
 780     SSI documents, output from CGI scripts, and byte range responses
 781     do not have this header.</p>
 782
 783 </div>
 784 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 785 <div class="directive-section"><h2><a name="DefaultRuntimeDir" id="DefaultRuntimeDir">DefaultRuntimeDir</a> <a name="defaultruntimedir" id="defaultruntimedir">Directive</a><a title="Permanent link" href="#defaultruntimedir" class="permalink">&para;</a></h2>
 786 <table class="directive">
 787 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the server run-time files</td></tr>
 788 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultRuntimeDir <var>directory-path</var></code></td></tr>
 789 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultRuntimeDir DEFAULT_REL_RUNTIMEDIR (logs/)</code></td></tr>
 790 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 791 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 792 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 793 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.4.2 and later</td></tr>
 794 </table>
 795     <p>The <code class="directive">DefaultRuntimeDir</code> directive sets the
 796     directory in which the server will create various run-time files
 797     (shared memory, locks, etc.). If set as a relative path, the full path
 798     will be relative to <code class="directive">ServerRoot</code>.</p>
 799
 800     <p><strong>Example</strong></p>
 801    <pre class="prettyprint lang-config">DefaultRuntimeDir scratch/</pre>
 802
 803
 804     <p>The default location of <code class="directive">DefaultRuntimeDir</code> may be
 805     modified by changing the <code>DEFAULT_REL_RUNTIMEDIR</code> #define
 806     at build time.</p>
 807
 808    <p>Note: <code class="directive">ServerRoot</code> should be specified before this
 809    directive is used. Otherwise, the default value of <code class="directive">ServerRoot</code>
 810    would be used to set the base directory.</p>
 811
 812
 813 <h3>See also</h3>
 814 <ul>
 815 <li><a href="../misc/security_tips.html#serverroot">the
 816     security tips</a> for information on how to properly set
 817     permissions on the <code class="directive">ServerRoot</code></li>
 818 </ul>
 819 </div>
 820 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 821 <div class="directive-section"><h2><a name="DefaultStateDir" id="DefaultStateDir">DefaultStateDir</a> <a name="defaultstatedir" id="defaultstatedir">Directive</a><a title="Permanent link" href="#defaultstatedir" class="permalink">&para;</a></h2>
 822 <table class="directive">
 823 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the persistent state files</td></tr>
 824 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultStateeDir <var>directory-path</var></code></td></tr>
 825 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultRuntimeDir DEFAULT_REL_STATEDIR (state/)</code></td></tr>
 826 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 827 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 828 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 829 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.5.1 and later</td></tr>
 830 </table>
 831     <p>The <code class="directive">DefaultStateDir</code> directive sets the
 832     directory in which the server will create various persistent state
 833     files (databases, long-lived caches, etc.). If set as a relative
 834     path, the full path will be relative to
 835     <code class="directive">ServerRoot</code>.</p>
 836
 837     <p><strong>Example</strong></p>
 838    <pre class="prettyprint lang-config">DefaultStateDir state/</pre>
 839
 840
 841     <p>The default location of <code class="directive">DefaultStateDir</code> may be
 842     modified by changing the <code>DEFAULT_REL_STATEDIR</code> #define
 843     at build time.</p>
 844
 845    <p>Note: <code class="directive">ServerRoot</code> should be specified before this
 846    directive is used. Otherwise, the default value of <code class="directive">ServerRoot</code>
 847    would be used to set the base directory.</p>
 848
 849
 850 <h3>See also</h3>
 851 <ul>
 852 <li><a href="../misc/security_tips.html#serverroot">the
 853     security tips</a> for information on how to properly set
 854     permissions on the <code class="directive">ServerRoot</code></li>
 855 </ul>
 856 </div>
 857 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 858 <div class="directive-section"><h2><a name="DefaultType" id="DefaultType">DefaultType</a> <a name="defaulttype" id="defaulttype">Directive</a><a title="Permanent link" href="#defaulttype" class="permalink">&para;</a></h2>
 859 <table class="directive">
 860 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>This directive has no effect other than to emit warnings
 861 if the value is not <code>none</code>. In prior versions, DefaultType
 862 would specify a default media type to assign to response content for
 863 which no other media type configuration could be found.
 864 </td></tr>
 865 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultType <var>media-type|none</var></code></td></tr>
 866 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultType none</code></td></tr>
 867 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 868 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 869 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 870 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 871 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>All choices except <code>none</code> are DISABLED for 2.3.x and later.
 872 </td></tr>
 873 </table>
 874     <p>This directive has been disabled.  For backwards compatibility
 875     of configuration files, it may be specified with the value
 876     <code>none</code>, meaning no default media type. For example:</p>
 877
 878     <pre class="prettyprint lang-config">DefaultType None</pre>
 879
 880
 881     <p><code>DefaultType None</code> is only available in
 882     httpd-2.2.7 and later.</p>
 883
 884     <p>Use the mime.types configuration file and the
 885     <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> to configure media
 886     type assignments via file extensions, or the
 887     <code class="directive"><a href="#forcetype">ForceType</a></code> directive to configure
 888     the media type for specific resources. Otherwise, the server will
 889     send the response without a Content-Type header field and the
 890     recipient may attempt to guess the media type.</p>
 891
 892 <h3>See also</h3>
 893 <ul>
 894 <li><code class="directive"><a href="#undefine">UnDefine</a></code></li>
 895 <li><code class="directive"><a href="#ifdefine">IfDefine</a></code></li>
 896 </ul>
 897 </div>
 898 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 899 <div class="directive-section"><h2><a name="Define" id="Define">Define</a> <a name="define" id="define">Directive</a><a title="Permanent link" href="#define" class="permalink">&para;</a></h2>
 900 <table class="directive">
 901 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a variable</td></tr>
 902 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Define <var>parameter-name</var> [<var>parameter-value</var>]</code></td></tr>
 903 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 904 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 905 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 906 </table>
 907     <p>In its one parameter form, <code class="directive">Define</code> is
 908     equivalent to passing the <code>-D</code> argument to
 909     <code class="program"><a href="../programs/httpd.html">httpd</a></code>. It can be used to toggle the use of
 910     <code class="directive"><a href="#ifdefine">&lt;IfDefine&gt;</a></code>
 911     sections without needing to alter <code>-D</code> arguments in any
 912     startup scripts.</p>
 913
 914     <p>In addition to that, if the second parameter is given, a config variable
 915     is set to this value. The variable can be used in the configuration using
 916     the <code>${VAR}</code> syntax. The variable is always globally defined
 917     and not limited to the scope of the surrounding config section.</p>
 918
 919     <pre class="prettyprint lang-config">&lt;IfDefine TEST&gt;
 920   Define servername test.example.com
 921 &lt;/IfDefine&gt;
 922 &lt;IfDefine !TEST&gt;
 923   Define servername www.example.com
 924   Define SSL
 925 &lt;/IfDefine&gt;
 926
 927 DocumentRoot "/var/www/${servername}/htdocs"</pre>
 928
 929
 930     <p>Variable names may not contain colon ":" characters, to avoid clashes
 931     with <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>'s syntax.</p>
 932
 933     <div class="note"><h3>Virtual Host scope and pitfalls</h3>
 934       <p>While this directive is supported in virtual host context,
 935          the changes it makes are visible to any later configuration
 936          directives, beyond any enclosing virtual host.</p>
 937     </div>
 938
 939 </div>
 940 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 941 <div class="directive-section"><h2><a name="Directory" id="Directory">&lt;Directory&gt;</a> <a name="directory" id="directory">Directive</a><a title="Permanent link" href="#directory" class="permalink">&para;</a></h2>
 942 <table class="directive">
 943 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of directives that apply only to the
 944 named file-system directory, sub-directories, and their contents.</td></tr>
 945 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Directory <var>directory-path</var>&gt;
 946 ... &lt;/Directory&gt;</code></td></tr>
 947 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 948 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
 949 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
 950 </table>
 951     <p><code class="directive">&lt;Directory&gt;</code> and
 952     <code>&lt;/Directory&gt;</code> are used to enclose a group of
 953     directives that will apply only to the named directory,
 954     sub-directories of that directory, and the files within the respective
 955     directories.  Any directive that is allowed
 956     in a directory context may be used. <var>Directory-path</var> is
 957     either the full path to a directory, or a wild-card string using
 958     Unix shell-style matching. In a wild-card string, <code>?</code> matches
 959     any single character, and <code>*</code> matches any sequences of
 960     characters. You may also use <code>[]</code> character ranges. None
 961     of the wildcards match a `/' character, so <code>&lt;Directory
 962     "/*/public_html"&gt;</code> will not match
 963     <code>/home/user/public_html</code>, but <code>&lt;Directory
 964     "/home/*/public_html"&gt;</code> will match. Example:</p>
 965
 966     <pre class="prettyprint lang-config">&lt;Directory "/usr/local/httpd/htdocs"&gt;
 967   Options Indexes FollowSymLinks
 968 &lt;/Directory&gt;</pre>
 969
 970
 971     <p>Directory paths <em>may</em> be quoted, if you like, however, it
 972     <em>must</em> be quoted if the path contains spaces. This is because a
 973     space would otherwise indicate the end of an argument.</p>
 974
 975     <div class="note">
 976       <p>Be careful with the <var>directory-path</var> arguments:
 977       They have to literally match the filesystem path which Apache httpd uses
 978       to access the files. Directives applied to a particular
 979       <code>&lt;Directory&gt;</code> will not apply to files accessed from
 980       that same directory via a different path, such as via different symbolic
 981       links.</p>
 982     </div>
 983
 984     <p><a class="glossarylink" href="../glossary.html#regex" title="see glossary">Regular
 985     expressions</a> can also be used, with the addition of the
 986     <code>~</code> character. For example:</p>
 987
 988     <pre class="prettyprint lang-config">&lt;Directory ~ "^/www/[0-9]{3}"&gt;
 989
 990 &lt;/Directory&gt;</pre>
 991
 992
 993     <p>would match directories in <code>/www/</code> that consisted of
 994     three numbers.</p>
 995
 996     <p>If multiple (non-regular expression) <code class="directive">&lt;Directory&gt;</code> sections
 997     match the directory (or one of its parents) containing a document,
 998     then the directives are applied in the order of shortest match
 999     first, interspersed with the directives from the <a href="#accessfilename">.htaccess</a> files. For example,
1000     with</p>
1001
1002     <pre class="prettyprint lang-config">&lt;Directory "/"&gt;
1003   AllowOverride None
1004 &lt;/Directory&gt;
1005
1006 &lt;Directory "/home"&gt;
1007   AllowOverride FileInfo
1008 &lt;/Directory&gt;</pre>
1009
1010
1011     <p>for access to the document <code>/home/web/dir/doc.html</code>
1012     the steps are:</p>
1013
1014     <ul>
1015       <li>Apply directive <code>AllowOverride None</code>
1016       (disabling <code>.htaccess</code> files).</li>
1017
1018       <li>Apply directive <code>AllowOverride FileInfo</code> (for
1019       directory <code>/home</code>).</li>
1020
1021       <li>Apply any <code>FileInfo</code> directives in
1022       <code>/home/.htaccess</code>, <code>/home/web/.htaccess</code> and
1023       <code>/home/web/dir/.htaccess</code> in that order.</li>
1024     </ul>
1025
1026     <p>Regular expressions are not considered until after all of the
1027     normal sections have been applied. Then all of the regular
1028     expressions are tested in the order they appeared in the
1029     configuration file. For example, with</p>
1030
1031     <pre class="prettyprint lang-config">&lt;Directory ~ "abc$"&gt;
1032   # ... directives here ...
1033 &lt;/Directory&gt;</pre>
1034
1035
1036     <p>the regular expression section won't be considered until after
1037     all normal <code class="directive">&lt;Directory&gt;</code>s and
1038     <code>.htaccess</code> files have been applied. Then the regular
1039     expression will match on <code>/home/abc/public_html/abc</code> and
1040     the corresponding <code class="directive">&lt;Directory&gt;</code> will
1041     be applied.</p>
1042
1043    <p><strong>Note that the default access for
1044     <code>&lt;Directory "/"&gt;</code> is to permit all access.
1045     This means that Apache httpd will serve any file mapped from an URL. It is
1046     recommended that you change this with a block such
1047     as</strong></p>
1048
1049     <pre class="prettyprint lang-config">&lt;Directory "/"&gt;
1050   Require all denied
1051 &lt;/Directory&gt;</pre>
1052
1053
1054     <p><strong>and then override this for directories you
1055     <em>want</em> accessible. See the <a href="../misc/security_tips.html">Security Tips</a> page for more
1056     details.</strong></p>
1057
1058     <p>The directory sections occur in the <code>httpd.conf</code> file.
1059     <code class="directive">&lt;Directory&gt;</code> directives
1060     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>
1061
1062 <h3>See also</h3>
1063 <ul>
1064 <li><a href="../sections.html">How &lt;Directory&gt;,
1065     &lt;Location&gt; and &lt;Files&gt; sections work</a> for an
1066     explanation of how these different sections are combined when a
1067     request is received</li>
1068 </ul>
1069 </div>
1070 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1071 <div class="directive-section"><h2><a name="DirectoryMatch" id="DirectoryMatch">&lt;DirectoryMatch&gt;</a> <a name="directorymatch" id="directorymatch">Directive</a><a title="Permanent link" href="#directorymatch" class="permalink">&para;</a></h2>
1072 <table class="directive">
1073 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose directives that apply to
1074 the contents of file-system directories matching a regular expression.</td></tr>
1075 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;DirectoryMatch <var>regex</var>&gt;
1076 ... &lt;/DirectoryMatch&gt;</code></td></tr>
1077 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1078 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1079 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1080 </table>
1081     <p><code class="directive">&lt;DirectoryMatch&gt;</code> and
1082     <code>&lt;/DirectoryMatch&gt;</code> are used to enclose a group
1083     of directives which will apply only to the named directory (and the files within),
1084     the same as <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>.
1085     However, it takes as an argument a
1086     <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.  For example:</p>
1087
1088     <pre class="prettyprint lang-config">&lt;DirectoryMatch "^/www/(.+/)?[0-9]{3}/"&gt;
1089     # ...
1090 &lt;/DirectoryMatch&gt;</pre>
1091
1092
1093     <p>matches directories in <code>/www/</code> (or any subdirectory thereof)
1094     that consist of three numbers.</p>
1095
1096    <div class="note"><h3>Compatibility</h3>
1097       Prior to 2.3.9, this directive implicitly applied to sub-directories
1098       (like <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>) and
1099       could not match the end of line symbol ($).  In 2.3.9 and later,
1100       only directories that match the expression are affected by the enclosed
1101       directives.
1102     </div>
1103
1104     <div class="note"><h3>Trailing Slash</h3>
1105       This directive applies to requests for directories that may or may
1106       not end in a trailing slash, so expressions that are anchored to the
1107       end of line ($) must be written with care.
1108     </div>
1109
1110     <p>From 2.4.8 onwards, named groups and backreferences are captured and
1111     written to the environment with the corresponding name prefixed with
1112     "MATCH_" and in upper case. This allows elements of paths to be referenced
1113     from within <a href="../expr.html">expressions</a> and modules like
1114     <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
1115     (unnamed) backreferences are ignored. Use named groups instead.</p>
1116
1117     <pre class="prettyprint lang-config">&lt;DirectoryMatch "^/var/www/combined/(?&lt;sitename&gt;[^/]+)"&gt;
1118     Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
1119 &lt;/DirectoryMatch&gt;</pre>
1120
1121
1122 <h3>See also</h3>
1123 <ul>
1124 <li><code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> for
1125 a description of how regular expressions are mixed in with normal
1126 <code class="directive">&lt;Directory&gt;</code>s</li>
1127 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt; and
1128 &lt;Files&gt; sections work</a> for an explanation of how these different
1129 sections are combined when a request is received</li>
1130 </ul>
1131 </div>
1132 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1133 <div class="directive-section"><h2><a name="DocumentRoot" id="DocumentRoot">DocumentRoot</a> <a name="documentroot" id="documentroot">Directive</a><a title="Permanent link" href="#documentroot" class="permalink">&para;</a></h2>
1134 <table class="directive">
1135 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory that forms the main document tree visible
1136 from the web</td></tr>
1137 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DocumentRoot <var>directory-path</var></code></td></tr>
1138 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DocumentRoot "/usr/local/apache/htdocs"</code></td></tr>
1139 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1140 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1141 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1142 </table>
1143     <p>This directive sets the directory from which <code class="program"><a href="../programs/httpd.html">httpd</a></code>
1144     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
1145     path from the requested URL to the document root to make the
1146     path to the document. Example:</p>
1147
1148     <pre class="prettyprint lang-config">DocumentRoot "/usr/web"</pre>
1149
1150
1151     <p>then an access to
1152     <code>http://my.example.com/index.html</code> refers to
1153     <code>/usr/web/index.html</code>. If the <var>directory-path</var> is
1154     not absolute then it is assumed to be relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p>
1155
1156     <p>The <code class="directive">DocumentRoot</code> should be specified without
1157     a trailing slash.</p>
1158
1159 <h3>See also</h3>
1160 <ul>
1161 <li><a href="../urlmapping.html#documentroot">Mapping URLs to Filesystem
1162 Locations</a></li>
1163 </ul>
1164 </div>
1165 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1166 <div class="directive-section"><h2><a name="Else" id="Else">&lt;Else&gt;</a> <a name="else" id="else">Directive</a><a title="Permanent link" href="#else" class="permalink">&para;</a></h2>
1167 <table class="directive">
1168 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if the condition of a
1169 previous <code class="directive"><a href="#if">&lt;If&gt;</a></code> or
1170 <code class="directive"><a href="#elseif">&lt;ElseIf&gt;</a></code> section is not
1171 satisfied by a request at runtime</td></tr>
1172 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Else&gt; ... &lt;/Else&gt;</code></td></tr>
1173 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1174 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1175 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1176 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1177 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Nested conditions are evaluated in 2.4.26 and later</td></tr>
1178 </table>
1179     <p>The <code class="directive">&lt;Else&gt;</code> applies the enclosed
1180     directives if and only if the most recent
1181     <code class="directive">&lt;If&gt;</code> or
1182     <code class="directive">&lt;ElseIf&gt;</code> section
1183     in the same scope has not been applied.
1184     For example: In </p>
1185
1186     <pre class="prettyprint lang-config">&lt;If "-z req('Host')"&gt;
1187   # ...
1188 &lt;/If&gt;
1189 &lt;Else&gt;
1190   # ...
1191 &lt;/Else&gt;</pre>
1192
1193
1194     <p> The <code class="directive">&lt;If&gt;</code> would match HTTP/1.0
1195         requests without a <var>Host:</var> header and the
1196         <code class="directive">&lt;Else&gt;</code> would match requests
1197         with a <var>Host:</var> header.</p>
1198
1199
1200 <h3>See also</h3>
1201 <ul>
1202 <li><code class="directive"><a href="#if">&lt;If&gt;</a></code></li>
1203 <li><code class="directive"><a href="#elseif">&lt;ElseIf&gt;</a></code></li>
1204 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;,
1205     &lt;Files&gt; sections work</a> for an explanation of how these
1206     different sections are combined when a request is received.
1207     <code class="directive">&lt;If&gt;</code>,
1208     <code class="directive">&lt;ElseIf&gt;</code>, and
1209     <code class="directive">&lt;Else&gt;</code> are applied last.</li>
1210 </ul>
1211 </div>
1212 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1213 <div class="directive-section"><h2><a name="ElseIf" id="ElseIf">&lt;ElseIf&gt;</a> <a name="elseif" id="elseif">Directive</a><a title="Permanent link" href="#elseif" class="permalink">&para;</a></h2>
1214 <table class="directive">
1215 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if a condition is satisfied
1216 by a request at runtime while the condition of a previous
1217 <code class="directive"><a href="#if">&lt;If&gt;</a></code> or
1218 <code class="directive">&lt;ElseIf&gt;</code> section is not
1219 satisfied</td></tr>
1220 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;ElseIf <var>expression</var>&gt; ... &lt;/ElseIf&gt;</code></td></tr>
1221 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1222 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1223 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1224 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1225 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Nested conditions are evaluated in 2.4.26 and later</td></tr>
1226 </table>
1227     <p>The <code class="directive">&lt;ElseIf&gt;</code> applies the enclosed
1228     directives if and only if both the given condition evaluates to true and
1229     the most recent <code class="directive">&lt;If&gt;</code> or
1230     <code class="directive">&lt;ElseIf&gt;</code> section in the same scope has
1231     not been applied.  For example: In </p>
1232
1233     <pre class="prettyprint lang-config">&lt;If "-R '10.1.0.0/16'"&gt;
1234   #...
1235 &lt;/If&gt;
1236 &lt;ElseIf "-R '10.0.0.0/8'"&gt;
1237   #...
1238 &lt;/ElseIf&gt;
1239 &lt;Else&gt;
1240   #...
1241 &lt;/Else&gt;</pre>
1242
1243
1244     <p>The <code class="directive">&lt;ElseIf&gt;</code> would match if
1245     the remote address of a request belongs to the subnet 10.0.0.0/8 but
1246     not to the subnet 10.1.0.0/16.</p>
1247
1248
1249 <h3>See also</h3>
1250 <ul>
1251 <li><a href="../expr.html">Expressions in Apache HTTP Server</a>,
1252 for a complete reference and more examples.</li>
1253 <li><code class="directive"><a href="#if">&lt;If&gt;</a></code></li>
1254 <li><code class="directive"><a href="#else">&lt;Else&gt;</a></code></li>
1255 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;,
1256     &lt;Files&gt; sections work</a> for an explanation of how these
1257     different sections are combined when a request is received.
1258     <code class="directive">&lt;If&gt;</code>,
1259     <code class="directive">&lt;ElseIf&gt;</code>, and
1260     <code class="directive">&lt;Else&gt;</code> are applied last.</li>
1261 </ul>
1262 </div>
1263 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1264 <div class="directive-section"><h2><a name="EnableMMAP" id="EnableMMAP">EnableMMAP</a> <a name="enablemmap" id="enablemmap">Directive</a><a title="Permanent link" href="#enablemmap" class="permalink">&para;</a></h2>
1265 <table class="directive">
1266 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use memory-mapping to read files during delivery</td></tr>
1267 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableMMAP On|Off</code></td></tr>
1268 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableMMAP On</code></td></tr>
1269 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1270 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1271 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1272 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1273 </table>
1274     <p>This directive controls whether the <code class="program"><a href="../programs/httpd.html">httpd</a></code> may use
1275     memory-mapping if it needs to read the contents of a file during
1276     delivery.  By default, when the handling of a request requires
1277     access to the data within a file -- for example, when delivering a
1278     server-parsed file using <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> -- Apache httpd
1279     memory-maps the file if the OS supports it.</p>
1280
1281     <p>This memory-mapping sometimes yields a performance improvement.
1282     But in some environments, it is better to disable the memory-mapping
1283     to prevent operational problems:</p>
1284
1285     <ul>
1286     <li>On some multiprocessor systems, memory-mapping can reduce the
1287     performance of the <code class="program"><a href="../programs/httpd.html">httpd</a></code>.</li>
1288     <li>Deleting or truncating a file while <code class="program"><a href="../programs/httpd.html">httpd</a></code>
1289       has it memory-mapped can cause <code class="program"><a href="../programs/httpd.html">httpd</a></code> to
1290       crash with a segmentation fault.
1291     </li>
1292     </ul>
1293
1294     <p>For server configurations that are vulnerable to these problems,
1295     you should disable memory-mapping of delivered files by specifying:</p>
1296
1297     <pre class="prettyprint lang-config">EnableMMAP Off</pre>
1298
1299
1300     <p>For NFS mounted files, this feature may be disabled explicitly for
1301     the offending files by specifying:</p>
1302
1303     <pre class="prettyprint lang-config">&lt;Directory "/path-to-nfs-files"&gt;
1304   EnableMMAP Off
1305 &lt;/Directory&gt;</pre>
1306
1307
1308 </div>
1309 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1310 <div class="directive-section"><h2><a name="EnableSendfile" id="EnableSendfile">EnableSendfile</a> <a name="enablesendfile" id="enablesendfile">Directive</a><a title="Permanent link" href="#enablesendfile" class="permalink">&para;</a></h2>
1311 <table class="directive">
1312 <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>
1313 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableSendfile On|Off</code></td></tr>
1314 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableSendfile Off</code></td></tr>
1315 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1316 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1317 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1318 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1319 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default changed to Off in
1320 version 2.3.9.</td></tr>
1321 </table>
1322     <p>This directive controls whether <code class="program"><a href="../programs/httpd.html">httpd</a></code> may use the
1323     sendfile support from the kernel to transmit file contents to the client.
1324     By default, when the handling of a request requires no access
1325     to the data within a file -- for example, when delivering a
1326     static file -- Apache httpd uses sendfile to deliver the file contents
1327     without ever reading the file if the OS supports it.</p>
1328
1329     <p>This sendfile mechanism avoids separate read and send operations,
1330     and buffer allocations. But on some platforms or within some
1331     filesystems, it is better to disable this feature to avoid
1332     operational problems:</p>
1333
1334     <ul>
1335     <li>Some platforms may have broken sendfile support that the build
1336     system did not detect, especially if the binaries were built on
1337     another box and moved to such a machine with broken sendfile
1338     support.</li>
1339     <li>On Linux the use of sendfile triggers TCP-checksum
1340     offloading bugs on certain networking cards when using IPv6.</li>
1341     <li>On Linux on Itanium, <code>sendfile</code> may be unable to handle
1342     files over 2GB in size.</li>
1343     <li>With a network-mounted <code class="directive"><a href="#documentroot">DocumentRoot</a></code> (e.g., NFS, SMB, CIFS, FUSE),
1344     the kernel may be unable to serve the network file through
1345     its own cache.</li>
1346     </ul>
1347
1348     <p>For server configurations that are not vulnerable to these problems,
1349     you may enable this feature by specifying:</p>
1350
1351     <pre class="prettyprint lang-config">EnableSendfile On</pre>
1352
1353
1354     <p>For network mounted files, this feature may be disabled explicitly
1355     for the offending files by specifying:</p>
1356
1357     <pre class="prettyprint lang-config">&lt;Directory "/path-to-nfs-files"&gt;
1358   EnableSendfile Off
1359 &lt;/Directory&gt;</pre>
1360
1361     <p>Please note that the per-directory and .htaccess configuration
1362        of <code class="directive">EnableSendfile</code> is not supported by
1363        <code class="module"><a href="../mod/mod_cache_disk.html">mod_cache_disk</a></code>.
1364        Only global definition of <code class="directive">EnableSendfile</code>
1365        is taken into account by the module.
1366     </p>
1367
1368 </div>
1369 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1370 <div class="directive-section"><h2><a name="Error" id="Error">Error</a> <a name="error" id="error">Directive</a><a title="Permanent link" href="#error" class="permalink">&para;</a></h2>
1371 <table class="directive">
1372 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Abort configuration parsing with a custom error message</td></tr>
1373 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Error <var>message</var></code></td></tr>
1374 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1375 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1376 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1377 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1378 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.3.9 and later</td></tr>
1379 </table>
1380     <p>If an error can be detected within the configuration, this
1381     directive can be used to generate a custom error message, and halt
1382     configuration parsing.  The typical use is for reporting required
1383     modules which are missing from the configuration.</p>
1384
1385     <pre class="prettyprint lang-config"># Example
1386 # ensure that mod_include is loaded
1387 &lt;IfModule !include_module&gt;
1388   Error "mod_include is required by mod_foo.  Load it with LoadModule."
1389 &lt;/IfModule&gt;
1390
1391 # ensure that exactly one of SSL,NOSSL is defined
1392 &lt;IfDefine SSL&gt;
1393 &lt;IfDefine NOSSL&gt;
1394   Error "Both SSL and NOSSL are defined.  Define only one of them."
1395 &lt;/IfDefine&gt;
1396 &lt;/IfDefine&gt;
1397 &lt;IfDefine !SSL&gt;
1398 &lt;IfDefine !NOSSL&gt;
1399   Error "Either SSL or NOSSL must be defined."
1400 &lt;/IfDefine&gt;
1401 &lt;/IfDefine&gt;</pre>
1402
1403
1404
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="ErrorDocument" id="ErrorDocument">ErrorDocument</a> <a name="errordocument" id="errordocument">Directive</a><a title="Permanent link" href="#errordocument" class="permalink">&para;</a></h2>
1408 <table class="directive">
1409 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>What the server will return to the client
1410 in case of an error</td></tr>
1411 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ErrorDocument <var>error-code</var> <var>document</var></code></td></tr>
1412 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1413 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1414 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1415 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1416 </table>
1417     <p>In the event of a problem or error, Apache httpd can be configured
1418     to do one of four things,</p>
1419
1420     <ol>
1421       <li>output a simple hardcoded error message</li>
1422
1423       <li>output a customized message</li>
1424
1425       <li>internally redirect to a local <var>URL-path</var> to handle the
1426       problem/error</li>
1427
1428       <li>redirect to an external <var>URL</var> to handle the
1429       problem/error</li>
1430     </ol>
1431
1432     <p>The first option is the default, while options 2-4 are
1433     configured using the <code class="directive">ErrorDocument</code>
1434     directive, which is followed by the HTTP response code and a URL
1435     or a message. Apache httpd will sometimes offer additional information
1436     regarding the problem/error.</p>
1437
1438     <p>From 2.4.13, <a href="../expr.html">expression syntax</a> can be
1439     used inside the directive to produce dynamic strings and URLs.</p>
1440
1441     <p>URLs can begin with a slash (/) for local web-paths (relative
1442     to the <code class="directive"><a href="#documentroot">DocumentRoot</a></code>), or be a
1443     full URL which the client can resolve. Alternatively, a message
1444     can be provided to be displayed by the browser. Note that deciding
1445     whether the parameter is an URL, a path or a message is performed
1446     before any expression is parsed. Examples:</p>
1447
1448     <pre class="prettyprint lang-config">ErrorDocument 500 http://example.com/cgi-bin/server-error.cgi
1449 ErrorDocument 404 /errors/bad_urls.php
1450 ErrorDocument 401 /subscription_info.html
1451 ErrorDocument 403 "Sorry, can't allow you access today"
1452 ErrorDocument 403 Forbidden!
1453 ErrorDocument 403 /errors/forbidden.py?referrer=%{escape:%{HTTP_REFERER}}</pre>
1454
1455
1456     <p>Additionally, the special value <code>default</code> can be used
1457     to specify Apache httpd's simple hardcoded message.  While not required
1458     under normal circumstances, <code>default</code> will restore
1459     Apache httpd's simple hardcoded message for configurations that would
1460     otherwise inherit an existing <code class="directive">ErrorDocument</code>.</p>
1461
1462     <pre class="prettyprint lang-config">ErrorDocument 404 /cgi-bin/bad_urls.pl
1463
1464 &lt;Directory "/web/docs"&gt;
1465   ErrorDocument 404 default
1466 &lt;/Directory&gt;</pre>
1467
1468
1469     <p>Note that when you specify an <code class="directive">ErrorDocument</code>
1470     that points to a remote URL (ie. anything with a method such as
1471     <code>http</code> in front of it), Apache HTTP Server will send a redirect to the
1472     client to tell it where to find the document, even if the
1473     document ends up being on the same server. This has several
1474     implications, the most important being that the client will not
1475     receive the original error status code, but instead will
1476     receive a redirect status code. This in turn can confuse web
1477     robots and other clients which try to determine if a URL is
1478     valid using the status code. In addition, if you use a remote
1479     URL in an <code>ErrorDocument 401</code>, the client will not
1480     know to prompt the user for a password since it will not
1481     receive the 401 status code. Therefore, <strong>if you use an
1482     <code>ErrorDocument 401</code> directive, then it must refer to a local
1483     document.</strong></p>
1484
1485     <p>Microsoft Internet Explorer (MSIE) will by default ignore
1486     server-generated error messages when they are "too small" and substitute
1487     its own "friendly" error messages. The size threshold varies depending on
1488     the type of error, but in general, if you make your error document
1489     greater than 512 bytes, then MSIE will show the server-generated
1490     error rather than masking it.  More information is available in
1491     Microsoft Knowledge Base article <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q294807">Q294807</a>.</p>
1492
1493     <p>Although most error messages can be overridden, there are certain
1494     circumstances where the internal messages are used regardless of the
1495     setting of <code class="directive"><a href="#errordocument">ErrorDocument</a></code>.  In
1496     particular, if a malformed request is detected, normal request processing
1497     will be immediately halted and the internal error message returned.
1498     This is necessary to guard against security problems caused by
1499     bad requests.</p>
1500
1501     <p>If you are using mod_proxy, you may wish to enable
1502     <code class="directive"><a href="../mod/mod_proxy.html#proxyerroroverride">ProxyErrorOverride</a></code> so that you can provide
1503     custom error messages on behalf of your Origin servers. If you don't enable ProxyErrorOverride,
1504     Apache httpd will not generate custom error documents for proxied content.</p>
1505
1506 <h3>See also</h3>
1507 <ul>
1508 <li><a href="../custom-error.html">documentation of
1509     customizable responses</a></li>
1510 </ul>
1511 </div>
1512 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1513 <div class="directive-section"><h2><a name="ErrorLog" id="ErrorLog">ErrorLog</a> <a name="errorlog" id="errorlog">Directive</a><a title="Permanent link" href="#errorlog" class="permalink">&para;</a></h2>
1514 <table class="directive">
1515 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location where the server will log errors</td></tr>
1516 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> ErrorLog <var>file-path</var>|syslog[:[<var>facility</var>][:<var>tag</var>]]</code></td></tr>
1517 <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>
1518 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1519 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1520 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1521 </table>
1522     <p>The <code class="directive">ErrorLog</code> directive sets the name of
1523     the file to which the server will log any errors it encounters. If
1524     the <var>file-path</var> is not absolute then it is assumed to be
1525     relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p>
1526
1527     <pre class="prettyprint lang-config">ErrorLog "/var/log/httpd/error_log"</pre>
1528
1529
1530     <p>If the <var>file-path</var>
1531     begins with a pipe character "<code>|</code>" then it is assumed to be a
1532     command to spawn to handle the error log.</p>
1533
1534     <pre class="prettyprint lang-config">ErrorLog "|/usr/local/bin/httpd_errors"</pre>
1535
1536
1537     <p>See the notes on <a href="../logs.html#piped">piped logs</a> for
1538     more information.</p>
1539
1540     <p>Using <code>syslog</code> instead of a filename enables logging
1541     via syslogd(8) if the system supports it and if <code class="module"><a href="../mod/mod_syslog.html">mod_syslog</a></code>
1542     is loaded. The default is to use syslog facility <code>local7</code>,
1543     but you can override this by using the <code>syslog:<var>facility</var></code>
1544     syntax where <var>facility</var> can be one of the names usually documented in
1545     syslog(1).  The facility is effectively global, and if it is changed
1546     in individual virtual hosts, the final facility specified affects the
1547     entire server. Same rules apply for the syslog tag, which by default
1548     uses the Apache binary name, <code>httpd</code> in most cases. You can
1549     also override this by using the <code>syslog::<var>tag</var></code>
1550     syntax.</p>
1551
1552     <pre class="prettyprint lang-config">ErrorLog syslog:user
1553 ErrorLog syslog:user:httpd.srv1
1554 ErrorLog syslog::httpd.srv2</pre>
1555
1556
1557     <p>Additional modules can provide their own ErrorLog providers. The syntax
1558     is similar to the <code>syslog</code> example above.</p>
1559
1560     <p>SECURITY: See the <a href="../misc/security_tips.html#serverroot">security tips</a>
1561     document for details on why your security could be compromised
1562     if the directory where log files are stored is writable by
1563     anyone other than the user that starts the server.</p>
1564     <div class="warning"><h3>Note</h3>
1565       <p>When entering a file path on non-Unix platforms, care should be taken
1566       to make sure that only forward slashes are used even though the platform
1567       may allow the use of back slashes. In general it is a good idea to always
1568       use forward slashes throughout the configuration files.</p>
1569     </div>
1570
1571 <h3>See also</h3>
1572 <ul>
1573 <li><code class="directive"><a href="#loglevel">LogLevel</a></code></li>
1574 <li><a href="../logs.html">Apache HTTP Server Log Files</a></li>
1575 </ul>
1576 </div>
1577 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1578 <div class="directive-section"><h2><a name="ErrorLogFormat" id="ErrorLogFormat">ErrorLogFormat</a> <a name="errorlogformat" id="errorlogformat">Directive</a><a title="Permanent link" href="#errorlogformat" class="permalink">&para;</a></h2>
1579 <table class="directive">
1580 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Format specification for error log entries</td></tr>
1581 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> ErrorLogFormat [connection|request] <var>format</var></code></td></tr>
1582 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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><code class="directive">ErrorLogFormat</code> allows to specify what
1587     supplementary information is logged in the error log in addition to the
1588     actual log message.</p>
1589
1590     <pre class="prettyprint lang-config">#Simple example
1591 ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"</pre>
1592
1593
1594     <p>Specifying <code>connection</code> or <code>request</code> as first
1595     parameter allows to specify additional formats, causing additional
1596     information to be logged when the first message is logged for a specific
1597     connection or request, respectively. This additional information is only
1598     logged once per connection/request. If a connection or request is processed
1599     without causing any log message, the additional information is not logged
1600     either.</p>
1601
1602     <p>It can happen that some format string items do not produce output.  For
1603     example, the Referer header is only present if the log message is
1604     associated to a request and the log message happens at a time when the
1605     Referer header has already been read from the client.  If no output is
1606     produced, the default behavior is to delete everything from the preceding
1607     space character to the next space character.  This means the log line is
1608     implicitly divided into fields on non-whitespace to whitespace transitions.
1609     If a format string item does not produce output, the whole field is
1610     omitted.  For example, if the remote address <code>%a</code> in the log
1611     format <code>[%t] [%l] [%a] %M&nbsp;</code> is not available, the surrounding
1612     brackets are not logged either.  Space characters can be escaped with a
1613     backslash to prevent them from delimiting a field.  The combination '%&nbsp;'
1614     (percent space) is a zero-width field delimiter that does not produce any
1615     output.</p>
1616
1617     <p>The above behavior can be changed by adding modifiers to the format
1618     string item. A <code>-</code> (minus) modifier causes a minus to be logged if the
1619     respective item does not produce any output. In once-per-connection/request
1620     formats, it is also possible to use the <code>+</code> (plus) modifier. If an
1621     item with the plus modifier does not produce any output, the whole line is
1622     omitted.</p>
1623
1624     <p>A number as modifier can be used to assign a log severity level to a
1625     format item. The item will only be logged if the severity of the log
1626     message is not higher than the specified log severity level. The number can
1627     range from 1 (alert) over 4 (warn) and 7 (debug) to 15 (trace8).</p>
1628
1629     <p>For example, here's what would happen if you added modifiers to
1630     the <code>%{Referer}i</code> token, which logs the
1631     <code>Referer</code> request header.</p>
1632
1633     <table class="bordered"><tr class="header"><th>Modified Token</th><th>Meaning</th></tr>
1634 <tr>
1635     <td><code>%-{Referer}i</code></td>
1636     <td>Logs a <code>-</code> if <code>Referer</code> is not set.</td>
1637     </tr>
1638 <tr class="odd">
1639     <td><code>%+{Referer}i</code></td>
1640     <td>Omits the entire line if <code>Referer</code> is not set.</td>
1641     </tr>
1642 <tr>
1643     <td><code>%4{Referer}i</code></td>
1644     <td>Logs the <code>Referer</code> only if the log message severity
1645     is higher than 4.</td>
1646     </tr>
1647 </table>
1648
1649     <p>Some format string items accept additional parameters in braces.</p>
1650
1651     <table class="bordered"><tr class="header"><th>Format&nbsp;String</th> <th>Description</th></tr>
1652 <tr><td><code>%%</code></td>
1653         <td>The percent sign</td></tr>
1654 <tr class="odd"><td><code>%a</code></td>
1655         <td>Client IP address and port of the request</td></tr>
1656 <tr><td><code>%{c}a</code></td>
1657         <td>Underlying peer IP address and port of the connection (see the
1658             <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> module)</td></tr>
1659 <tr class="odd"><td><code>%A</code></td>
1660         <td>Local IP-address and port</td></tr>
1661 <tr><td><code>%{<em>name</em>}e</code></td>
1662         <td>Request environment variable <em>name</em></td></tr>
1663 <tr class="odd"><td><code>%E</code></td>
1664         <td>APR/OS error status code and string</td></tr>
1665 <tr><td><code>%F</code></td>
1666         <td>Source file name and line number of the log call</td></tr>
1667 <tr class="odd"><td><code>%{<em>name</em>}i</code></td>
1668         <td>Request header <em>name</em></td></tr>
1669 <tr><td><code>%k</code></td>
1670         <td>Number of keep-alive requests on this connection</td></tr>
1671 <tr class="odd"><td><code>%l</code></td>
1672         <td>Loglevel of the message</td></tr>
1673 <tr><td><code>%L</code></td>
1674         <td>Log ID of the request</td></tr>
1675 <tr class="odd"><td><code>%{c}L</code></td>
1676         <td>Log ID of the connection</td></tr>
1677 <tr><td><code>%{C}L</code></td>
1678         <td>Log ID of the connection if used in connection scope, empty otherwise</td></tr>
1679 <tr class="odd"><td><code>%m</code></td>
1680         <td>Name of the module logging the message</td></tr>
1681 <tr><td><code>%M</code></td>
1682         <td>The actual log message</td></tr>
1683 <tr class="odd"><td><code>%{<em>name</em>}n</code></td>
1684         <td>Request note <em>name</em></td></tr>
1685 <tr><td><code>%P</code></td>
1686         <td>Process ID of current process</td></tr>
1687 <tr class="odd"><td><code>%T</code></td>
1688         <td>Thread ID of current thread</td></tr>
1689 <tr><td><code>%{g}T</code></td>
1690         <td>System unique thread ID of current thread (the same ID as
1691             displayed by e.g. <code>top</code>; currently Linux only)</td></tr>
1692 <tr class="odd"><td><code>%t</code></td>
1693         <td>The current time</td></tr>
1694 <tr><td><code>%{u}t</code></td>
1695         <td>The current time including micro-seconds</td></tr>
1696 <tr class="odd"><td><code>%{cu}t</code></td>
1697         <td>The current time in compact ISO 8601 format, including
1698             micro-seconds</td></tr>
1699 <tr><td><code>%v</code></td>
1700         <td>The canonical <code class="directive"><a href="#servername">ServerName</a></code>
1701             of the current server.</td></tr>
1702 <tr class="odd"><td><code>%V</code></td>
1703         <td>The server name of the server serving the request according to the
1704             <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code>
1705             setting.</td></tr>
1706 <tr><td><code>\&nbsp;</code> (backslash space)</td>
1707         <td>Non-field delimiting space</td></tr>
1708 <tr class="odd"><td><code>%&nbsp;</code> (percent space)</td>
1709         <td>Field delimiter (no output)</td></tr>
1710 </table>
1711
1712     <p>The log ID format <code>%L</code> produces a unique id for a connection
1713     or request. This can be used to correlate which log lines belong to the
1714     same connection or request, which request happens on which connection.
1715     A <code>%L</code> format string is also available in
1716     <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> to allow to correlate access log entries
1717     with error log lines. If <code class="module"><a href="../mod/mod_unique_id.html">mod_unique_id</a></code> is loaded, its
1718     unique id will be used as log ID for requests.</p>
1719
1720     <pre class="prettyprint lang-config">#Example (default format for threaded MPMs)
1721 ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P:tid %T] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"</pre>
1722
1723
1724     <p>This would result in error messages such as:</p>
1725
1726     <div class="example"><p><code>
1727     [Thu May 12 08:28:57.652118 2011] [core:error] [pid 8777:tid 4326490112] [client ::1:58619] File does not exist: /usr/local/apache2/htdocs/favicon.ico
1728     </code></p></div>
1729
1730     <p>Notice that, as discussed above, some fields are omitted
1731     entirely because they are not defined.</p>
1732
1733     <pre class="prettyprint lang-config">#Example (similar to the 2.2.x format)
1734 ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"</pre>
1735
1736
1737     <pre class="prettyprint lang-config">#Advanced example with request/connection log IDs
1738 ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M"
1739 ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T"
1740 ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'"
1741 ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'"
1742 ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"</pre>
1743
1744
1745
1746 <h3>See also</h3>
1747 <ul>
1748 <li><code class="directive"><a href="#errorlog">ErrorLog</a></code></li>
1749 <li><code class="directive"><a href="#loglevel">LogLevel</a></code></li>
1750 <li><a href="../logs.html">Apache HTTP Server Log Files</a></li>
1751 </ul>
1752 </div>
1753 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1754 <div class="directive-section"><h2><a name="ExtendedStatus" id="ExtendedStatus">ExtendedStatus</a> <a name="extendedstatus" id="extendedstatus">Directive</a><a title="Permanent link" href="#extendedstatus" class="permalink">&para;</a></h2>
1755 <table class="directive">
1756 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keep track of extended status information for each
1757 request</td></tr>
1758 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtendedStatus On|Off</code></td></tr>
1759 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ExtendedStatus Off[*]</code></td></tr>
1760 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1761 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1762 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1763 </table>
1764     <p>This option tracks additional data per worker about the
1765     currently executing request and creates a utilization summary.
1766     You can see these variables during runtime by configuring
1767     <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.  Note that other modules may
1768     rely on this scoreboard.</p>
1769
1770     <p>This setting applies to the entire server and cannot be
1771     enabled or disabled on a virtualhost-by-virtualhost basis.
1772     The collection of extended status information can slow down
1773     the server.  Also note that this setting cannot be changed
1774     during a graceful restart.</p>
1775
1776     <div class="note">
1777     <p>Note that loading <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> will change
1778     the default behavior to ExtendedStatus On, while other
1779     third party modules may do the same.  Such modules rely on
1780     collecting detailed information about the state of all workers.
1781     The default is changed by <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> beginning
1782     with version 2.3.6. The previous default was always Off.</p>
1783     </div>
1784
1785
1786 </div>
1787 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1788 <div class="directive-section"><h2><a name="FileETag" id="FileETag">FileETag</a> <a name="fileetag" id="fileetag">Directive</a><a title="Permanent link" href="#fileetag" class="permalink">&para;</a></h2>
1789 <table class="directive">
1790 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File attributes used to create the ETag
1791 HTTP response header for static files</td></tr>
1792 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FileETag <var>component</var> ...</code></td></tr>
1793 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>FileETag MTime Size</code></td></tr>
1794 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1795 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1796 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1797 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1798 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The default used to be "INode&nbsp;MTime&nbsp;Size" in 2.3.14 and
1799 earlier.</td></tr>
1800 </table>
1801     <p>
1802     The <code class="directive">FileETag</code> directive configures the file
1803     attributes that are used to create the <code>ETag</code> (entity
1804     tag) response header field when the document is based on a static file.
1805     (The <code>ETag</code> value is used in cache management to save
1806     network bandwidth.) The
1807     <code class="directive">FileETag</code> directive allows you to choose
1808     which of these -- if any -- should be used. The recognized keywords are:
1809     </p>
1810
1811     <dl>
1812      <dt><strong>INode</strong></dt>
1813      <dd>The file's i-node number will be included in the calculation</dd>
1814      <dt><strong>MTime</strong></dt>
1815      <dd>The date and time the file was last modified will be included</dd>
1816      <dt><strong>Size</strong></dt>
1817      <dd>The number of bytes in the file will be included</dd>
1818      <dt><strong>All</strong></dt>
1819      <dd>All available fields will be used. This is equivalent to:
1820          <pre class="prettyprint lang-config">FileETag INode MTime Size</pre>
1821 </dd>
1822      <dt><strong>None</strong></dt>
1823      <dd>If a document is file-based, no <code>ETag</code> field will be
1824        included in the response</dd>
1825     </dl>
1826
1827     <p>The <code>INode</code>, <code>MTime</code>, and <code>Size</code>
1828     keywords may be prefixed with either <code>+</code> or <code>-</code>,
1829     which allow changes to be made to the default setting inherited
1830     from a broader scope. Any keyword appearing without such a prefix
1831     immediately and completely cancels the inherited setting.</p>
1832
1833     <p>If a directory's configuration includes
1834     <code>FileETag&nbsp;INode&nbsp;MTime&nbsp;Size</code>, and a
1835     subdirectory's includes <code>FileETag&nbsp;-INode</code>,
1836     the setting for that subdirectory (which will be inherited by
1837     any sub-subdirectories that don't override it) will be equivalent to
1838     <code>FileETag&nbsp;MTime&nbsp;Size</code>.</p>
1839     <div class="warning"><h3>Warning</h3>
1840     Do not change the default for directories or locations that have WebDAV
1841     enabled and use <code class="module"><a href="../mod/mod_dav_fs.html">mod_dav_fs</a></code> as a storage provider.
1842     <code class="module"><a href="../mod/mod_dav_fs.html">mod_dav_fs</a></code> uses <code>MTime&nbsp;Size</code>
1843     as a fixed format for <code>ETag</code> comparisons on conditional requests.
1844     These conditional requests will break if the <code>ETag</code> format is
1845     changed via <code class="directive">FileETag</code>.
1846     </div>
1847     <div class="note"><h3>Server Side Includes</h3>
1848     An ETag is not generated for responses parsed by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
1849     since the response entity can change without a change of the INode, MTime, or Size
1850     of the static file with embedded SSI directives.
1851     </div>
1852
1853
1854 </div>
1855 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1856 <div class="directive-section"><h2><a name="Files" id="Files">&lt;Files&gt;</a> <a name="files" id="files">Directive</a><a title="Permanent link" href="#files" class="permalink">&para;</a></h2>
1857 <table class="directive">
1858 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to matched
1859 filenames</td></tr>
1860 <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>
1861 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1862 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1863 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1864 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1865 </table>
1866     <p>The <code class="directive">&lt;Files&gt;</code> directive
1867     limits the scope of the enclosed directives by filename. It is comparable
1868     to the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
1869     and <code class="directive"><a href="#location">&lt;Location&gt;</a></code>
1870     directives. It should be matched with a <code>&lt;/Files&gt;</code>
1871     directive. The directives given within this section will be applied to
1872     any object with a basename (last component of filename) matching the
1873     specified filename. <code class="directive">&lt;Files&gt;</code>
1874     sections are processed in the order they appear in the
1875     configuration file, after the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections and
1876     <code>.htaccess</code> files are read, but before <code class="directive"><a href="#location">&lt;Location&gt;</a></code> sections. Note
1877     that <code class="directive">&lt;Files&gt;</code> can be nested
1878     inside <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections to restrict the
1879     portion of the filesystem they apply to.</p>
1880
1881     <p>The <var>filename</var> argument should include a filename, or
1882     a wild-card string, where <code>?</code> matches any single character,
1883     and <code>*</code> matches any sequences of characters.</p>
1884     <pre class="prettyprint lang-config">&lt;Files "cat.html"&gt;
1885     # Insert stuff that applies to cat.html here
1886 &lt;/Files&gt;
1887
1888 &lt;Files "?at.*"&gt;
1889     # This would apply to cat.html, bat.html, hat.php and so on.
1890 &lt;/Files&gt;</pre>
1891
1892     <p><a class="glossarylink" href="../glossary.html#regex" title="see glossary">Regular expressions</a>
1893     can also be used, with the addition of the
1894     <code>~</code> character. For example:</p>
1895
1896     <pre class="prettyprint lang-config">&lt;Files ~ "\.(gif|jpe?g|png)$"&gt;
1897     #...
1898 &lt;/Files&gt;</pre>
1899
1900
1901     <p>would match most common Internet graphics formats. <code class="directive"><a href="#filesmatch">&lt;FilesMatch&gt;</a></code> is preferred,
1902     however.</p>
1903
1904     <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
1905     <code>.htaccess</code> files. This allows users to control access to
1906     their own files, at a file-by-file level.</p>
1907
1908
1909 <h3>See also</h3>
1910 <ul>
1911 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1912     and &lt;Files&gt; sections work</a> for an explanation of how these
1913     different sections are combined when a request is received</li>
1914 </ul>
1915 </div>
1916 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1917 <div class="directive-section"><h2><a name="FilesMatch" id="FilesMatch">&lt;FilesMatch&gt;</a> <a name="filesmatch" id="filesmatch">Directive</a><a title="Permanent link" href="#filesmatch" class="permalink">&para;</a></h2>
1918 <table class="directive">
1919 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to regular-expression matched
1920 filenames</td></tr>
1921 <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>
1922 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1923 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1924 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1925 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1926 </table>
1927     <p>The <code class="directive">&lt;FilesMatch&gt;</code> directive
1928     limits the scope of the enclosed directives by filename, just as the
1929     <code class="directive"><a href="#files">&lt;Files&gt;</a></code> directive
1930     does. However, it accepts a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
1931     expression</a>. For example:</p>
1932
1933     <pre class="prettyprint lang-config">&lt;FilesMatch ".+\.(gif|jpe?g|png)$"&gt;
1934     # ...
1935 &lt;/FilesMatch&gt;</pre>
1936
1937
1938     <p>would match most common Internet graphics formats.</p>
1939
1940     <div class="note">The <code>.+</code> at the start of the regex ensures that
1941     files named <code>.png</code>, or <code>.gif</code>, for example,
1942     are not matched.</div>
1943
1944     <p>From 2.4.8 onwards, named groups and backreferences are captured and
1945     written to the environment with the corresponding name prefixed with
1946     "MATCH_" and in upper case. This allows elements of files to be referenced
1947     from within <a href="../expr.html">expressions</a> and modules like
1948     <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
1949     (unnamed) backreferences are ignored. Use named groups instead.</p>
1950
1951     <pre class="prettyprint lang-config">&lt;FilesMatch "^(?&lt;sitename&gt;[^/]+)"&gt;
1952     Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
1953 &lt;/FilesMatch&gt;</pre>
1954
1955
1956 <h3>See also</h3>
1957 <ul>
1958 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
1959     and &lt;Files&gt; sections work</a> for an explanation of how these
1960     different sections are combined when a request is received</li>
1961 </ul>
1962 </div>
1963 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1964 <div class="directive-section"><h2><a name="ForceType" id="ForceType">ForceType</a> <a name="forcetype" id="forcetype">Directive</a><a title="Permanent link" href="#forcetype" class="permalink">&para;</a></h2>
1965 <table class="directive">
1966 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be served with the specified
1967 media type in the HTTP Content-Type header field</td></tr>
1968 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceType <var>media-type</var>|None</code></td></tr>
1969 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
1970 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1971 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
1972 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
1973 </table>
1974     <p>When placed into an <code>.htaccess</code> file or a
1975     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>, or
1976     <code class="directive"><a href="#location">&lt;Location&gt;</a></code> or
1977     <code class="directive"><a href="#files">&lt;Files&gt;</a></code>
1978     section, this directive forces all matching files to be served
1979     with the content type identification given by
1980     <var>media-type</var>. For example, if you had a directory full of
1981     GIF files, but did not want to label them all with <code>.gif</code>,
1982     you might want to use:</p>
1983
1984     <pre class="prettyprint lang-config">ForceType image/gif</pre>
1985
1986
1987     <p>Note that this directive overrides other indirect media type
1988     associations defined in mime.types or via the
1989     <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code>.</p>
1990
1991     <p>You can also override more general
1992     <code class="directive">ForceType</code> settings
1993     by using the value of <code>None</code>:</p>
1994
1995     <pre class="prettyprint lang-config"># force all files to be image/gif:
1996 &lt;Location "/images"&gt;
1997   ForceType image/gif
1998 &lt;/Location&gt;
1999
2000 # but normal mime-type associations here:
2001 &lt;Location "/images/mixed"&gt;
2002   ForceType None
2003 &lt;/Location&gt;</pre>
2004
2005
2006     <p>This directive primarily overrides the content types generated for
2007     static files served out of the filesystem.  For resources other than
2008     static files, where the generator of the response typically specifies
2009     a Content-Type, this directive has no effect.</p>
2010
2011
2012     <div class="note"><h3>Note</h3>
2013     <p>If no handler is explicitly set for a request, the specified content
2014     type will also be used as the handler name. </p>
2015
2016     <p>When explicit directives such as
2017     <code class="directive"><a href="#sethandler">SetHandler</a></code> or
2018     <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> do not apply
2019     to the current request, the internal handler name normally set by those
2020     directives is instead set to the content type specified by this directive.
2021     </p>
2022     <p>
2023     This is a historical behavior that some third-party modules
2024     (such as mod_php) may look for a "synthetic" content type used only to
2025     signal the module to take responsibility for the matching request.
2026     </p>
2027
2028     <p>Configurations that rely on such "synthetic" types should be avoided.
2029     Additionally, configurations that restrict access to
2030     <code class="directive"><a href="#sethandler">SetHandler</a></code> or
2031     <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> should
2032     restrict access to this directive as well.</p>
2033     </div>
2034
2035
2036 </div>
2037 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2038 <div class="directive-section"><h2><a name="GprofDir" id="GprofDir">GprofDir</a> <a name="gprofdir" id="gprofdir">Directive</a><a title="Permanent link" href="#gprofdir" class="permalink">&para;</a></h2>
2039 <table class="directive">
2040 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory to write gmon.out profiling data to.  </td></tr>
2041 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>GprofDir <var>/tmp/gprof/</var>|<var>/tmp/gprof/</var>%</code></td></tr>
2042 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2043 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2044 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2045 </table>
2046     <p>When the server has been compiled with gprof profiling support,
2047     <code class="directive">GprofDir</code> causes <code>gmon.out</code> files to
2048     be written to the specified directory when the process exits.  If the
2049     argument ends with a percent symbol ('%'), subdirectories are created
2050     for each process id.</p>
2051
2052     <p>This directive currently only works with the <code class="module"><a href="../mod/prefork.html">prefork</a></code>
2053     MPM.</p>
2054
2055 </div>
2056 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2057 <div class="directive-section"><h2><a name="HostnameLookups" id="HostnameLookups">HostnameLookups</a> <a name="hostnamelookups" id="hostnamelookups">Directive</a><a title="Permanent link" href="#hostnamelookups" class="permalink">&para;</a></h2>
2058 <table class="directive">
2059 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables DNS lookups on client IP addresses</td></tr>
2060 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HostnameLookups On|Off|Double</code></td></tr>
2061 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>HostnameLookups Off</code></td></tr>
2062 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
2063 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2064 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2065 </table>
2066     <p>This directive enables DNS lookups so that host names can be
2067     logged (and passed to CGIs/SSIs in <code>REMOTE_HOST</code>).
2068     The value <code>Double</code> refers to doing double-reverse
2069     DNS lookup. That is, after a reverse lookup is performed, a forward
2070     lookup is then performed on that result. At least one of the IP
2071     addresses in the forward lookup must match the original
2072     address. (In "tcpwrappers" terminology this is called
2073     <code>PARANOID</code>.)</p>
2074
2075     <p>Regardless of the setting, when <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code> is
2076     used for controlling access by hostname, a double reverse lookup
2077     will be performed.  This is necessary for security. Note that the
2078     result of this double-reverse isn't generally available unless you
2079     set <code>HostnameLookups Double</code>. For example, if only
2080     <code>HostnameLookups On</code> and a request is made to an object
2081     that is protected by hostname restrictions, regardless of whether
2082     the double-reverse fails or not, CGIs will still be passed the
2083     single-reverse result in <code>REMOTE_HOST</code>.</p>
2084
2085     <p>The default is <code>Off</code> in order to save the network
2086     traffic for those sites that don't truly need the reverse
2087     lookups done. It is also better for the end users because they
2088     don't have to suffer the extra latency that a lookup entails.
2089     Heavily loaded sites should leave this directive
2090     <code>Off</code>, since DNS lookups can take considerable
2091     amounts of time. The utility <code class="program"><a href="../programs/logresolve.html">logresolve</a></code>, compiled by
2092     default to the <code>bin</code> subdirectory of your installation
2093     directory, can be used to look up host names from logged IP addresses
2094     offline.</p>
2095
2096     <p>Finally, if you have <a href="mod_authz_host.html#reqhost">hostname-based Require
2097     directives</a>, a hostname lookup will be performed regardless of
2098     the setting of <code>HostnameLookups</code>.</p>
2099
2100 </div>
2101 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2102 <div class="directive-section"><h2><a name="HttpProtocolOptions" id="HttpProtocolOptions">HttpProtocolOptions</a> <a name="httpprotocoloptions" id="httpprotocoloptions">Directive</a><a title="Permanent link" href="#httpprotocoloptions" class="permalink">&para;</a></h2>
2103 <table class="directive">
2104 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Modify restrictions on HTTP Request Messages</td></tr>
2105 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods]
2106  [Allow0.9|Require1.0]</code></td></tr>
2107 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>HttpProtocolOptions Strict LenientMethods Allow0.9</code></td></tr>
2108 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2109 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2110 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2111 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.2.32 or 2.4.24 and later</td></tr>
2112 </table>
2113     <p>This directive changes the rules applied to the HTTP Request Line
2114     (<a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">RFC 7230 §3.1.1</a>) and the HTTP Request Header Fields
2115     (<a href="https://tools.ietf.org/html/rfc7230#section-3.2">RFC 7230 §3.2</a>), which are now applied by default or using
2116     the <code>Strict</code> option. Due to legacy modules, applications or
2117     custom user-agents which must be deprecated the <code>Unsafe</code>
2118     option has been added to revert to the legacy behaviors.</p>
2119
2120     <p>These rules are applied prior to request processing,
2121     so must be configured at the global or default (first) matching
2122     virtual host section, by IP/port interface (and not by name)
2123     to be honored.</p>
2124
2125     <p>The directive accepts three parameters from the following list
2126        of choices, applying the default to the ones not specified:</p>
2127
2128     <dl>
2129     <dt>Strict|Unsafe</dt>
2130     <dd>
2131       <p>Prior to the introduction of this directive, the Apache HTTP Server
2132       request message parsers were tolerant of a number of forms of input
2133       which did not conform to the protocol.
2134       <a href="https://tools.ietf.org/html/rfc7230#section-9.4">RFC 7230 §9.4 Request Splitting</a> and
2135       <a href="https://tools.ietf.org/html/rfc7230#section-9.5">§9.5 Response Smuggling</a> call out only two of the potential
2136       risks of accepting non-conformant request messages, while
2137       <a href="https://tools.ietf.org/html/rfc7230#section-3.5">RFC 7230 §3.5</a> "Message Parsing Robustness" identify the
2138       risks of accepting obscure whitespace and request message formatting.
2139       As of the introduction of this directive, all grammar rules of the
2140       specification are enforced in the default <code>Strict</code> operating
2141       mode, and the strict whitespace suggested by section 3.5 is enforced
2142       and cannot be relaxed.</p>
2143
2144       <div class="warning"><h3>Security risks of Unsafe</h3>
2145         <p>Users are strongly cautioned against toggling the <code>Unsafe</code>
2146         mode of operation, particularly on outward-facing, publicly accessible
2147         server deployments.  If an interface is required for faulty monitoring
2148         or other custom service consumers running on an intranet, users should
2149         toggle the Unsafe option only on a specific virtual host configured
2150         to service their internal private network.</p>
2151       </div>
2152
2153       <div class="example"><h3>Example of a request leading to HTTP 400 with Strict mode</h3><p><code>
2154
2155         # Missing CRLF<br />
2156         GET / HTTP/1.0\n\n
2157       </code></p></div>
2158       <div class="warning"><h3>Command line tools and CRLF</h3>
2159         <p>Some tools need to be forced to use CRLF, otherwise httpd will return
2160         a HTTP 400 response like described in the above use case. For example,
2161         the <strong>OpenSSL s_client needs the -crlf parameter to work
2162         properly</strong>.</p>
2163         <p>The <code class="directive"><a href="../mod/mod_dumpio.html#dumpioinput">DumpIOInput</a></code> directive
2164         can help while reviewing the HTTP request to identify issues like the
2165         absence of CRLF.</p>
2166       </div>
2167     </dd>
2168     <dt>RegisteredMethods|LenientMethods</dt>
2169     <dd>
2170       <p><a href="https://tools.ietf.org/html/rfc7231#section-4.1">RFC 7231 §4.1</a> "Request Methods" "Overview" requires that
2171       origin servers shall respond with a HTTP 501 status code when an
2172       unsupported method is encountered in the request line.
2173       This already happens when the <code>LenientMethods</code> option is used,
2174       but administrators may wish to toggle the <code>RegisteredMethods</code>
2175       option and register any non-standard methods using the
2176       <code class="directive"><a href="#registerhttpmethod">RegisterHttpMethod</a></code>
2177       directive, particularly if the <code>Unsafe</code>
2178       option has been toggled.</p>
2179
2180       <div class="warning"><h3>Forward Proxy compatibility</h3>
2181         <p>The <code>RegisteredMethods</code> option should <strong>not</strong>
2182         be toggled for forward proxy hosts, as the methods supported by the
2183         origin servers are unknown to the proxy server.</p>
2184       </div>
2185
2186       <div class="example"><h3>Example of a request leading to HTTP 501 with LenientMethods mode</h3><p><code>
2187
2188         # Unknown HTTP method<br />
2189         WOW / HTTP/1.0\r\n\r\n<br /><br />
2190         # Lowercase HTTP method<br />
2191         get / HTTP/1.0\r\n\r\n<br />
2192       </code></p></div>
2193       </dd>
2194       <dt>Allow0.9|Require1.0</dt>
2195       <dd>
2196       <p><a href="https://tools.ietf.org/html/rfc2616#section-19.6">RFC 2616 §19.6</a> "Compatibility With Previous Versions" had
2197       encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230
2198       supersedes this with "The expectation to support HTTP/0.9 requests has
2199       been removed" and offers additional comments in
2200       <a href="https://tools.ietf.org/html/rfc7230#appendix-A">RFC 7230 Appendix A</a>. The <code>Require1.0</code> option allows
2201       the user to remove support of the default <code>Allow0.9</code> option's
2202       behavior.</p>
2203
2204       <div class="example"><h3>Example of a request leading to HTTP 400 with Require1.0 mode</h3><p><code>
2205
2206         # Unsupported HTTP version<br />
2207         GET /\r\n\r\n
2208       </code></p></div>
2209     </dd>
2210     </dl>
2211     <p>Reviewing the messages logged to the
2212     <code class="directive"><a href="#errorlog">ErrorLog</a></code>, configured with
2213     <code class="directive"><a href="#loglevel">LogLevel</a></code> <code>debug</code> level,
2214     can help identify such faulty requests along with their origin.
2215     Users should pay particular attention to the 400 responses in the access
2216     log for invalid requests which were unexpectedly rejected.</p>
2217
2218 </div>
2219 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2220 <div class="directive-section"><h2><a name="If" id="If">&lt;If&gt;</a> <a name="if" id="if">Directive</a><a title="Permanent link" href="#if" class="permalink">&para;</a></h2>
2221 <table class="directive">
2222 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if a condition is
2223 satisfied by a request at runtime</td></tr>
2224 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;If <var>expression</var>&gt; ... &lt;/If&gt;</code></td></tr>
2225 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2226 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2227 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2228 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2229 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Nested conditions are evaluated in 2.4.26 and later</td></tr>
2230 </table>
2231     <p>The <code class="directive">&lt;If&gt;</code> directive
2232     evaluates an expression at runtime, and applies the enclosed
2233     directives if and only if the expression evaluates to true.
2234     For example:</p>
2235
2236     <pre class="prettyprint lang-config">&lt;If "-z req('Host')"&gt;</pre>
2237
2238
2239     <p>would match HTTP/1.0 requests without a <var>Host:</var> header.
2240     Expressions may contain various shell-like operators for string
2241     comparison (<code>==</code>, <code>!=</code>, <code>&lt;</code>, ...),
2242     integer comparison (<code>-eq</code>, <code>-ne</code>, ...),
2243     and others (<code>-n</code>, <code>-z</code>, <code>-f</code>, ...).
2244     It is also possible to use regular expressions, </p>
2245
2246     <pre class="prettyprint lang-config">&lt;If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/"&gt;</pre>
2247
2248
2249     <p>shell-like pattern matches and many other operations. These operations
2250     can be done on request headers (<code>req</code>), environment variables
2251     (<code>env</code>), and a large number of other properties. The full
2252     documentation is available in <a href="../expr.html">Expressions in
2253     Apache HTTP Server</a>.</p>
2254
2255     <p>Only directives that support the <a href="directive-dict.html#Context">directory context</a> can be used within this configuration section.</p>
2256
2257     <div class="warning">
2258     Certain variables, such as <code>CONTENT_TYPE</code> and other
2259     response headers, are set after &lt;If&gt; conditions have already
2260     been evaluated, and so will not be available to use in this
2261     directive.
2262     </div>
2263
2264
2265 <h3>See also</h3>
2266 <ul>
2267 <li><a href="../expr.html">Expressions in Apache HTTP Server</a>,
2268 for a complete reference and more examples.</li>
2269 <li><code class="directive"><a href="#elseif">&lt;ElseIf&gt;</a></code></li>
2270 <li><code class="directive"><a href="#else">&lt;Else&gt;</a></code></li>
2271 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;,
2272     &lt;Files&gt; sections work</a> for an explanation of how these
2273     different sections are combined when a request is received.
2274     <code class="directive">&lt;If&gt;</code>,
2275     <code class="directive">&lt;ElseIf&gt;</code>, and
2276     <code class="directive">&lt;Else&gt;</code> are applied last.</li>
2277 </ul>
2278 </div>
2279 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2280 <div class="directive-section"><h2><a name="IfDefine" id="IfDefine">&lt;IfDefine&gt;</a> <a name="ifdefine" id="ifdefine">Directive</a><a title="Permanent link" href="#ifdefine" class="permalink">&para;</a></h2>
2281 <table class="directive">
2282 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that will be processed only
2283 if a test is true at startup</td></tr>
2284 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfDefine [!]<var>parameter-name</var>&gt; ...
2285     &lt;/IfDefine&gt;</code></td></tr>
2286 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2287 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2288 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2289 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2290 </table>
2291     <p>The <code>&lt;IfDefine <var>test</var>&gt;...&lt;/IfDefine&gt;
2292     </code> section is used to mark directives that are conditional. The
2293     directives within an <code class="directive">&lt;IfDefine&gt;</code>
2294     section are only processed if the <var>test</var> is true. If <var>
2295     test</var> is false, everything between the start and end markers is
2296     ignored.</p>
2297
2298     <p>The <var>test</var> in the <code class="directive">&lt;IfDefine&gt;</code> section directive can be one of two forms:</p>
2299
2300     <ul>
2301       <li><var>parameter-name</var></li>
2302
2303       <li><code>!</code><var>parameter-name</var></li>
2304     </ul>
2305
2306     <p>In the former case, the directives between the start and end
2307     markers are only processed if the parameter named
2308     <var>parameter-name</var> is defined. The second format reverses
2309     the test, and only processes the directives if
2310     <var>parameter-name</var> is <strong>not</strong> defined.</p>
2311
2312     <p>The <var>parameter-name</var> argument is a define as given on the
2313     <code class="program"><a href="../programs/httpd.html">httpd</a></code> command line via <code>-D<var>parameter</var>
2314     </code> at the time the server was started or by the <code class="directive"><a href="#define">Define</a></code> directive.</p>
2315
2316     <p><code class="directive">&lt;IfDefine&gt;</code> sections are
2317     nest-able, which can be used to implement simple
2318     multiple-parameter tests. Example:</p>
2319
2320     <div class="example"><p><code>httpd -DReverseProxy -DUseCache -DMemCache ...</code></p></div>
2321     <pre class="prettyprint lang-config">&lt;IfDefine ReverseProxy&gt;
2322   LoadModule proxy_module   modules/mod_proxy.so
2323   LoadModule proxy_http_module   modules/mod_proxy_http.so
2324   &lt;IfDefine UseCache&gt;
2325     LoadModule cache_module   modules/mod_cache.so
2326     &lt;IfDefine MemCache&gt;
2327       LoadModule mem_cache_module   modules/mod_mem_cache.so
2328     &lt;/IfDefine&gt;
2329     &lt;IfDefine !MemCache&gt;
2330       LoadModule cache_disk_module   modules/mod_cache_disk.so
2331     &lt;/IfDefine&gt;
2332   &lt;/IfDefine&gt;
2333 &lt;/IfDefine&gt;</pre>
2334
2335
2336 </div>
2337 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2338 <div class="directive-section"><h2><a name="IfDirective" id="IfDirective">&lt;IfDirective&gt;</a> <a name="ifdirective" id="ifdirective">Directive</a><a title="Permanent link" href="#ifdirective" class="permalink">&para;</a></h2>
2339 <table class="directive">
2340 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that are processed conditional on the
2341 presence or absence of a specific directive</td></tr>
2342 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfDirective [!]<var>directive-name</var>&gt; ...
2343     &lt;/IfDirective&gt;</code></td></tr>
2344 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2345 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2346 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2347 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2348 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in 2.4.34 and later</td></tr>
2349 </table>
2350     <p>The <code>&lt;IfDirective <var>test</var>&gt;...&lt;/IfDirective&gt;</code>
2351     section is used to mark directives that are conditional on the presence of
2352     a specific directive. The directives within an <code class="directive">&lt;IfDirective&gt;</code> section are only processed if the <var>test</var>
2353     is true. If <var>test</var> is false, everything between the start and
2354     end markers is ignored.</p>
2355
2356     <p>The <var>test</var> in the <code class="directive">&lt;IfDirective&gt;</code> section can be one of two forms:</p>
2357
2358     <ul>
2359       <li><var>directive-name</var></li>
2360
2361       <li>!<var>directive-name</var></li>
2362     </ul>
2363
2364     <p>In the former case, the directives between the start and end
2365     markers are only processed if a directive of the given name is
2366     available at the time of processing.  The second format reverses the test,
2367     and only processes the directives if <var>directive-name</var> is
2368     <strong>not</strong> available.</p>
2369
2370     <div class="note">This section should only be used if you need to have one
2371     configuration file that works across multiple versions of
2372     <code class="program"><a href="../programs/httpd.html">httpd</a></code>, regardless of whether a particular
2373     directive is available. In normal operation, directives need not
2374     be placed in <code class="directive">&lt;IfDirective&gt;</code>
2375     sections.</div>
2376
2377 <h3>See also</h3>
2378 <ul>
2379 <li><code class="directive"><a href="#ifsection">&lt;IfSection&gt;</a></code></li>
2380 </ul>
2381 </div>
2382 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2383 <div class="directive-section"><h2><a name="IfFile" id="IfFile">&lt;IfFile&gt;</a> <a name="iffile" id="iffile">Directive</a><a title="Permanent link" href="#iffile" class="permalink">&para;</a></h2>
2384 <table class="directive">
2385 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that will be processed only
2386 if file exists at startup</td></tr>
2387 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfFile [!]<var>parameter-name</var>&gt; ...
2388     &lt;/IfFile&gt;</code></td></tr>
2389 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2390 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2391 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2392 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2393 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in 2.4.34 and later</td></tr>
2394 </table>
2395     <p>The <code>&lt;IfFile <var>filename</var>&gt;...&lt;/IfFile&gt;
2396     </code> section is used to mark directives that are conditional on
2397     the existence of a file on disk. The directives within an
2398     <code class="directive">&lt;IfFile&gt;</code> section are only
2399     processed if <var>filename</var> exists. If <var>filename</var>
2400     doesn't exist, everything between the start and end markers is
2401     ignored. <var>filename</var> can be an absolute path or a path
2402     relative to the server root.</p>
2403
2404     <p>The <var>filename</var> in the <code class="directive">&lt;IfFile&gt;</code> section directive can take the same forms as the
2405     <var>test</var> variable in the <code class="directive"><a href="#ifdefine">&lt;IfDefine&gt;</a></code> section, i.e. the test can be negated if the <code>
2406     !</code> character is placed directly before <var>filename</var>.
2407     </p>
2408
2409     <p>If a relative <var>filename</var> is supplied, the check is
2410     <code class="directive"><a href="#serverroot">ServerRoot</a></code> relative. In the case where
2411     this directive occurs before the <code class="directive"><a href="#serverroot">ServerRoot</a></code>,
2412     the path will be checked relative to the compiled-in server root or
2413     the server root passed in on the command line via the <code>-d</code>
2414     parameter.</p>
2415
2416     <div class="warning"><h3>Warning</h3>
2417     In 2.4.34, it is not possible to specify a <var>filename</var>
2418     with surrounding quotes. This would generate a parsing error at start-up.
2419     The main impact is that filenames with spaces can't be used.
2420     This behavior is fixed in 2.4.35.</div>
2421
2422
2423 </div>
2424 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2425 <div class="directive-section"><h2><a name="IfModule" id="IfModule">&lt;IfModule&gt;</a> <a name="ifmodule" id="ifmodule">Directive</a><a title="Permanent link" href="#ifmodule" class="permalink">&para;</a></h2>
2426 <table class="directive">
2427 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that are processed conditional on the
2428 presence or absence of a specific module</td></tr>
2429 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfModule [!]<var>module-file</var>|<var>module-identifier</var>&gt; ...
2430     &lt;/IfModule&gt;</code></td></tr>
2431 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2432 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2433 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2434 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2435 </table>
2436     <p>The <code>&lt;IfModule <var>test</var>&gt;...&lt;/IfModule&gt;</code>
2437     section is used to mark directives that are conditional on the presence of
2438     a specific module. The directives within an <code class="directive">&lt;IfModule&gt;</code> section are only processed if the <var>test</var>
2439     is true. If <var>test</var> is false, everything between the start and
2440     end markers is ignored.</p>
2441
2442     <p>The <var>test</var> in the <code class="directive">&lt;IfModule&gt;</code> section directive can be one of two forms:</p>
2443
2444     <ul>
2445       <li><var>module</var></li>
2446
2447       <li>!<var>module</var></li>
2448     </ul>
2449
2450     <p>In the former case, the directives between the start and end
2451     markers are only processed if the module named <var>module</var>
2452     is included in Apache httpd -- either compiled in or
2453     dynamically loaded using <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>. The second format reverses the test,
2454     and only processes the directives if <var>module</var> is
2455     <strong>not</strong> included.</p>
2456
2457     <p>The <var>module</var> argument can be either the module identifier or
2458     the file name of the module, at the time it was compiled.  For example,
2459     <code>rewrite_module</code> is the identifier and
2460     <code>mod_rewrite.c</code> is the file name. If a module consists of
2461     several source files, use the name of the file containing the string
2462     <code>STANDARD20_MODULE_STUFF</code>.</p>
2463
2464     <p><code class="directive">&lt;IfModule&gt;</code> sections are
2465     nest-able, which can be used to implement simple multiple-module
2466     tests.</p>
2467
2468     <div class="note">This section should only be used if you need to have one
2469     configuration file that works whether or not a specific module
2470     is available. In normal operation, directives need not be
2471     placed in <code class="directive">&lt;IfModule&gt;</code>
2472     sections.</div>
2473
2474 </div>
2475 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2476 <div class="directive-section"><h2><a name="IfSection" id="IfSection">&lt;IfSection&gt;</a> <a name="ifsection" id="ifsection">Directive</a><a title="Permanent link" href="#ifsection" class="permalink">&para;</a></h2>
2477 <table class="directive">
2478 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that are processed conditional on the
2479 presence or absence of a specific section directive</td></tr>
2480 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;IfSection [!]<var>section-name</var>&gt; ...
2481     &lt;/IfSection&gt;</code></td></tr>
2482 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2483 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2484 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2485 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2486 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in 2.4.34 and later</td></tr>
2487 </table>
2488     <p>The <code>&lt;IfSection
2489     <var>test</var>&gt;...&lt;/IfSection&gt;</code> section is used
2490     to mark directives that are conditional on the presence of a
2491     specific section directive.  A section directive is any directive
2492     such as <code class="directive">&lt;VirtualHost&gt;</code> which
2493     encloses other directives, and has a directive name with a leading
2494     "&lt;".</p>
2495
2496     <p>The directives within an <code class="directive">&lt;IfSection&gt;</code> section are only processed if the <var>test</var>
2497     is true. If <var>test</var> is false, everything between the start and
2498     end markers is ignored.</p>
2499
2500     <p>The <var>section-name</var> must be specified without either
2501     the leading "&lt;" or closing "&gt;".  The <var>test</var> in the
2502     <code class="directive">&lt;IfSection&gt;</code> section can be one
2503     of two forms:</p>
2504
2505     <ul>
2506       <li><var>section-name</var></li>
2507       <li>!<var>section-name</var></li>
2508     </ul>
2509
2510     <p>In the former case, the directives between the start and end
2511     markers are only processed if a section directive of the given
2512     name is available at the time of processing.  The second format
2513     reverses the test, and only processes the directives if
2514     <var>section-name</var> is <strong>not</strong> an available
2515     section directive.</p>
2516
2517     <p>For example:</p>
2518
2519     <pre class="prettyprint lang-config">&lt;IfSection VirtualHost&gt;
2520    ...
2521 &lt;/IfSection&gt;</pre>
2522
2523
2524     <div class="note">This section should only be used if you need to have one
2525     configuration file that works across multiple versions of <code class="program"><a href="../programs/httpd.html">httpd</a></code>,
2526     regardless of whether a particular section directive is
2527     available. In normal operation, directives need not be placed in
2528     <code class="directive">&lt;IfSection&gt;</code> sections.</div>
2529
2530 <h3>See also</h3>
2531 <ul>
2532 <li><code class="directive"><a href="#ifdirective">&lt;IfDirective&gt;</a></code></li>
2533 </ul>
2534 </div>
2535 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2536 <div class="directive-section"><h2><a name="Include" id="Include">Include</a> <a name="include" id="include">Directive</a><a title="Permanent link" href="#include" class="permalink">&para;</a></h2>
2537 <table class="directive">
2538 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Includes other configuration files from within
2539 the server configuration files</td></tr>
2540 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Include <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></code></td></tr>
2541 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
2542 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2543 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2544 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Directory
2545 wildcard matching available in 2.3.6 and later</td></tr>
2546 </table>
2547     <p>This directive allows inclusion of other configuration files
2548     from within the server configuration files.</p>
2549
2550     <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used
2551     in the filename or directory parts of the path to include several files
2552     at once, in alphabetical order. In addition, if
2553     <code class="directive">Include</code> points to a directory, rather than a file,
2554     Apache httpd will read all files in that directory and any subdirectory.
2555     However, including entire directories is not recommended, because it is
2556     easy to accidentally leave temporary files in a directory that can cause
2557     <code class="program"><a href="../programs/httpd.html">httpd</a></code> to fail. Instead, we encourage you to use the
2558     wildcard syntax shown below, to include files that match a particular
2559     pattern, such as *.conf, for example.</p>
2560
2561     <p>The <code class="directive"><a href="#include">Include</a></code> directive will
2562     <strong>fail with an error</strong> if a wildcard expression does not
2563     match any file. The <code class="directive"><a href="#includeoptional">IncludeOptional</a></code>
2564     directive can be used if non-matching wildcards should be ignored.</p>
2565
2566     <p>The file path specified may be an absolute path, or may be relative
2567     to the <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory.</p>
2568
2569     <p>Examples:</p>
2570
2571     <pre class="prettyprint lang-config">Include /usr/local/apache2/conf/ssl.conf
2572 Include /usr/local/apache2/conf/vhosts/*.conf</pre>
2573
2574
2575     <p>Or, providing paths relative to your <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory:</p>
2576
2577     <pre class="prettyprint lang-config">Include conf/ssl.conf
2578 Include conf/vhosts/*.conf</pre>
2579
2580
2581     <p>Wildcards may be included in the directory or file portion of the
2582     path. This example will fail if there is no subdirectory in conf/vhosts
2583     that contains at least one *.conf file:</p>
2584
2585     <pre class="prettyprint lang-config">Include conf/vhosts/*/*.conf</pre>
2586
2587
2588     <p>Alternatively, the following command will just be ignored in case of
2589     missing files or directories:</p>
2590
2591     <pre class="prettyprint lang-config">IncludeOptional conf/vhosts/*/*.conf</pre>
2592
2593
2594
2595 <h3>See also</h3>
2596 <ul>
2597 <li><code class="directive"><a href="#includeoptional">IncludeOptional</a></code></li>
2598 <li><code class="program"><a href="../programs/apachectl.html">apachectl</a></code></li>
2599 </ul>
2600 </div>
2601 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2602 <div class="directive-section"><h2><a name="IncludeOptional" id="IncludeOptional">IncludeOptional</a> <a name="includeoptional" id="includeoptional">Directive</a><a title="Permanent link" href="#includeoptional" class="permalink">&para;</a></h2>
2603 <table class="directive">
2604 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Includes other configuration files from within
2605 the server configuration files</td></tr>
2606 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>IncludeOptional <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></code></td></tr>
2607 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
2608 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2609 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2610 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in 2.3.6 and later. Not existent file paths without wildcards
2611                do not cause SyntaxError after 2.4.30</td></tr>
2612 </table>
2613     <p>This directive allows inclusion of other configuration files
2614     from within the server configuration files. It works identically to the
2615     <code class="directive"><a href="#include">Include</a></code> directive, but it will be
2616     silently ignored (instead of causing an error) if wildcards are used and
2617     they do not match any file or directory or if a file path does not exist
2618     on the file system.</p>
2619
2620 <h3>See also</h3>
2621 <ul>
2622 <li><code class="directive"><a href="#include">Include</a></code></li>
2623 <li><code class="program"><a href="../programs/apachectl.html">apachectl</a></code></li>
2624 </ul>
2625 </div>
2626 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2627 <div class="directive-section"><h2><a name="KeepAlive" id="KeepAlive">KeepAlive</a> <a name="keepalive" id="keepalive">Directive</a><a title="Permanent link" href="#keepalive" class="permalink">&para;</a></h2>
2628 <table class="directive">
2629 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables HTTP persistent connections</td></tr>
2630 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAlive On|Off</code></td></tr>
2631 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAlive On</code></td></tr>
2632 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2633 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2634 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2635 </table>
2636     <p>The Keep-Alive extension to HTTP/1.0 and the persistent
2637     connection feature of HTTP/1.1 provide long-lived HTTP sessions
2638     which allow multiple requests to be sent over the same TCP
2639     connection. In some cases this has been shown to result in an
2640     almost 50% speedup in latency times for HTML documents with
2641     many images. To enable Keep-Alive connections, set
2642     <code>KeepAlive On</code>.</p>
2643
2644     <p>For HTTP/1.0 clients, Keep-Alive connections will only be
2645     used if they are specifically requested by a client. In
2646     addition, a Keep-Alive connection with an HTTP/1.0 client can
2647     only be used when the length of the content is known in
2648     advance. This implies that dynamic content such as CGI output,
2649     SSI pages, and server-generated directory listings will
2650     generally not use Keep-Alive connections to HTTP/1.0 clients.
2651     For HTTP/1.1 clients, persistent connections are the default
2652     unless otherwise specified. If the client requests it, chunked
2653     encoding will be used in order to send content of unknown
2654     length over persistent connections.</p>
2655
2656     <p>When a client uses a Keep-Alive connection, it will be counted
2657     as a single "request" for the <code class="directive"><a href="../mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code> directive, regardless
2658     of how many requests are sent using the connection.</p>
2659
2660 <h3>See also</h3>
2661 <ul>
2662 <li><code class="directive"><a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></code></li>
2663 </ul>
2664 </div>
2665 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2666 <div class="directive-section"><h2><a name="KeepAliveTimeout" id="KeepAliveTimeout">KeepAliveTimeout</a> <a name="keepalivetimeout" id="keepalivetimeout">Directive</a><a title="Permanent link" href="#keepalivetimeout" class="permalink">&para;</a></h2>
2667 <table class="directive">
2668 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for subsequent
2669 requests on a persistent connection</td></tr>
2670 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAliveTimeout <var>num</var>[ms]</code></td></tr>
2671 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAliveTimeout 5</code></td></tr>
2672 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2673 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2674 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2675 </table>
2676     <p>The number of seconds Apache httpd will wait for a subsequent
2677     request before closing the connection. By adding a postfix of ms the
2678     timeout can be also set in milliseconds. Once a request has been
2679     received, the timeout value specified by the
2680     <code class="directive"><a href="#timeout">Timeout</a></code> directive applies.</p>
2681
2682     <p>Setting <code class="directive">KeepAliveTimeout</code> to a high value
2683     may cause performance problems in heavily loaded servers. The
2684     higher the timeout, the more server processes will be kept
2685     occupied waiting on connections with idle clients.</p>
2686
2687     <p>If <code class="directive">KeepAliveTimeout</code> is <strong>not</strong>
2688     set for a name-based virtual host, the value of the first defined
2689     virtual host best matching the local IP and port will be used.</p>
2690
2691 </div>
2692 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2693 <div class="directive-section"><h2><a name="Limit" id="Limit">&lt;Limit&gt;</a> <a name="limit" id="limit">Directive</a><a title="Permanent link" href="#limit" class="permalink">&para;</a></h2>
2694 <table class="directive">
2695 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict enclosed access controls to only certain HTTP
2696 methods</td></tr>
2697 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Limit <var>method</var> [<var>method</var>] ... &gt; ...
2698     &lt;/Limit&gt;</code></td></tr>
2699 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
2700 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig, Limit</td></tr>
2701 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2702 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2703 </table>
2704     <p>Access controls are normally effective for
2705     <strong>all</strong> access methods, and this is the usual
2706     desired behavior. <strong>In the general case, access control
2707     directives should not be placed within a
2708     <code class="directive">&lt;Limit&gt;</code> section.</strong></p>
2709
2710     <p>The purpose of the <code class="directive">&lt;Limit&gt;</code>
2711     directive is to restrict the effect of the access controls to the
2712     nominated HTTP methods. For all other methods, the access
2713     restrictions that are enclosed in the <code class="directive">&lt;Limit&gt;</code> bracket <strong>will have no
2714     effect</strong>. The following example applies the access control
2715     only to the methods <code>POST</code>, <code>PUT</code>, and
2716     <code>DELETE</code>, leaving all other methods unprotected:</p>
2717
2718     <pre class="prettyprint lang-config">&lt;Limit POST PUT DELETE&gt;
2719   Require valid-user
2720 &lt;/Limit&gt;</pre>
2721
2722
2723     <p>The method names listed can be one or more of: <code>GET</code>,
2724     <code>POST</code>, <code>PUT</code>, <code>DELETE</code>,
2725     <code>CONNECT</code>, <code>OPTIONS</code>,
2726     <code>PATCH</code>, <code>PROPFIND</code>, <code>PROPPATCH</code>,
2727     <code>MKCOL</code>, <code>COPY</code>, <code>MOVE</code>,
2728     <code>LOCK</code>, and <code>UNLOCK</code>. <strong>The method name is
2729     case-sensitive.</strong> If <code>GET</code> is used, it will also
2730     restrict <code>HEAD</code> requests. The <code>TRACE</code> method
2731     cannot be limited (see <code class="directive"><a href="#traceenable">TraceEnable</a></code>).</p>
2732
2733     <div class="warning">A <code class="directive"><a href="#limitexcept">&lt;LimitExcept&gt;</a></code> section should always be
2734     used in preference to a <code class="directive">&lt;Limit&gt;</code>
2735     section when restricting access, since a <code class="directive"><a href="#limitexcept">&lt;LimitExcept&gt;</a></code> section provides protection
2736     against arbitrary methods.</div>
2737
2738     <p>The <code class="directive">&lt;Limit&gt;</code> and
2739     <code class="directive"><a href="#limitexcept">&lt;LimitExcept&gt;</a></code>
2740     directives may be nested.  In this case, each successive level of
2741     <code class="directive">&lt;Limit&gt;</code> or <code class="directive"><a href="#limitexcept">&lt;LimitExcept&gt;</a></code> directives must
2742     further restrict the set of methods to which access controls apply.</p>
2743
2744     <div class="warning">When using
2745     <code class="directive">&lt;Limit&gt;</code> or
2746     <code class="directive">&lt;LimitExcept&gt;</code> directives with
2747     the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive,
2748     note that the first <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
2749     to succeed authorizes the request, regardless of the presence of other
2750     <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directives.</div>
2751
2752     <p>For example, given the following configuration, all users will
2753     be authorized for <code>POST</code> requests, and the
2754     <code>Require group editors</code> directive will be ignored
2755     in all cases:</p>
2756
2757     <pre class="prettyprint lang-config">&lt;LimitExcept GET&gt;
2758   Require valid-user
2759 &lt;/LimitExcept&gt;
2760 &lt;Limit POST&gt;
2761   Require group editors
2762 &lt;/Limit&gt;</pre>
2763
2764
2765 </div>
2766 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2767 <div class="directive-section"><h2><a name="LimitExcept" id="LimitExcept">&lt;LimitExcept&gt;</a> <a name="limitexcept" id="limitexcept">Directive</a><a title="Permanent link" href="#limitexcept" class="permalink">&para;</a></h2>
2768 <table class="directive">
2769 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict access controls to all HTTP methods
2770 except the named ones</td></tr>
2771 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;LimitExcept <var>method</var> [<var>method</var>] ... &gt; ...
2772     &lt;/LimitExcept&gt;</code></td></tr>
2773 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
2774 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig, Limit</td></tr>
2775 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2776 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2777 </table>
2778     <p><code class="directive">&lt;LimitExcept&gt;</code> and
2779     <code>&lt;/LimitExcept&gt;</code> are used to enclose
2780     a group of access control directives which will then apply to any
2781     HTTP access method <strong>not</strong> listed in the arguments;
2782     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
2783     both standard and nonstandard/unrecognized methods. See the
2784     documentation for <code class="directive"><a href="#limit">&lt;Limit&gt;</a></code> for more details.</p>
2785
2786     <p>For example:</p>
2787
2788     <pre class="prettyprint lang-config">&lt;LimitExcept POST GET&gt;
2789   Require valid-user
2790 &lt;/LimitExcept&gt;</pre>
2791
2792
2793
2794 </div>
2795 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2796 <div class="directive-section"><h2><a name="LimitInternalRecursion" id="LimitInternalRecursion">LimitInternalRecursion</a> <a name="limitinternalrecursion" id="limitinternalrecursion">Directive</a><a title="Permanent link" href="#limitinternalrecursion" class="permalink">&para;</a></h2>
2797 <table class="directive">
2798 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine maximum number of internal redirects and nested
2799 subrequests</td></tr>
2800 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitInternalRecursion <var>number</var> [<var>number</var>]</code></td></tr>
2801 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitInternalRecursion 10</code></td></tr>
2802 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2803 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2804 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2805 </table>
2806     <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
2807     redirects the original request to a CGI script. A subrequest is Apache httpd's
2808     mechanism to find out what would happen for some URI if it were requested.
2809     For example, <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> uses subrequests to look for the
2810     files listed in the <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
2811     directive.</p>
2812
2813     <p><code class="directive">LimitInternalRecursion</code> prevents the server
2814     from crashing when entering an infinite loop of internal redirects or
2815     subrequests. Such loops are usually caused by misconfigurations.</p>
2816
2817     <p>The directive stores two different limits, which are evaluated on
2818     per-request basis. The first <var>number</var> is the maximum number of
2819     internal redirects that may follow each other. The second <var>number</var>
2820     determines how deeply subrequests may be nested. If you specify only one
2821     <var>number</var>, it will be assigned to both limits.</p>
2822
2823     <pre class="prettyprint lang-config">LimitInternalRecursion 5</pre>
2824
2825
2826 </div>
2827 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2828 <div class="directive-section"><h2><a name="LimitRequestBody" id="LimitRequestBody">LimitRequestBody</a> <a name="limitrequestbody" id="limitrequestbody">Directive</a><a title="Permanent link" href="#limitrequestbody" class="permalink">&para;</a></h2>
2829 <table class="directive">
2830 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restricts the total size of the HTTP request body sent
2831 from the client</td></tr>
2832 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestBody <var>bytes</var></code></td></tr>
2833 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestBody 0</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>All</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>This directive specifies the number of <var>bytes</var> from 0
2840     (meaning unlimited) to 2147483647 (2GB) that are allowed in a
2841     request body. See the note below for the limited applicability
2842     to proxy requests.</p>
2843
2844     <p>The <code class="directive">LimitRequestBody</code> directive allows
2845     the user to set a limit on the allowed size of an HTTP request
2846     message body within the context in which the directive is given
2847     (server, per-directory, per-file or per-location). If the client
2848     request exceeds that limit, the server will return an error
2849     response instead of servicing the request. The size of a normal
2850     request message body will vary greatly depending on the nature of
2851     the resource and the methods allowed on that resource. CGI scripts
2852     typically use the message body for retrieving form information.
2853     Implementations of the <code>PUT</code> method will require
2854     a value at least as large as any representation that the server
2855     wishes to accept for that resource.</p>
2856
2857     <p>This directive gives the server administrator greater
2858     control over abnormal client request behavior, which may be
2859     useful for avoiding some forms of denial-of-service
2860     attacks.</p>
2861
2862     <p>If, for example, you are permitting file upload to a particular
2863     location and wish to limit the size of the uploaded file to 100K,
2864     you might use the following directive:</p>
2865
2866     <pre class="prettyprint lang-config">LimitRequestBody 102400</pre>
2867
2868
2869     <div class="note"><p>For a full description of how this directive is interpreted by
2870     proxy requests, see the <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> documentation.</p>
2871     </div>
2872
2873
2874 </div>
2875 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2876 <div class="directive-section"><h2><a name="LimitRequestFields" id="LimitRequestFields">LimitRequestFields</a> <a name="limitrequestfields" id="limitrequestfields">Directive</a><a title="Permanent link" href="#limitrequestfields" class="permalink">&para;</a></h2>
2877 <table class="directive">
2878 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of HTTP request header fields that
2879 will be accepted from the client</td></tr>
2880 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFields <var>number</var></code></td></tr>
2881 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFields 100</code></td></tr>
2882 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2883 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2884 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2885 </table>
2886     <p><var>Number</var> is an integer from 0 (meaning unlimited) to
2887     32767. The default value is defined by the compile-time
2888     constant <code>DEFAULT_LIMIT_REQUEST_FIELDS</code> (100 as
2889     distributed).</p>
2890
2891     <p>The <code class="directive">LimitRequestFields</code> directive allows
2892     the server administrator to modify the limit on the number of
2893     request header fields allowed in an HTTP request. A server needs
2894     this value to be larger than the number of fields that a normal
2895     client request might include. The number of request header fields
2896     used by a client rarely exceeds 20, but this may vary among
2897     different client implementations, often depending upon the extent
2898     to which a user has configured their browser to support detailed
2899     content negotiation. Optional HTTP extensions are often expressed
2900     using request header fields.</p>
2901
2902     <p>This directive gives the server administrator greater
2903     control over abnormal client request behavior, which may be
2904     useful for avoiding some forms of denial-of-service attacks.
2905     The value should be increased if normal clients see an error
2906     response from the server that indicates too many fields were
2907     sent in the request.</p>
2908
2909     <p>For example:</p>
2910
2911     <pre class="prettyprint lang-config">LimitRequestFields 50</pre>
2912
2913
2914      <div class="warning"><h3>Warning</h3>
2915      <p> When name-based virtual hosting is used, the value for this
2916      directive is taken from the default (first-listed) virtual host for the
2917      local IP and port combination.</p>
2918      </div>
2919
2920
2921 </div>
2922 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2923 <div class="directive-section"><h2><a name="LimitRequestFieldSize" id="LimitRequestFieldSize">LimitRequestFieldSize</a> <a name="limitrequestfieldsize" id="limitrequestfieldsize">Directive</a><a title="Permanent link" href="#limitrequestfieldsize" class="permalink">&para;</a></h2>
2924 <table class="directive">
2925 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of the HTTP request header allowed from the
2926 client</td></tr>
2927 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFieldSize <var>bytes</var></code></td></tr>
2928 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFieldSize 8190</code></td></tr>
2929 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2930 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2931 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2932 </table>
2933     <p>This directive specifies the number of <var>bytes</var>
2934     that will be allowed in an HTTP request header.</p>
2935
2936     <p>The <code class="directive">LimitRequestFieldSize</code> directive
2937     allows the server administrator to set the limit
2938     on the allowed size of an HTTP request header field. A server
2939     needs this value to be large enough to hold any one header field
2940     from a normal client request. The size of a normal request header
2941     field will vary greatly among different client implementations,
2942     often depending upon the extent to which a user has configured
2943     their browser to support detailed content negotiation. SPNEGO
2944     authentication headers can be up to 12392 bytes.</p>
2945
2946     <p>This directive gives the server administrator greater
2947     control over abnormal client request behavior, which may be
2948     useful for avoiding some forms of denial-of-service attacks.</p>
2949
2950     <p>For example:</p>
2951
2952     <pre class="prettyprint lang-config">LimitRequestFieldSize 4094</pre>
2953
2954
2955     <div class="note">Under normal conditions, the value should not be changed from
2956     the default.</div>
2957
2958     <div class="warning"><h3>Warning</h3>
2959     <p> When name-based virtual hosting is used, the value for this
2960     directive is taken from the default (first-listed) virtual host best
2961     matching the current IP address and port combination.</p>
2962     </div>
2963
2964 </div>
2965 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
2966 <div class="directive-section"><h2><a name="LimitRequestLine" id="LimitRequestLine">LimitRequestLine</a> <a name="limitrequestline" id="limitrequestline">Directive</a><a title="Permanent link" href="#limitrequestline" class="permalink">&para;</a></h2>
2967 <table class="directive">
2968 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit the size of the HTTP request line that will be accepted
2969 from the client</td></tr>
2970 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestLine <var>bytes</var></code></td></tr>
2971 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestLine 8190</code></td></tr>
2972 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2973 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
2974 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
2975 </table>
2976     <p>This directive sets the number of <var>bytes</var> that will be
2977     allowed on the HTTP request-line.</p>
2978
2979     <p>The <code class="directive">LimitRequestLine</code> directive allows
2980     the server administrator to set the limit on the allowed size
2981     of a client's HTTP request-line. Since the request-line consists of the
2982     HTTP method, URI, and protocol version, the
2983     <code class="directive">LimitRequestLine</code> directive places a
2984     restriction on the length of a request-URI allowed for a request
2985     on the server. A server needs this value to be large enough to
2986     hold any of its resource names, including any information that
2987     might be passed in the query part of a <code>GET</code> request.</p>
2988
2989     <p>This directive gives the server administrator greater
2990     control over abnormal client request behavior, which may be
2991     useful for avoiding some forms of denial-of-service attacks.</p>
2992
2993     <p>For example:</p>
2994
2995     <pre class="prettyprint lang-config">LimitRequestLine 4094</pre>
2996
2997
2998     <div class="note">Under normal conditions, the value should not be changed from
2999     the default.</div>
3000
3001     <div class="warning"><h3>Warning</h3>
3002     <p> When name-based virtual hosting is used, the value for this
3003     directive is taken from the default (first-listed) virtual host best
3004     matching the current IP address and port combination.</p>
3005     </div>
3006
3007
3008 </div>
3009 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3010 <div class="directive-section"><h2><a name="LimitXMLRequestBody" id="LimitXMLRequestBody">LimitXMLRequestBody</a> <a name="limitxmlrequestbody" id="limitxmlrequestbody">Directive</a><a title="Permanent link" href="#limitxmlrequestbody" class="permalink">&para;</a></h2>
3011 <table class="directive">
3012 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of an XML-based request body</td></tr>
3013 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitXMLRequestBody <var>bytes</var></code></td></tr>
3014 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitXMLRequestBody 1000000</code></td></tr>
3015 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
3016 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
3017 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3018 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3019 </table>
3020     <p>Limit (in bytes) on maximum size of an XML-based request
3021     body. A value of <code>0</code> will disable any checking.</p>
3022
3023     <p>Example:</p>
3024
3025     <pre class="prettyprint lang-config">LimitXMLRequestBody 0</pre>
3026
3027
3028
3029 </div>
3030 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3031 <div class="directive-section"><h2><a name="Location" id="Location">&lt;Location&gt;</a> <a name="location" id="location">Directive</a><a title="Permanent link" href="#location" class="permalink">&para;</a></h2>
3032 <table class="directive">
3033 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to matching
3034 URLs</td></tr>
3035 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Location
3036     <var>URL-path</var>|<var>URL</var>&gt; ... &lt;/Location&gt;</code></td></tr>
3037 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
3038 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3039 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3040 </table>
3041     <p>The <code class="directive">&lt;Location&gt;</code> directive
3042     limits the scope of the enclosed directives by URL. It is similar to the
3043     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>
3044     directive, and starts a subsection which is terminated with a
3045     <code>&lt;/Location&gt;</code> directive. <code class="directive">&lt;Location&gt;</code> sections are processed in the
3046     order they appear in the configuration file, after the <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections and
3047     <code>.htaccess</code> files are read, and after the <code class="directive"><a href="#files">&lt;Files&gt;</a></code> sections.</p>
3048
3049     <p><code class="directive">&lt;Location&gt;</code> sections operate
3050     completely outside the filesystem.  This has several consequences.
3051     Most importantly, <code class="directive">&lt;Location&gt;</code>
3052     directives should not be used to control access to filesystem
3053     locations.  Since several different URLs may map to the same
3054     filesystem location, such access controls may by circumvented.</p>
3055
3056     <p>The enclosed directives will be applied to the request if the path component
3057     of the URL meets <em>any</em> of the following criteria:
3058     </p>
3059     <ul>
3060       <li>The specified location matches exactly the path component of the URL.
3061       </li>
3062       <li>The specified location, which ends in a forward slash, is a prefix
3063       of the path component of the URL (treated as a context root).
3064       </li>
3065       <li>The specified location, with the addition of a trailing slash, is a
3066       prefix of the path component of the URL (also treated as a context root).
3067       </li>
3068     </ul>
3069     <p>
3070     In the example below, where no trailing slash is used, requests to
3071     /private1, /private1/ and /private1/file.txt will have the enclosed
3072     directives applied, but /private1other would not.
3073     </p>
3074     <pre class="prettyprint lang-config">&lt;Location "/private1"&gt;
3075     #  ...
3076 &lt;/Location&gt;</pre>
3077
3078     <p>
3079     In the example below, where a trailing slash is used, requests to
3080     /private2/ and /private2/file.txt will have the enclosed
3081     directives applied, but /private2 and /private2other would not.
3082     </p>
3083     <pre class="prettyprint lang-config">&lt;Location "/private2<em>/</em>"&gt;
3084     # ...
3085 &lt;/Location&gt;</pre>
3086
3087
3088     <div class="note"><h3>When to use <code class="directive">&lt;Location&gt;</code></h3>
3089
3090     <p>Use <code class="directive">&lt;Location&gt;</code> to apply
3091     directives to content that lives outside the filesystem.  For
3092     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
3093     <code>&lt;Location "/"&gt;</code>, which is an easy way to
3094     apply a configuration to the entire server.</p>
3095     </div>
3096
3097     <p>For all origin (non-proxy) requests, the URL to be matched is a
3098     URL-path of the form <code>/path/</code>.  <em>No scheme, hostname,
3099     port, or query string may be included.</em>  For proxy requests, the
3100     URL to be matched is of the form
3101     <code>scheme://servername/path</code>, and you must include the
3102     prefix.</p>
3103
3104     <p>The URL may use wildcards. In a wild-card string, <code>?</code> matches
3105     any single character, and <code>*</code> matches any sequences of
3106     characters. Neither wildcard character matches a / in the URL-path.</p>
3107
3108     <p><a class="glossarylink" href="../glossary.html#regex" title="see glossary">Regular expressions</a>
3109     can also be used, with the addition of the <code>~</code>
3110     character. For example:</p>
3111
3112     <pre class="prettyprint lang-config">&lt;Location ~ "/(extra|special)/data"&gt;
3113     #...
3114 &lt;/Location&gt;</pre>
3115
3116
3117     <p>would match URLs that contained the substring <code>/extra/data</code>
3118     or <code>/special/data</code>. The directive <code class="directive"><a href="#locationmatch">&lt;LocationMatch&gt;</a></code> behaves
3119     identical to the regex version of <code class="directive">&lt;Location&gt;</code>, and is preferred, for the
3120     simple reason that <code>~</code> is hard to distinguish from
3121     <code>-</code> in many fonts.</p>
3122
3123     <p>The <code class="directive">&lt;Location&gt;</code>
3124     functionality is especially useful when combined with the
3125     <code class="directive"><a href="#sethandler">SetHandler</a></code>
3126     directive. For example, to enable status requests but allow them
3127     only from browsers at <code>example.com</code>, you might use:</p>
3128
3129     <pre class="prettyprint lang-config">&lt;Location "/status"&gt;
3130   SetHandler server-status
3131   Require host example.com
3132 &lt;/Location&gt;</pre>
3133
3134
3135     <div class="note"><h3>Note about / (slash)</h3>
3136       <p>The slash character has special meaning depending on where in a
3137       URL it appears. People may be used to its behavior in the filesystem
3138       where multiple adjacent slashes are frequently collapsed to a single
3139       slash (<em>i.e.</em>, <code>/home///foo</code> is the same as
3140       <code>/home/foo</code>). In URL-space this is not necessarily true.
3141       The <code class="directive"><a href="#locationmatch">&lt;LocationMatch&gt;</a></code>
3142       directive and the regex version of <code class="directive">&lt;Location&gt;</code> require you to explicitly specify multiple
3143       slashes if that is your intention.</p>
3144
3145       <p>For example, <code>&lt;LocationMatch "^/abc"&gt;</code> would match
3146       the request URL <code>/abc</code> but not the request URL <code>
3147       //abc</code>. The (non-regex) <code class="directive">&lt;Location&gt;</code> directive behaves similarly when used for
3148       proxy requests. But when (non-regex) <code class="directive">&lt;Location&gt;</code> is used for non-proxy requests it will
3149       implicitly match multiple slashes with a single slash. For example,
3150       if you specify <code>&lt;Location "/abc/def"&gt;</code> and the
3151       request is to <code>/abc//def</code> then it will match.</p>
3152     </div>
3153
3154 <h3>See also</h3>
3155 <ul>
3156 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
3157     and &lt;Files&gt; sections work</a> for an explanation of how these
3158     different sections are combined when a request is received.</li>
3159 <li><code class="directive"><a href="#locationmatch">LocationMatch</a></code></li>
3160 </ul>
3161 </div>
3162 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3163 <div class="directive-section"><h2><a name="LocationMatch" id="LocationMatch">&lt;LocationMatch&gt;</a> <a name="locationmatch" id="locationmatch">Directive</a><a title="Permanent link" href="#locationmatch" class="permalink">&para;</a></h2>
3164 <table class="directive">
3165 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to regular-expression
3166 matching URLs</td></tr>
3167 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;LocationMatch
3168     <var>regex</var>&gt; ... &lt;/LocationMatch&gt;</code></td></tr>
3169 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
3170 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3171 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3172 </table>
3173     <p>The <code class="directive">&lt;LocationMatch&gt;</code> directive
3174     limits the scope of the enclosed directives by URL, in an identical manner
3175     to <code class="directive"><a href="#location">&lt;Location&gt;</a></code>. However,
3176     it takes a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
3177     as an argument instead of a simple string. For example:</p>
3178
3179     <pre class="prettyprint lang-config">&lt;LocationMatch "/(extra|special)/data"&gt;
3180     # ...
3181 &lt;/LocationMatch&gt;</pre>
3182
3183
3184     <p>would match URLs that contained the substring <code>/extra/data</code>
3185     or <code>/special/data</code>.</p>
3186
3187     <div class="note"><p>If the intent is that a URL <strong>starts with</strong>
3188     <code>/extra/data</code>, rather than merely
3189     <strong>contains</strong> <code>/extra/data</code>, prefix the
3190     regular expression with a <code>^</code> to require this.</p>
3191
3192     <pre class="prettyprint lang-config">&lt;LocationMatch "^/(extra|special)/data"&gt;</pre>
3193
3194     </div>
3195
3196     <p>From 2.4.8 onwards, named groups and backreferences are captured and
3197     written to the environment with the corresponding name prefixed with
3198     "MATCH_" and in upper case. This allows elements of URLs to be referenced
3199     from within <a href="../expr.html">expressions</a> and modules like
3200     <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
3201     (unnamed) backreferences are ignored. Use named groups instead.</p>
3202
3203     <pre class="prettyprint lang-config">&lt;LocationMatch "^/combined/(?&lt;sitename&gt;[^/]+)"&gt;
3204     Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
3205 &lt;/LocationMatch&gt;</pre>
3206
3207
3208 <h3>See also</h3>
3209 <ul>
3210 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
3211     and &lt;Files&gt; sections work</a> for an explanation of how these
3212     different sections are combined when a request is received</li>
3213 </ul>
3214 </div>
3215 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3216 <div class="directive-section"><h2><a name="LogLevel" id="LogLevel">LogLevel</a> <a name="loglevel" id="loglevel">Directive</a><a title="Permanent link" href="#loglevel" class="permalink">&para;</a></h2>
3217 <table class="directive">
3218 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls the verbosity of the ErrorLog</td></tr>
3219 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogLevel [<var>module</var>:]<var>level</var>
3220     [<var>module</var>:<var>level</var>] ...
3221 </code></td></tr>
3222 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LogLevel warn</code></td></tr>
3223 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
3224 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3225 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3226 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Per-module and per-directory configuration is available in
3227     Apache HTTP Server 2.3.6 and later</td></tr>
3228 </table>
3229     <p><code class="directive">LogLevel</code> adjusts the verbosity of the
3230     messages recorded in the error logs (see <code class="directive"><a href="#errorlog">ErrorLog</a></code> directive). The following
3231     <var>level</var>s are available, in order of decreasing
3232     significance:</p>
3233
3234     <table class="bordered">
3235
3236       <tr>
3237         <th><strong>Level</strong> </th>
3238
3239         <th><strong>Description</strong> </th>
3240
3241         <th><strong>Example</strong> </th>
3242       </tr>
3243
3244       <tr>
3245         <td><code>emerg</code> </td>
3246
3247         <td>Emergencies - system is unusable.</td>
3248
3249         <td>"Child cannot open lock file. Exiting"</td>
3250       </tr>
3251
3252       <tr>
3253         <td><code>alert</code> </td>
3254
3255         <td>Action must be taken immediately.</td>
3256
3257         <td>"getpwuid: couldn't determine user name from uid"</td>
3258       </tr>
3259
3260       <tr>
3261         <td><code>crit</code> </td>
3262
3263         <td>Critical Conditions.</td>
3264
3265         <td>"socket: Failed to get a socket, exiting child"</td>
3266       </tr>
3267
3268       <tr>
3269         <td><code>error</code> </td>
3270
3271         <td>Error conditions.</td>
3272
3273         <td>"Premature end of script headers"</td>
3274       </tr>
3275
3276       <tr>
3277         <td><code>warn</code> </td>
3278
3279         <td>Warning conditions.</td>
3280
3281         <td>"child process 1234 did not exit, sending another
3282         SIGHUP"</td>
3283       </tr>
3284
3285       <tr>
3286         <td><code>notice</code> </td>
3287
3288         <td>Normal but significant condition.</td>
3289
3290         <td>"httpd: caught SIGBUS, attempting to dump core in
3291         ..."</td>
3292       </tr>
3293
3294       <tr>
3295         <td><code>info</code> </td>
3296
3297         <td>Informational.</td>
3298
3299         <td>"Server seems busy, (you may need to increase
3300         StartServers, or Min/MaxSpareServers)..."</td>
3301       </tr>
3302
3303       <tr>
3304         <td><code>debug</code> </td>
3305
3306         <td>Debug-level messages</td>
3307
3308         <td>"Opening config file ..."</td>
3309       </tr>
3310       <tr>
3311         <td><code>trace1</code> </td>
3312
3313         <td>Trace messages</td>
3314
3315         <td>"proxy: FTP: control connection complete"</td>
3316       </tr>
3317       <tr>
3318         <td><code>trace2</code> </td>
3319
3320         <td>Trace messages</td>
3321
3322         <td>"proxy: CONNECT: sending the CONNECT request to the remote proxy"</td>
3323       </tr>
3324       <tr>
3325         <td><code>trace3</code> </td>
3326
3327         <td>Trace messages</td>
3328
3329         <td>"openssl: Handshake: start"</td>
3330       </tr>
3331       <tr>
3332         <td><code>trace4</code> </td>
3333
3334         <td>Trace messages</td>
3335
3336         <td>"read from buffered SSL brigade, mode 0, 17 bytes"</td>
3337       </tr>
3338       <tr>
3339         <td><code>trace5</code> </td>
3340
3341         <td>Trace messages</td>
3342
3343         <td>"map lookup FAILED: map=rewritemap key=keyname"</td>
3344       </tr>
3345       <tr>
3346         <td><code>trace6</code> </td>
3347
3348         <td>Trace messages</td>
3349
3350         <td>"cache lookup FAILED, forcing new map lookup"</td>
3351       </tr>
3352       <tr>
3353         <td><code>trace7</code> </td>
3354
3355         <td>Trace messages, dumping large amounts of data</td>
3356
3357         <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td>
3358       </tr>
3359       <tr>
3360         <td><code>trace8</code> </td>
3361
3362         <td>Trace messages, dumping large amounts of data</td>
3363
3364         <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td>
3365       </tr>
3366     </table>
3367
3368     <p>When a particular level is specified, messages from all
3369     other levels of higher significance will be reported as well.
3370     <em>E.g.</em>, when <code>LogLevel info</code> is specified,
3371     then messages with log levels of <code>notice</code> and
3372     <code>warn</code> will also be posted.</p>
3373
3374     <p>Using a level of at least <code>crit</code> is
3375     recommended.</p>
3376
3377     <p>For example:</p>
3378
3379     <pre class="prettyprint lang-config">LogLevel notice</pre>
3380
3381
3382     <div class="note"><h3>Note</h3>
3383       <p>When logging to a regular file, messages of the level
3384       <code>notice</code> cannot be suppressed and thus are always
3385       logged. However, this doesn't apply when logging is done
3386       using <code>syslog</code>.</p>
3387     </div>
3388
3389     <p>Specifying a level without a module name will reset the level
3390     for all modules to that level.  Specifying a level with a module
3391     name will set the level for that module only. It is possible to
3392     use the module source file name, the module identifier, or the
3393     module identifier with the trailing <code>_module</code> omitted
3394     as module specification. This means the following three specifications
3395     are equivalent:</p>
3396
3397     <pre class="prettyprint lang-config">LogLevel info ssl:warn
3398 LogLevel info mod_ssl.c:warn
3399 LogLevel info ssl_module:warn</pre>
3400
3401
3402     <p>It is also possible to change the level per directory:</p>
3403
3404     <pre class="prettyprint lang-config">LogLevel info
3405 &lt;Directory "/usr/local/apache/htdocs/app"&gt;
3406   LogLevel debug
3407 &lt;/Directory&gt;</pre>
3408
3409
3410     <div class="note">
3411         Per directory loglevel configuration only affects messages that are
3412         logged after the request has been parsed and that are associated with
3413         the request. Log messages which are associated with the server or
3414         the connection are not affected. The latter can be influenced by the
3415         <code class="directive"><a href="#logleveloverride">LogLevelOverride</a></code> directive,
3416         though.
3417     </div>
3418
3419 <h3>See also</h3>
3420 <ul>
3421 <li><code class="directive"><a href="#errorlog">ErrorLog</a></code></li>
3422 <li><code class="directive"><a href="#errorlogformat">ErrorLogFormat</a></code></li>
3423 <li><code class="directive"><a href="#logleveloverride">LogLevelOverride</a></code></li>
3424 <li><a href="../logs.html">Apache HTTP Server Log Files</a></li>
3425 </ul>
3426 </div>
3427 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3428 <div class="directive-section"><h2><a name="LogLevelOverride" id="LogLevelOverride">LogLevelOverride</a> <a name="logleveloverride" id="logleveloverride">Directive</a><a title="Permanent link" href="#logleveloverride" class="permalink">&para;</a></h2>
3429 <table class="directive">
3430 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override the verbosity of the ErrorLog for certain clients</td></tr>
3431 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogLevel <var>ipaddress</var>[/<var>prefixlen</var>]
3432     [<var>module</var>:]<var>level</var> [<var>module</var>:<var>level</var>] ...
3433 </code></td></tr>
3434 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>unset</code></td></tr>
3435 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
3436 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3437 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3438 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.5.0 and later</td></tr>
3439 </table>
3440     <p><code class="directive">LogLevelOverride</code> adjusts the
3441     <code class="directive"><a href="#loglevel">LogLevel</a></code> for requests coming from
3442     certain client IP addresses.
3443     This allows to enable verbose logging only for certain test clients.
3444     The IP address is checked at a very early state in the connection
3445     processing.  Therefore, <code class="directive">LogLevelOverride</code> allows to
3446     change the log level for things like the SSL handshake which happen before
3447     a <code class="directive"><a href="#loglevel">LogLevel</a></code> directive in an
3448     <code class="directive"><a href="#if">&lt;If&gt;</a></code> container would
3449     be evaluated.</p>
3450
3451     <p><code class="directive">LogLevelOverride</code> accepts either a single
3452     IP-address or a CIDR IP-address/len subnet specification.
3453     For the syntax of the loglevel specification, see the
3454     <code class="directive"><a href="#loglevel">LogLevel</a></code> directive.</p>
3455
3456     <p>For requests that match a <code class="directive">LogLevelOverride</code>
3457     directive, per-directory specifications of
3458     <code class="directive"><a href="#loglevel">LogLevel</a></code> are ignored.</p>
3459
3460     <p>Examples:</p>
3461
3462     <pre class="prettyprint lang-config">    LogLevelOverride 192.0.2.0/24 ssl:trace6
3463     LogLevelOverride 192.0.2.7 ssl:trace8</pre>
3464
3465
3466     <div class="note">
3467         <code class="directive">LogLevelOverride</code> only affects
3468         log messages that are associated with the request or the connection.
3469         Log messages which are associated with the server are not affected.
3470     </div>
3471
3472
3473 <h3>See also</h3>
3474 <ul>
3475 <li><code class="directive"><a href="#loglevel">LogLevel</a></code></li>
3476 </ul>
3477 </div>
3478 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3479 <div class="directive-section"><h2><a name="MaxKeepAliveRequests" id="MaxKeepAliveRequests">MaxKeepAliveRequests</a> <a name="maxkeepaliverequests" id="maxkeepaliverequests">Directive</a><a title="Permanent link" href="#maxkeepaliverequests" class="permalink">&para;</a></h2>
3480 <table class="directive">
3481 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of requests allowed on a persistent
3482 connection</td></tr>
3483 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxKeepAliveRequests <var>number</var></code></td></tr>
3484 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxKeepAliveRequests 100</code></td></tr>
3485 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
3486 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3487 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3488 </table>
3489     <p>The <code class="directive">MaxKeepAliveRequests</code> directive
3490     limits the number of requests allowed per connection when
3491     <code class="directive"><a href="#keepalive">KeepAlive</a></code> is on. If it is
3492     set to <code>0</code>, unlimited requests will be allowed. We
3493     recommend that this setting be kept to a high value for maximum
3494     server performance.</p>
3495
3496     <p>For example:</p>
3497
3498     <pre class="prettyprint lang-config">MaxKeepAliveRequests 500</pre>
3499
3500
3501 </div>
3502 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3503 <div class="directive-section"><h2><a name="MaxRangeOverlaps" id="MaxRangeOverlaps">MaxRangeOverlaps</a> <a name="maxrangeoverlaps" id="maxrangeoverlaps">Directive</a><a title="Permanent link" href="#maxrangeoverlaps" class="permalink">&para;</a></h2>
3504 <table class="directive">
3505 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of overlapping ranges (eg: <code>100-200,150-300</code>) allowed before returning the complete
3506         resource </td></tr>
3507 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxRangeOverlaps default | unlimited | none | <var>number-of-ranges</var></code></td></tr>
3508 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRangeOverlaps 20</code></td></tr>
3509 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
3510 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3511 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3512 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr>
3513 </table>
3514         <p>The <code class="directive">MaxRangeOverlaps</code> directive
3515             limits the number of overlapping HTTP ranges the server is willing to
3516             return to the client. If more overlapping ranges than permitted are requested,
3517             the complete resource is returned instead.</p>
3518
3519         <dl>
3520             <dt><strong>default</strong></dt>
3521             <dd>Limits the number of overlapping ranges to a compile-time default of 20.</dd>
3522
3523             <dt><strong>none</strong></dt>
3524             <dd>No overlapping Range headers are allowed.</dd>
3525
3526             <dt><strong>unlimited</strong></dt>
3527             <dd>The server does not limit the number of overlapping ranges it is
3528                 willing to satisfy.</dd>
3529
3530             <dt><var>number-of-ranges</var></dt>
3531             <dd>A positive number representing the maximum number of overlapping ranges the
3532                 server is willing to satisfy.</dd>
3533         </dl>
3534
3535 </div>
3536 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3537 <div class="directive-section"><h2><a name="MaxRangeReversals" id="MaxRangeReversals">MaxRangeReversals</a> <a name="maxrangereversals" id="maxrangereversals">Directive</a><a title="Permanent link" href="#maxrangereversals" class="permalink">&para;</a></h2>
3538 <table class="directive">
3539 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of range reversals (eg: <code>100-200,50-70</code>) allowed before returning the complete
3540         resource </td></tr>
3541 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxRangeReversals default | unlimited | none | <var>number-of-ranges</var></code></td></tr>
3542 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRangeReversals 20</code></td></tr>
3543 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
3544 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3545 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3546 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr>
3547 </table>
3548         <p>The <code class="directive">MaxRangeReversals</code> directive
3549             limits the number of HTTP Range reversals the server is willing to
3550             return to the client. If more ranges reversals than permitted are requested,
3551             the complete resource is returned instead.</p>
3552
3553         <dl>
3554             <dt><strong>default</strong></dt>
3555             <dd>Limits the number of range reversals to a compile-time default of 20.</dd>
3556
3557             <dt><strong>none</strong></dt>
3558             <dd>No Range reversals headers are allowed.</dd>
3559
3560             <dt><strong>unlimited</strong></dt>
3561             <dd>The server does not limit the number of range reversals it is
3562                 willing to satisfy.</dd>
3563
3564             <dt><var>number-of-ranges</var></dt>
3565             <dd>A positive number representing the maximum number of range reversals the
3566                 server is willing to satisfy.</dd>
3567         </dl>
3568
3569 </div>
3570 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3571 <div class="directive-section"><h2><a name="MaxRanges" id="MaxRanges">MaxRanges</a> <a name="maxranges" id="maxranges">Directive</a><a title="Permanent link" href="#maxranges" class="permalink">&para;</a></h2>
3572 <table class="directive">
3573 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of ranges allowed before returning the complete
3574 resource </td></tr>
3575 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxRanges default | unlimited | none | <var>number-of-ranges</var></code></td></tr>
3576 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRanges 200</code></td></tr>
3577 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
3578 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3579 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3580 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr>
3581 </table>
3582     <p>The <code class="directive">MaxRanges</code> directive
3583     limits the number of HTTP ranges the server is willing to
3584     return to the client. If more ranges than permitted are requested,
3585     the complete resource is returned instead.</p>
3586
3587     <dl>
3588       <dt><strong>default</strong></dt>
3589       <dd>Limits the number of ranges to a compile-time default of 200.</dd>
3590
3591       <dt><strong>none</strong></dt>
3592       <dd>Range headers are ignored.</dd>
3593
3594       <dt><strong>unlimited</strong></dt>
3595       <dd>The server does not limit the number of ranges it is
3596           willing to satisfy.</dd>
3597
3598       <dt><var>number-of-ranges</var></dt>
3599       <dd>A positive number representing the maximum number of ranges the
3600       server is willing to satisfy.</dd>
3601     </dl>
3602
3603 </div>
3604 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3605 <div class="directive-section"><h2><a name="MergeTrailers" id="MergeTrailers">MergeTrailers</a> <a name="mergetrailers" id="mergetrailers">Directive</a><a title="Permanent link" href="#mergetrailers" class="permalink">&para;</a></h2>
3606 <table class="directive">
3607 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether trailers are merged into headers</td></tr>
3608 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MergeTrailers [on|off]</code></td></tr>
3609 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MergeTrailers off</code></td></tr>
3610 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
3611 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3612 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3613 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.11 and later</td></tr>
3614 </table>
3615     <p>This directive controls whether HTTP trailers are copied into the
3616     internal representation of HTTP headers. This merging occurs when the
3617     request body has been completely consumed, long after most header
3618     processing would have a chance to examine or modify request headers.</p>
3619     <p>This option is provided for compatibility with releases prior to 2.4.11,
3620     where trailers were always merged.</p>
3621
3622 </div>
3623 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3624 <div class="directive-section"><h2><a name="Mutex" id="Mutex">Mutex</a> <a name="mutex" id="mutex">Directive</a><a title="Permanent link" href="#mutex" class="permalink">&para;</a></h2>
3625 <table class="directive">
3626 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures mutex mechanism and lock file directory for all
3627 or specified mutexes</td></tr>
3628 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Mutex <var>mechanism</var> [default|<var>mutex-name</var>] ... [OmitPID]</code></td></tr>
3629 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Mutex default</code></td></tr>
3630 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
3631 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3632 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3633 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.4 and later</td></tr>
3634 </table>
3635     <p>The <code class="directive">Mutex</code> directive sets the mechanism,
3636     and optionally the lock file location, that httpd and modules use
3637     to serialize access to resources.  Specify <code>default</code> as
3638     the second argument to change the settings for all mutexes; specify
3639     a mutex name (see table below) as the second argument to override
3640     defaults only for that mutex.</p>
3641
3642     <p>The <code class="directive">Mutex</code> directive is typically used in
3643     the following exceptional situations:</p>
3644
3645     <ul>
3646         <li>change the mutex mechanism when the default mechanism selected
3647         by <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> has a functional or performance
3648         problem</li>
3649
3650         <li>change the directory used by file-based mutexes when the
3651         default directory does not support locking</li>
3652     </ul>
3653
3654     <div class="note"><h3>Supported modules</h3>
3655     <p>This directive only configures mutexes which have been registered
3656     with the core server using the <code>ap_mutex_register()</code> API.
3657     All modules bundled with httpd support the <code class="directive">Mutex</code>
3658     directive, but third-party modules may not.  Consult the documentation
3659     of the third-party module, which must indicate the mutex name(s) which
3660     can be configured if this directive is supported.</p>
3661     </div>
3662
3663     <p>The following mutex <em>mechanisms</em> are available:</p>
3664     <ul>
3665         <li><code>default | yes</code>
3666         <p>This selects the default locking implementation, as determined by
3667         <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a>.  The default locking implementation can
3668         be displayed by running <code class="program"><a href="../programs/httpd.html">httpd</a></code> with the
3669         <code>-V</code> option.</p></li>
3670
3671         <li><code>none | no</code>
3672         <p>This effectively disables the mutex, and is only allowed for a
3673         mutex if the module indicates that it is a valid choice.  Consult the
3674         module documentation for more information.</p></li>
3675
3676         <li><code>posixsem</code>
3677         <p>This is a mutex variant based on a Posix semaphore.</p>
3678
3679         <div class="warning"><h3>Warning</h3>
3680         <p>The semaphore ownership is not recovered if a thread in the process
3681         holding the mutex segfaults, resulting in a hang of the web server.</p>
3682         </div>
3683         </li>
3684
3685         <li><code>sysvsem</code>
3686         <p>This is a mutex variant based on a SystemV IPC semaphore.</p>
3687
3688         <div class="warning"><h3>Warning</h3>
3689         <p>It is possible to "leak" SysV semaphores if processes crash
3690         before the semaphore is removed.</p>
3691         </div>
3692
3693         <div class="warning"><h3>Security</h3>
3694         <p>The semaphore API allows for a denial of service attack by any
3695         CGIs running under the same uid as the webserver (<em>i.e.</em>,
3696         all CGIs, unless you use something like <code class="program"><a href="../programs/suexec.html">suexec</a></code>
3697         or <code>cgiwrapper</code>).</p>
3698         </div>
3699         </li>
3700
3701         <li><code>sem</code>
3702         <p>This selects the "best" available semaphore implementation, choosing
3703         between Posix and SystemV IPC semaphores, in that order.</p></li>
3704
3705         <li><code>pthread</code>
3706         <p>This is a mutex variant based on cross-process Posix thread
3707         mutexes.</p>
3708
3709         <div class="warning"><h3>Warning</h3>
3710         <p>On most systems, if a child process terminates abnormally while
3711         holding a mutex that uses this implementation, the server will deadlock
3712         and stop responding to requests.  When this occurs, the server will
3713         require a manual restart to recover.</p>
3714         <p>Solaris and Linux are notable exceptions as they provide a mechanism which
3715         usually allows the mutex to be recovered after a child process
3716         terminates abnormally while holding a mutex.</p>
3717         <p>If your system is POSIX compliant or if it implements the
3718         <code>pthread_mutexattr_setrobust_np()</code> function, you may be able
3719         to use the <code>pthread</code> option safely.</p>
3720         </div>
3721         </li>
3722
3723         <li><code>fcntl:/path/to/mutex</code>
3724         <p>This is a mutex variant where a physical (lock-)file and the
3725         <code>fcntl()</code> function are used as the mutex.</p>
3726
3727         <div class="warning"><h3>Warning</h3>
3728         <p>When multiple mutexes based on this mechanism are used within
3729         multi-threaded, multi-process environments, deadlock errors (EDEADLK)
3730         can be reported for valid mutex operations if <code>fcntl()</code>
3731         is not thread-aware, such as on Solaris.</p>
3732         </div>
3733         </li>
3734
3735         <li><code>flock:/path/to/mutex</code>
3736         <p>This is similar to the <code>fcntl:/path/to/mutex</code> method
3737         with the exception that the <code>flock()</code> function is used to
3738         provide file locking.</p></li>
3739
3740         <li><code>file:/path/to/mutex</code>
3741         <p>This selects the "best" available file locking implementation,
3742         choosing between <code>fcntl</code> and <code>flock</code>, in that
3743         order.</p></li>
3744     </ul>
3745
3746     <p>Most mechanisms are only available on selected platforms, where the
3747     underlying platform and <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> support it.  Mechanisms
3748     which aren't available on all platforms are <em>posixsem</em>,
3749     <em>sysvsem</em>, <em>sem</em>, <em>pthread</em>, <em>fcntl</em>,
3750     <em>flock</em>, and <em>file</em>.</p>
3751
3752     <p>With the file-based mechanisms <em>fcntl</em> and <em>flock</em>,
3753     the path, if provided, is a directory where the lock file will be created.
3754     The default directory is httpd's run-time file directory,
3755     <code class="directive"><a href="#defaultruntimedir">DefaultRuntimeDir</a></code>.  If a relative
3756     path is provided, it is relative to
3757     <code class="directive"><a href="#defaultruntimedir">DefaultRuntimeDir</a></code>.  Always use a local
3758     disk filesystem for <code>/path/to/mutex</code> and never a directory residing
3759     on a NFS- or AFS-filesystem.  The basename of the file will be the mutex
3760     type, an optional instance string provided by the module, and unless the
3761     <code>OmitPID</code> keyword is specified, the process id of the httpd
3762     parent process will be appended to make the file name unique, avoiding
3763     conflicts when multiple httpd instances share a lock file directory.  For
3764     example, if the mutex name is <code>mpm-accept</code> and the lock file
3765     directory is <code>/var/httpd/locks</code>, the lock file name for the
3766     httpd instance with parent process id 12345 would be
3767     <code>/var/httpd/locks/mpm-accept.12345</code>.</p>
3768
3769     <div class="warning"><h3>Security</h3>
3770     <p>It is best to <em>avoid</em> putting mutex files in a world-writable
3771     directory such as <code>/var/tmp</code> because someone could create
3772     a denial of service attack and prevent the server from starting by
3773     creating a lockfile with the same name as the one the server will try
3774     to create.</p>
3775     </div>
3776
3777     <p>The following table documents the names of mutexes used by httpd
3778     and bundled modules.</p>
3779
3780     <table class="bordered"><tr class="header">
3781             <th>Mutex name</th>
3782             <th>Module(s)</th>
3783             <th>Protected resource</th>
3784         </tr>
3785 <tr>
3786             <td><code>mpm-accept</code></td>
3787             <td><code class="module"><a href="../mod/prefork.html">prefork</a></code> and <code class="module"><a href="../mod/worker.html">worker</a></code> MPMs</td>
3788             <td>incoming connections, to avoid the thundering herd problem;
3789             for more information, refer to the
3790             <a href="../misc/perf-tuning.html">performance tuning</a>
3791             documentation</td>
3792         </tr>
3793 <tr class="odd">
3794             <td><code>authdigest-client</code></td>
3795             <td><code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code></td>
3796             <td>client list in shared memory</td>
3797         </tr>
3798 <tr>
3799             <td><code>authdigest-opaque</code></td>
3800             <td><code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code></td>
3801             <td>counter in shared memory</td>
3802         </tr>
3803 <tr class="odd">
3804             <td><code>ldap-cache</code></td>
3805             <td><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code></td>
3806             <td>LDAP result cache</td>
3807         </tr>
3808 <tr>
3809             <td><code>rewrite-map</code></td>
3810             <td><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></td>
3811             <td>communication with external mapping programs, to avoid
3812             intermixed I/O from multiple requests</td>
3813         </tr>
3814 <tr class="odd">
3815             <td><code>ssl-cache</code></td>
3816             <td><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></td>
3817             <td>SSL session cache</td>
3818         </tr>
3819 <tr>
3820             <td><code>ssl-stapling</code></td>
3821             <td><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></td>
3822             <td>OCSP stapling response cache</td>
3823         </tr>
3824 <tr class="odd">
3825             <td><code>watchdog-callback</code></td>
3826             <td><code class="module"><a href="../mod/mod_watchdog.html">mod_watchdog</a></code></td>
3827             <td>callback function of a particular client module</td>
3828         </tr>
3829 </table>
3830
3831     <p>The <code>OmitPID</code> keyword suppresses the addition of the httpd
3832     parent process id from the lock file name.</p>
3833
3834     <p>In the following example, the mutex mechanism for the MPM accept
3835     mutex will be changed from the compiled-in default to <code>fcntl</code>,
3836     with the associated lock file created in directory
3837     <code>/var/httpd/locks</code>.  The mutex mechanism for all other mutexes
3838     will be changed from the compiled-in default to <code>sysvsem</code>.</p>
3839
3840     <pre class="prettyprint lang-config">Mutex sysvsem default
3841 Mutex fcntl:/var/httpd/locks mpm-accept</pre>
3842
3843
3844 </div>
3845 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3846 <div class="directive-section"><h2><a name="NameVirtualHost" id="NameVirtualHost">NameVirtualHost</a> <a name="namevirtualhost" id="namevirtualhost">Directive</a><a title="Permanent link" href="#namevirtualhost" class="permalink">&para;</a></h2>
3847 <table class="directive">
3848 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>DEPRECATED: Designates an IP address for name-virtual
3849 hosting</td></tr>
3850 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NameVirtualHost <var>addr</var>[:<var>port</var>]</code></td></tr>
3851 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
3852 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3853 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3854 </table>
3855
3856 <p>Prior to 2.3.11, <code class="directive">NameVirtualHost</code> was required
3857 to instruct the server that a particular IP address and port combination
3858 was usable as a name-based virtual host.  In 2.3.11 and later,
3859 any time an IP address and port combination is used in multiple virtual
3860 hosts, name-based virtual hosting is automatically enabled for that address.</p>
3861
3862 <p>This directive currently has no effect.</p>
3863
3864 <h3>See also</h3>
3865 <ul>
3866 <li><a href="../vhosts/">Virtual Hosts
3867 documentation</a></li>
3868 </ul>
3869 </div>
3870 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
3871 <div class="directive-section"><h2><a name="Options" id="Options">Options</a> <a name="options" id="options">Directive</a><a title="Permanent link" href="#options" class="permalink">&para;</a></h2>
3872 <table class="directive">
3873 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures what features are available in a particular
3874 directory</td></tr>
3875 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Options
3876     [+|-]<var>option</var> [[+|-]<var>option</var>] ...</code></td></tr>
3877 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Options FollowSymlinks</code></td></tr>
3878 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
3879 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
3880 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
3881 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
3882 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The default was changed from All to FollowSymlinks in 2.3.11</td></tr>
3883 </table>
3884     <p>The <code class="directive">Options</code> directive controls which
3885     server features are available in a particular directory.</p>
3886
3887     <p><var>option</var> can be set to <code>None</code>, in which
3888     case none of the extra features are enabled, or one or more of
3889     the following:</p>
3890
3891     <dl>
3892       <dt><code>All</code></dt>
3893
3894       <dd>All options except for <code>MultiViews</code>.</dd>
3895
3896       <dt><code>ExecCGI</code></dt>
3897
3898       <dd>
3899       Execution of CGI scripts using <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>
3900       is permitted.</dd>
3901
3902       <dt><code>FollowSymLinks</code></dt>
3903
3904       <dd>
3905       The server will follow symbolic links in this directory. This is
3906       the default setting.
3907       <div class="note">
3908       <p>Even though the server follows the symlink it does <em>not</em>
3909       change the pathname used to match against <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections.</p>
3910
3911       <p>The <code>FollowSymLinks</code> and
3912       <code>SymLinksIfOwnerMatch</code> <code class="directive"><a href="#options">Options</a></code> work only in <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections or
3913       <code>.htaccess</code> files.</p>
3914
3915       <p>Omitting this option should not be considered a security restriction,
3916       since symlink testing is subject to race conditions that make it
3917       circumventable.</p>
3918       </div></dd>
3919
3920       <dt><code>Includes</code></dt>
3921
3922       <dd>
3923       Server-side includes provided by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
3924       are permitted.</dd>
3925
3926       <dt><code>IncludesNOEXEC</code></dt>
3927
3928       <dd>
3929
3930       Server-side includes are permitted, but the <code>#exec
3931       cmd</code> and <code>#exec cgi</code> are disabled. It is still
3932       possible to <code>#include virtual</code> CGI scripts from
3933       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed
3934       directories.</dd>
3935
3936       <dt><code>Indexes</code></dt>
3937
3938       <dd>
3939       If a URL which maps to a directory is requested and there
3940       is no <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
3941       (<em>e.g.</em>, <code>index.html</code>) in that directory, then
3942       <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code> will return a formatted listing
3943       of the directory.</dd>
3944
3945       <dt><code>MultiViews</code></dt>
3946
3947       <dd>
3948       <a href="../content-negotiation.html">Content negotiated</a>
3949       "MultiViews" are allowed using
3950       <code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code>.
3951       <div class="note"><h3>Note</h3> <p>This option gets ignored if set
3952       anywhere other than <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code>, as <code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code>
3953       needs real resources to compare against and evaluate from.</p></div>
3954       </dd>
3955
3956       <dt><code>SymLinksIfOwnerMatch</code></dt>
3957
3958       <dd>The server will only follow symbolic links for which the
3959       target file or directory is owned by the same user id as the
3960       link.
3961
3962       <div class="note"><h3>Note</h3>
3963       <p>The <code>FollowSymLinks</code> and
3964       <code>SymLinksIfOwnerMatch</code> <code class="directive"><a href="#options">Options</a></code> work only in <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> sections or
3965       <code>.htaccess</code> files.</p>
3966
3967       <p>This option should not be considered a security restriction,
3968       since symlink testing is subject to race conditions that make it
3969       circumventable.</p>
3970       </div> </dd>
3971     </dl>
3972
3973     <p>Normally, if multiple <code class="directive">Options</code> could
3974     apply to a directory, then the most specific one is used and
3975     others are ignored; the options are not merged. (See <a href="../sections.html#merging">how sections are merged</a>.)
3976     However if <em>all</em> the options on the
3977     <code class="directive">Options</code> directive are preceded by a
3978     <code>+</code> or <code>-</code> symbol, the options are
3979     merged. Any options preceded by a <code>+</code> are added to the
3980     options currently in force, and any options preceded by a
3981     <code>-</code> are removed from the options currently in
3982     force. </p>
3983
3984     <div class="note"><h3>Note</h3>
3985     <p>Mixing <code class="directive">Options</code> with a <code>+</code> or
3986     <code>-</code> with those without is not valid syntax and will be
3987     rejected during server startup by the syntax check with an abort.</p>
3988     </div>
3989
3990     <p>For example, without any <code>+</code> and <code>-</code> symbols:</p>
3991
3992     <pre class="prettyprint lang-config">&lt;Directory "/web/docs"&gt;
3993   Options Indexes FollowSymLinks
3994 &lt;/Directory&gt;
3995
3996 &lt;Directory "/web/docs/spec"&gt;
3997   Options Includes
3998 &lt;/Directory&gt;</pre>
3999
4000
4001     <p>then only <code>Includes</code> will be set for the
4002     <code>/web/docs/spec</code> directory. However if the second
4003     <code class="directive">Options</code> directive uses the <code>+</code> and
4004     <code>-</code> symbols:</p>
4005
4006     <pre class="prettyprint lang-config">&lt;Directory "/web/docs"&gt;
4007   Options Indexes FollowSymLinks
4008 &lt;/Directory&gt;
4009
4010 &lt;Directory "/web/docs/spec"&gt;
4011   Options +Includes -Indexes
4012 &lt;/Directory&gt;</pre>
4013
4014
4015     <p>then the options <code>FollowSymLinks</code> and
4016     <code>Includes</code> are set for the <code>/web/docs/spec</code>
4017     directory.</p>
4018
4019     <div class="note"><h3>Note</h3>
4020       <p>Using <code>-IncludesNOEXEC</code> or
4021       <code>-Includes</code> disables server-side includes completely
4022       regardless of the previous setting.</p>
4023     </div>
4024
4025     <p>The default in the absence of any other settings is
4026     <code>FollowSymlinks</code>.</p>
4027
4028 </div>
4029 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4030 <div class="directive-section"><h2><a name="Protocol" id="Protocol">Protocol</a> <a name="protocol" id="protocol">Directive</a><a title="Permanent link" href="#protocol" class="permalink">&para;</a></h2>
4031 <table class="directive">
4032 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Protocol for a listening socket</td></tr>
4033 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Protocol <var>protocol</var></code></td></tr>
4034 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4035 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4036 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4037 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>On Windows, only available from Apache 2.3.3 and later.</td></tr>
4038 </table>
4039     <p>This directive specifies the protocol used for a specific listening socket.
4040        The protocol is used to determine which module should handle a request and
4041        to apply protocol specific optimizations with the <code class="directive">AcceptFilter</code>
4042        directive.</p>
4043
4044     <p>You only need to set the protocol if you are running on non-standard ports;
4045        otherwise, <code>http</code> is assumed for port 80 and <code>https</code>
4046        for port 443.</p>
4047
4048     <p>For example, if you are running <code>https</code> on a non-standard port,
4049        specify the protocol explicitly:</p>
4050
4051     <pre class="prettyprint lang-config">Protocol https</pre>
4052
4053
4054     <p>You can also specify the protocol using the <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code> directive.</p>
4055
4056 <h3>See also</h3>
4057 <ul>
4058 <li><code class="directive"><a href="#acceptfilter">AcceptFilter</a></code></li>
4059 <li><code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code></li>
4060 </ul>
4061 </div>
4062 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4063 <div class="directive-section"><h2><a name="Protocols" id="Protocols">Protocols</a> <a name="protocols" id="protocols">Directive</a><a title="Permanent link" href="#protocols" class="permalink">&para;</a></h2>
4064 <table class="directive">
4065 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Protocols available for a server/virtual host</td></tr>
4066 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Protocols <var>protocol</var> ...</code></td></tr>
4067 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Protocols http/1.1</code></td></tr>
4068 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4069 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4070 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4071 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Only available from Apache 2.4.17 and later.</td></tr>
4072 </table>
4073         <p>This directive specifies the list of protocols supported for a
4074             server/virtual host. The list determines the allowed protocols
4075             a client may negotiate for this server/host.</p>
4076
4077         <p>You need to set protocols if you want to extend the available
4078             protocols for a server/host. By default, only the http/1.1 protocol
4079             (which includes the compatibility with 1.0 and 0.9 clients) is
4080             allowed.</p>
4081
4082         <p>For example, if you want to support HTTP/2 for a server with TLS,
4083             specify:</p>
4084
4085         <pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
4086
4087
4088         <p>Valid protocols are <code>http/1.1</code> for http and https connections,
4089             <code>h2</code> on https connections and <code>h2c</code> for http
4090             connections. Modules may enable more protocols.</p>
4091
4092         <p>It is safe to specify protocols that are unavailable/disabled. Such
4093         protocol names will simply be ignored.</p>
4094
4095         <p>Protocols specified in base servers are inherited for virtual hosts
4096             only if the virtual host has no own Protocols directive. Or, the other
4097             way around, Protocols directives in virtual hosts replace any
4098             such directive in the base server.
4099         </p>
4100
4101
4102 <h3>See also</h3>
4103 <ul>
4104 <li><code class="directive"><a href="#protocolshonororder">ProtocolsHonorOrder</a></code></li>
4105 </ul>
4106 </div>
4107 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4108 <div class="directive-section"><h2><a name="ProtocolsHonorOrder" id="ProtocolsHonorOrder">ProtocolsHonorOrder</a> <a name="protocolshonororder" id="protocolshonororder">Directive</a><a title="Permanent link" href="#protocolshonororder" class="permalink">&para;</a></h2>
4109 <table class="directive">
4110 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines if order of Protocols determines precedence during negotiation</td></tr>
4111 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProtocolsHonorOrder On|Off</code></td></tr>
4112 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProtocolsHonorOrder On</code></td></tr>
4113 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4114 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4115 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4116 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Only available from Apache 2.4.17 and later.</td></tr>
4117 </table>
4118         <p>This directive specifies if the server should honor the order in which
4119         the <code class="directive">Protocols</code> directive lists protocols.</p>
4120
4121         <p>If configured Off, the client supplied list order of protocols has
4122             precedence over the order in the server configuration.</p>
4123
4124         <p>With <code class="directive">ProtocolsHonorOrder</code> set to <code>on</code>
4125             (default), the client ordering does not matter and only the ordering
4126             in the server settings influences the outcome of the protocol
4127             negotiation.</p>
4128
4129
4130 <h3>See also</h3>
4131 <ul>
4132 <li><code class="directive"><a href="#protocols">Protocols</a></code></li>
4133 </ul>
4134 </div>
4135 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4136 <div class="directive-section"><h2><a name="QualifyRedirectURL" id="QualifyRedirectURL">QualifyRedirectURL</a> <a name="qualifyredirecturl" id="qualifyredirecturl">Directive</a><a title="Permanent link" href="#qualifyredirecturl" class="permalink">&para;</a></h2>
4137 <table class="directive">
4138 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether the REDIRECT_URL environment variable is
4139              fully qualified</td></tr>
4140 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>QualifyRedirectURL ON|OFF</code></td></tr>
4141 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>QualifyRedirectURL OFF</code></td></tr>
4142 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
4143 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
4144 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4145 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4146 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Directive supported in 2.4.18 and later. 2.4.17 acted
4147 as if 'QualifyRedirectURL ON' was configured.</td></tr>
4148 </table>
4149     <p>This directive controls whether the server will ensure that the
4150     REDIRECT_URL environment variable is fully qualified.  By default,
4151     the variable contains the verbatim URL requested by the client,
4152     such as "/index.html".  With <code class="directive"><a href="#qualifyredirecturl on">QualifyRedirectURL ON</a></code>, the same request would result in a
4153     value such as "http://www.example.com/index.html".</p>
4154     <p>Even without this directive set, when a request is issued against a
4155     fully qualified URL, REDIRECT_URL will remain fully qualified.
4156     </p>
4157
4158 </div>
4159 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4160 <div class="directive-section"><h2><a name="RegexDefaultOptions" id="RegexDefaultOptions">RegexDefaultOptions</a> <a name="regexdefaultoptions" id="regexdefaultoptions">Directive</a><a title="Permanent link" href="#regexdefaultoptions" class="permalink">&para;</a></h2>
4161 <table class="directive">
4162 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow to configure global/default options for regexes</td></tr>
4163 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RegexDefaultOptions [none] [+|-]<var>option</var> [[+|-]<var>option</var>] ...</code></td></tr>
4164 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RegexDefaultOptions DOLLAR_ENDONLY</code></td></tr>
4165 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
4166 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4167 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4168 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Only available from Apache 2.4.30 and later.</td></tr>
4169 </table>
4170         <p>This directive adds some default behavior to ANY regular expression
4171         used afterwards.</p>
4172
4173         <p>Any option preceded by a '+' is added to the already set options.<br />
4174         Any option preceded by a '-' is removed from the already set options.<br />
4175         Any option without a '+' or a '-' will be set, removing any other
4176         already set option.<br />
4177         The <code>none</code> keyword resets any already set options.</p>
4178
4179         <p><var>option</var> can be:</p>
4180         <dl>
4181             <dt><code>ICASE</code></dt>
4182             <dd>Use a case-insensitive match.</dd>
4183
4184             <dt><code>DOTALL</code></dt>
4185             <dd>Perl's /s flag.</dd>
4186
4187             <dt><code>DOLLAR_ENDONLY</code></dt>
4188             <dd>'$' matches at end of subject string only.</dd>
4189             <dd>.</dd>
4190         </dl>
4191         <pre class="prettyprint lang-config">#
4192 RegexDefaultOptions +ICASE +DOLLAR_ENDONLY
4193 ...
4194 # Remove the ICASE option, but keep all the other already set options
4195 RegexDefaultOptions -ICASE
4196 ...
4197 # Set the default option to DOTALL, resetting any other option
4198 RegexDefaultOptions DOTALL
4199 ...
4200 # Reset all defined option
4201 RegexDefaultOptions none
4202 ...</pre>
4203
4204
4205 </div>
4206 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4207 <div class="directive-section"><h2><a name="RegisterHttpMethod" id="RegisterHttpMethod">RegisterHttpMethod</a> <a name="registerhttpmethod" id="registerhttpmethod">Directive</a><a title="Permanent link" href="#registerhttpmethod" class="permalink">&para;</a></h2>
4208 <table class="directive">
4209 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register non-standard HTTP methods</td></tr>
4210 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RegisterHttpMethod <var>method</var> [<var>method</var> [...]]</code></td></tr>
4211 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
4212 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4213 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4214 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.4.24 and later</td></tr>
4215 </table>
4216 <p>This directive may be used to register additional HTTP methods.  This is
4217 necessary if non-standard methods need to be used with directives that accept
4218 method names as parameters, or to allow particular non-standard methods to be
4219 used via proxy or CGI script when the server has been configured to only pass
4220 recognized methods to modules.</p>
4221
4222 <h3>See also</h3>
4223 <ul>
4224 <li><code class="directive"><a href="#httpprotocoloptions">HTTPProtocolOptions</a></code></li>
4225 <li><code class="directive"><a href="../mod/mod_allowmethods.html#allowmethods">AllowMethods</a></code></li>
4226 </ul>
4227 </div>
4228 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4229 <div class="directive-section"><h2><a name="RLimitCPU" id="RLimitCPU">RLimitCPU</a> <a name="rlimitcpu" id="rlimitcpu">Directive</a><a title="Permanent link" href="#rlimitcpu" class="permalink">&para;</a></h2>
4230 <table class="directive">
4231 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the CPU consumption of processes launched
4232 by Apache httpd children</td></tr>
4233 <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>
4234 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
4235 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4236 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
4237 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4238 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4239 </table>
4240     <p>Takes 1 or 2 parameters. The first parameter sets the soft
4241     resource limit for all processes and the second parameter sets
4242     the maximum resource limit. Either parameter can be a number,
4243     or <code>max</code> to indicate to the server that the limit should
4244     be set to the maximum allowed by the operating system
4245     configuration. Raising the maximum resource limit requires that
4246     the server is running as <code>root</code> or in the initial startup
4247     phase.</p>
4248
4249     <p>This applies to processes forked from Apache httpd children
4250     servicing requests, not the Apache httpd children themselves. This
4251     includes CGI scripts and SSI exec commands, but not any
4252     processes forked from the Apache httpd parent, such as piped
4253     logs.</p>
4254
4255     <p>CPU resource limits are expressed in seconds per
4256     process.</p>
4257
4258 <h3>See also</h3>
4259 <ul>
4260 <li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li>
4261 <li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li>
4262 </ul>
4263 </div>
4264 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4265 <div class="directive-section"><h2><a name="RLimitMEM" id="RLimitMEM">RLimitMEM</a> <a name="rlimitmem" id="rlimitmem">Directive</a><a title="Permanent link" href="#rlimitmem" class="permalink">&para;</a></h2>
4266 <table class="directive">
4267 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the memory consumption of processes launched
4268 by Apache httpd children</td></tr>
4269 <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>
4270 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
4271 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4272 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
4273 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4274 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4275 </table>
4276     <p>Takes 1 or 2 parameters. The first parameter sets the soft
4277     resource limit for all processes and the second parameter sets
4278     the maximum resource limit. Either parameter can be a number,
4279     or <code>max</code> to indicate to the server that the limit should
4280     be set to the maximum allowed by the operating system
4281     configuration. Raising the maximum resource limit requires that
4282     the server is running as <code>root</code> or in the initial startup
4283     phase.</p>
4284
4285     <p>This applies to processes forked from Apache httpd children
4286     servicing requests, not the Apache httpd children themselves. This
4287     includes CGI scripts and SSI exec commands, but not any
4288     processes forked from the Apache httpd parent, such as piped
4289     logs.</p>
4290
4291     <p>Memory resource limits are expressed in bytes per
4292     process.</p>
4293
4294 <h3>See also</h3>
4295 <ul>
4296 <li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li>
4297 <li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li>
4298 </ul>
4299 </div>
4300 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4301 <div class="directive-section"><h2><a name="RLimitNPROC" id="RLimitNPROC">RLimitNPROC</a> <a name="rlimitnproc" id="rlimitnproc">Directive</a><a title="Permanent link" href="#rlimitnproc" class="permalink">&para;</a></h2>
4302 <table class="directive">
4303 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of processes that can be launched by
4304 processes launched by Apache httpd children</td></tr>
4305 <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>
4306 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr>
4307 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4308 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
4309 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4310 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4311 </table>
4312     <p>Takes 1 or 2 parameters. The first parameter sets the soft
4313     resource limit for all processes, and the second parameter sets
4314     the maximum resource limit. Either parameter can be a number,
4315     or <code>max</code> to indicate to the server that the limit
4316     should be set to the maximum allowed by the operating system
4317     configuration. Raising the maximum resource limit requires that
4318     the server is running as <code>root</code> or in the initial startup
4319     phase.</p>
4320
4321     <p>This applies to processes forked from Apache httpd children
4322     servicing requests, not the Apache httpd children themselves. This
4323     includes CGI scripts and SSI exec commands, but not any
4324     processes forked from the Apache httpd parent, such as piped
4325     logs.</p>
4326
4327     <p>Process limits control the number of processes per user.</p>
4328
4329     <div class="note"><h3>Note</h3>
4330       <p>If CGI processes are <strong>not</strong> running
4331       under user ids other than the web server user id, this directive
4332       will limit the number of processes that the server itself can
4333       create. Evidence of this situation will be indicated by
4334       <strong><code>cannot fork</code></strong> messages in the
4335       <code>error_log</code>.</p>
4336     </div>
4337
4338 <h3>See also</h3>
4339 <ul>
4340 <li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li>
4341 <li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li>
4342 </ul>
4343 </div>
4344 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4345 <div class="directive-section"><h2><a name="ScriptInterpreterSource" id="ScriptInterpreterSource">ScriptInterpreterSource</a> <a name="scriptinterpretersource" id="scriptinterpretersource">Directive</a><a title="Permanent link" href="#scriptinterpretersource" class="permalink">&para;</a></h2>
4346 <table class="directive">
4347 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI
4348 scripts</td></tr>
4349 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptInterpreterSource Registry|Registry-Strict|Script</code></td></tr>
4350 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptInterpreterSource Script</code></td></tr>
4351 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4352 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
4353 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4354 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4355 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Win32 only.</td></tr>
4356 </table>
4357     <p>This directive is used to control how Apache httpd finds the
4358     interpreter used to run CGI scripts. The default setting is
4359     <code>Script</code>. This causes Apache httpd to use the interpreter pointed to
4360     by the shebang line (first line, starting with <code>#!</code>) in the
4361     script. On Win32 systems this line usually looks like:</p>
4362
4363     <pre class="prettyprint lang-perl">#!C:/Perl/bin/perl.exe</pre>
4364
4365
4366     <p>or, if <code>perl</code> is in the <code>PATH</code>, simply:</p>
4367
4368     <pre class="prettyprint lang-perl">#!perl</pre>
4369
4370
4371     <p>Setting <code>ScriptInterpreterSource Registry</code> will
4372     cause the Windows Registry tree <code>HKEY_CLASSES_ROOT</code> to be
4373     searched using the script file extension (e.g., <code>.pl</code>) as a
4374     search key. The command defined by the registry subkey
4375     <code>Shell\ExecCGI\Command</code> or, if it does not exist, by the subkey
4376     <code>Shell\Open\Command</code> is used to open the script file. If the
4377     registry keys cannot be found, Apache httpd falls back to the behavior of the
4378     <code>Script</code> option.</p>
4379
4380     <div class="warning"><h3>Security</h3>
4381     <p>Be careful when using <code>ScriptInterpreterSource
4382     Registry</code> with <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>'ed directories, because
4383     Apache httpd will try to execute <strong>every</strong> file within this
4384     directory. The <code>Registry</code> setting may cause undesired
4385     program calls on files which are typically not executed. For
4386     example, the default open command on <code>.htm</code> files on
4387     most Windows systems will execute Microsoft Internet Explorer, so
4388     any HTTP request for an <code>.htm</code> file existing within the
4389     script directory would start the browser in the background on the
4390     server. This is a good way to crash your system within a minute or
4391     so.</p>
4392     </div>
4393
4394     <p>The option <code>Registry-Strict</code> which is new in Apache HTTP Server
4395     2.0 does the same thing as <code>Registry</code> but uses only the
4396     subkey <code>Shell\ExecCGI\Command</code>. The
4397     <code>ExecCGI</code> key is not a common one. It must be
4398     configured manually in the windows registry and hence prevents
4399     accidental program calls on your system.</p>
4400
4401 </div>
4402 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4403 <div class="directive-section"><h2><a name="SeeRequestTail" id="SeeRequestTail">SeeRequestTail</a> <a name="seerequesttail" id="seerequesttail">Directive</a><a title="Permanent link" href="#seerequesttail" class="permalink">&para;</a></h2>
4404 <table class="directive">
4405 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine if mod_status displays the first 63 characters
4406 of a request or the last 63, assuming the request itself is greater than
4407 63 chars.</td></tr>
4408 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SeeRequestTail On|Off</code></td></tr>
4409 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SeeRequestTail Off</code></td></tr>
4410 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
4411 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4412 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4413 </table>
4414     <p>mod_status with <code>ExtendedStatus On</code>
4415     displays the actual request being handled.
4416     For historical purposes, only 63 characters of the request
4417     are actually stored for display purposes. This directive
4418     controls whether the 1st 63 characters are stored (the previous
4419     behavior and the default) or if the last 63 characters are. This
4420     is only applicable, of course, if the length of the request is
4421     64 characters or greater.</p>
4422
4423     <p>If Apache httpd is handling <code>GET&nbsp;/disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg&nbsp;HTTP/1.1</code> mod_status displays as follows:
4424     </p>
4425
4426     <table class="bordered">
4427       <tr>
4428         <th>Off (default)</th>
4429         <td>GET&nbsp;/disk1/storage/apache/htdocs/images/imagestore1/food/apples</td>
4430       </tr>
4431       <tr>
4432         <th>On</th>
4433         <td>orage/apache/htdocs/images/imagestore1/food/apples.jpg&nbsp;HTTP/1.1</td>
4434       </tr>
4435     </table>
4436
4437
4438 </div>
4439 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4440 <div class="directive-section"><h2><a name="ServerAdmin" id="ServerAdmin">ServerAdmin</a> <a name="serveradmin" id="serveradmin">Directive</a><a title="Permanent link" href="#serveradmin" class="permalink">&para;</a></h2>
4441 <table class="directive">
4442 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Email address that the server includes in error
4443 messages sent to the client</td></tr>
4444 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAdmin <var>email-address</var>|<var>URL</var></code></td></tr>
4445 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4446 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4447 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4448 </table>
4449     <p>The <code class="directive">ServerAdmin</code> sets the contact address
4450     that the server includes in any error messages it returns to the
4451     client. If the <code>httpd</code> doesn't recognize the supplied argument
4452     as an URL, it
4453     assumes, that it's an <var>email-address</var> and prepends it with
4454     <code>mailto:</code> in hyperlink targets. However, it's recommended to
4455     actually use an email address, since there are a lot of CGI scripts that
4456     make that assumption. If you want to use an URL, it should point to another
4457     server under your control. Otherwise users may not be able to contact you in
4458     case of errors.</p>
4459
4460     <p>It may be worth setting up a dedicated address for this, e.g.</p>
4461
4462     <pre class="prettyprint lang-config">ServerAdmin www-admin@foo.example.com</pre>
4463
4464     <p>as users do not always mention that they are talking about the
4465     server!</p>
4466
4467 </div>
4468 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4469 <div class="directive-section"><h2><a name="ServerAlias" id="ServerAlias">ServerAlias</a> <a name="serveralias" id="serveralias">Directive</a><a title="Permanent link" href="#serveralias" class="permalink">&para;</a></h2>
4470 <table class="directive">
4471 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Alternate names for a host used when matching requests
4472 to name-virtual hosts</td></tr>
4473 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAlias <var>hostname</var> [<var>hostname</var>] ...</code></td></tr>
4474 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr>
4475 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4476 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4477 </table>
4478     <p>The <code class="directive">ServerAlias</code> directive sets the
4479     alternate names for a host, for use with <a href="../vhosts/name-based.html">name-based virtual hosts</a>. The
4480     <code class="directive">ServerAlias</code> may include wildcards, if appropriate.</p>
4481
4482     <pre class="prettyprint lang-config">&lt;VirtualHost *:80&gt;
4483   ServerName server.example.com
4484   ServerAlias server server2.example.com server2
4485   ServerAlias *.example.com
4486   UseCanonicalName Off
4487   # ...
4488 &lt;/VirtualHost&gt;</pre>
4489
4490
4491     <p>Name-based virtual hosts for the best-matching set of  <code class="directive"><a href="#virtualhost">&lt;virtualhost&gt;</a></code>s are processed
4492     in the order they appear in the configuration.  The first matching <code class="directive"><a href="#servername">ServerName</a></code> or <code class="directive"><a href="#serveralias">ServerAlias</a></code> is used, with no different precedence for wildcards
4493     (nor for ServerName vs. ServerAlias).  </p>
4494
4495     <p>The complete list of names in the <code class="directive"><a href="#virtualhost">&lt;VirtualHost&gt;</a></code>
4496     directive are treated just like a (non wildcard)
4497     <code class="directive">ServerAlias</code>.</p>
4498
4499
4500 <h3>See also</h3>
4501 <ul>
4502 <li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li>
4503 <li><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></li>
4504 </ul>
4505 </div>
4506 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4507 <div class="directive-section"><h2><a name="ServerName" id="ServerName">ServerName</a> <a name="servername" id="servername">Directive</a><a title="Permanent link" href="#servername" class="permalink">&para;</a></h2>
4508 <table class="directive">
4509 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hostname and port that the server uses to identify
4510 itself</td></tr>
4511 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerName [<var>scheme</var>://]<var>domain-name</var>|<var>ip-address</var>[:<var>port</var>]</code></td></tr>
4512 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4513 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4514 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4515 </table>
4516     <p>The <code class="directive">ServerName</code> directive sets the
4517     request scheme, hostname and port that the server uses to identify itself.
4518     </p>
4519
4520     <p><code class="directive">ServerName</code> is used (possibly
4521     in conjunction with <code class="directive"><a href="#serveralias">ServerAlias</a></code>) to uniquely
4522     identify a virtual host, when using <a href="../vhosts/name-based.html">name-based virtual hosts</a>.</p>
4523
4524     <p>Additionally, this is used when
4525     creating self-referential redirection URLs when
4526     <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> is set to a non-default
4527     value.</p>
4528
4529     <p>For example, if the name of the
4530     machine hosting the web server is <code>simple.example.com</code>,
4531     but the machine also has the DNS alias <code>www.example.com</code>
4532     and you wish the web server to be so identified, the following
4533     directive should be used:</p>
4534
4535     <pre class="prettyprint lang-config">ServerName www.example.com</pre>
4536
4537
4538     <p>The <code class="directive">ServerName</code> directive
4539     may appear anywhere within the definition of a server. However,
4540     each appearance overrides the previous appearance (within that
4541     server).</p>
4542
4543     <p>If no <code class="directive">ServerName</code> is specified, the
4544     server attempts to deduce the client visible hostname by first asking
4545     the operating system for the system hostname, and if that fails,
4546     performing a reverse lookup on an IP address present on the system.</p>
4547
4548     <p>If no port is specified in the
4549     <code class="directive">ServerName</code>, then the server will use the
4550     port from the incoming request. For optimal reliability and
4551     predictability, you should specify an explicit hostname and port
4552     using the <code class="directive">ServerName</code> directive.</p>
4553
4554     <p>If you are using <a href="../vhosts/name-based.html">name-based virtual hosts</a>,
4555     the <code class="directive">ServerName</code> inside a
4556     <code class="directive"><a href="#virtualhost">&lt;VirtualHost&gt;</a></code>
4557     section specifies what hostname must appear in the request's
4558     <code>Host:</code> header to match this virtual host.</p>
4559
4560     <p>Sometimes, the server runs behind a device that processes SSL,
4561     such as a reverse proxy, load balancer or SSL offload
4562     appliance. When this is the case, specify the
4563     <code>https://</code> scheme and the port number to which the
4564     clients connect in the <code class="directive">ServerName</code> directive
4565     to make sure that the server generates the correct
4566     self-referential URLs.
4567     </p>
4568
4569     <p>See the description of the
4570     <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> and
4571     <code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code> directives for
4572     settings which determine whether self-referential URLs (e.g., by the
4573     <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> module) will refer to the
4574     specified port, or to the port number given in the client's request.
4575     </p>
4576
4577     <div class="warning">
4578     <p>Failure to set <code class="directive">ServerName</code> to a name that
4579     your server can resolve to an IP address will result in a startup
4580     warning. <code>httpd</code> will then use whatever hostname it can
4581     determine, using the system's <code>hostname</code> command. This
4582     will almost never be the hostname you actually want.</p>
4583     <div class="example"><p><code>
4584     httpd: Could not reliably determine the server's fully qualified domain name, using rocinante.local for ServerName
4585     </code></p></div>
4586     </div>
4587
4588
4589 <h3>See also</h3>
4590 <ul>
4591 <li><a href="../dns-caveats.html">Issues Regarding DNS and
4592     Apache HTTP Server</a></li>
4593 <li><a href="../vhosts/">Apache HTTP Server virtual host
4594     documentation</a></li>
4595 <li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li>
4596 <li><code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code></li>
4597 <li><code class="directive"><a href="#serveralias">ServerAlias</a></code></li>
4598 </ul>
4599 </div>
4600 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4601 <div class="directive-section"><h2><a name="ServerPath" id="ServerPath">ServerPath</a> <a name="serverpath" id="serverpath">Directive</a><a title="Permanent link" href="#serverpath" class="permalink">&para;</a></h2>
4602 <table class="directive">
4603 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Legacy URL pathname for a name-based virtual host that
4604 is accessed by an incompatible browser</td></tr>
4605 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerPath <var>URL-path</var></code></td></tr>
4606 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr>
4607 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4608 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4609 </table>
4610     <p>The <code class="directive">ServerPath</code> directive sets the legacy
4611     URL pathname for a host, for use with <a href="../vhosts/">name-based virtual hosts</a>.</p>
4612
4613 <h3>See also</h3>
4614 <ul>
4615 <li><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></li>
4616 </ul>
4617 </div>
4618 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4619 <div class="directive-section"><h2><a name="ServerRoot" id="ServerRoot">ServerRoot</a> <a name="serverroot" id="serverroot">Directive</a><a title="Permanent link" href="#serverroot" class="permalink">&para;</a></h2>
4620 <table class="directive">
4621 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the server installation</td></tr>
4622 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerRoot <var>directory-path</var></code></td></tr>
4623 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerRoot /usr/local/apache</code></td></tr>
4624 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
4625 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4626 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4627 </table>
4628     <p>The <code class="directive">ServerRoot</code> directive sets the
4629     directory in which the server lives. Typically it will contain the
4630     subdirectories <code>conf/</code> and <code>logs/</code>. Relative
4631     paths in other configuration directives (such as <code class="directive"><a href="#include">Include</a></code> or <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>, for example) are taken as
4632     relative to this directory.</p>
4633
4634     <pre class="prettyprint lang-config">ServerRoot "/home/httpd"</pre>
4635
4636
4637     <p>The default location of <code class="directive">ServerRoot</code> may be
4638     modified by using the <code>--prefix</code> argument to
4639     <a href="../programs/configure.html"><code>configure</code></a>, and
4640     most third-party distributions of the server have a different
4641     default location from the one listed above.</p>
4642
4643
4644 <h3>See also</h3>
4645 <ul>
4646 <li><a href="../invoking.html">the <code>-d</code>
4647     option to <code>httpd</code></a></li>
4648 <li><a href="../misc/security_tips.html#serverroot">the
4649     security tips</a> for information on how to properly set
4650     permissions on the <code class="directive">ServerRoot</code></li>
4651 </ul>
4652 </div>
4653 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4654 <div class="directive-section"><h2><a name="ServerSignature" id="ServerSignature">ServerSignature</a> <a name="serversignature" id="serversignature">Directive</a><a title="Permanent link" href="#serversignature" class="permalink">&para;</a></h2>
4655 <table class="directive">
4656 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the footer on server-generated documents</td></tr>
4657 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerSignature On|Off|EMail</code></td></tr>
4658 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerSignature Off</code></td></tr>
4659 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4660 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
4661 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4662 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4663 </table>
4664     <p>The <code class="directive">ServerSignature</code> directive allows the
4665     configuration of a trailing footer line under server-generated
4666     documents (error messages, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> ftp directory
4667     listings, <code class="module"><a href="../mod/mod_info.html">mod_info</a></code> output, ...). The reason why you
4668     would want to enable such a footer line is that in a chain of proxies,
4669     the user often has no possibility to tell which of the chained servers
4670     actually produced a returned error message.</p>
4671
4672     <p>The <code>Off</code>
4673     setting, which is the default, suppresses the footer line (and is
4674     therefore compatible with the behavior of Apache-1.2 and
4675     below). The <code>On</code> setting simply adds a line with the
4676     server version number and <code class="directive"><a href="#servername">ServerName</a></code> of the serving virtual host,
4677     and the <code>EMail</code> setting additionally creates a
4678     "mailto:" reference to the <code class="directive"><a href="#serveradmin">ServerAdmin</a></code> of the referenced
4679     document.</p>
4680
4681     <p>After version 2.0.44, the details of the server version number
4682     presented are controlled by the <code class="directive"><a href="#servertokens">ServerTokens</a></code> directive.</p>
4683
4684 <h3>See also</h3>
4685 <ul>
4686 <li><code class="directive"><a href="#servertokens">ServerTokens</a></code></li>
4687 </ul>
4688 </div>
4689 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4690 <div class="directive-section"><h2><a name="ServerTokens" id="ServerTokens">ServerTokens</a> <a name="servertokens" id="servertokens">Directive</a><a title="Permanent link" href="#servertokens" class="permalink">&para;</a></h2>
4691 <table class="directive">
4692 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the <code>Server</code> HTTP response
4693 header</td></tr>
4694 <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>
4695 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerTokens Full</code></td></tr>
4696 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
4697 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4698 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4699 </table>
4700     <p>This directive controls whether <code>Server</code> response
4701     header field which is sent back to clients includes a
4702     description of the generic OS-type of the server as well as
4703     information about compiled-in modules.</p>
4704
4705     <dl>
4706       <dt><code>ServerTokens Full</code> (or not specified)</dt>
4707
4708       <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2
4709       (Unix) PHP/4.2.2 MyMod/1.2</code></dd>
4710
4711       <dt><code>ServerTokens Prod[uctOnly]</code></dt>
4712
4713       <dd>Server sends (<em>e.g.</em>): <code>Server:
4714       Apache</code></dd>
4715
4716       <dt><code>ServerTokens Major</code></dt>
4717
4718       <dd>Server sends (<em>e.g.</em>): <code>Server:
4719       Apache/2</code></dd>
4720
4721       <dt><code>ServerTokens Minor</code></dt>
4722
4723       <dd>Server sends (<em>e.g.</em>): <code>Server:
4724       Apache/2.4</code></dd>
4725
4726       <dt><code>ServerTokens Min[imal]</code></dt>
4727
4728       <dd>Server sends (<em>e.g.</em>): <code>Server:
4729       Apache/2.4.2</code></dd>
4730
4731       <dt><code>ServerTokens OS</code></dt>
4732
4733       <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2
4734       (Unix)</code></dd>
4735
4736     </dl>
4737
4738     <p>This setting applies to the entire server, and cannot be
4739     enabled or disabled on a virtualhost-by-virtualhost basis.</p>
4740
4741     <p>After version 2.0.44, this directive also controls the
4742     information presented by the <code class="directive"><a href="#serversignature">ServerSignature</a></code> directive.</p>
4743
4744     <div class="note">Setting <code class="directive">ServerTokens</code> to less than
4745     <code>minimal</code> is not recommended because it makes it more
4746     difficult to debug interoperational problems. Also note that
4747     disabling the Server: header does nothing at all to make your
4748     server more secure. The idea of "security through obscurity"
4749     is a myth and leads to a false sense of safety.</div>
4750
4751 <h3>See also</h3>
4752 <ul>
4753 <li><code class="directive"><a href="#serversignature">ServerSignature</a></code></li>
4754 </ul>
4755 </div>
4756 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4757 <div class="directive-section"><h2><a name="SetHandler" id="SetHandler">SetHandler</a> <a name="sethandler" id="sethandler">Directive</a><a title="Permanent link" href="#sethandler" class="permalink">&para;</a></h2>
4758 <table class="directive">
4759 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be processed by a
4760 handler</td></tr>
4761 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetHandler <var>handler-name</var>|none|<var>expression</var></code></td></tr>
4762 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4763 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
4764 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4765 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4766 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.5 and later</td></tr>
4767 </table>
4768     <p>When placed into an <code>.htaccess</code> file or a
4769     <code class="directive"><a href="#directory">&lt;Directory&gt;</a></code> or
4770     <code class="directive"><a href="#location">&lt;Location&gt;</a></code>
4771     section, this directive forces all matching files to be parsed
4772     through the <a href="../handler.html">handler</a> given by
4773     <var>handler-name</var>. For example, if you had a directory you
4774     wanted to be parsed entirely as imagemap rule files, regardless
4775     of extension, you might put the following into an
4776     <code>.htaccess</code> file in that directory:</p>
4777
4778     <pre class="prettyprint lang-config">SetHandler imap-file</pre>
4779
4780
4781     <p>Another example: if you wanted to have the server display a
4782     status report whenever a URL of
4783     <code>http://servername/status</code> was called, you might put
4784     the following into <code>httpd.conf</code>:</p>
4785
4786     <pre class="prettyprint lang-config">&lt;Location "/status"&gt;
4787   SetHandler server-status
4788 &lt;/Location&gt;</pre>
4789
4790
4791     <p>You could also use this directive to configure a particular
4792     handler for files with a particular file extension. For example:</p>
4793
4794     <pre class="prettyprint lang-config">&lt;FilesMatch "\.php$"&gt;
4795     SetHandler application/x-httpd-php
4796 &lt;/FilesMatch&gt;</pre>
4797
4798
4799     <p>String-valued expressions can be used to reference per-request
4800     variables, including backreferences to named regular expressions:</p>
4801
4802     <pre class="prettyprint lang-config">&lt;LocationMatch ^/app/(?&lt;sub&gt;[^/]+)/&gt;
4803      SetHandler "proxy:unix:/var/run/app_%{env:MATCH_sub}.sock|fcgi://localhost:8080"
4804 &lt;/LocationMatch&gt;</pre>
4805
4806
4807     <p>You can override an earlier defined <code class="directive">SetHandler</code>
4808     directive by using the value <code>None</code>.</p>
4809
4810     <div class="note"><h3>Note</h3>
4811     <p>Because <code class="directive">SetHandler</code> overrides default handlers,
4812     normal behavior such as handling of URLs ending in a slash (/) as
4813     directories or index files is suppressed.</p></div>
4814
4815 <h3>See also</h3>
4816 <ul>
4817 <li><code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code></li>
4818 </ul>
4819 </div>
4820 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4821 <div class="directive-section"><h2><a name="SetInputFilter" id="SetInputFilter">SetInputFilter</a> <a name="setinputfilter" id="setinputfilter">Directive</a><a title="Permanent link" href="#setinputfilter" class="permalink">&para;</a></h2>
4822 <table class="directive">
4823 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process client requests and POST
4824 input</td></tr>
4825 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetInputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr>
4826 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4827 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
4828 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4829 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4830 </table>
4831     <p>The <code class="directive">SetInputFilter</code> directive sets the
4832     filter or filters which will process client requests and POST
4833     input when they are received by the server. This is in addition to
4834     any filters defined elsewhere, including the
4835     <code class="directive"><a href="../mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>
4836     directive.</p>
4837
4838     <p>If more than one filter is specified, they must be separated
4839     by semicolons in the order in which they should process the
4840     content.</p>
4841
4842 <h3>See also</h3>
4843 <ul>
4844 <li><a href="../filter.html">Filters</a> documentation</li>
4845 </ul>
4846 </div>
4847 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4848 <div class="directive-section"><h2><a name="SetOutputFilter" id="SetOutputFilter">SetOutputFilter</a> <a name="setoutputfilter" id="setoutputfilter">Directive</a><a title="Permanent link" href="#setoutputfilter" class="permalink">&para;</a></h2>
4849 <table class="directive">
4850 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process responses from the
4851 server</td></tr>
4852 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetOutputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr>
4853 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
4854 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
4855 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4856 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4857 </table>
4858     <p>The <code class="directive">SetOutputFilter</code> directive sets the filters
4859     which will process responses from the server before they are
4860     sent to the client. This is in addition to any filters defined
4861     elsewhere, including the
4862     <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code>
4863     directive.</p>
4864
4865     <p>For example, the following configuration will process all files
4866     in the <code>/www/data/</code> directory for server-side
4867     includes.</p>
4868
4869     <pre class="prettyprint lang-config">&lt;Directory "/www/data/"&gt;
4870   SetOutputFilter INCLUDES
4871 &lt;/Directory&gt;</pre>
4872
4873
4874     <p>If more than one filter is specified, they must be separated
4875     by semicolons in the order in which they should process the
4876     content.</p>
4877
4878 <h3>See also</h3>
4879 <ul>
4880 <li><a href="../filter.html">Filters</a> documentation</li>
4881 </ul>
4882 </div>
4883 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4884 <div class="directive-section"><h2><a name="StrictHostCheck" id="StrictHostCheck">StrictHostCheck</a> <a name="stricthostcheck" id="stricthostcheck">Directive</a><a title="Permanent link" href="#stricthostcheck" class="permalink">&para;</a></h2>
4885 <table class="directive">
4886 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether the server requires the requested hostname be
4887              listed enumerated in the virtual host handling the request
4888              </td></tr>
4889 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>StrictHostCheck ON|OFF</code></td></tr>
4890 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>StrictHostCheck OFF</code></td></tr>
4891 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4892 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4893 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4894 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Added in 2.5.1</td></tr>
4895 </table>
4896     <p>By default, the server will respond to requests for any hostname,
4897     including requests addressed to unexpected or unconfigured hostnames.
4898     While this is convenient, it is sometimes desirable to limit what hostnames
4899     a backend application handles since it will often generate self-referential
4900     responses.</p>
4901
4902     <p>By setting <code class="directive">StrictHostCheck</code> to <em>ON</em>,
4903     the server will return an HTTP 400 error if the requested hostname
4904     hasn't been explicitly listed by either <code class="directive"><a href="#servername">ServerName</a></code> or <code class="directive"><a href="#serveralias">ServerAlias</a></code> in the virtual host that best matches the
4905     details of the incoming connection.</p>
4906
4907    <p>This directive also allows matching of the requested hostname to hostnames
4908    specified within the opening <code class="directive"><a href="#virtualhost">VirtualHost</a></code>
4909    tag, which is a relatively obscure configuration mechanism that acts like
4910    additional <code class="directive"><a href="#serveralias">ServerAlias</a></code> entries.</p>
4911
4912    <p>This directive has no affect in non-default virtual hosts. The value
4913    inherited from the global server configuration, or the default virtualhost
4914    for the ip:port the underlying connection, determine the effective value.</p>
4915
4916 </div>
4917 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4918 <div class="directive-section"><h2><a name="TimeOut" id="TimeOut">TimeOut</a> <a name="timeout" id="timeout">Directive</a><a title="Permanent link" href="#timeout" class="permalink">&para;</a></h2>
4919 <table class="directive">
4920 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for
4921 certain events before failing a request</td></tr>
4922 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TimeOut <var>time-interval</var>[s]</code></td></tr>
4923 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>TimeOut 60</code></td></tr>
4924 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4925 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4926 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4927 </table>
4928     <p>The <code class="directive">TimeOut</code> directive defines the length
4929     of time Apache httpd will wait for I/O in various circumstances:</p>
4930
4931     <ul>
4932       <li><p>When reading data from the client, the length of time to
4933       wait for a TCP packet to arrive if the read buffer is
4934       empty.</p>
4935       <p> For initial data on a new connection, this directive doesn't
4936       take effect until after any configured <code class="directive"><a href="#acceptfilter">
4937       AcceptFilter</a></code> has passed the new connection to the server.</p>
4938       </li>
4939
4940       <li>When writing data to the client, the length of time to wait
4941       for an acknowledgement of a packet if the send buffer is
4942       full.</li>
4943
4944       <li>In <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> and <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code>,
4945       the length of time to wait for any individual block of output
4946       from a CGI script.</li>
4947
4948       <li>In <code class="module"><a href="../mod/mod_ext_filter.html">mod_ext_filter</a></code>, the length of time to
4949       wait for output from a filtering process.</li>
4950
4951       <li>In <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, the default timeout value if
4952       <code class="directive"><a href="../mod/mod_proxy.html#proxytimeout">ProxyTimeout</a></code> is not
4953       configured.</li>
4954     </ul>
4955
4956
4957 </div>
4958 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4959 <div class="directive-section"><h2><a name="TraceEnable" id="TraceEnable">TraceEnable</a> <a name="traceenable" id="traceenable">Directive</a><a title="Permanent link" href="#traceenable" class="permalink">&para;</a></h2>
4960 <table class="directive">
4961 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines the behavior on <code>TRACE</code> requests</td></tr>
4962 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TraceEnable <var>[on|off|extended]</var></code></td></tr>
4963 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>TraceEnable on</code></td></tr>
4964 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
4965 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
4966 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
4967 </table>
4968     <p>This directive overrides the behavior of <code>TRACE</code> for both
4969     the core server and <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>.  The default
4970     <code>TraceEnable on</code> permits <code>TRACE</code> requests per
4971     RFC 2616, which disallows any request body to accompany the request.
4972     <code>TraceEnable off</code> causes the core server and
4973     <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> to return a <code>405</code> (Method not
4974     allowed) error to the client.</p>
4975
4976     <p>Finally, for testing and diagnostic purposes only, request
4977     bodies may be allowed using the non-compliant <code>TraceEnable
4978     extended</code> directive.  The core (as an origin server) will
4979     restrict the request body to 64Kb (plus 8Kb for chunk headers if
4980     <code>Transfer-Encoding: chunked</code> is used).  The core will
4981     reflect the full headers and all chunk headers with the response
4982     body.  As a proxy server, the request body is not restricted to 64Kb.</p>
4983
4984     <div class="note"><h3>Note</h3>
4985
4986     <p>Despite claims to the contrary, enabling the <code>TRACE</code>
4987     method does not expose any security vulnerability in Apache httpd.
4988     The <code>TRACE</code> method is defined by the HTTP/1.1
4989     specification and implementations are expected to support it.</p>
4990
4991     </div>
4992
4993 </div>
4994 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
4995 <div class="directive-section"><h2><a name="UnDefine" id="UnDefine">UnDefine</a> <a name="undefine" id="undefine">Directive</a><a title="Permanent link" href="#undefine" class="permalink">&para;</a></h2>
4996 <table class="directive">
4997 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine the existence of a variable</td></tr>
4998 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UnDefine <var>parameter-name</var></code></td></tr>
4999 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
5000 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
5001 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
5002 </table>
5003     <p>Undoes the effect of a <code class="directive"><a href="#define">Define</a></code> or
5004     of passing a <code>-D</code> argument to <code class="program"><a href="../programs/httpd.html">httpd</a></code>.</p>
5005     <p>This directive can be used to toggle the use of <code class="directive"><a href="#ifdefine">&lt;IfDefine&gt;</a></code> sections without needing to alter
5006     <code>-D</code> arguments in any startup scripts.</p>
5007     <p>While this directive is supported in virtual host context,
5008        the changes it makes are visible to any later configuration
5009        directives, beyond any enclosing virtual host.</p>
5010
5011 <h3>See also</h3>
5012 <ul>
5013 <li><code class="directive"><a href="#define">Define</a></code></li>
5014 <li><code class="directive"><a href="#ifdefine">IfDefine</a></code></li>
5015 </ul>
5016 </div>
5017 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
5018 <div class="directive-section"><h2><a name="UseCanonicalName" id="UseCanonicalName">UseCanonicalName</a> <a name="usecanonicalname" id="usecanonicalname">Directive</a><a title="Permanent link" href="#usecanonicalname" class="permalink">&para;</a></h2>
5019 <table class="directive">
5020 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures how the server determines its own name and
5021 port</td></tr>
5022 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UseCanonicalName On|Off|DNS</code></td></tr>
5023 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>UseCanonicalName Off</code></td></tr>
5024 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
5025 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
5026 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
5027 </table>
5028     <p>In many situations Apache httpd must construct a <em>self-referential</em>
5029     URL -- that is, a URL that refers back to the same server. With
5030     <code>UseCanonicalName On</code> Apache httpd will use the hostname and port
5031     specified in the <code class="directive"><a href="#servername">ServerName</a></code>
5032     directive to construct the canonical name for the server. This name
5033     is used in all self-referential URLs, and for the values of
5034     <code>SERVER_NAME</code> and <code>SERVER_PORT</code> in CGIs.</p>
5035
5036     <p>With <code>UseCanonicalName Off</code> Apache httpd will form
5037     self-referential URLs using the hostname and port supplied by
5038     the client if any are supplied (otherwise it will use the
5039     canonical name, as defined above). These values are the same
5040     that are used to implement <a href="../vhosts/name-based.html">name-based virtual hosts</a>
5041     and are available with the same clients. The CGI variables
5042     <code>SERVER_NAME</code> and <code>SERVER_PORT</code> will be
5043     constructed from the client supplied values as well.</p>
5044
5045     <p>An example where this may be useful is on an intranet server
5046     where you have users connecting to the machine using short
5047     names such as <code>www</code>. You'll notice that if the users
5048     type a shortname and a URL which is a directory, such as
5049     <code>http://www/splat</code>, <em>without the trailing
5050     slash</em>, then Apache httpd will redirect them to
5051     <code>http://www.example.com/splat/</code>. If you have
5052     authentication enabled, this will cause the user to have to
5053     authenticate twice (once for <code>www</code> and once again
5054     for <code>www.example.com</code> -- see <a href="http://wiki.apache.org/httpd/FAQ#Why_does_Apache_ask_for_my_password_twice_before_serving_a_file.3F">
5055     the FAQ on this subject for more information</a>). But if
5056     <code class="directive">UseCanonicalName</code> is set <code>Off</code>, then
5057     Apache httpd will redirect to <code>http://www/splat/</code>.</p>
5058
5059     <p>There is a third option, <code>UseCanonicalName DNS</code>,
5060     which is intended for use with mass IP-based virtual hosting to
5061     support ancient clients that do not provide a
5062     <code>Host:</code> header. With this option, Apache httpd does a
5063     reverse DNS lookup on the server IP address that the client
5064     connected to in order to work out self-referential URLs.</p>
5065
5066     <div class="warning"><h3>Warning</h3>
5067     <p>If CGIs make assumptions about the values of <code>SERVER_NAME</code>,
5068     they may be broken by this option. The client is essentially free
5069     to give whatever value they want as a hostname. But if the CGI is
5070     only using <code>SERVER_NAME</code> to construct self-referential URLs,
5071     then it should be just fine.</p>
5072     </div>
5073
5074 <h3>See also</h3>
5075 <ul>
5076 <li><code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code></li>
5077 <li><code class="directive"><a href="#servername">ServerName</a></code></li>
5078 <li><code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code></li>
5079 </ul>
5080 </div>
5081 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
5082 <div class="directive-section"><h2><a name="UseCanonicalPhysicalPort" id="UseCanonicalPhysicalPort">UseCanonicalPhysicalPort</a> <a name="usecanonicalphysicalport" id="usecanonicalphysicalport">Directive</a><a title="Permanent link" href="#usecanonicalphysicalport" class="permalink">&para;</a></h2>
5083 <table class="directive">
5084 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures how the server determines its own port</td></tr>
5085 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UseCanonicalPhysicalPort On|Off</code></td></tr>
5086 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>UseCanonicalPhysicalPort Off</code></td></tr>
5087 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
5088 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
5089 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
5090 </table>
5091     <p>In many situations Apache httpd must construct a <em>self-referential</em>
5092     URL -- that is, a URL that refers back to the same server. With
5093     <code>UseCanonicalPhysicalPort On</code>, Apache httpd will, when
5094     constructing the canonical port for the server to honor
5095     the <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> directive,
5096     provide the actual physical port number being used by this request
5097     as a potential port. With <code>UseCanonicalPhysicalPort Off</code>,
5098     Apache httpd will not ever use the actual physical port number, instead
5099     relying on all configured information to construct a valid port number.</p>
5100
5101     <div class="note"><h3>Note</h3>
5102     <p>The ordering of the lookup when the physical port is used is as
5103     follows:</p>
5104      <dl>
5105      <dt><code>UseCanonicalName Off | DNS</code></dt>
5106      <dd>
5107      <ol>
5108       <li>Parsed port from <code>Host:</code> header</li>
5109       <li>Physical port (only with <code class="directive">UseCanonicalPhysicalPort</code> ON)</li>
5110       <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li>
5111       <li>Default port</li>
5112      </ol>
5113      </dd>
5114      <dt><code>UseCanonicalName On</code></dt>
5115      <dd>
5116      <ol>
5117       <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li>
5118       <li>Physical port (only with <code class="directive">UseCanonicalPhysicalPort</code> ON)</li>
5119       <li>Default port</li>
5120      </ol>
5121      </dd>
5122     </dl>
5123
5124     <p>Only with <code>UseCanonicalPhysicalPort On</code>, the
5125     physical ports are included in the search.</p>
5126     </div>
5127
5128
5129 <h3>See also</h3>
5130 <ul>
5131 <li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li>
5132 <li><code class="directive"><a href="#servername">ServerName</a></code></li>
5133 <li><code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code></li>
5134 </ul>
5135 </div>
5136 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
5137 <div class="directive-section"><h2><a name="VirtualHost" id="VirtualHost">&lt;VirtualHost&gt;</a> <a name="virtualhost" id="virtualhost">Directive</a><a title="Permanent link" href="#virtualhost" class="permalink">&para;</a></h2>
5138 <table class="directive">
5139 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only to a specific
5140 hostname or IP address</td></tr>
5141 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;VirtualHost
5142     <var>addr</var>[:<var>port</var>] [<var>addr</var>[:<var>port</var>]]
5143     ...&gt; ... &lt;/VirtualHost&gt;</code></td></tr>
5144 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
5145 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
5146 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
5147 </table>
5148     <p><code class="directive">&lt;VirtualHost&gt;</code> and
5149     <code>&lt;/VirtualHost&gt;</code> are used to enclose a group of
5150     directives that will apply only to a particular virtual host. Any
5151     directive that is allowed in a virtual host context may be
5152     used. When the server receives a request for a document on a
5153     particular virtual host, it uses the configuration directives
5154     enclosed in the <code class="directive">&lt;VirtualHost&gt;</code>
5155     section. <var>Addr</var> can be any of the following, optionally followed by
5156     a colon and a port number (or *):</p>
5157
5158     <ul>
5159       <li>The IP address of the virtual host;</li>
5160
5161       <li>A fully qualified domain name for the IP address of the
5162       virtual host (not recommended);</li>
5163
5164       <li>The character <code>*</code>, which acts as a wildcard and matches
5165       any IP address.</li>
5166
5167       <li>The string <code>_default_</code>, which is an alias for <code>*</code></li>
5168
5169     </ul>
5170
5171     <pre class="prettyprint lang-config">&lt;VirtualHost 10.1.2.3:80&gt;
5172   ServerAdmin webmaster@host.example.com
5173   DocumentRoot "/www/docs/host.example.com"
5174   ServerName host.example.com
5175   ErrorLog "logs/host.example.com-error_log"
5176   TransferLog "logs/host.example.com-access_log"
5177 &lt;/VirtualHost&gt;</pre>
5178
5179
5180
5181     <p>IPv6 addresses must be specified in square brackets because
5182     the optional port number could not be determined otherwise.  An
5183     IPv6 example is shown below:</p>
5184
5185     <pre class="prettyprint lang-config">&lt;VirtualHost [2001:db8::a00:20ff:fea7:ccea]:80&gt;
5186   ServerAdmin webmaster@host.example.com
5187   DocumentRoot "/www/docs/host.example.com"
5188   ServerName host.example.com
5189   ErrorLog "logs/host.example.com-error_log"
5190   TransferLog "logs/host.example.com-access_log"
5191 &lt;/VirtualHost&gt;</pre>
5192
5193
5194     <p>Each Virtual Host must correspond to a different IP address,
5195     different port number, or a different host name for the server,
5196     in the former case the server machine must be configured to
5197     accept IP packets for multiple addresses. (If the machine does
5198     not have multiple network interfaces, then this can be
5199     accomplished with the <code>ifconfig alias</code> command -- if
5200     your OS supports it).</p>
5201
5202     <div class="note"><h3>Note</h3>
5203     <p>The use of <code class="directive">&lt;VirtualHost&gt;</code> does
5204     <strong>not</strong> affect what addresses Apache httpd listens on. You
5205     may need to ensure that Apache httpd is listening on the correct addresses
5206     using <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>.</p>
5207     </div>
5208
5209     <p>A <code class="directive"><a href="#servername">ServerName</a></code> should be
5210     specified inside each <code class="directive">&lt;VirtualHost&gt;</code> block. If it is absent, the
5211     <code class="directive"><a href="#servername">ServerName</a></code> from the "main"
5212     server configuration will be inherited.</p>
5213
5214     <p>When a request is received, the server first maps it to the best matching
5215     <code class="directive">&lt;VirtualHost&gt;</code> based on the local
5216     IP address and port combination only.  Non-wildcards have a higher
5217     precedence. If no match based on IP and port occurs at all, the
5218     "main" server configuration is used.</p>
5219
5220     <p>If multiple virtual hosts contain the best matching IP address and port,
5221     the server selects from these virtual hosts the best match based on the
5222     requested hostname.  If no matching name-based virtual host is found,
5223     then the first listed virtual host that matched the IP address will be
5224     used.  As a consequence, the first listed virtual host for a given IP address
5225     and port combination is the default virtual host for that IP and port
5226     combination.</p>
5227
5228     <div class="warning"><h3>Security</h3>
5229     <p>See the <a href="../misc/security_tips.html">security tips</a>
5230     document for details on why your security could be compromised if the
5231     directory where log files are stored is writable by anyone other
5232     than the user that starts the server.</p>
5233     </div>
5234
5235 <h3>See also</h3>
5236 <ul>
5237 <li><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></li>
5238 <li><a href="../dns-caveats.html">Issues Regarding DNS and
5239     Apache HTTP Server</a></li>
5240 <li><a href="../bind.html">Setting
5241     which addresses and ports Apache HTTP Server uses</a></li>
5242 <li><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
5243     and &lt;Files&gt; sections work</a> for an explanation of how these
5244     different sections are combined when a request is received</li>
5245 </ul>
5246 </div>
5247 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
5248 <div class="directive-section"><h2><a name="Warning" id="Warning">Warning</a> <a name="warning" id="warning">Directive</a><a title="Permanent link" href="#warning" class="permalink">&para;</a></h2>
5249 <table class="directive">
5250 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Warn from configuration parsing with a custom message</td></tr>
5251 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Warning <var>message</var></code></td></tr>
5252 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
5253 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
5254 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
5255 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
5256 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.5 and later</td></tr>
5257 </table>
5258     <p>If an issue can be detected from within the configuration, this
5259     directive can be used to generate a custom warning message. The
5260     configuration parsing is not halted. The typical use is to check
5261     whether some user define options are set, and warn if not.</p>
5262
5263     <pre class="prettyprint lang-config"># Example
5264 # tell when ReverseProxy is not set
5265 &lt;IfDefine !ReverseProxy&gt;
5266   Warning "reverse proxy is not started, hope this is okay!"
5267 &lt;/IfDefine&gt;
5268
5269 &lt;IfDefine ReverseProxy&gt;
5270   # define custom proxy configuration
5271 &lt;/IfDefine&gt;</pre>
5272
5273
5274
5275 </div>
5276 </div>
5277 <div class="bottomlang">
5278 <p><span>Available Languages: </span><a href="../de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
5279 <a href="../en/mod/core.html" title="English">&nbsp;en&nbsp;</a> |
5280 <a href="../es/mod/core.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
5281 <a href="../fr/mod/core.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
5282 <a href="../ja/mod/core.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
5283 <a href="../tr/mod/core.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
5284 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
5285 <script type="text/javascript"><!--//--><![CDATA[//><!--
5286 var comments_shortname = 'httpd';
5287 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/core.html';
5288 (function(w, d) {
5289     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
5290         d.write('<div id="comments_thread"><\/div>');
5291         var s = d.createElement('script');
5292         s.type = 'text/javascript';
5293         s.async = true;
5294         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
5295         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
5296     }
5297     else {
5298         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
5299     }
5300 })(window, document);
5301 //--><!]]></script></div><div id="footer">
5302 <p class="apache">Copyright 2018 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
5303 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
5304 if (typeof(prettyPrint) !== 'undefined') {
5305     prettyPrint();
5306 }
5307 //--><!]]></script>
5308 </body></html>