1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>core - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Core Features</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> | 28<a href="/en/mod/core.html" title="English"> en </a> | 29<a href="/es/mod/core.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> | 30<a href="/fr/mod/core.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 31<a href="/ja/mod/core.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 32<a href="/tr/mod/core.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 33</div> 34<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Core Apache HTTP Server features that are always 35available</td></tr> 36<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Core</td></tr></table> 37</div> 38<div id="quickview"><h3 class="directives">Directives</h3> 39<ul id="toc"> 40<li><img alt="" src="/images/down.gif" /> <a href="#acceptfilter">AcceptFilter</a></li> 41<li><img alt="" src="/images/down.gif" /> <a href="#acceptpathinfo">AcceptPathInfo</a></li> 42<li><img alt="" src="/images/down.gif" /> <a href="#accessfilename">AccessFileName</a></li> 43<li><img alt="" src="/images/down.gif" /> <a href="#adddefaultcharset">AddDefaultCharset</a></li> 44<li><img alt="" src="/images/down.gif" /> <a href="#allowencodedslashes">AllowEncodedSlashes</a></li> 45<li><img alt="" src="/images/down.gif" /> <a href="#allowoverride">AllowOverride</a></li> 46<li><img alt="" src="/images/down.gif" /> <a href="#allowoverridelist">AllowOverrideList</a></li> 47<li><img alt="" src="/images/down.gif" /> <a href="#cgimapextension">CGIMapExtension</a></li> 48<li><img alt="" src="/images/down.gif" /> <a href="#contentdigest">ContentDigest</a></li> 49<li><img alt="" src="/images/down.gif" /> <a href="#defaultruntimedir">DefaultRuntimeDir</a></li> 50<li><img alt="" src="/images/down.gif" /> <a href="#defaulttype">DefaultType</a></li> 51<li><img alt="" src="/images/down.gif" /> <a href="#define">Define</a></li> 52<li><img alt="" src="/images/down.gif" /> <a href="#directory"><Directory></a></li> 53<li><img alt="" src="/images/down.gif" /> <a href="#directorymatch"><DirectoryMatch></a></li> 54<li><img alt="" src="/images/down.gif" /> <a href="#documentroot">DocumentRoot</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#else"><Else></a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#elseif"><ElseIf></a></li> 57<li><img alt="" src="/images/down.gif" /> <a href="#enablemmap">EnableMMAP</a></li> 58<li><img alt="" src="/images/down.gif" /> <a href="#enablesendfile">EnableSendfile</a></li> 59<li><img alt="" src="/images/down.gif" /> <a href="#error">Error</a></li> 60<li><img alt="" src="/images/down.gif" /> <a href="#errordocument">ErrorDocument</a></li> 61<li><img alt="" src="/images/down.gif" /> <a href="#errorlog">ErrorLog</a></li> 62<li><img alt="" src="/images/down.gif" /> <a href="#errorlogformat">ErrorLogFormat</a></li> 63<li><img alt="" src="/images/down.gif" /> <a href="#extendedstatus">ExtendedStatus</a></li> 64<li><img alt="" src="/images/down.gif" /> <a href="#fileetag">FileETag</a></li> 65<li><img alt="" src="/images/down.gif" /> <a href="#files"><Files></a></li> 66<li><img alt="" src="/images/down.gif" /> <a href="#filesmatch"><FilesMatch></a></li> 67<li><img alt="" src="/images/down.gif" /> <a href="#forcetype">ForceType</a></li> 68<li><img alt="" src="/images/down.gif" /> <a href="#gprofdir">GprofDir</a></li> 69<li><img alt="" src="/images/down.gif" /> <a href="#hostnamelookups">HostnameLookups</a></li> 70<li><img alt="" src="/images/down.gif" /> <a href="#if"><If></a></li> 71<li><img alt="" src="/images/down.gif" /> <a href="#ifdefine"><IfDefine></a></li> 72<li><img alt="" src="/images/down.gif" /> <a href="#ifmodule"><IfModule></a></li> 73<li><img alt="" src="/images/down.gif" /> <a href="#include">Include</a></li> 74<li><img alt="" src="/images/down.gif" /> <a href="#includeoptional">IncludeOptional</a></li> 75<li><img alt="" src="/images/down.gif" /> <a href="#keepalive">KeepAlive</a></li> 76<li><img alt="" src="/images/down.gif" /> <a href="#keepalivetimeout">KeepAliveTimeout</a></li> 77<li><img alt="" src="/images/down.gif" /> <a href="#limit"><Limit></a></li> 78<li><img alt="" src="/images/down.gif" /> <a href="#limitexcept"><LimitExcept></a></li> 79<li><img alt="" src="/images/down.gif" /> <a href="#limitinternalrecursion">LimitInternalRecursion</a></li> 80<li><img alt="" src="/images/down.gif" /> <a href="#limitrequestbody">LimitRequestBody</a></li> 81<li><img alt="" src="/images/down.gif" /> <a href="#limitrequestfields">LimitRequestFields</a></li> 82<li><img alt="" src="/images/down.gif" /> <a href="#limitrequestfieldsize">LimitRequestFieldSize</a></li> 83<li><img alt="" src="/images/down.gif" /> <a href="#limitrequestline">LimitRequestLine</a></li> 84<li><img alt="" src="/images/down.gif" /> <a href="#limitxmlrequestbody">LimitXMLRequestBody</a></li> 85<li><img alt="" src="/images/down.gif" /> <a href="#location"><Location></a></li> 86<li><img alt="" src="/images/down.gif" /> <a href="#locationmatch"><LocationMatch></a></li> 87<li><img alt="" src="/images/down.gif" /> <a href="#loglevel">LogLevel</a></li> 88<li><img alt="" src="/images/down.gif" /> <a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></li> 89<li><img alt="" src="/images/down.gif" /> <a href="#maxrangeoverlaps">MaxRangeOverlaps</a></li> 90<li><img alt="" src="/images/down.gif" /> <a href="#maxrangereversals">MaxRangeReversals</a></li> 91<li><img alt="" src="/images/down.gif" /> <a href="#maxranges">MaxRanges</a></li> 92<li><img alt="" src="/images/down.gif" /> <a href="#mutex">Mutex</a></li> 93<li><img alt="" src="/images/down.gif" /> <a href="#namevirtualhost">NameVirtualHost</a></li> 94<li><img alt="" src="/images/down.gif" /> <a href="#options">Options</a></li> 95<li><img alt="" src="/images/down.gif" /> <a href="#protocol">Protocol</a></li> 96<li><img alt="" src="/images/down.gif" /> <a href="#rlimitcpu">RLimitCPU</a></li> 97<li><img alt="" src="/images/down.gif" /> <a href="#rlimitmem">RLimitMEM</a></li> 98<li><img alt="" src="/images/down.gif" /> <a href="#rlimitnproc">RLimitNPROC</a></li> 99<li><img alt="" src="/images/down.gif" /> <a href="#scriptinterpretersource">ScriptInterpreterSource</a></li> 100<li><img alt="" src="/images/down.gif" /> <a href="#seerequesttail">SeeRequestTail</a></li> 101<li><img alt="" src="/images/down.gif" /> <a href="#serveradmin">ServerAdmin</a></li> 102<li><img alt="" src="/images/down.gif" /> <a href="#serveralias">ServerAlias</a></li> 103<li><img alt="" src="/images/down.gif" /> <a href="#servername">ServerName</a></li> 104<li><img alt="" src="/images/down.gif" /> <a href="#serverpath">ServerPath</a></li> 105<li><img alt="" src="/images/down.gif" /> <a href="#serverroot">ServerRoot</a></li> 106<li><img alt="" src="/images/down.gif" /> <a href="#serversignature">ServerSignature</a></li> 107<li><img alt="" src="/images/down.gif" /> <a href="#servertokens">ServerTokens</a></li> 108<li><img alt="" src="/images/down.gif" /> <a href="#sethandler">SetHandler</a></li> 109<li><img alt="" src="/images/down.gif" /> <a href="#setinputfilter">SetInputFilter</a></li> 110<li><img alt="" src="/images/down.gif" /> <a href="#setoutputfilter">SetOutputFilter</a></li> 111<li><img alt="" src="/images/down.gif" /> <a href="#timeout">TimeOut</a></li> 112<li><img alt="" src="/images/down.gif" /> <a href="#traceenable">TraceEnable</a></li> 113<li><img alt="" src="/images/down.gif" /> <a href="#undefine">UnDefine</a></li> 114<li><img alt="" src="/images/down.gif" /> <a href="#usecanonicalname">UseCanonicalName</a></li> 115<li><img alt="" src="/images/down.gif" /> <a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></li> 116<li><img alt="" src="/images/down.gif" /> <a href="#virtualhost"><VirtualHost></a></li> 117</ul> 118<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 119 120<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 121<div class="directive-section"><h2><a name="AcceptFilter" id="AcceptFilter">AcceptFilter</a> <a name="acceptfilter" id="acceptfilter">Directive</a></h2> 122<table class="directive"> 123<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures optimizations for a Protocol's Listener Sockets</td></tr> 124<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AcceptFilter <var>protocol</var> <var>accept_filter</var></code></td></tr> 125<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 126<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 127<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 128<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache httpd 2.1.5 and later. 129On Windows from Apache httpd 2.3.3 and later.</td></tr> 130</table> 131 <p>This directive enables operating system specific optimizations for a 132 listening socket by the <code class="directive">Protocol</code> type. 133 The basic premise is for the kernel to not send a socket to the server 134 process until either data is received or an entire HTTP Request is buffered. 135 Only <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&sektion=9"> 136 FreeBSD's Accept Filters</a>, Linux's more primitive 137 <code>TCP_DEFER_ACCEPT</code>, and Windows' optimized AcceptEx() 138 are currently supported.</p> 139 140 <p>Using <code>none</code> for an argument will disable any accept filters 141 for that protocol. This is useful for protocols that require a server 142 send data first, such as <code>ftp:</code> or <code>nntp</code>:</p> 143 <pre class="prettyprint lang-config">AcceptFilter nntp none</pre> 144 145 146 <p>The default protocol names are <code>https</code> for port 443 147 and <code>http</code> for all other ports. To specify another protocol 148 is being used with a listening port, add the <var>protocol</var> 149 argument to the <code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code> 150 directive.</p> 151 152 <p>The default values on FreeBSD are:</p> 153 <pre class="prettyprint lang-config">AcceptFilter http httpready 154AcceptFilter https dataready</pre> 155 156 157 <p>The <code>httpready</code> accept filter buffers entire HTTP requests at 158 the kernel level. Once an entire request is received, the kernel then 159 sends it to the server. See the 160 <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_http&sektion=9"> 161 accf_http(9)</a> man page for more details. Since HTTPS requests are 162 encrypted only the <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_data&sektion=9"> 163 accf_data(9)</a> filter is used.</p> 164 165 <p>The default values on Linux are:</p> 166 <pre class="prettyprint lang-config">AcceptFilter http data 167AcceptFilter https data</pre> 168 169 170 <p>Linux's <code>TCP_DEFER_ACCEPT</code> does not support buffering http 171 requests. Any value besides <code>none</code> will enable 172 <code>TCP_DEFER_ACCEPT</code> on that listener. For more details 173 see the Linux 174 <a href="http://homepages.cwi.nl/~aeb/linux/man2html/man7/tcp.7.html"> 175 tcp(7)</a> man page.</p> 176 177 <p>The default values on Windows are:</p> 178 <pre class="prettyprint lang-config">AcceptFilter http data 179AcceptFilter https data</pre> 180 181 182 <p>Window's mpm_winnt interprets the AcceptFilter to toggle the AcceptEx() 183 API, and does not support http protocol buffering. There are two values 184 which utilize the Windows AcceptEx() API and will recycle network 185 sockets between connections. <code>data</code> waits until data has 186 been transmitted as documented above, and the initial data buffer and 187 network endpoint addresses are all retrieved from the single AcceptEx() 188 invocation. <code>connect</code> will use the AcceptEx() API, also 189 retrieve the network endpoint addresses, but like <code>none</code> 190 the <code>connect</code> option does not wait for the initial data 191 transmission.</p> 192 193 <p>On Windows, <code>none</code> uses accept() rather than AcceptEx() 194 and will not recycle sockets between connections. This is useful for 195 network adapters with broken driver support, as well as some virtual 196 network providers such as vpn drivers, or spam, virus or spyware 197 filters.</p> 198 199 200<h3>See also</h3> 201<ul> 202<li><code class="directive"><a href="#protocol">Protocol</a></code></li> 203</ul> 204</div> 205<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 206<div class="directive-section"><h2><a name="AcceptPathInfo" id="AcceptPathInfo">AcceptPathInfo</a> <a name="acceptpathinfo" id="acceptpathinfo">Directive</a></h2> 207<table class="directive"> 208<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Resources accept trailing pathname information</td></tr> 209<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AcceptPathInfo On|Off|Default</code></td></tr> 210<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AcceptPathInfo Default</code></td></tr> 211<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 212<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 213<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 214<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 215</table> 216 217 <p>This directive controls whether requests that contain trailing 218 pathname information that follows an actual filename (or 219 non-existent file in an existing directory) will be accepted or 220 rejected. The trailing pathname information can be made 221 available to scripts in the <code>PATH_INFO</code> environment 222 variable.</p> 223 224 <p>For example, assume the location <code>/test/</code> points to 225 a directory that contains only the single file 226 <code>here.html</code>. Then requests for 227 <code>/test/here.html/more</code> and 228 <code>/test/nothere.html/more</code> both collect 229 <code>/more</code> as <code>PATH_INFO</code>.</p> 230 231 <p>The three possible arguments for the 232 <code class="directive">AcceptPathInfo</code> directive are:</p> 233 <dl> 234 <dt><code>Off</code></dt><dd>A request will only be accepted if it 235 maps to a literal path that exists. Therefore a request with 236 trailing pathname information after the true filename such as 237 <code>/test/here.html/more</code> in the above example will return 238 a 404 NOT FOUND error.</dd> 239 240 <dt><code>On</code></dt><dd>A request will be accepted if a 241 leading path component maps to a file that exists. The above 242 example <code>/test/here.html/more</code> will be accepted if 243 <code>/test/here.html</code> maps to a valid file.</dd> 244 245 <dt><code>Default</code></dt><dd>The treatment of requests with 246 trailing pathname information is determined by the <a href="/handler.html">handler</a> responsible for the request. 247 The core handler for normal files defaults to rejecting 248 <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 249 <code>PATH_INFO</code> by default.</dd> 250 </dl> 251 252 <p>The primary purpose of the <code>AcceptPathInfo</code> 253 directive is to allow you to override the handler's choice of 254 accepting or rejecting <code>PATH_INFO</code>. This override is required, 255 for example, when you use a <a href="/filter.html">filter</a>, such 256 as <a href="mod_include.html">INCLUDES</a>, to generate content 257 based on <code>PATH_INFO</code>. The core handler would usually reject 258 the request, so you can use the following configuration to enable 259 such a script:</p> 260 261 <pre class="prettyprint lang-config"><Files "mypaths.shtml"> 262 Options +Includes 263 SetOutputFilter INCLUDES 264 AcceptPathInfo On 265</Files></pre> 266 267 268 269</div> 270<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 271<div class="directive-section"><h2><a name="AccessFileName" id="AccessFileName">AccessFileName</a> <a name="accessfilename" id="accessfilename">Directive</a></h2> 272<table class="directive"> 273<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name of the distributed configuration file</td></tr> 274<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AccessFileName <var>filename</var> [<var>filename</var>] ...</code></td></tr> 275<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AccessFileName .htaccess</code></td></tr> 276<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 277<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 278<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 279</table> 280 <p>While processing a request the server looks for 281 the first existing configuration file from this list of names in 282 every directory of the path to the document, if distributed 283 configuration files are <a href="#allowoverride">enabled for that 284 directory</a>. For example:</p> 285 286 <pre class="prettyprint lang-config">AccessFileName .acl</pre> 287 288 289 <p>before returning the document 290 <code>/usr/local/web/index.html</code>, the server will read 291 <code>/.acl</code>, <code>/usr/.acl</code>, 292 <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code> 293 for directives, unless they have been disabled with</p> 294 295 <pre class="prettyprint lang-config"><Directory /> 296 AllowOverride None 297</Directory></pre> 298 299 300<h3>See also</h3> 301<ul> 302<li><code class="directive"><a href="#allowoverride">AllowOverride</a></code></li> 303<li><a href="/configuring.html">Configuration Files</a></li> 304<li><a href="/howto/htaccess.html">.htaccess Files</a></li> 305</ul> 306</div> 307<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 308<div class="directive-section"><h2><a name="AddDefaultCharset" id="AddDefaultCharset">AddDefaultCharset</a> <a name="adddefaultcharset" id="adddefaultcharset">Directive</a></h2> 309<table class="directive"> 310<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default charset parameter to be added when a response 311content-type is <code>text/plain</code> or <code>text/html</code></td></tr> 312<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddDefaultCharset On|Off|<var>charset</var></code></td></tr> 313<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AddDefaultCharset Off</code></td></tr> 314<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 315<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 316<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 317<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 318</table> 319 <p>This directive specifies a default value for the media type 320 charset parameter (the name of a character encoding) to be added 321 to a response if and only if the response's content-type is either 322 <code>text/plain</code> or <code>text/html</code>. This should override 323 any charset specified in the body of the response via a <code>META</code> 324 element, though the exact behavior is often dependent on the user's client 325 configuration. A setting of <code>AddDefaultCharset Off</code> 326 disables this functionality. <code>AddDefaultCharset On</code> enables 327 a default charset of <code>iso-8859-1</code>. Any other value is assumed 328 to be the <var>charset</var> to be used, which should be one of the 329 <a href="http://www.iana.org/assignments/character-sets">IANA registered 330 charset values</a> for use in Internet media types (MIME types). 331 For example:</p> 332 333 <pre class="prettyprint lang-config">AddDefaultCharset utf-8</pre> 334 335 336 <p><code class="directive">AddDefaultCharset</code> should only be used when all 337 of the text resources to which it applies are known to be in that 338 character encoding and it is too inconvenient to label their charset 339 individually. One such example is to add the charset parameter 340 to resources containing generated content, such as legacy CGI 341 scripts, that might be vulnerable to cross-site scripting attacks 342 due to user-provided data being included in the output. Note, however, 343 that a better solution is to just fix (or delete) those scripts, since 344 setting a default charset does not protect users that have enabled 345 the "auto-detect character encoding" feature on their browser.</p> 346 347<h3>See also</h3> 348<ul> 349<li><code class="directive"><a href="/mod/mod_mime.html#addcharset">AddCharset</a></code></li> 350</ul> 351</div> 352<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 353<div class="directive-section"><h2><a name="AllowEncodedSlashes" id="AllowEncodedSlashes">AllowEncodedSlashes</a> <a name="allowencodedslashes" id="allowencodedslashes">Directive</a></h2> 354<table class="directive"> 355<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether encoded path separators in URLs are allowed to 356be passed through</td></tr> 357<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowEncodedSlashes On|Off|NoDecode</code></td></tr> 358<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowEncodedSlashes Off</code></td></tr> 359<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 360<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 361<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 362<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td> 363NoDecode option available in 2.3.12 and later.</td></tr> 364</table> 365 <p>The <code class="directive">AllowEncodedSlashes</code> directive allows URLs 366 which contain encoded path separators (<code>%2F</code> for <code>/</code> 367 and additionally <code>%5C</code> for <code>\</code> on according systems) 368 to be used in the path info.</p> 369 370 <p>With the default value, <code>Off</code>, such URLs are refused 371 with a 404 (Not found) error.</p> 372 373 <p>With the value <code>On</code>, such URLs are accepted, and encoded 374 slashes are decoded like all other encoded characters.</p> 375 376 <p>With the value <code>NoDecode</code>, such URLs are accepted, but 377 encoded slashes are not decoded but left in their encoded state.</p> 378 379 <p>Turning <code class="directive">AllowEncodedSlashes</code> <code>On</code> is 380 mostly useful when used in conjunction with <code>PATH_INFO</code>.</p> 381 382 <div class="note"><h3>Note</h3> 383 <p>If encoded slashes are needed in path info, use of <code>NoDecode</code> is 384 strongly recommended as a security measure. Allowing slashes 385 to be decoded could potentially allow unsafe paths.</p> 386 </div> 387 388<h3>See also</h3> 389<ul> 390<li><code class="directive"><a href="#acceptpathinfo">AcceptPathInfo</a></code></li> 391</ul> 392</div> 393<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 394<div class="directive-section"><h2><a name="AllowOverride" id="AllowOverride">AllowOverride</a> <a name="allowoverride" id="allowoverride">Directive</a></h2> 395<table class="directive"> 396<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Types of directives that are allowed in 397<code>.htaccess</code> files</td></tr> 398<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowOverride All|None|<var>directive-type</var> 399[<var>directive-type</var>] ...</code></td></tr> 400<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> 401<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr> 402<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 403<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 404</table> 405 <p>When the server finds an <code>.htaccess</code> file (as 406 specified by <code class="directive"><a href="#accessfilename">AccessFileName</a></code>) 407 it needs to know which directives declared in that file can override 408 earlier configuration directives.</p> 409 410 <div class="note"><h3>Only available in <Directory> sections</h3> 411 <code class="directive">AllowOverride</code> is valid only in 412 <code class="directive"><a href="#directory"><Directory></a></code> 413 sections specified without regular expressions, not in <code class="directive"><a href="#location"><Location></a></code>, <code class="directive"><a href="#directorymatch"><DirectoryMatch></a></code> or 414 <code class="directive"><a href="#files"><Files></a></code> sections. 415 </div> 416 417 <p>When this directive is set to <code>None</code> and <code class="directive"><a href="#allowoverridelist">AllowOverrideList</a></code> is set to 418 <code>None</code> <a href="#accessfilename">.htaccess</a> files are 419 completely ignored. In this case, the server will not even attempt 420 to read <code>.htaccess</code> files in the filesystem.</p> 421 422 <p>When this directive is set to <code>All</code>, then any 423 directive which has the .htaccess <a href="directive-dict.html#Context">Context</a> is allowed in 424 <code>.htaccess</code> files.</p> 425 426 <p>The <var>directive-type</var> can be one of the following 427 groupings of directives.</p> 428 429 <dl> 430 <dt>AuthConfig</dt> 431 432 <dd> 433 434 Allow use of the authorization directives (<code class="directive"><a href="/mod/mod_authz_dbm.html#authdbmgroupfile">AuthDBMGroupFile</a></code>, 435 <code class="directive"><a href="/mod/mod_authn_dbm.html#authdbmuserfile">AuthDBMUserFile</a></code>, 436 <code class="directive"><a href="/mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>, 437 <code class="directive"><a href="/mod/mod_authn_core.html#authname">AuthName</a></code>, 438 <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> 439 440 <dt>FileInfo</dt> 441 442 <dd> 443 Allow use of the directives controlling document types 444 (<code class="directive"><a href="#errordocument">ErrorDocument</a></code>, 445 <code class="directive"><a href="#forcetype">ForceType</a></code>, 446 <code class="directive"><a href="/mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>, 447 <code class="directive"><a href="#sethandler">SetHandler</a></code>, 448 <code class="directive"><a href="#setinputfilter">SetInputFilter</a></code>, 449 <code class="directive"><a href="#setoutputfilter">SetOutputFilter</a></code>, and 450 <code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code> Add* and Remove* directives), 451 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>), 452 <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>), 453 <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 454 <code class="directive"><a href="/mod/mod_actions.html#action">Action</a></code> from 455 <code class="module"><a href="/mod/mod_actions.html">mod_actions</a></code>. 456 </dd> 457 458 <dt>Indexes</dt> 459 460 <dd> 461 Allow use of the directives controlling directory indexing 462 (<code class="directive"><a href="/mod/mod_autoindex.html#adddescription">AddDescription</a></code>, 463 <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>, 464 <code class="directive"><a href="/mod/mod_autoindex.html#addiconbytype">AddIconByType</a></code>, 465 <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>, <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>, 466 <em>etc.</em>).</dd> 467 468 <dt>Limit</dt> 469 470 <dd> 471 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> 472 473 <dt>Nonfatal=[Override|Unknown|All]</dt> 474 475 <dd> 476 Allow use of AllowOverride option to treat syntax errors in 477 .htaccess as non-fatal: instead of causing an Internal Server 478 Error, disallowed or unrecognised directives will be ignored 479 and a warning logged: 480 <ul> 481 <li><strong>Nonfatal=Override</strong> treats directives 482 forbidden by AllowOverride as non-fatal.</li> 483 <li><strong>Nonfatal=Unknown</strong> treats unknown directives 484 as non-fatal. This covers typos and directives implemented 485 by a module that's not present.</li> 486 <li><strong>Nonfatal=All</strong> treats both the above as non-fatal.</li> 487 </ul> 488 <p>Note that a syntax error in a valid directive will still cause 489 an internal server error.</p> 490 <div class="warning"><h3>Security</h3> 491 Nonfatal errors may have security implications for .htaccess users. 492 For example, if AllowOverride disallows AuthConfig, users' 493 configuration designed to restrict access to a site will be disabled. 494 </div> 495 </dd> 496 497 <dt>Options[=<var>Option</var>,...]</dt> 498 499 <dd> 500 Allow use of the directives controlling specific directory 501 features (<code class="directive"><a href="#options">Options</a></code> and 502 <code class="directive"><a href="/mod/mod_include.html#xbithack">XBitHack</a></code>). 503 An equal sign may be given followed by a comma (but no spaces) 504 separated lists of options that may be set using the <code class="directive"><a href="#options">Options</a></code> command. 505 506 <div class="note"><h3>Implicit disabling of Options</h3> 507 <p>Even though the list of options that may be used in .htaccess files 508 can be limited with this directive, as long as any <code class="directive"><a href="#options">Options</a></code> directive is allowed any 509 other inherited option can be disabled by using the non-relative 510 syntax. In other words, this mechanism cannot force a specific option 511 to remain <em>set</em> while allowing any others to be set. 512 </p></div> 513 514 <div class="example"><p><code> 515 AllowOverride Options=Indexes,MultiViews 516 </code></p></div> 517 </dd> 518 </dl> 519 520 <p>Example:</p> 521 522 <pre class="prettyprint lang-config">AllowOverride AuthConfig Indexes</pre> 523 524 525 <p>In the example above all directives that are neither in the group 526 <code>AuthConfig</code> nor <code>Indexes</code> cause an internal 527 server error.</p> 528 529 <div class="note"><p>For security and performance reasons, do not set 530 <code>AllowOverride</code> to anything other than <code>None</code> 531 in your <code><Directory /></code> block. Instead, find (or 532 create) the <code><Directory></code> block that refers to the 533 directory where you're actually planning to place a 534 <code>.htaccess</code> file.</p> 535 </div> 536 537<h3>See also</h3> 538<ul> 539<li><code class="directive"><a href="#accessfilename">AccessFileName</a></code></li> 540<li><code class="directive"><a href="#allowoverridelist">AllowOverrideList</a></code></li> 541<li><a href="/configuring.html">Configuration Files</a></li> 542<li><a href="/howto/htaccess.html">.htaccess Files</a></li> 543</ul> 544</div> 545<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 546<div class="directive-section"><h2><a name="AllowOverrideList" id="AllowOverrideList">AllowOverrideList</a> <a name="allowoverridelist" id="allowoverridelist">Directive</a></h2> 547<table class="directive"> 548<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Individual directives that are allowed in 549<code>.htaccess</code> files</td></tr> 550<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowOverrideList None|<var>directive</var> 551[<var>directive-type</var>] ...</code></td></tr> 552<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowOverrideList None</code></td></tr> 553<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr> 554<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 555<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 556</table> 557 <p>When the server finds an <code>.htaccess</code> file (as 558 specified by <code class="directive"><a href="#accessfilename">AccessFileName</a></code>) 559 it needs to know which directives declared in that file can override 560 earlier configuration directives.</p> 561 562 <div class="note"><h3>Only available in <Directory> sections</h3> 563 <code class="directive">AllowOverrideList</code> is valid only in 564 <code class="directive"><a href="#directory"><Directory></a></code> 565 sections specified without regular expressions, not in <code class="directive"><a href="#location"><Location></a></code>, <code class="directive"><a href="#directorymatch"><DirectoryMatch></a></code> or 566 <code class="directive"><a href="#files"><Files></a></code> sections. 567 </div> 568 569 <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>, 570 then <a href="#accessfilename">.htaccess</a> files are completely 571 ignored. In this case, the server will not even attempt to read 572 <code>.htaccess</code> files in the filesystem.</p> 573 574 <p>Example:</p> 575 576 <pre class="prettyprint lang-config">AllowOverride None 577AllowOverrideList Redirect RedirectMatch</pre> 578 579 580 <p>In the example above only the <code>Redirect</code> and 581 <code>RedirectMatch</code> directives are allowed. All others will 582 cause an internal server error.</p> 583 584 <p>Example:</p> 585 586 <pre class="prettyprint lang-config">AllowOverride AuthConfig 587AllowOverrideList CookieTracking CookieName</pre> 588 589 590 <p>In the example above <code class="directive"><a href="#allowoverride">AllowOverride 591 </a></code> grants permission to the <code>AuthConfig</code> 592 directive grouping and <code class="directive">AllowOverrideList</code> grants 593 permission to only two directives from the <code>FileInfo</code> directive 594 grouping. All others will cause an internal server error.</p> 595 596<h3>See also</h3> 597<ul> 598<li><code class="directive"><a href="#accessfilename">AccessFileName</a></code></li> 599<li><code class="directive"><a href="#allowoverride">AllowOverride</a></code></li> 600<li><a href="/configuring.html">Configuration Files</a></li> 601<li><a href="/howto/htaccess.html">.htaccess Files</a></li> 602</ul> 603</div> 604<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 605<div class="directive-section"><h2><a name="CGIMapExtension" id="CGIMapExtension">CGIMapExtension</a> <a name="cgimapextension" id="cgimapextension">Directive</a></h2> 606<table class="directive"> 607<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI 608scripts</td></tr> 609<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIMapExtension <var>cgi-path</var> <var>.extension</var></code></td></tr> 610<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 611<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 612<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 613<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 614<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>NetWare only</td></tr> 615</table> 616 <p>This directive is used to control how Apache httpd finds the 617 interpreter used to run CGI scripts. For example, setting 618 <code>CGIMapExtension sys:\foo.nlm .foo</code> will 619 cause all CGI script files with a <code>.foo</code> extension to 620 be passed to the FOO interpreter.</p> 621 622</div> 623<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 624<div class="directive-section"><h2><a name="ContentDigest" id="ContentDigest">ContentDigest</a> <a name="contentdigest" id="contentdigest">Directive</a></h2> 625<table class="directive"> 626<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables the generation of <code>Content-MD5</code> HTTP Response 627headers</td></tr> 628<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ContentDigest On|Off</code></td></tr> 629<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ContentDigest Off</code></td></tr> 630<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 631<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 632<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 633<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 634</table> 635 <p>This directive enables the generation of 636 <code>Content-MD5</code> headers as defined in RFC1864 637 respectively RFC2616.</p> 638 639 <p>MD5 is an algorithm for computing a "message digest" 640 (sometimes called "fingerprint") of arbitrary-length data, with 641 a high degree of confidence that any alterations in the data 642 will be reflected in alterations in the message digest.</p> 643 644 <p>The <code>Content-MD5</code> header provides an end-to-end 645 message integrity check (MIC) of the entity-body. A proxy or 646 client may check this header for detecting accidental 647 modification of the entity-body in transit. Example header:</p> 648 649 <div class="example"><p><code> 650 Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA== 651 </code></p></div> 652 653 <p>Note that this can cause performance problems on your server 654 since the message digest is computed on every request (the 655 values are not cached).</p> 656 657 <p><code>Content-MD5</code> is only sent for documents served 658 by the <code class="module"><a href="/mod/core.html">core</a></code>, and not by any module. For example, 659 SSI documents, output from CGI scripts, and byte range responses 660 do not have this header.</p> 661 662</div> 663<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 664<div class="directive-section"><h2><a name="DefaultRuntimeDir" id="DefaultRuntimeDir">DefaultRuntimeDir</a> <a name="defaultruntimedir" id="defaultruntimedir">Directive</a></h2> 665<table class="directive"> 666<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the server run-time files</td></tr> 667<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultRuntimeDir <var>directory-path</var></code></td></tr> 668<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultRuntimeDir DEFAULT_REL_RUNTIMEDIR (logs/)</code></td></tr> 669<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</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</table> 673 <p>The <code class="directive">DefaultRuntimeDir</code> directive sets the 674 directory in which the server will create various run-time files 675 (shared memory, locks, etc.). If set as a relative path, the full path 676 will be relative to <code class="directive">ServerRoot</code>.</p> 677 678 <p><strong>Example</strong></p> 679 <pre class="prettyprint lang-config">DefaultRuntimeDir scratch/</pre> 680 681 682 <p>The default location of <code class="directive">DefaultRuntimeDir</code> may be 683 modified by changing the <code>DEFAULT_REL_RUNTIMEDIR</code> #define 684 at build time.</p> 685 686 <p>Note: <code class="directive">ServerRoot</code> should be specified before this 687 directive is used, otherwise the default value of <code class="directive">ServerRoot</code> 688 would be used to set the base directory.</p> 689 690 691<h3>See also</h3> 692<ul> 693<li><a href="/misc/security_tips.html#serverroot">the 694 security tips</a> for information on how to properly set 695 permissions on the <code class="directive">ServerRoot</code></li> 696</ul> 697</div> 698<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 699<div class="directive-section"><h2><a name="DefaultType" id="DefaultType">DefaultType</a> <a name="defaulttype" id="defaulttype">Directive</a></h2> 700<table class="directive"> 701<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>This directive has no effect other than to emit warnings 702if the value is not <code>none</code>. In prior versions, DefaultType 703would specify a default media type to assign to response content for 704which no other media type configuration could be found. 705</td></tr> 706<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultType <var>media-type|none</var></code></td></tr> 707<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultType none</code></td></tr> 708<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 709<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 710<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 711<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 712<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The argument <code>none</code> is available in Apache httpd 2.2.7 and later. All other choices are DISABLED for 2.3.x and later.</td></tr> 713</table> 714 <p>This directive has been disabled. For backwards compatibility 715 of configuration files, it may be specified with the value 716 <code>none</code>, meaning no default media type. For example:</p> 717 718 <pre class="prettyprint lang-config">DefaultType None</pre> 719 720 721 <p><code>DefaultType None</code> is only available in 722 httpd-2.2.7 and later.</p> 723 724 <p>Use the mime.types configuration file and the 725 <code class="directive"><a href="/mod/mod_mime.html#addtype">AddType</a></code> to configure media 726 type assignments via file extensions, or the 727 <code class="directive"><a href="#forcetype">ForceType</a></code> directive to configure 728 the media type for specific resources. Otherwise, the server will 729 send the response without a Content-Type header field and the 730 recipient may attempt to guess the media type.</p> 731 732</div> 733<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 734<div class="directive-section"><h2><a name="Define" id="Define">Define</a> <a name="define" id="define">Directive</a></h2> 735<table class="directive"> 736<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a variable</td></tr> 737<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> 738<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 739<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 740<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 741</table> 742 <p>In its one parameter form, <code class="directive">Define</code> is equivalent 743 to passing the <code>-D</code> argument to <code class="program"><a href="/programs/httpd.html">httpd</a></code>. It 744 can be used to toggle the use of 745 <code class="directive"><a href="#ifdefine"><IfDefine></a></code> sections 746 without needing to alter <code>-D</code> arguments in any startup 747 scripts.</p> 748 749 <p>In addition to that, if the second parameter is given, a config variable 750 is set to this value. The variable can be used in the configuration using 751 the <code>${VAR}</code> syntax. The variable is always globally defined 752 and not limited to the scope of the surrounding config section.</p> 753 754 <pre class="prettyprint lang-config"><IfDefine TEST> 755 Define servername test.example.com 756</IfDefine> 757<IfDefine !TEST> 758 Define servername www.example.com 759 Define SSL 760</IfDefine> 761 762DocumentRoot /var/www/${servername}/htdocs</pre> 763 764 765 <p>Variable names may not contain colon ":" characters, to avoid clashes 766 with <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>'s syntax.</p> 767 768</div> 769<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 770<div class="directive-section"><h2><a name="Directory" id="Directory"><Directory></a> <a name="directory" id="directory">Directive</a></h2> 771<table class="directive"> 772<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of directives that apply only to the 773named file-system directory, sub-directories, and their contents.</td></tr> 774<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Directory <var>directory-path</var>> 775... </Directory></code></td></tr> 776<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 777<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 778<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 779</table> 780 <p><code class="directive"><Directory></code> and 781 <code></Directory></code> are used to enclose a group of 782 directives that will apply only to the named directory, 783 sub-directories of that directory, and the files within the respective 784 directories. Any directive that is allowed 785 in a directory context may be used. <var>Directory-path</var> is 786 either the full path to a directory, or a wild-card string using 787 Unix shell-style matching. In a wild-card string, <code>?</code> matches 788 any single character, and <code>*</code> matches any sequences of 789 characters. You may also use <code>[]</code> character ranges. None 790 of the wildcards match a `/' character, so <code><Directory 791 /*/public_html></code> will not match 792 <code>/home/user/public_html</code>, but <code><Directory 793 /home/*/public_html></code> will match. Example:</p> 794 795 <pre class="prettyprint lang-config"><Directory "/usr/local/httpd/htdocs"> 796 Options Indexes FollowSymLinks 797</Directory></pre> 798 799 800 <div class="note"> 801 <p>Be careful with the <var>directory-path</var> arguments: 802 They have to literally match the filesystem path which Apache httpd uses 803 to access the files. Directives applied to a particular 804 <code><Directory></code> will not apply to files accessed from 805 that same directory via a different path, such as via different symbolic 806 links.</p> 807 </div> 808 809 <p><a class="glossarylink" href="/glossary.html#regex" title="see glossary">Regular 810 expressions</a> can also be used, with the addition of the 811 <code>~</code> character. For example:</p> 812 813 <pre class="prettyprint lang-config"><Directory ~ "^/www/[0-9]{3}"> 814 815</Directory></pre> 816 817 818 <p>would match directories in <code>/www/</code> that consisted of 819 three numbers.</p> 820 821 <p>If multiple (non-regular expression) <code class="directive"><Directory></code> sections 822 match the directory (or one of its parents) containing a document, 823 then the directives are applied in the order of shortest match 824 first, interspersed with the directives from the <a href="#accessfilename">.htaccess</a> files. For example, 825 with</p> 826 827 <pre class="prettyprint lang-config"><Directory /> 828 AllowOverride None 829</Directory> 830 831<Directory "/home"> 832 AllowOverride FileInfo 833</Directory></pre> 834 835 836 <p>for access to the document <code>/home/web/dir/doc.html</code> 837 the steps are:</p> 838 839 <ul> 840 <li>Apply directive <code>AllowOverride None</code> 841 (disabling <code>.htaccess</code> files).</li> 842 843 <li>Apply directive <code>AllowOverride FileInfo</code> (for 844 directory <code>/home</code>).</li> 845 846 <li>Apply any <code>FileInfo</code> directives in 847 <code>/home/.htaccess</code>, <code>/home/web/.htaccess</code> and 848 <code>/home/web/dir/.htaccess</code> in that order.</li> 849 </ul> 850 851 <p>Regular expressions are not considered until after all of the 852 normal sections have been applied. Then all of the regular 853 expressions are tested in the order they appeared in the 854 configuration file. For example, with</p> 855 856 <pre class="prettyprint lang-config"><Directory ~ "abc$"> 857 # ... directives here ... 858</Directory></pre> 859 860 861 <p>the regular expression section won't be considered until after 862 all normal <code class="directive"><Directory></code>s and 863 <code>.htaccess</code> files have been applied. Then the regular 864 expression will match on <code>/home/abc/public_html/abc</code> and 865 the corresponding <code class="directive"><Directory></code> will 866 be applied.</p> 867 868 <p><strong>Note that the default access for 869 <code><Directory /></code> is to permit all access. 870 This means that Apache httpd will serve any file mapped from an URL. It is 871 recommended that you change this with a block such 872 as</strong></p> 873 874 <pre class="prettyprint lang-config"><Directory /> 875 Require all denied 876</Directory></pre> 877 878 879 <p><strong>and then override this for directories you 880 <em>want</em> accessible. See the <a href="/misc/security_tips.html">Security Tips</a> page for more 881 details.</strong></p> 882 883 <p>The directory sections occur in the <code>httpd.conf</code> file. 884 <code class="directive"><Directory></code> directives 885 cannot nest, and cannot appear in a <code class="directive"><a href="#limit"><Limit></a></code> or <code class="directive"><a href="#limitexcept"><LimitExcept></a></code> section.</p> 886 887<h3>See also</h3> 888<ul> 889<li><a href="/sections.html">How <Directory>, 890 <Location> and <Files> sections work</a> for an 891 explanation of how these different sections are combined when a 892 request is received</li> 893</ul> 894</div> 895<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 896<div class="directive-section"><h2><a name="DirectoryMatch" id="DirectoryMatch"><DirectoryMatch></a> <a name="directorymatch" id="directorymatch">Directive</a></h2> 897<table class="directive"> 898<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose directives that apply to 899the contents of file-system directories matching a regular expression.</td></tr> 900<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><DirectoryMatch <var>regex</var>> 901... </DirectoryMatch></code></td></tr> 902<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 903<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 904<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 905</table> 906 <p><code class="directive"><DirectoryMatch></code> and 907 <code></DirectoryMatch></code> are used to enclose a group 908 of directives which will apply only to the named directory (and the files within), 909 the same as <code class="directive"><a href="#directory"><Directory></a></code>. 910 However, it takes as an argument a 911 <a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular expression</a>. For example:</p> 912 913 <pre class="prettyprint lang-config"><DirectoryMatch "^/www/(.+/)?[0-9]{3}"> 914 # ... 915</DirectoryMatch></pre> 916 917 918 <p>would match directories in <code>/www/</code> that consisted of three 919 numbers.</p> 920 921 <div class="note"><h3>Compatability</h3> 922 Prior to 2.3.9, this directive implicitly applied to sub-directories 923 (like <code class="directive"><a href="#directory"><Directory></a></code>) and 924 could not match the end of line symbol ($). In 2.3.9 and later, 925 only directories that match the expression are affected by the enclosed 926 directives. 927 </div> 928 929 <div class="note"><h3>Trailing Slash</h3> 930 This directive applies to requests for directories that may or may 931 not end in a trailing slash, so expressions that are anchored to the 932 end of line ($) must be written with care. 933 </div> 934 935 <p>From 2.4.8 onwards, named groups and backreferences are captured and 936 written to the environment with the corresponding name prefixed with 937 "MATCH_" and in upper case. This allows elements of paths to be referenced 938 from within <a href="/expr.html">expressions</a> and modules like 939 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered 940 (unnamed) backreferences are ignored. Use named groups instead.</p> 941 942<pre class="prettyprint lang-config"><DirectoryMatch ^/var/www/combined/(?<sitename>[^/]+)> 943 require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example 944</DirectoryMatch></pre> 945 946 947<h3>See also</h3> 948<ul> 949<li><code class="directive"><a href="#directory"><Directory></a></code> for 950a description of how regular expressions are mixed in with normal 951<code class="directive"><Directory></code>s</li> 952<li><a href="/sections.html">How <Directory>, <Location> and 953<Files> sections work</a> for an explanation of how these different 954sections are combined when a request is received</li> 955</ul> 956</div> 957<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 958<div class="directive-section"><h2><a name="DocumentRoot" id="DocumentRoot">DocumentRoot</a> <a name="documentroot" id="documentroot">Directive</a></h2> 959<table class="directive"> 960<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory that forms the main document tree visible 961from the web</td></tr> 962<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DocumentRoot <var>directory-path</var></code></td></tr> 963<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DocumentRoot /usr/local/apache/htdocs</code></td></tr> 964<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 965<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 966<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 967</table> 968 <p>This directive sets the directory from which <code class="program"><a href="/programs/httpd.html">httpd</a></code> 969 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 970 path from the requested URL to the document root to make the 971 path to the document. Example:</p> 972 973 <pre class="prettyprint lang-config">DocumentRoot "/usr/web"</pre> 974 975 976 <p>then an access to 977 <code>http://my.example.com/index.html</code> refers to 978 <code>/usr/web/index.html</code>. If the <var>directory-path</var> is 979 not absolute then it is assumed to be relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p> 980 981 <p>The <code class="directive">DocumentRoot</code> should be specified without 982 a trailing slash.</p> 983 984<h3>See also</h3> 985<ul> 986<li><a href="/urlmapping.html#documentroot">Mapping URLs to Filesystem 987Locations</a></li> 988</ul> 989</div> 990<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 991<div class="directive-section"><h2><a name="Else" id="Else"><Else></a> <a name="else" id="else">Directive</a></h2> 992<table class="directive"> 993<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if the condition of a 994previous <code class="directive"><a href="#if"><If></a></code> or 995<code class="directive"><a href="#elseif"><ElseIf></a></code> section is not 996satisfied by a request at runtime</td></tr> 997<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Else> ... </Else></code></td></tr> 998<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 999<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1000<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1001<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1002</table> 1003 <p>The <code class="directive"><Else></code> applies the enclosed 1004 directives if and only if the most recent 1005 <code class="directive"><If></code> or 1006 <code class="directive"><ElseIf></code> section 1007 in the same scope has not been applied. 1008 For example: In </p> 1009 1010 <pre class="prettyprint lang-config"><If "-z req('Host')"> 1011 # ... 1012</If> 1013<Else> 1014 # ... 1015</Else></pre> 1016 1017 1018 <p> The <code class="directive"><If></code> would match HTTP/1.0 1019 requests without a <var>Host:</var> header and the 1020 <code class="directive"><Else></code> would match requests 1021 with a <var>Host:</var> header.</p> 1022 1023 1024<h3>See also</h3> 1025<ul> 1026<li><code class="directive"><a href="#if"><If></a></code></li> 1027<li><code class="directive"><a href="#elseif"><ElseIf></a></code></li> 1028<li><a href="/sections.html">How <Directory>, <Location>, 1029 <Files> sections work</a> for an explanation of how these 1030 different sections are combined when a request is received. 1031 <code class="directive"><If></code>, 1032 <code class="directive"><ElseIf></code>, and 1033 <code class="directive"><Else></code> are applied last.</li> 1034</ul> 1035</div> 1036<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1037<div class="directive-section"><h2><a name="ElseIf" id="ElseIf"><ElseIf></a> <a name="elseif" id="elseif">Directive</a></h2> 1038<table class="directive"> 1039<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if a condition is satisfied 1040by a request at runtime while the condition of a previous 1041<code class="directive"><a href="#if"><If></a></code> or 1042<code class="directive"><ElseIf></code> section is not 1043satisfied</td></tr> 1044<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><ElseIf <var>expression</var>> ... </ElseIf></code></td></tr> 1045<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1046<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1047<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1048<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1049</table> 1050 <p>The <code class="directive"><ElseIf></code> applies the enclosed 1051 directives if and only if both the given condition evaluates to true and 1052 the most recent <code class="directive"><If></code> or 1053 <code class="directive"><ElseIf></code> section in the same scope has 1054 not been applied. For example: In </p> 1055 1056 <pre class="prettyprint lang-config"><If "-R '10.1.0.0/16'"> 1057 #... 1058</If> 1059<ElseIf "-R '10.0.0.0/8'"> 1060 #... 1061</ElseIf> 1062<Else> 1063 #... 1064</Else></pre> 1065 1066 1067 <p>The <code class="directive"><ElseIf></code> would match if 1068 the remote address of a request belongs to the subnet 10.0.0.0/8 but 1069 not to the subnet 10.1.0.0/16.</p> 1070 1071 1072<h3>See also</h3> 1073<ul> 1074<li><a href="/expr.html">Expressions in Apache HTTP Server</a>, 1075for a complete reference and more examples.</li> 1076<li><code class="directive"><a href="#if"><If></a></code></li> 1077<li><code class="directive"><a href="#else"><Else></a></code></li> 1078<li><a href="/sections.html">How <Directory>, <Location>, 1079 <Files> sections work</a> for an explanation of how these 1080 different sections are combined when a request is received. 1081 <code class="directive"><If></code>, 1082 <code class="directive"><ElseIf></code>, and 1083 <code class="directive"><Else></code> are applied last.</li> 1084</ul> 1085</div> 1086<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1087<div class="directive-section"><h2><a name="EnableMMAP" id="EnableMMAP">EnableMMAP</a> <a name="enablemmap" id="enablemmap">Directive</a></h2> 1088<table class="directive"> 1089<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use memory-mapping to read files during delivery</td></tr> 1090<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableMMAP On|Off</code></td></tr> 1091<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableMMAP On</code></td></tr> 1092<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1093<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 1094<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1095<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1096</table> 1097 <p>This directive controls whether the <code class="program"><a href="/programs/httpd.html">httpd</a></code> may use 1098 memory-mapping if it needs to read the contents of a file during 1099 delivery. By default, when the handling of a request requires 1100 access to the data within a file -- for example, when delivering a 1101 server-parsed file using <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> -- Apache httpd 1102 memory-maps the file if the OS supports it.</p> 1103 1104 <p>This memory-mapping sometimes yields a performance improvement. 1105 But in some environments, it is better to disable the memory-mapping 1106 to prevent operational problems:</p> 1107 1108 <ul> 1109 <li>On some multiprocessor systems, memory-mapping can reduce the 1110 performance of the <code class="program"><a href="/programs/httpd.html">httpd</a></code>.</li> 1111 <li>Deleting or truncating a file while <code class="program"><a href="/programs/httpd.html">httpd</a></code> 1112 has it memory-mapped can cause <code class="program"><a href="/programs/httpd.html">httpd</a></code> to 1113 crash with a segmentation fault. 1114 </li> 1115 </ul> 1116 1117 <p>For server configurations that are vulnerable to these problems, 1118 you should disable memory-mapping of delivered files by specifying:</p> 1119 1120 <pre class="prettyprint lang-config">EnableMMAP Off</pre> 1121 1122 1123 <p>For NFS mounted files, this feature may be disabled explicitly for 1124 the offending files by specifying:</p> 1125 1126 <pre class="prettyprint lang-config"><Directory "/path-to-nfs-files"> 1127 EnableMMAP Off 1128</Directory></pre> 1129 1130 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="EnableSendfile" id="EnableSendfile">EnableSendfile</a> <a name="enablesendfile" id="enablesendfile">Directive</a></h2> 1134<table class="directive"> 1135<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> 1136<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>EnableSendfile On|Off</code></td></tr> 1137<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>EnableSendfile Off</code></td></tr> 1138<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1139<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</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<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default changed to Off in 1143version 2.3.9.</td></tr> 1144</table> 1145 <p>This directive controls whether <code class="program"><a href="/programs/httpd.html">httpd</a></code> may use the 1146 sendfile support from the kernel to transmit file contents to the client. 1147 By default, when the handling of a request requires no access 1148 to the data within a file -- for example, when delivering a 1149 static file -- Apache httpd uses sendfile to deliver the file contents 1150 without ever reading the file if the OS supports it.</p> 1151 1152 <p>This sendfile mechanism avoids separate read and send operations, 1153 and buffer allocations. But on some platforms or within some 1154 filesystems, it is better to disable this feature to avoid 1155 operational problems:</p> 1156 1157 <ul> 1158 <li>Some platforms may have broken sendfile support that the build 1159 system did not detect, especially if the binaries were built on 1160 another box and moved to such a machine with broken sendfile 1161 support.</li> 1162 <li>On Linux the use of sendfile triggers TCP-checksum 1163 offloading bugs on certain networking cards when using IPv6.</li> 1164 <li>On Linux on Itanium, <code>sendfile</code> may be unable to handle 1165 files over 2GB in size.</li> 1166 <li>With a network-mounted <code class="directive"><a href="#documentroot">DocumentRoot</a></code> (e.g., NFS, SMB, CIFS, FUSE), 1167 the kernel may be unable to serve the network file through 1168 its own cache.</li> 1169 </ul> 1170 1171 <p>For server configurations that are not vulnerable to these problems, 1172 you may enable this feature by specifying:</p> 1173 1174 <pre class="prettyprint lang-config">EnableSendfile On</pre> 1175 1176 1177 <p>For network mounted files, this feature may be disabled explicitly 1178 for the offending files by specifying:</p> 1179 1180 <pre class="prettyprint lang-config"><Directory "/path-to-nfs-files"> 1181 EnableSendfile Off 1182</Directory></pre> 1183 1184 <p>Please note that the per-directory and .htaccess configuration 1185 of <code class="directive">EnableSendfile</code> is not supported by 1186 <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code>. 1187 Only global definition of <code class="directive">EnableSendfile</code> 1188 is taken into account by the module. 1189 </p> 1190 1191</div> 1192<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1193<div class="directive-section"><h2><a name="Error" id="Error">Error</a> <a name="error" id="error">Directive</a></h2> 1194<table class="directive"> 1195<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Abort configuration parsing with a custom error message</td></tr> 1196<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Error <var>message</var></code></td></tr> 1197<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1198<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1199<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1200<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.3.9 and later</td></tr> 1201</table> 1202 <p>If an error can be detected within the configuration, this 1203 directive can be used to generate a custom error message, and halt 1204 configuration parsing. The typical use is for reporting required 1205 modules which are missing from the configuration.</p> 1206 1207 <pre class="prettyprint lang-config"># Example 1208# ensure that mod_include is loaded 1209<IfModule !include_module> 1210 Error "mod_include is required by mod_foo. Load it with LoadModule." 1211</IfModule> 1212 1213# ensure that exactly one of SSL,NOSSL is defined 1214<IfDefine SSL> 1215<IfDefine NOSSL> 1216 Error "Both SSL and NOSSL are defined. Define only one of them." 1217</IfDefine> 1218</IfDefine> 1219<IfDefine !SSL> 1220<IfDefine !NOSSL> 1221 Error "Either SSL or NOSSL must be defined." 1222</IfDefine> 1223</IfDefine></pre> 1224 1225 1226 1227</div> 1228<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1229<div class="directive-section"><h2><a name="ErrorDocument" id="ErrorDocument">ErrorDocument</a> <a name="errordocument" id="errordocument">Directive</a></h2> 1230<table class="directive"> 1231<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>What the server will return to the client 1232in case of an error</td></tr> 1233<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ErrorDocument <var>error-code</var> <var>document</var></code></td></tr> 1234<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1235<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 1236<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1237<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1238</table> 1239 <p>In the event of a problem or error, Apache httpd can be configured 1240 to do one of four things,</p> 1241 1242 <ol> 1243 <li>output a simple hardcoded error message</li> 1244 1245 <li>output a customized message</li> 1246 1247 <li>internally redirect to a local <var>URL-path</var> to handle the 1248 problem/error</li> 1249 1250 <li>redirect to an external <var>URL</var> to handle the 1251 problem/error</li> 1252 </ol> 1253 1254 <p>The first option is the default, while options 2-4 are 1255 configured using the <code class="directive">ErrorDocument</code> 1256 directive, which is followed by the HTTP response code and a URL 1257 or a message. Apache httpd will sometimes offer additional information 1258 regarding the problem/error.</p> 1259 1260 <p>URLs can begin with a slash (/) for local web-paths (relative 1261 to the <code class="directive"><a href="#documentroot">DocumentRoot</a></code>), or be a 1262 full URL which the client can resolve. Alternatively, a message 1263 can be provided to be displayed by the browser. Examples:</p> 1264 1265 <pre class="prettyprint lang-config">ErrorDocument 500 http://foo.example.com/cgi-bin/tester 1266ErrorDocument 404 /cgi-bin/bad_urls.pl 1267ErrorDocument 401 /subscription_info.html 1268ErrorDocument 403 "Sorry can't allow you access today" 1269ErrorDocument 403 Forbidden!</pre> 1270 1271 1272 <p>Additionally, the special value <code>default</code> can be used 1273 to specify Apache httpd's simple hardcoded message. While not required 1274 under normal circumstances, <code>default</code> will restore 1275 Apache httpd's simple hardcoded message for configurations that would 1276 otherwise inherit an existing <code class="directive">ErrorDocument</code>.</p> 1277 1278 <pre class="prettyprint lang-config">ErrorDocument 404 /cgi-bin/bad_urls.pl 1279 1280<Directory /web/docs> 1281 ErrorDocument 404 default 1282</Directory></pre> 1283 1284 1285 <p>Note that when you specify an <code class="directive">ErrorDocument</code> 1286 that points to a remote URL (ie. anything with a method such as 1287 <code>http</code> in front of it), Apache HTTP Server will send a redirect to the 1288 client to tell it where to find the document, even if the 1289 document ends up being on the same server. This has several 1290 implications, the most important being that the client will not 1291 receive the original error status code, but instead will 1292 receive a redirect status code. This in turn can confuse web 1293 robots and other clients which try to determine if a URL is 1294 valid using the status code. In addition, if you use a remote 1295 URL in an <code>ErrorDocument 401</code>, the client will not 1296 know to prompt the user for a password since it will not 1297 receive the 401 status code. Therefore, <strong>if you use an 1298 <code>ErrorDocument 401</code> directive then it must refer to a local 1299 document.</strong></p> 1300 1301 <p>Microsoft Internet Explorer (MSIE) will by default ignore 1302 server-generated error messages when they are "too small" and substitute 1303 its own "friendly" error messages. The size threshold varies depending on 1304 the type of error, but in general, if you make your error document 1305 greater than 512 bytes, then MSIE will show the server-generated 1306 error rather than masking it. More information is available in 1307 Microsoft Knowledge Base article <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q294807">Q294807</a>.</p> 1308 1309 <p>Although most error messages can be overridden, there are certain 1310 circumstances where the internal messages are used regardless of the 1311 setting of <code class="directive"><a href="#errordocument">ErrorDocument</a></code>. In 1312 particular, if a malformed request is detected, normal request processing 1313 will be immediately halted and the internal error message returned. 1314 This is necessary to guard against security problems caused by 1315 bad requests.</p> 1316 1317 <p>If you are using mod_proxy, you may wish to enable 1318 <code class="directive"><a href="/mod/mod_proxy.html#proxyerroroverride">ProxyErrorOverride</a></code> so that you can provide 1319 custom error messages on behalf of your Origin servers. If you don't enable ProxyErrorOverride, 1320 Apache httpd will not generate custom error documents for proxied content.</p> 1321 1322<h3>See also</h3> 1323<ul> 1324<li><a href="/custom-error.html">documentation of 1325 customizable responses</a></li> 1326</ul> 1327</div> 1328<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1329<div class="directive-section"><h2><a name="ErrorLog" id="ErrorLog">ErrorLog</a> <a name="errorlog" id="errorlog">Directive</a></h2> 1330<table class="directive"> 1331<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location where the server will log errors</td></tr> 1332<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> ErrorLog <var>file-path</var>|syslog[:<var>facility</var>]</code></td></tr> 1333<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> 1334<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1335<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1336<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1337</table> 1338 <p>The <code class="directive">ErrorLog</code> directive sets the name of 1339 the file to which the server will log any errors it encounters. If 1340 the <var>file-path</var> is not absolute then it is assumed to be 1341 relative to the <code class="directive"><a href="#serverroot">ServerRoot</a></code>.</p> 1342 1343 <pre class="prettyprint lang-config">ErrorLog "/var/log/httpd/error_log"</pre> 1344 1345 1346 <p>If the <var>file-path</var> 1347 begins with a pipe character "<code>|</code>" then it is assumed to be a 1348 command to spawn to handle the error log.</p> 1349 1350 <pre class="prettyprint lang-config">ErrorLog "|/usr/local/bin/httpd_errors"</pre> 1351 1352 1353 <p>See the notes on <a href="/logs.html#piped">piped logs</a> for 1354 more information.</p> 1355 1356 <p>Using <code>syslog</code> instead of a filename enables logging 1357 via syslogd(8) if the system supports it. The default is to use 1358 syslog facility <code>local7</code>, but you can override this by 1359 using the <code>syslog:<var>facility</var></code> syntax where 1360 <var>facility</var> can be one of the names usually documented in 1361 syslog(1). The facility is effectively global, and if it is changed 1362 in individual virtual hosts, the final facility specified affects the 1363 entire server.</p> 1364 1365 <pre class="prettyprint lang-config">ErrorLog syslog:user</pre> 1366 1367 1368 <p>SECURITY: See the <a href="/misc/security_tips.html#serverroot">security tips</a> 1369 document for details on why your security could be compromised 1370 if the directory where log files are stored is writable by 1371 anyone other than the user that starts the server.</p> 1372 <div class="warning"><h3>Note</h3> 1373 <p>When entering a file path on non-Unix platforms, care should be taken 1374 to make sure that only forward slashes are used even though the platform 1375 may allow the use of back slashes. In general it is a good idea to always 1376 use forward slashes throughout the configuration files.</p> 1377 </div> 1378 1379<h3>See also</h3> 1380<ul> 1381<li><code class="directive"><a href="#loglevel">LogLevel</a></code></li> 1382<li><a href="/logs.html">Apache HTTP Server Log Files</a></li> 1383</ul> 1384</div> 1385<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1386<div class="directive-section"><h2><a name="ErrorLogFormat" id="ErrorLogFormat">ErrorLogFormat</a> <a name="errorlogformat" id="errorlogformat">Directive</a></h2> 1387<table class="directive"> 1388<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Format specification for error log entries</td></tr> 1389<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> ErrorLogFormat [connection|request] <var>format</var></code></td></tr> 1390<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1391<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1392<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1393<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache httpd 2.3.9 and later</td></tr> 1394</table> 1395 <p><code class="directive">ErrorLogFormat</code> allows to specify what 1396 supplementary information is logged in the error log in addition to the 1397 actual log message.</p> 1398 1399 <pre class="prettyprint lang-config">#Simple example 1400ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"</pre> 1401 1402 1403 <p>Specifying <code>connection</code> or <code>request</code> as first 1404 parameter allows to specify additional formats, causing additional 1405 information to be logged when the first message is logged for a specific 1406 connection or request, respectively. This additional information is only 1407 logged once per connection/request. If a connection or request is processed 1408 without causing any log message, the additional information is not logged 1409 either.</p> 1410 1411 <p>It can happen that some format string items do not produce output. For 1412 example, the Referer header is only present if the log message is 1413 associated to a request and the log message happens at a time when the 1414 Referer header has already been read from the client. If no output is 1415 produced, the default behavior is to delete everything from the preceding 1416 space character to the next space character. This means the log line is 1417 implicitly divided into fields on non-whitespace to whitespace transitions. 1418 If a format string item does not produce output, the whole field is 1419 omitted. For example, if the remote address <code>%a</code> in the log 1420 format <code>[%t] [%l] [%a] %M </code> is not available, the surrounding 1421 brackets are not logged either. Space characters can be escaped with a 1422 backslash to prevent them from delimiting a field. The combination '% ' 1423 (percent space) is a zero-width field delimiter that does not produce any 1424 output.</p> 1425 1426 <p>The above behavior can be changed by adding modifiers to the format 1427 string item. A <code>-</code> (minus) modifier causes a minus to be logged if the 1428 respective item does not produce any output. In once-per-connection/request 1429 formats, it is also possible to use the <code>+</code> (plus) modifier. If an 1430 item with the plus modifier does not produce any output, the whole line is 1431 omitted.</p> 1432 1433 <p>A number as modifier can be used to assign a log severity level to a 1434 format item. The item will only be logged if the severity of the log 1435 message is not higher than the specified log severity level. The number can 1436 range from 1 (alert) over 4 (warn) and 7 (debug) to 15 (trace8).</p> 1437 1438 <p>For example, here's what would happen if you added modifiers to 1439 the <code>%{Referer}i</code> token, which logs the 1440 <code>Referer</code> request header.</p> 1441 1442 <table class="bordered"><tr class="header"><th>Modified Token</th><th>Meaning</th></tr> 1443<tr> 1444 <td><code>%-{Referer}i</code></td> 1445 <td>Logs a <code>-</code> if <code>Referer</code> is not set.</td> 1446 </tr> 1447<tr class="odd"> 1448 <td><code>%+{Referer}i</code></td> 1449 <td>Omits the entire line if <code>Referer</code> is not set.</td> 1450 </tr> 1451<tr> 1452 <td><code>%4{Referer}i</code></td> 1453 <td>Logs the <code>Referer</code> only if the log message severity 1454 is higher than 4.</td> 1455 </tr> 1456</table> 1457 1458 <p>Some format string items accept additional parameters in braces.</p> 1459 1460 <table class="bordered"><tr class="header"><th>Format String</th> <th>Description</th></tr> 1461<tr><td><code>%%</code></td> 1462 <td>The percent sign</td></tr> 1463<tr class="odd"><td><code>%a</code></td> 1464 <td>Client IP address and port of the request</td></tr> 1465<tr><td><code>%{c}a</code></td> 1466 <td>Underlying peer IP address and port of the connection (see the 1467 <code class="module"><a href="/mod/mod_remoteip.html">mod_remoteip</a></code> module)</td></tr> 1468<tr class="odd"><td><code>%A</code></td> 1469 <td>Local IP-address and port</td></tr> 1470<tr><td><code>%{<em>name</em>}e</code></td> 1471 <td>Request environment variable <em>name</em></td></tr> 1472<tr class="odd"><td><code>%E</code></td> 1473 <td>APR/OS error status code and string</td></tr> 1474<tr><td><code>%F</code></td> 1475 <td>Source file name and line number of the log call</td></tr> 1476<tr class="odd"><td><code>%{<em>name</em>}i</code></td> 1477 <td>Request header <em>name</em></td></tr> 1478<tr><td><code>%k</code></td> 1479 <td>Number of keep-alive requests on this connection</td></tr> 1480<tr class="odd"><td><code>%l</code></td> 1481 <td>Loglevel of the message</td></tr> 1482<tr><td><code>%L</code></td> 1483 <td>Log ID of the request</td></tr> 1484<tr class="odd"><td><code>%{c}L</code></td> 1485 <td>Log ID of the connection</td></tr> 1486<tr><td><code>%{C}L</code></td> 1487 <td>Log ID of the connection if used in connection scope, empty otherwise</td></tr> 1488<tr class="odd"><td><code>%m</code></td> 1489 <td>Name of the module logging the message</td></tr> 1490<tr><td><code>%M</code></td> 1491 <td>The actual log message</td></tr> 1492<tr class="odd"><td><code>%{<em>name</em>}n</code></td> 1493 <td>Request note <em>name</em></td></tr> 1494<tr><td><code>%P</code></td> 1495 <td>Process ID of current process</td></tr> 1496<tr class="odd"><td><code>%T</code></td> 1497 <td>Thread ID of current thread</td></tr> 1498<tr><td><code>%{g}T</code></td> 1499 <td>System unique thread ID of current thread (the same ID as 1500 displayed by e.g. <code>top</code>; currently Linux only)</td></tr> 1501<tr class="odd"><td><code>%t</code></td> 1502 <td>The current time</td></tr> 1503<tr><td><code>%{u}t</code></td> 1504 <td>The current time including micro-seconds</td></tr> 1505<tr class="odd"><td><code>%{cu}t</code></td> 1506 <td>The current time in compact ISO 8601 format, including 1507 micro-seconds</td></tr> 1508<tr><td><code>%v</code></td> 1509 <td>The canonical <code class="directive"><a href="#servername">ServerName</a></code> 1510 of the current server.</td></tr> 1511<tr class="odd"><td><code>%V</code></td> 1512 <td>The server name of the server serving the request according to the 1513 <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> 1514 setting.</td></tr> 1515<tr><td><code>\ </code> (backslash space)</td> 1516 <td>Non-field delimiting space</td></tr> 1517<tr class="odd"><td><code>% </code> (percent space)</td> 1518 <td>Field delimiter (no output)</td></tr> 1519</table> 1520 1521 <p>The log ID format <code>%L</code> produces a unique id for a connection 1522 or request. This can be used to correlate which log lines belong to the 1523 same connection or request, which request happens on which connection. 1524 A <code>%L</code> format string is also available in 1525 <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code>, to allow to correlate access log entries 1526 with error log lines. If <code class="module"><a href="/mod/mod_unique_id.html">mod_unique_id</a></code> is loaded, its 1527 unique id will be used as log ID for requests.</p> 1528 1529 <pre class="prettyprint lang-config">#Example (default format for threaded MPMs) 1530ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P:tid %T] %7F: %E: [client\ %a] %M%�,\�referer\�%{Referer}i"</pre> 1531 1532 1533 <p>This would result in error messages such as:</p> 1534 1535 <div class="example"><p><code> 1536 [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 1537 </code></p></div> 1538 1539 <p>Notice that, as discussed above, some fields are omitted 1540 entirely because they are not defined.</p> 1541 1542 <pre class="prettyprint lang-config">#Example (similar to the 2.2.x format) 1543ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M%�,\�referer\�%{Referer}i"</pre> 1544 1545 1546 <pre class="prettyprint lang-config">#Advanced example with request/connection log IDs 1547ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M" 1548ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T" 1549ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'" 1550ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'" 1551ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"</pre> 1552 1553 1554 1555<h3>See also</h3> 1556<ul> 1557<li><code class="directive"><a href="#errorlog">ErrorLog</a></code></li> 1558<li><code class="directive"><a href="#loglevel">LogLevel</a></code></li> 1559<li><a href="/logs.html">Apache HTTP Server Log Files</a></li> 1560</ul> 1561</div> 1562<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1563<div class="directive-section"><h2><a name="ExtendedStatus" id="ExtendedStatus">ExtendedStatus</a> <a name="extendedstatus" id="extendedstatus">Directive</a></h2> 1564<table class="directive"> 1565<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keep track of extended status information for each 1566request</td></tr> 1567<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtendedStatus On|Off</code></td></tr> 1568<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ExtendedStatus Off[*]</code></td></tr> 1569<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1570<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1571<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1572</table> 1573 <p>This option tracks additional data per worker about the 1574 currently executing request, and a utilization summary; you 1575 can see these variables during runtime by configuring 1576 <code class="module"><a href="/mod/mod_status.html">mod_status</a></code>. Note that other modules may 1577 rely on this scoreboard.</p> 1578 1579 <p>This setting applies to the entire server, and cannot be 1580 enabled or disabled on a virtualhost-by-virtualhost basis. 1581 The collection of extended status information can slow down 1582 the server. Also note that this setting cannot be changed 1583 during a graceful restart.</p> 1584 1585 <div class="note"> 1586 <p>Note that loading <code class="module"><a href="/mod/mod_status.html">mod_status</a></code> will change 1587 the default behavior to ExtendedStatus On, while other 1588 third party modules may do the same. Such modules rely on 1589 collecting detailed information about the state of all workers. 1590 The default is changed by <code class="module"><a href="/mod/mod_status.html">mod_status</a></code> beginning 1591 with version 2.3.6; the previous default was always Off.</p> 1592 </div> 1593 1594 1595</div> 1596<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1597<div class="directive-section"><h2><a name="FileETag" id="FileETag">FileETag</a> <a name="fileetag" id="fileetag">Directive</a></h2> 1598<table class="directive"> 1599<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File attributes used to create the ETag 1600HTTP response header for static files</td></tr> 1601<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FileETag <var>component</var> ...</code></td></tr> 1602<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>FileETag MTime Size</code></td></tr> 1603<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1604<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 1605<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1606<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1607<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The default used to be "INode MTime Size" in 2.3.14 and 1608earlier.</td></tr> 1609</table> 1610 <p> 1611 The <code class="directive">FileETag</code> directive configures the file 1612 attributes that are used to create the <code>ETag</code> (entity 1613 tag) response header field when the document is based on a static file. 1614 (The <code>ETag</code> value is used in cache management to save 1615 network bandwidth.) The 1616 <code class="directive">FileETag</code> directive allows you to choose 1617 which of these -- if any -- should be used. The recognized keywords are: 1618 </p> 1619 1620 <dl> 1621 <dt><strong>INode</strong></dt> 1622 <dd>The file's i-node number will be included in the calculation</dd> 1623 <dt><strong>MTime</strong></dt> 1624 <dd>The date and time the file was last modified will be included</dd> 1625 <dt><strong>Size</strong></dt> 1626 <dd>The number of bytes in the file will be included</dd> 1627 <dt><strong>All</strong></dt> 1628 <dd>All available fields will be used. This is equivalent to: 1629 <pre class="prettyprint lang-config">FileETag INode MTime Size</pre> 1630</dd> 1631 <dt><strong>None</strong></dt> 1632 <dd>If a document is file-based, no <code>ETag</code> field will be 1633 included in the response</dd> 1634 </dl> 1635 1636 <p>The <code>INode</code>, <code>MTime</code>, and <code>Size</code> 1637 keywords may be prefixed with either <code>+</code> or <code>-</code>, 1638 which allow changes to be made to the default setting inherited 1639 from a broader scope. Any keyword appearing without such a prefix 1640 immediately and completely cancels the inherited setting.</p> 1641 1642 <p>If a directory's configuration includes 1643 <code>FileETag INode MTime Size</code>, and a 1644 subdirectory's includes <code>FileETag -INode</code>, 1645 the setting for that subdirectory (which will be inherited by 1646 any sub-subdirectories that don't override it) will be equivalent to 1647 <code>FileETag MTime Size</code>.</p> 1648 <div class="warning"><h3>Warning</h3> 1649 Do not change the default for directories or locations that have WebDAV 1650 enabled and use <code class="module"><a href="/mod/mod_dav_fs.html">mod_dav_fs</a></code> as a storage provider. 1651 <code class="module"><a href="/mod/mod_dav_fs.html">mod_dav_fs</a></code> uses <code>MTime Size</code> 1652 as a fixed format for <code>ETag</code> comparisons on conditional requests. 1653 These conditional requests will break if the <code>ETag</code> format is 1654 changed via <code class="directive">FileETag</code>. 1655 </div> 1656 <div class="note"><h3>Server Side Includes</h3> 1657 An ETag is not generated for responses parsed by <code class="module"><a href="/mod/mod_include.html">mod_include</a></code>, 1658 since the response entity can change without a change of the INode, MTime, or Size 1659 of the static file with embedded SSI directives. 1660 </div> 1661 1662 1663</div> 1664<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1665<div class="directive-section"><h2><a name="Files" id="Files"><Files></a> <a name="files" id="files">Directive</a></h2> 1666<table class="directive"> 1667<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to matched 1668filenames</td></tr> 1669<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Files <var>filename</var>> ... </Files></code></td></tr> 1670<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1671<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1672<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1673<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1674</table> 1675 <p>The <code class="directive"><Files></code> directive 1676 limits the scope of the enclosed directives by filename. It is comparable 1677 to the <code class="directive"><a href="#directory"><Directory></a></code> 1678 and <code class="directive"><a href="#location"><Location></a></code> 1679 directives. It should be matched with a <code></Files></code> 1680 directive. The directives given within this section will be applied to 1681 any object with a basename (last component of filename) matching the 1682 specified filename. <code class="directive"><Files></code> 1683 sections are processed in the order they appear in the 1684 configuration file, after the <code class="directive"><a href="#directory"><Directory></a></code> sections and 1685 <code>.htaccess</code> files are read, but before <code class="directive"><a href="#location"><Location></a></code> sections. Note 1686 that <code class="directive"><Files></code> can be nested 1687 inside <code class="directive"><a href="#directory"><Directory></a></code> sections to restrict the 1688 portion of the filesystem they apply to.</p> 1689 1690 <p>The <var>filename</var> argument should include a filename, or 1691 a wild-card string, where <code>?</code> matches any single character, 1692 and <code>*</code> matches any sequences of characters.</p> 1693 <pre class="prettyprint lang-config"><Files "cat.html"> 1694 # Insert stuff that applies to cat.html here 1695</Files> 1696 1697<Files "?at.*"> 1698 # This would apply to cat.html, bat.html, hat.php and so on. 1699</Files></pre> 1700 1701 <p><a class="glossarylink" href="/glossary.html#regex" title="see glossary">Regular expressions</a> 1702 can also be used, with the addition of the 1703 <code>~</code> character. For example:</p> 1704 1705 <pre class="prettyprint lang-config"><Files ~ "\.(gif|jpe?g|png)$"> 1706 #... 1707</Files></pre> 1708 1709 1710 <p>would match most common Internet graphics formats. <code class="directive"><a href="#filesmatch"><FilesMatch></a></code> is preferred, 1711 however.</p> 1712 1713 <p>Note that unlike <code class="directive"><a href="#directory"><Directory></a></code> and <code class="directive"><a href="#location"><Location></a></code> sections, <code class="directive"><Files></code> sections can be used inside 1714 <code>.htaccess</code> files. This allows users to control access to 1715 their own files, at a file-by-file level.</p> 1716 1717 1718<h3>See also</h3> 1719<ul> 1720<li><a href="/sections.html">How <Directory>, <Location> 1721 and <Files> sections work</a> for an explanation of how these 1722 different sections are combined when a request is received</li> 1723</ul> 1724</div> 1725<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1726<div class="directive-section"><h2><a name="FilesMatch" id="FilesMatch"><FilesMatch></a> <a name="filesmatch" id="filesmatch">Directive</a></h2> 1727<table class="directive"> 1728<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply to regular-expression matched 1729filenames</td></tr> 1730<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><FilesMatch <var>regex</var>> ... </FilesMatch></code></td></tr> 1731<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1732<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1733<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1734<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1735</table> 1736 <p>The <code class="directive"><FilesMatch></code> directive 1737 limits the scope of the enclosed directives by filename, just as the 1738 <code class="directive"><a href="#files"><Files></a></code> directive 1739 does. However, it accepts a <a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular 1740 expression</a>. For example:</p> 1741 1742<pre class="prettyprint lang-config"><FilesMatch "\.(gif|jpe?g|png)$"> 1743 # ... 1744</FilesMatch></pre> 1745 1746 1747 <p>would match most common Internet graphics formats.</p> 1748 1749 <p>From 2.4.8 onwards, named groups and backreferences are captured and 1750 written to the environment with the corresponding name prefixed with 1751 "MATCH_" and in upper case. This allows elements of files to be referenced 1752 from within <a href="/expr.html">expressions</a> and modules like 1753 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered 1754 (unnamed) backreferences are ignored. Use named groups instead.</p> 1755 1756<pre class="prettyprint lang-config"><FileMatch ^(?<sitename>[^/]+)> 1757 require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example 1758</FileMatch></pre> 1759 1760 1761<h3>See also</h3> 1762<ul> 1763<li><a href="/sections.html">How <Directory>, <Location> 1764 and <Files> sections work</a> for an explanation of how these 1765 different sections are combined when a request is received</li> 1766</ul> 1767</div> 1768<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1769<div class="directive-section"><h2><a name="ForceType" id="ForceType">ForceType</a> <a name="forcetype" id="forcetype">Directive</a></h2> 1770<table class="directive"> 1771<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be served with the specified 1772media type in the HTTP Content-Type header field</td></tr> 1773<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceType <var>media-type</var>|None</code></td></tr> 1774<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 1775<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 1776<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1777<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1778</table> 1779 <p>When placed into an <code>.htaccess</code> file or a 1780 <code class="directive"><a href="#directory"><Directory></a></code>, or 1781 <code class="directive"><a href="#location"><Location></a></code> or 1782 <code class="directive"><a href="#files"><Files></a></code> 1783 section, this directive forces all matching files to be served 1784 with the content type identification given by 1785 <var>media-type</var>. For example, if you had a directory full of 1786 GIF files, but did not want to label them all with <code>.gif</code>, 1787 you might want to use:</p> 1788 1789 <pre class="prettyprint lang-config">ForceType image/gif</pre> 1790 1791 1792 <p>Note that this directive overrides other indirect media type 1793 associations defined in mime.types or via the 1794 <code class="directive"><a href="/mod/mod_mime.html#addtype">AddType</a></code>.</p> 1795 1796 <p>You can also override more general 1797 <code class="directive">ForceType</code> settings 1798 by using the value of <code>None</code>:</p> 1799 1800 <pre class="prettyprint lang-config"># force all files to be image/gif: 1801<Location /images> 1802 ForceType image/gif 1803</Location> 1804 1805# but normal mime-type associations here: 1806<Location /images/mixed> 1807 ForceType None 1808</Location></pre> 1809 1810 1811 <p>This directive primarily overrides the content types generated for 1812 static files served out of the filesystem. For resources other than 1813 static files, where the generator of the response typically specifies 1814 a Content-Type, this directive has no effect.</p> 1815 1816 1817</div> 1818<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1819<div class="directive-section"><h2><a name="GprofDir" id="GprofDir">GprofDir</a> <a name="gprofdir" id="gprofdir">Directive</a></h2> 1820<table class="directive"> 1821<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory to write gmon.out profiling data to. </td></tr> 1822<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> 1823<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1824<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1825<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1826</table> 1827 <p>When the server has been compiled with gprof profiling support, 1828 <code class="directive">GprofDir</code> causes <code>gmon.out</code> files to 1829 be written to the specified directory when the process exits. If the 1830 argument ends with a percent symbol ('%'), subdirectories are created 1831 for each process id.</p> 1832 1833 <p>This directive currently only works with the <code class="module"><a href="/mod/prefork.html">prefork</a></code> 1834 MPM.</p> 1835 1836</div> 1837<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1838<div class="directive-section"><h2><a name="HostnameLookups" id="HostnameLookups">HostnameLookups</a> <a name="hostnamelookups" id="hostnamelookups">Directive</a></h2> 1839<table class="directive"> 1840<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables DNS lookups on client IP addresses</td></tr> 1841<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HostnameLookups On|Off|Double</code></td></tr> 1842<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>HostnameLookups Off</code></td></tr> 1843<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 1844<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1845<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1846</table> 1847 <p>This directive enables DNS lookups so that host names can be 1848 logged (and passed to CGIs/SSIs in <code>REMOTE_HOST</code>). 1849 The value <code>Double</code> refers to doing double-reverse 1850 DNS lookup. That is, after a reverse lookup is performed, a forward 1851 lookup is then performed on that result. At least one of the IP 1852 addresses in the forward lookup must match the original 1853 address. (In "tcpwrappers" terminology this is called 1854 <code>PARANOID</code>.)</p> 1855 1856 <p>Regardless of the setting, when <code class="module"><a href="/mod/mod_authz_host.html">mod_authz_host</a></code> is 1857 used for controlling access by hostname, a double reverse lookup 1858 will be performed. This is necessary for security. Note that the 1859 result of this double-reverse isn't generally available unless you 1860 set <code>HostnameLookups Double</code>. For example, if only 1861 <code>HostnameLookups On</code> and a request is made to an object 1862 that is protected by hostname restrictions, regardless of whether 1863 the double-reverse fails or not, CGIs will still be passed the 1864 single-reverse result in <code>REMOTE_HOST</code>.</p> 1865 1866 <p>The default is <code>Off</code> in order to save the network 1867 traffic for those sites that don't truly need the reverse 1868 lookups done. It is also better for the end users because they 1869 don't have to suffer the extra latency that a lookup entails. 1870 Heavily loaded sites should leave this directive 1871 <code>Off</code>, since DNS lookups can take considerable 1872 amounts of time. The utility <code class="program"><a href="/programs/logresolve.html">logresolve</a></code>, compiled by 1873 default to the <code>bin</code> subdirectory of your installation 1874 directory, can be used to look up host names from logged IP addresses 1875 offline.</p> 1876 1877 <p>Finally, if you have <a href="mod_authz_host.html#reqhost">hostname-based Require 1878 directives</a>, a hostname lookup will be performed regardless of 1879 the setting of <code>HostnameLookups</code>.</p> 1880 1881</div> 1882<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1883<div class="directive-section"><h2><a name="If" id="If"><If></a> <a name="if" id="if">Directive</a></h2> 1884<table class="directive"> 1885<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only if a condition is 1886satisfied by a request at runtime</td></tr> 1887<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><If <var>expression</var>> ... </If></code></td></tr> 1888<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1889<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1890<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1891<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1892</table> 1893 <p>The <code class="directive"><If></code> directive 1894 evaluates an expression at runtime, and applies the enclosed 1895 directives if and only if the expression evaluates to true. 1896 For example:</p> 1897 1898 <pre class="prettyprint lang-config"><If "-z req('Host')"></pre> 1899 1900 1901 <p>would match HTTP/1.0 requests without a <var>Host:</var> header. 1902 Expressions may contain various shell-like operators for string 1903 comparison (<code>=</code>, <code>!=</code>, <code><</code>, ...), 1904 integer comparison (<code>-eq</code>, <code>-ne</code>, ...), 1905 and others (<code>-n</code>, <code>-z</code>, <code>-f</code>, ...). 1906 It is also possible to use regular expressions, </p> 1907 1908 <pre class="prettyprint lang-config"><If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/"></pre> 1909 1910 1911 <p>shell-like pattern matches and many other operations. These operations 1912 can be done on request headers (<code>req</code>), environment variables 1913 (<code>env</code>), and a large number of other properties. The full 1914 documentation is available in <a href="/expr.html">Expressions in 1915 Apache HTTP Server</a>.</p> 1916 1917 <p>Only directives that support the <a href="directive-dict.html#Context">directory context</a> can be used within this configuration section.</p> 1918 1919 1920<h3>See also</h3> 1921<ul> 1922<li><a href="/expr.html">Expressions in Apache HTTP Server</a>, 1923for a complete reference and more examples.</li> 1924<li><code class="directive"><a href="#elseif"><ElseIf></a></code></li> 1925<li><code class="directive"><a href="#else"><Else></a></code></li> 1926<li><a href="/sections.html">How <Directory>, <Location>, 1927 <Files> sections work</a> for an explanation of how these 1928 different sections are combined when a request is received. 1929 <code class="directive"><If></code>, 1930 <code class="directive"><ElseIf></code>, and 1931 <code class="directive"><Else></code> are applied last.</li> 1932</ul> 1933</div> 1934<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1935<div class="directive-section"><h2><a name="IfDefine" id="IfDefine"><IfDefine></a> <a name="ifdefine" id="ifdefine">Directive</a></h2> 1936<table class="directive"> 1937<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that will be processed only 1938if a test is true at startup</td></tr> 1939<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><IfDefine [!]<var>parameter-name</var>> ... 1940 </IfDefine></code></td></tr> 1941<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1942<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 1943<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 1944<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 1945</table> 1946 <p>The <code><IfDefine <var>test</var>>...</IfDefine> 1947 </code> section is used to mark directives that are conditional. The 1948 directives within an <code class="directive"><IfDefine></code> 1949 section are only processed if the <var>test</var> is true. If <var> 1950 test</var> is false, everything between the start and end markers is 1951 ignored.</p> 1952 1953 <p>The <var>test</var> in the <code class="directive"><IfDefine></code> section directive can be one of two forms:</p> 1954 1955 <ul> 1956 <li><var>parameter-name</var></li> 1957 1958 <li><code>!</code><var>parameter-name</var></li> 1959 </ul> 1960 1961 <p>In the former case, the directives between the start and end 1962 markers are only processed if the parameter named 1963 <var>parameter-name</var> is defined. The second format reverses 1964 the test, and only processes the directives if 1965 <var>parameter-name</var> is <strong>not</strong> defined.</p> 1966 1967 <p>The <var>parameter-name</var> argument is a define as given on the 1968 <code class="program"><a href="/programs/httpd.html">httpd</a></code> command line via <code>-D<var>parameter</var> 1969 </code> at the time the server was started or by the <code class="directive"><a href="#define">Define</a></code> directive.</p> 1970 1971 <p><code class="directive"><IfDefine></code> sections are 1972 nest-able, which can be used to implement simple 1973 multiple-parameter tests. Example:</p> 1974 1975 <div class="example"><p><code>httpd -DReverseProxy -DUseCache -DMemCache ...</code></p></div> 1976 <pre class="prettyprint lang-config"><IfDefine ReverseProxy> 1977 LoadModule proxy_module modules/mod_proxy.so 1978 LoadModule proxy_http_module modules/mod_proxy_http.so 1979 <IfDefine UseCache> 1980 LoadModule cache_module modules/mod_cache.so 1981 <IfDefine MemCache> 1982 LoadModule mem_cache_module modules/mod_mem_cache.so 1983 </IfDefine> 1984 <IfDefine !MemCache> 1985 LoadModule cache_disk_module modules/mod_cache_disk.so 1986 </IfDefine> 1987 </IfDefine> 1988</IfDefine></pre> 1989 1990 1991</div> 1992<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1993<div class="directive-section"><h2><a name="IfModule" id="IfModule"><IfModule></a> <a name="ifmodule" id="ifmodule">Directive</a></h2> 1994<table class="directive"> 1995<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Encloses directives that are processed conditional on the 1996presence or absence of a specific module</td></tr> 1997<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><IfModule [!]<var>module-file</var>|<var>module-identifier</var>> ... 1998 </IfModule></code></td></tr> 1999<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 2000<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 2001<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2002<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2003<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Module identifiers are available in version 2.1 and 2004later.</td></tr> 2005</table> 2006 <p>The <code><IfModule <var>test</var>>...</IfModule></code> 2007 section is used to mark directives that are conditional on the presence of 2008 a specific module. The directives within an <code class="directive"><IfModule></code> section are only processed if the <var>test</var> 2009 is true. If <var>test</var> is false, everything between the start and 2010 end markers is ignored.</p> 2011 2012 <p>The <var>test</var> in the <code class="directive"><IfModule></code> section directive can be one of two forms:</p> 2013 2014 <ul> 2015 <li><var>module</var></li> 2016 2017 <li>!<var>module</var></li> 2018 </ul> 2019 2020 <p>In the former case, the directives between the start and end 2021 markers are only processed if the module named <var>module</var> 2022 is included in Apache httpd -- either compiled in or 2023 dynamically loaded using <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code>. The second format reverses the test, 2024 and only processes the directives if <var>module</var> is 2025 <strong>not</strong> included.</p> 2026 2027 <p>The <var>module</var> argument can be either the module identifier or 2028 the file name of the module, at the time it was compiled. For example, 2029 <code>rewrite_module</code> is the identifier and 2030 <code>mod_rewrite.c</code> is the file name. If a module consists of 2031 several source files, use the name of the file containing the string 2032 <code>STANDARD20_MODULE_STUFF</code>.</p> 2033 2034 <p><code class="directive"><IfModule></code> sections are 2035 nest-able, which can be used to implement simple multiple-module 2036 tests.</p> 2037 2038 <div class="note">This section should only be used if you need to have one 2039 configuration file that works whether or not a specific module 2040 is available. In normal operation, directives need not be 2041 placed in <code class="directive"><IfModule></code> 2042 sections.</div> 2043 2044</div> 2045<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2046<div class="directive-section"><h2><a name="Include" id="Include">Include</a> <a name="include" id="include">Directive</a></h2> 2047<table class="directive"> 2048<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Includes other configuration files from within 2049the server configuration files</td></tr> 2050<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> 2051<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 2052<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2053<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2054<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Directory 2055wildcard matching available in 2.3.6 and later</td></tr> 2056</table> 2057 <p>This directive allows inclusion of other configuration files 2058 from within the server configuration files.</p> 2059 2060 <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used 2061 in the filename or directory parts of the path to include several files 2062 at once, in alphabetical order. In addition, if 2063 <code class="directive">Include</code> points to a directory, rather than a file, 2064 Apache httpd will read all files in that directory and any subdirectory. 2065 However, including entire directories is not recommended, because it is 2066 easy to accidentally leave temporary files in a directory that can cause 2067 <code class="program"><a href="/programs/httpd.html">httpd</a></code> to fail. Instead, we encourage you to use the 2068 wildcard syntax shown below, to include files that match a particular 2069 pattern, such as *.conf, for example.</p> 2070 2071 <p>The <code class="directive"><a href="#include">Include</a></code> directive will 2072 <strong>fail with an error</strong> if a wildcard expression does not 2073 match any file. The <code class="directive"><a href="#includeoptional">IncludeOptional</a></code> 2074 directive can be used if non-matching wildcards should be ignored.</p> 2075 2076 <p>The file path specified may be an absolute path, or may be relative 2077 to the <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory.</p> 2078 2079 <p>Examples:</p> 2080 2081 <pre class="prettyprint lang-config">Include /usr/local/apache2/conf/ssl.conf 2082Include /usr/local/apache2/conf/vhosts/*.conf</pre> 2083 2084 2085 <p>Or, providing paths relative to your <code class="directive"><a href="#serverroot">ServerRoot</a></code> directory:</p> 2086 2087 <pre class="prettyprint lang-config">Include conf/ssl.conf 2088Include conf/vhosts/*.conf</pre> 2089 2090 2091 <p>Wildcards may be included in the directory or file portion of the 2092 path. This example will fail if there is no subdirectory in conf/vhosts 2093 that contains at least one *.conf file:</p> 2094 2095 <pre class="prettyprint lang-config">Include conf/vhosts/*/*.conf</pre> 2096 2097 2098 <p>Alternatively, the following command will just be ignored in case of 2099 missing files or directories:</p> 2100 2101 <pre class="prettyprint lang-config">IncludeOptional conf/vhosts/*/*.conf</pre> 2102 2103 2104 2105<h3>See also</h3> 2106<ul> 2107<li><code class="directive"><a href="#includeoptional">IncludeOptional</a></code></li> 2108<li><code class="program"><a href="/programs/apachectl.html">apachectl</a></code></li> 2109</ul> 2110</div> 2111<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2112<div class="directive-section"><h2><a name="IncludeOptional" id="IncludeOptional">IncludeOptional</a> <a name="includeoptional" id="includeoptional">Directive</a></h2> 2113<table class="directive"> 2114<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Includes other configuration files from within 2115the server configuration files</td></tr> 2116<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> 2117<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 2118<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2119<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2120<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in 2.3.6 and later</td></tr> 2121</table> 2122 <p>This directive allows inclusion of other configuration files 2123 from within the server configuration files. It works identically to the 2124 <code class="directive"><a href="#include">Include</a></code> directive, with the 2125 exception that if wildcards do not match any file or directory, the 2126 <code class="directive"><a href="#includeoptional">IncludeOptional</a></code> directive will be 2127 silently ignored instead of causing an error.</p> 2128 2129<h3>See also</h3> 2130<ul> 2131<li><code class="directive"><a href="#include">Include</a></code></li> 2132<li><code class="program"><a href="/programs/apachectl.html">apachectl</a></code></li> 2133</ul> 2134</div> 2135<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2136<div class="directive-section"><h2><a name="KeepAlive" id="KeepAlive">KeepAlive</a> <a name="keepalive" id="keepalive">Directive</a></h2> 2137<table class="directive"> 2138<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables HTTP persistent connections</td></tr> 2139<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAlive On|Off</code></td></tr> 2140<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAlive On</code></td></tr> 2141<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2142<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2143<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2144</table> 2145 <p>The Keep-Alive extension to HTTP/1.0 and the persistent 2146 connection feature of HTTP/1.1 provide long-lived HTTP sessions 2147 which allow multiple requests to be sent over the same TCP 2148 connection. In some cases this has been shown to result in an 2149 almost 50% speedup in latency times for HTML documents with 2150 many images. To enable Keep-Alive connections, set 2151 <code>KeepAlive On</code>.</p> 2152 2153 <p>For HTTP/1.0 clients, Keep-Alive connections will only be 2154 used if they are specifically requested by a client. In 2155 addition, a Keep-Alive connection with an HTTP/1.0 client can 2156 only be used when the length of the content is known in 2157 advance. This implies that dynamic content such as CGI output, 2158 SSI pages, and server-generated directory listings will 2159 generally not use Keep-Alive connections to HTTP/1.0 clients. 2160 For HTTP/1.1 clients, persistent connections are the default 2161 unless otherwise specified. If the client requests it, chunked 2162 encoding will be used in order to send content of unknown 2163 length over persistent connections.</p> 2164 2165 <p>When a client uses a Keep-Alive connection it will be counted 2166 as a single "request" for the <code class="directive"><a href="/mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code> directive, regardless 2167 of how many requests are sent using the connection.</p> 2168 2169<h3>See also</h3> 2170<ul> 2171<li><code class="directive"><a href="#maxkeepaliverequests">MaxKeepAliveRequests</a></code></li> 2172</ul> 2173</div> 2174<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2175<div class="directive-section"><h2><a name="KeepAliveTimeout" id="KeepAliveTimeout">KeepAliveTimeout</a> <a name="keepalivetimeout" id="keepalivetimeout">Directive</a></h2> 2176<table class="directive"> 2177<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for subsequent 2178requests on a persistent connection</td></tr> 2179<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>KeepAliveTimeout <var>num</var>[ms]</code></td></tr> 2180<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>KeepAliveTimeout 5</code></td></tr> 2181<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2182<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2183<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2184<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Specifying a value in milliseconds is available in 2185Apache httpd 2.3.2 and later</td></tr> 2186</table> 2187 <p>The number of seconds Apache httpd will wait for a subsequent 2188 request before closing the connection. By adding a postfix of ms the 2189 timeout can be also set in milliseconds. Once a request has been 2190 received, the timeout value specified by the 2191 <code class="directive"><a href="#timeout">Timeout</a></code> directive applies.</p> 2192 2193 <p>Setting <code class="directive">KeepAliveTimeout</code> to a high value 2194 may cause performance problems in heavily loaded servers. The 2195 higher the timeout, the more server processes will be kept 2196 occupied waiting on connections with idle clients.</p> 2197 2198 <p>In a name-based virtual host context, the value of the first 2199 defined virtual host best matching the local IP and port will be used.</p> 2200 2201</div> 2202<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2203<div class="directive-section"><h2><a name="Limit" id="Limit"><Limit></a> <a name="limit" id="limit">Directive</a></h2> 2204<table class="directive"> 2205<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict enclosed access controls to only certain HTTP 2206methods</td></tr> 2207<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Limit <var>method</var> [<var>method</var>] ... > ... 2208 </Limit></code></td></tr> 2209<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 2210<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig, Limit</td></tr> 2211<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2212<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2213</table> 2214 <p>Access controls are normally effective for 2215 <strong>all</strong> access methods, and this is the usual 2216 desired behavior. <strong>In the general case, access control 2217 directives should not be placed within a 2218 <code class="directive"><Limit></code> section.</strong></p> 2219 2220 <p>The purpose of the <code class="directive"><Limit></code> 2221 directive is to restrict the effect of the access controls to the 2222 nominated HTTP methods. For all other methods, the access 2223 restrictions that are enclosed in the <code class="directive"><Limit></code> bracket <strong>will have no 2224 effect</strong>. The following example applies the access control 2225 only to the methods <code>POST</code>, <code>PUT</code>, and 2226 <code>DELETE</code>, leaving all other methods unprotected:</p> 2227 2228 <pre class="prettyprint lang-config"><Limit POST PUT DELETE> 2229 Require valid-user 2230</Limit></pre> 2231 2232 2233 <p>The method names listed can be one or more of: <code>GET</code>, 2234 <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, 2235 <code>CONNECT</code>, <code>OPTIONS</code>, 2236 <code>PATCH</code>, <code>PROPFIND</code>, <code>PROPPATCH</code>, 2237 <code>MKCOL</code>, <code>COPY</code>, <code>MOVE</code>, 2238 <code>LOCK</code>, and <code>UNLOCK</code>. <strong>The method name is 2239 case-sensitive.</strong> If <code>GET</code> is used it will also 2240 restrict <code>HEAD</code> requests. The <code>TRACE</code> method 2241 cannot be limited (see <code class="directive"><a href="#traceenable">TraceEnable</a></code>).</p> 2242 2243 <div class="warning">A <code class="directive"><a href="#limitexcept"><LimitExcept></a></code> section should always be 2244 used in preference to a <code class="directive"><Limit></code> 2245 section when restricting access, since a <code class="directive"><a href="#limitexcept"><LimitExcept></a></code> section provides protection 2246 against arbitrary methods.</div> 2247 2248 <p>The <code class="directive"><Limit></code> and 2249 <code class="directive"><a href="#limitexcept"><LimitExcept></a></code> 2250 directives may be nested. In this case, each successive level of 2251 <code class="directive"><Limit></code> or <code class="directive"><a href="#limitexcept"><LimitExcept></a></code> directives must 2252 further restrict the set of methods to which access controls apply.</p> 2253 2254 <div class="warning">When using 2255 <code class="directive"><Limit></code> or 2256 <code class="directive"><LimitExcept></code> directives with 2257 the <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> directive, 2258 note that the first <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> 2259 to succeed authorizes the request, regardless of the presence of other 2260 <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> directives.</div> 2261 2262 <p>For example, given the following configuration, all users will 2263 be authorized for <code>POST</code> requests, and the 2264 <code>Require group editors</code> directive will be ignored 2265 in all cases:</p> 2266 2267 <pre class="prettyprint lang-config"><LimitExcept GET> 2268 Require valid-user 2269</LimitExcept> 2270<Limit POST> 2271 Require group editors 2272</Limit></pre> 2273 2274 2275</div> 2276<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2277<div class="directive-section"><h2><a name="LimitExcept" id="LimitExcept"><LimitExcept></a> <a name="limitexcept" id="limitexcept">Directive</a></h2> 2278<table class="directive"> 2279<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restrict access controls to all HTTP methods 2280except the named ones</td></tr> 2281<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><LimitExcept <var>method</var> [<var>method</var>] ... > ... 2282 </LimitExcept></code></td></tr> 2283<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 2284<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig, Limit</td></tr> 2285<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2286<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2287</table> 2288 <p><code class="directive"><LimitExcept></code> and 2289 <code></LimitExcept></code> are used to enclose 2290 a group of access control directives which will then apply to any 2291 HTTP access method <strong>not</strong> listed in the arguments; 2292 i.e., it is the opposite of a <code class="directive"><a href="#limit"><Limit></a></code> section and can be used to control 2293 both standard and nonstandard/unrecognized methods. See the 2294 documentation for <code class="directive"><a href="#limit"><Limit></a></code> for more details.</p> 2295 2296 <p>For example:</p> 2297 2298 <pre class="prettyprint lang-config"><LimitExcept POST GET> 2299 Require valid-user 2300</LimitExcept></pre> 2301 2302 2303 2304</div> 2305<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2306<div class="directive-section"><h2><a name="LimitInternalRecursion" id="LimitInternalRecursion">LimitInternalRecursion</a> <a name="limitinternalrecursion" id="limitinternalrecursion">Directive</a></h2> 2307<table class="directive"> 2308<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine maximum number of internal redirects and nested 2309subrequests</td></tr> 2310<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitInternalRecursion <var>number</var> [<var>number</var>]</code></td></tr> 2311<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitInternalRecursion 10</code></td></tr> 2312<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2313<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2314<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2315</table> 2316 <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 2317 redirects the original request to a CGI script. A subrequest is Apache httpd's 2318 mechanism to find out what would happen for some URI if it were requested. 2319 For example, <code class="module"><a href="/mod/mod_dir.html">mod_dir</a></code> uses subrequests to look for the 2320 files listed in the <code class="directive"><a href="/mod/mod_dir.html#directoryindex">DirectoryIndex</a></code> 2321 directive.</p> 2322 2323 <p><code class="directive">LimitInternalRecursion</code> prevents the server 2324 from crashing when entering an infinite loop of internal redirects or 2325 subrequests. Such loops are usually caused by misconfigurations.</p> 2326 2327 <p>The directive stores two different limits, which are evaluated on 2328 per-request basis. The first <var>number</var> is the maximum number of 2329 internal redirects, that may follow each other. The second <var>number</var> 2330 determines, how deep subrequests may be nested. If you specify only one 2331 <var>number</var>, it will be assigned to both limits.</p> 2332 2333 <pre class="prettyprint lang-config">LimitInternalRecursion 5</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="LimitRequestBody" id="LimitRequestBody">LimitRequestBody</a> <a name="limitrequestbody" id="limitrequestbody">Directive</a></h2> 2339<table class="directive"> 2340<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Restricts the total size of the HTTP request body sent 2341from the client</td></tr> 2342<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestBody <var>bytes</var></code></td></tr> 2343<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestBody 0</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</table> 2349 <p>This directive specifies the number of <var>bytes</var> from 0 2350 (meaning unlimited) to 2147483647 (2GB) that are allowed in a 2351 request body. See the note below for the limited applicability 2352 to proxy requests.</p> 2353 2354 <p>The <code class="directive">LimitRequestBody</code> directive allows 2355 the user to set a limit on the allowed size of an HTTP request 2356 message body within the context in which the directive is given 2357 (server, per-directory, per-file or per-location). If the client 2358 request exceeds that limit, the server will return an error 2359 response instead of servicing the request. The size of a normal 2360 request message body will vary greatly depending on the nature of 2361 the resource and the methods allowed on that resource. CGI scripts 2362 typically use the message body for retrieving form information. 2363 Implementations of the <code>PUT</code> method will require 2364 a value at least as large as any representation that the server 2365 wishes to accept for that resource.</p> 2366 2367 <p>This directive gives the server administrator greater 2368 control over abnormal client request behavior, which may be 2369 useful for avoiding some forms of denial-of-service 2370 attacks.</p> 2371 2372 <p>If, for example, you are permitting file upload to a particular 2373 location, and wish to limit the size of the uploaded file to 100K, 2374 you might use the following directive:</p> 2375 2376 <pre class="prettyprint lang-config">LimitRequestBody 102400</pre> 2377 2378 2379 <div class="note"><p>For a full description of how this directive is interpreted by 2380 proxy requests, see the <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> documentation.</p> 2381 </div> 2382 2383 2384</div> 2385<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2386<div class="directive-section"><h2><a name="LimitRequestFields" id="LimitRequestFields">LimitRequestFields</a> <a name="limitrequestfields" id="limitrequestfields">Directive</a></h2> 2387<table class="directive"> 2388<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of HTTP request header fields that 2389will be accepted from the client</td></tr> 2390<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFields <var>number</var></code></td></tr> 2391<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFields 100</code></td></tr> 2392<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2393<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2394<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2395</table> 2396 <p><var>Number</var> is an integer from 0 (meaning unlimited) to 2397 32767. The default value is defined by the compile-time 2398 constant <code>DEFAULT_LIMIT_REQUEST_FIELDS</code> (100 as 2399 distributed).</p> 2400 2401 <p>The <code class="directive">LimitRequestFields</code> directive allows 2402 the server administrator to modify the limit on the number of 2403 request header fields allowed in an HTTP request. A server needs 2404 this value to be larger than the number of fields that a normal 2405 client request might include. The number of request header fields 2406 used by a client rarely exceeds 20, but this may vary among 2407 different client implementations, often depending upon the extent 2408 to which a user has configured their browser to support detailed 2409 content negotiation. Optional HTTP extensions are often expressed 2410 using request header fields.</p> 2411 2412 <p>This directive gives the server administrator greater 2413 control over abnormal client request behavior, which may be 2414 useful for avoiding some forms of denial-of-service attacks. 2415 The value should be increased if normal clients see an error 2416 response from the server that indicates too many fields were 2417 sent in the request.</p> 2418 2419 <p>For example:</p> 2420 2421 <pre class="prettyprint lang-config">LimitRequestFields 50</pre> 2422 2423 2424 <div class="warning"><h3>Warning</h3> 2425 <p> When name-based virtual hosting is used, the value for this 2426 directive is taken from the default (first-listed) virtual host for the 2427 local IP and port combination.</p> 2428 </div> 2429 2430 2431</div> 2432<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2433<div class="directive-section"><h2><a name="LimitRequestFieldSize" id="LimitRequestFieldSize">LimitRequestFieldSize</a> <a name="limitrequestfieldsize" id="limitrequestfieldsize">Directive</a></h2> 2434<table class="directive"> 2435<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of the HTTP request header allowed from the 2436client</td></tr> 2437<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestFieldSize <var>bytes</var></code></td></tr> 2438<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestFieldSize 8190</code></td></tr> 2439<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2440<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2441<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2442</table> 2443 <p>This directive specifies the number of <var>bytes</var> 2444 that will be allowed in an HTTP request header.</p> 2445 2446 <p>The <code class="directive">LimitRequestFieldSize</code> directive 2447 allows the server administrator to set the limit 2448 on the allowed size of an HTTP request header field. A server 2449 needs this value to be large enough to hold any one header field 2450 from a normal client request. The size of a normal request header 2451 field will vary greatly among different client implementations, 2452 often depending upon the extent to which a user has configured 2453 their browser to support detailed content negotiation. SPNEGO 2454 authentication headers can be up to 12392 bytes.</p> 2455 2456 <p>This directive gives the server administrator greater 2457 control over abnormal client request behavior, which may be 2458 useful for avoiding some forms of denial-of-service attacks.</p> 2459 2460 <p>For example:</p> 2461 2462 <pre class="prettyprint lang-config">LimitRequestFieldSize 4094</pre> 2463 2464 2465 <div class="note">Under normal conditions, the value should not be changed from 2466 the default.</div> 2467 2468 <div class="warning"><h3>Warning</h3> 2469 <p> When name-based virtual hosting is used, the value for this 2470 directive is taken from the default (first-listed) virtual host best 2471 matching the current IP address and port combination.</p> 2472 </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="LimitRequestLine" id="LimitRequestLine">LimitRequestLine</a> <a name="limitrequestline" id="limitrequestline">Directive</a></h2> 2477<table class="directive"> 2478<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit the size of the HTTP request line that will be accepted 2479from the client</td></tr> 2480<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitRequestLine <var>bytes</var></code></td></tr> 2481<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitRequestLine 8190</code></td></tr> 2482<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2483<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2484<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2485</table> 2486 <p>This directive sets the number of <var>bytes</var> that will be 2487 allowed on the HTTP request-line.</p> 2488 2489 <p>The <code class="directive">LimitRequestLine</code> directive allows 2490 the server administrator to set the limit on the allowed size 2491 of a client's HTTP request-line. Since the request-line consists of the 2492 HTTP method, URI, and protocol version, the 2493 <code class="directive">LimitRequestLine</code> directive places a 2494 restriction on the length of a request-URI allowed for a request 2495 on the server. A server needs this value to be large enough to 2496 hold any of its resource names, including any information that 2497 might be passed in the query part of a <code>GET</code> request.</p> 2498 2499 <p>This directive gives the server administrator greater 2500 control over abnormal client request behavior, which may be 2501 useful for avoiding some forms of denial-of-service attacks.</p> 2502 2503 <p>For example:</p> 2504 2505 <pre class="prettyprint lang-config">LimitRequestLine 4094</pre> 2506 2507 2508 <div class="note">Under normal conditions, the value should not be changed from 2509 the default. Also, you can't set this higher than 8190 without 2510 modifying the source and rebuilding.</div> 2511 2512 <div class="warning"><h3>Warning</h3> 2513 <p> When name-based virtual hosting is used, the value for this 2514 directive is taken from the default (first-listed) virtual host best 2515 matching the current IP address and port combination.</p> 2516 </div> 2517 2518 2519</div> 2520<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2521<div class="directive-section"><h2><a name="LimitXMLRequestBody" id="LimitXMLRequestBody">LimitXMLRequestBody</a> <a name="limitxmlrequestbody" id="limitxmlrequestbody">Directive</a></h2> 2522<table class="directive"> 2523<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the size of an XML-based request body</td></tr> 2524<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LimitXMLRequestBody <var>bytes</var></code></td></tr> 2525<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LimitXMLRequestBody 1000000</code></td></tr> 2526<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 2527<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 2528<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2529<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2530</table> 2531 <p>Limit (in bytes) on maximum size of an XML-based request 2532 body. A value of <code>0</code> will disable any checking.</p> 2533 2534 <p>Example:</p> 2535 2536 <pre class="prettyprint lang-config">LimitXMLRequestBody 0</pre> 2537 2538 2539 2540</div> 2541<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2542<div class="directive-section"><h2><a name="Location" id="Location"><Location></a> <a name="location" id="location">Directive</a></h2> 2543<table class="directive"> 2544<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to matching 2545URLs</td></tr> 2546<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Location 2547 <var>URL-path</var>|<var>URL</var>> ... </Location></code></td></tr> 2548<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2549<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2550<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2551</table> 2552 <p>The <code class="directive"><Location></code> directive 2553 limits the scope of the enclosed directives by URL. It is similar to the 2554 <code class="directive"><a href="#directory"><Directory></a></code> 2555 directive, and starts a subsection which is terminated with a 2556 <code></Location></code> directive. <code class="directive"><Location></code> sections are processed in the 2557 order they appear in the configuration file, after the <code class="directive"><a href="#directory"><Directory></a></code> sections and 2558 <code>.htaccess</code> files are read, and after the <code class="directive"><a href="#files"><Files></a></code> sections.</p> 2559 2560 <p><code class="directive"><Location></code> sections operate 2561 completely outside the filesystem. This has several consequences. 2562 Most importantly, <code class="directive"><Location></code> 2563 directives should not be used to control access to filesystem 2564 locations. Since several different URLs may map to the same 2565 filesystem location, such access controls may by circumvented.</p> 2566 2567 <p>The enclosed directives will be applied to the request if the path component 2568 of the URL meets <em>any</em> of the following criteria: 2569 </p> 2570 <ul> 2571 <li>The specified location matches exactly the path component of the URL. 2572 </li> 2573 <li>The specified location, which ends in a forward slash, is a prefix 2574 of the path component of the URL (treated as a context root). 2575 </li> 2576 <li>The specified location, with the addition of a trailing slash, is a 2577 prefix of the path component of the URL (also treated as a context root). 2578 </li> 2579 </ul> 2580 <p> 2581 In the example below, where no trailing slash is used, requests to 2582 /private1, /private1/ and /private1/file.txt will have the enclosed 2583 directives applied, but /private1other would not. 2584 </p> 2585 <pre class="prettyprint lang-config"><Location /private1> 2586 # ... 2587</Location></pre> 2588 2589 <p> 2590 In the example below, where a trailing slash is used, requests to 2591 /private2/ and /private2/file.txt will have the enclosed 2592 directives applied, but /private2 and /private2other would not. 2593 </p> 2594 <pre class="prettyprint lang-config"><Location /private2<em>/</em>> 2595 # ... 2596</Location></pre> 2597 2598 2599 <div class="note"><h3>When to use <code class="directive"><Location></code></h3> 2600 2601 <p>Use <code class="directive"><Location></code> to apply 2602 directives to content that lives outside the filesystem. For 2603 content that lives in the filesystem, use <code class="directive"><a href="#directory"><Directory></a></code> and <code class="directive"><a href="#files"><Files></a></code>. An exception is 2604 <code><Location /></code>, which is an easy way to 2605 apply a configuration to the entire server.</p> 2606 </div> 2607 2608 <p>For all origin (non-proxy) requests, the URL to be matched is a 2609 URL-path of the form <code>/path/</code>. <em>No scheme, hostname, 2610 port, or query string may be included.</em> For proxy requests, the 2611 URL to be matched is of the form 2612 <code>scheme://servername/path</code>, and you must include the 2613 prefix.</p> 2614 2615 <p>The URL may use wildcards. In a wild-card string, <code>?</code> matches 2616 any single character, and <code>*</code> matches any sequences of 2617 characters. Neither wildcard character matches a / in the URL-path.</p> 2618 2619 <p><a class="glossarylink" href="/glossary.html#regex" title="see glossary">Regular expressions</a> 2620 can also be used, with the addition of the <code>~</code> 2621 character. For example:</p> 2622 2623 <pre class="prettyprint lang-config"><Location ~ "/(extra|special)/data"> 2624 #... 2625</Location></pre> 2626 2627 2628 <p>would match URLs that contained the substring <code>/extra/data</code> 2629 or <code>/special/data</code>. The directive <code class="directive"><a href="#locationmatch"><LocationMatch></a></code> behaves 2630 identical to the regex version of <code class="directive"><Location></code>, and is preferred, for the 2631 simple reason that <code>~</code> is hard to distinguish from 2632 <code>-</code> in many fonts.</p> 2633 2634 <p>The <code class="directive"><Location></code> 2635 functionality is especially useful when combined with the 2636 <code class="directive"><a href="#sethandler">SetHandler</a></code> 2637 directive. For example, to enable status requests, but allow them 2638 only from browsers at <code>example.com</code>, you might use:</p> 2639 2640 <pre class="prettyprint lang-config"><Location /status> 2641 SetHandler server-status 2642 Require host example.com 2643</Location></pre> 2644 2645 2646 <div class="note"><h3>Note about / (slash)</h3> 2647 <p>The slash character has special meaning depending on where in a 2648 URL it appears. People may be used to its behavior in the filesystem 2649 where multiple adjacent slashes are frequently collapsed to a single 2650 slash (<em>i.e.</em>, <code>/home///foo</code> is the same as 2651 <code>/home/foo</code>). In URL-space this is not necessarily true. 2652 The <code class="directive"><a href="#locationmatch"><LocationMatch></a></code> 2653 directive and the regex version of <code class="directive"><Location></code> require you to explicitly specify multiple 2654 slashes if that is your intention.</p> 2655 2656 <p>For example, <code><LocationMatch ^/abc></code> would match 2657 the request URL <code>/abc</code> but not the request URL <code> 2658 //abc</code>. The (non-regex) <code class="directive"><Location></code> directive behaves similarly when used for 2659 proxy requests. But when (non-regex) <code class="directive"><Location></code> is used for non-proxy requests it will 2660 implicitly match multiple slashes with a single slash. For example, 2661 if you specify <code><Location /abc/def></code> and the 2662 request is to <code>/abc//def</code> then it will match.</p> 2663 </div> 2664 2665<h3>See also</h3> 2666<ul> 2667<li><a href="/sections.html">How <Directory>, <Location> 2668 and <Files> sections work</a> for an explanation of how these 2669 different sections are combined when a request is received.</li> 2670<li><code class="directive"><a href="#locationmatch">LocationMatch</a></code></li> 2671</ul> 2672</div> 2673<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2674<div class="directive-section"><h2><a name="LocationMatch" id="LocationMatch"><LocationMatch></a> <a name="locationmatch" id="locationmatch">Directive</a></h2> 2675<table class="directive"> 2676<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Applies the enclosed directives only to regular-expression 2677matching URLs</td></tr> 2678<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><LocationMatch 2679 <var>regex</var>> ... </LocationMatch></code></td></tr> 2680<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2681<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2682<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2683</table> 2684 <p>The <code class="directive"><LocationMatch></code> directive 2685 limits the scope of the enclosed directives by URL, in an identical manner 2686 to <code class="directive"><a href="#location"><Location></a></code>. However, 2687 it takes a <a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular expression</a> 2688 as an argument instead of a simple string. For example:</p> 2689 2690 <pre class="prettyprint lang-config"><LocationMatch "/(extra|special)/data"> 2691 # ... 2692</LocationMatch></pre> 2693 2694 2695 <p>would match URLs that contained the substring <code>/extra/data</code> 2696 or <code>/special/data</code>.</p> 2697 2698 <p>From 2.4.8 onwards, named groups and backreferences are captured and 2699 written to the environment with the corresponding name prefixed with 2700 "MATCH_" and in upper case. This allows elements of URLs to be referenced 2701 from within <a href="/expr.html">expressions</a> and modules like 2702 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered 2703 (unnamed) backreferences are ignored. Use named groups instead.</p> 2704 2705<pre class="prettyprint lang-config"><LocationMatch ^/combined/(?<sitename>[^/]+)> 2706 require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example 2707</LocationMatch></pre> 2708 2709 2710<h3>See also</h3> 2711<ul> 2712<li><a href="/sections.html">How <Directory>, <Location> 2713 and <Files> sections work</a> for an explanation of how these 2714 different sections are combined when a request is received</li> 2715</ul> 2716</div> 2717<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2718<div class="directive-section"><h2><a name="LogLevel" id="LogLevel">LogLevel</a> <a name="loglevel" id="loglevel">Directive</a></h2> 2719<table class="directive"> 2720<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls the verbosity of the ErrorLog</td></tr> 2721<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogLevel [<var>module</var>:]<var>level</var> 2722 [<var>module</var>:<var>level</var>] ... 2723</code></td></tr> 2724<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LogLevel warn</code></td></tr> 2725<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 2726<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2727<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2728<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Per-module and per-directory configuration is available in 2729 Apache HTTP Server 2.3.6 and later</td></tr> 2730</table> 2731 <p><code class="directive">LogLevel</code> adjusts the verbosity of the 2732 messages recorded in the error logs (see <code class="directive"><a href="#errorlog">ErrorLog</a></code> directive). The following 2733 <var>level</var>s are available, in order of decreasing 2734 significance:</p> 2735 2736 <table class="bordered"> 2737 2738 <tr> 2739 <th><strong>Level</strong> </th> 2740 2741 <th><strong>Description</strong> </th> 2742 2743 <th><strong>Example</strong> </th> 2744 </tr> 2745 2746 <tr> 2747 <td><code>emerg</code> </td> 2748 2749 <td>Emergencies - system is unusable.</td> 2750 2751 <td>"Child cannot open lock file. Exiting"</td> 2752 </tr> 2753 2754 <tr> 2755 <td><code>alert</code> </td> 2756 2757 <td>Action must be taken immediately.</td> 2758 2759 <td>"getpwuid: couldn't determine user name from uid"</td> 2760 </tr> 2761 2762 <tr> 2763 <td><code>crit</code> </td> 2764 2765 <td>Critical Conditions.</td> 2766 2767 <td>"socket: Failed to get a socket, exiting child"</td> 2768 </tr> 2769 2770 <tr> 2771 <td><code>error</code> </td> 2772 2773 <td>Error conditions.</td> 2774 2775 <td>"Premature end of script headers"</td> 2776 </tr> 2777 2778 <tr> 2779 <td><code>warn</code> </td> 2780 2781 <td>Warning conditions.</td> 2782 2783 <td>"child process 1234 did not exit, sending another 2784 SIGHUP"</td> 2785 </tr> 2786 2787 <tr> 2788 <td><code>notice</code> </td> 2789 2790 <td>Normal but significant condition.</td> 2791 2792 <td>"httpd: caught SIGBUS, attempting to dump core in 2793 ..."</td> 2794 </tr> 2795 2796 <tr> 2797 <td><code>info</code> </td> 2798 2799 <td>Informational.</td> 2800 2801 <td>"Server seems busy, (you may need to increase 2802 StartServers, or Min/MaxSpareServers)..."</td> 2803 </tr> 2804 2805 <tr> 2806 <td><code>debug</code> </td> 2807 2808 <td>Debug-level messages</td> 2809 2810 <td>"Opening config file ..."</td> 2811 </tr> 2812 <tr> 2813 <td><code>trace1</code> </td> 2814 2815 <td>Trace messages</td> 2816 2817 <td>"proxy: FTP: control connection complete"</td> 2818 </tr> 2819 <tr> 2820 <td><code>trace2</code> </td> 2821 2822 <td>Trace messages</td> 2823 2824 <td>"proxy: CONNECT: sending the CONNECT request to the remote proxy"</td> 2825 </tr> 2826 <tr> 2827 <td><code>trace3</code> </td> 2828 2829 <td>Trace messages</td> 2830 2831 <td>"openssl: Handshake: start"</td> 2832 </tr> 2833 <tr> 2834 <td><code>trace4</code> </td> 2835 2836 <td>Trace messages</td> 2837 2838 <td>"read from buffered SSL brigade, mode 0, 17 bytes"</td> 2839 </tr> 2840 <tr> 2841 <td><code>trace5</code> </td> 2842 2843 <td>Trace messages</td> 2844 2845 <td>"map lookup FAILED: map=rewritemap key=keyname"</td> 2846 </tr> 2847 <tr> 2848 <td><code>trace6</code> </td> 2849 2850 <td>Trace messages</td> 2851 2852 <td>"cache lookup FAILED, forcing new map lookup"</td> 2853 </tr> 2854 <tr> 2855 <td><code>trace7</code> </td> 2856 2857 <td>Trace messages, dumping large amounts of data</td> 2858 2859 <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td> 2860 </tr> 2861 <tr> 2862 <td><code>trace8</code> </td> 2863 2864 <td>Trace messages, dumping large amounts of data</td> 2865 2866 <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td> 2867 </tr> 2868 </table> 2869 2870 <p>When a particular level is specified, messages from all 2871 other levels of higher significance will be reported as well. 2872 <em>E.g.</em>, when <code>LogLevel info</code> is specified, 2873 then messages with log levels of <code>notice</code> and 2874 <code>warn</code> will also be posted.</p> 2875 2876 <p>Using a level of at least <code>crit</code> is 2877 recommended.</p> 2878 2879 <p>For example:</p> 2880 2881 <pre class="prettyprint lang-config">LogLevel notice</pre> 2882 2883 2884 <div class="note"><h3>Note</h3> 2885 <p>When logging to a regular file messages of the level 2886 <code>notice</code> cannot be suppressed and thus are always 2887 logged. However, this doesn't apply when logging is done 2888 using <code>syslog</code>.</p> 2889 </div> 2890 2891 <p>Specifying a level without a module name will reset the level 2892 for all modules to that level. Specifying a level with a module 2893 name will set the level for that module only. It is possible to 2894 use the module source file name, the module identifier, or the 2895 module identifier with the trailing <code>_module</code> omitted 2896 as module specification. This means the following three specifications 2897 are equivalent:</p> 2898 2899 <pre class="prettyprint lang-config">LogLevel info ssl:warn 2900LogLevel info mod_ssl.c:warn 2901LogLevel info ssl_module:warn</pre> 2902 2903 2904 <p>It is also possible to change the level per directory:</p> 2905 2906 <pre class="prettyprint lang-config">LogLevel info 2907<Directory "/usr/local/apache/htdocs/app"> 2908 LogLevel debug 2909</Directory></pre> 2910 2911 2912 <div class="note"> 2913 Per directory loglevel configuration only affects messages that are 2914 logged after the request has been parsed and that are associated with 2915 the request. Log messages which are associated with the connection or 2916 the server are not affected. 2917 </div> 2918 2919<h3>See also</h3> 2920<ul> 2921<li><code class="directive"><a href="#errorlog">ErrorLog</a></code></li> 2922<li><code class="directive"><a href="#errorlogformat">ErrorLogFormat</a></code></li> 2923<li><a href="/logs.html">Apache HTTP Server Log Files</a></li> 2924</ul> 2925</div> 2926<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2927<div class="directive-section"><h2><a name="MaxKeepAliveRequests" id="MaxKeepAliveRequests">MaxKeepAliveRequests</a> <a name="maxkeepaliverequests" id="maxkeepaliverequests">Directive</a></h2> 2928<table class="directive"> 2929<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of requests allowed on a persistent 2930connection</td></tr> 2931<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxKeepAliveRequests <var>number</var></code></td></tr> 2932<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxKeepAliveRequests 100</code></td></tr> 2933<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2934<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2935<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2936</table> 2937 <p>The <code class="directive">MaxKeepAliveRequests</code> directive 2938 limits the number of requests allowed per connection when 2939 <code class="directive"><a href="#keepalive">KeepAlive</a></code> is on. If it is 2940 set to <code>0</code>, unlimited requests will be allowed. We 2941 recommend that this setting be kept to a high value for maximum 2942 server performance.</p> 2943 2944 <p>For example:</p> 2945 2946 <pre class="prettyprint lang-config">MaxKeepAliveRequests 500</pre> 2947 2948 2949</div> 2950<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2951<div class="directive-section"><h2><a name="MaxRangeOverlaps" id="MaxRangeOverlaps">MaxRangeOverlaps</a> <a name="maxrangeoverlaps" id="maxrangeoverlaps">Directive</a></h2> 2952<table class="directive"> 2953<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 2954 resource </td></tr> 2955<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> 2956<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRangeOverlaps 20</code></td></tr> 2957<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 2958<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2959<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2960<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr> 2961</table> 2962 <p>The <code class="directive">MaxRangeOverlaps</code> directive 2963 limits the number of overlapping HTTP ranges the server is willing to 2964 return to the client. If more overlapping ranges than permitted are requested, 2965 the complete resource is returned instead.</p> 2966 2967 <dl> 2968 <dt><strong>default</strong></dt> 2969 <dd>Limits the number of overlapping ranges to a compile-time default of 20.</dd> 2970 2971 <dt><strong>none</strong></dt> 2972 <dd>No overlapping Range headers are allowed.</dd> 2973 2974 <dt><strong>unlimited</strong></dt> 2975 <dd>The server does not limit the number of overlapping ranges it is 2976 willing to satisfy.</dd> 2977 2978 <dt><var>number-of-ranges</var></dt> 2979 <dd>A positive number representing the maximum number of overlapping ranges the 2980 server is willing to satisfy.</dd> 2981 </dl> 2982 2983</div> 2984<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2985<div class="directive-section"><h2><a name="MaxRangeReversals" id="MaxRangeReversals">MaxRangeReversals</a> <a name="maxrangereversals" id="maxrangereversals">Directive</a></h2> 2986<table class="directive"> 2987<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 2988 resource </td></tr> 2989<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> 2990<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRangeReversals 20</code></td></tr> 2991<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 2992<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 2993<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 2994<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr> 2995</table> 2996 <p>The <code class="directive">MaxRangeReversals</code> directive 2997 limits the number of HTTP Range reversals the server is willing to 2998 return to the client. If more ranges reversals than permitted are requested, 2999 the complete resource is returned instead.</p> 3000 3001 <dl> 3002 <dt><strong>default</strong></dt> 3003 <dd>Limits the number of range reversals to a compile-time default of 20.</dd> 3004 3005 <dt><strong>none</strong></dt> 3006 <dd>No Range reversals headers are allowed.</dd> 3007 3008 <dt><strong>unlimited</strong></dt> 3009 <dd>The server does not limit the number of range reversals it is 3010 willing to satisfy.</dd> 3011 3012 <dt><var>number-of-ranges</var></dt> 3013 <dd>A positive number representing the maximum number of range reversals the 3014 server is willing to satisfy.</dd> 3015 </dl> 3016 3017</div> 3018<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3019<div class="directive-section"><h2><a name="MaxRanges" id="MaxRanges">MaxRanges</a> <a name="maxranges" id="maxranges">Directive</a></h2> 3020<table class="directive"> 3021<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of ranges allowed before returning the complete 3022resource </td></tr> 3023<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> 3024<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxRanges 200</code></td></tr> 3025<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 3026<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3027<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3028<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.15 and later</td></tr> 3029</table> 3030 <p>The <code class="directive">MaxRanges</code> directive 3031 limits the number of HTTP ranges the server is willing to 3032 return to the client. If more ranges than permitted are requested, 3033 the complete resource is returned instead.</p> 3034 3035 <dl> 3036 <dt><strong>default</strong></dt> 3037 <dd>Limits the number of ranges to a compile-time default of 200.</dd> 3038 3039 <dt><strong>none</strong></dt> 3040 <dd>Range headers are ignored.</dd> 3041 3042 <dt><strong>unlimited</strong></dt> 3043 <dd>The server does not limit the number of ranges it is 3044 willing to satisfy.</dd> 3045 3046 <dt><var>number-of-ranges</var></dt> 3047 <dd>A positive number representing the maximum number of ranges the 3048 server is willing to satisfy.</dd> 3049 </dl> 3050 3051</div> 3052<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3053<div class="directive-section"><h2><a name="Mutex" id="Mutex">Mutex</a> <a name="mutex" id="mutex">Directive</a></h2> 3054<table class="directive"> 3055<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures mutex mechanism and lock file directory for all 3056or specified mutexes</td></tr> 3057<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> 3058<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Mutex default</code></td></tr> 3059<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 3060<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3061<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3062<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.3.4 and later</td></tr> 3063</table> 3064 <p>The <code class="directive">Mutex</code> directive sets the mechanism, 3065 and optionally the lock file location, that httpd and modules use 3066 to serialize access to resources. Specify <code>default</code> as 3067 the first argument to change the settings for all mutexes; specify 3068 a mutex name (see table below) as the first argument to override 3069 defaults only for that mutex.</p> 3070 3071 <p>The <code class="directive">Mutex</code> directive is typically used in 3072 the following exceptional situations:</p> 3073 3074 <ul> 3075 <li>change the mutex mechanism when the default mechanism selected 3076 by <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a> has a functional or performance 3077 problem</li> 3078 3079 <li>change the directory used by file-based mutexes when the 3080 default directory does not support locking</li> 3081 </ul> 3082 3083 <div class="note"><h3>Supported modules</h3> 3084 <p>This directive only configures mutexes which have been registered 3085 with the core server using the <code>ap_mutex_register()</code> API. 3086 All modules bundled with httpd support the <code class="directive">Mutex</code> 3087 directive, but third-party modules may not. Consult the documentation 3088 of the third-party module, which must indicate the mutex name(s) which 3089 can be configured if this directive is supported.</p> 3090 </div> 3091 3092 <p>The following mutex <em>mechanisms</em> are available:</p> 3093 <ul> 3094 <li><code>default | yes</code> 3095 <p>This selects the default locking implementation, as determined by 3096 <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a>. The default locking implementation can 3097 be displayed by running <code class="program"><a href="/programs/httpd.html">httpd</a></code> with the 3098 <code>-V</code> option.</p></li> 3099 3100 <li><code>none | no</code> 3101 <p>This effectively disables the mutex, and is only allowed for a 3102 mutex if the module indicates that it is a valid choice. Consult the 3103 module documentation for more information.</p></li> 3104 3105 <li><code>posixsem</code> 3106 <p>This is a mutex variant based on a Posix semaphore.</p> 3107 3108 <div class="warning"><h3>Warning</h3> 3109 <p>The semaphore ownership is not recovered if a thread in the process 3110 holding the mutex segfaults, resulting in a hang of the web server.</p> 3111 </div> 3112 </li> 3113 3114 <li><code>sysvsem</code> 3115 <p>This is a mutex variant based on a SystemV IPC semaphore.</p> 3116 3117 <div class="warning"><h3>Warning</h3> 3118 <p>It is possible to "leak" SysV semaphores if processes crash 3119 before the semaphore is removed.</p> 3120 </div> 3121 3122 <div class="warning"><h3>Security</h3> 3123 <p>The semaphore API allows for a denial of service attack by any 3124 CGIs running under the same uid as the webserver (<em>i.e.</em>, 3125 all CGIs, unless you use something like <code class="program"><a href="/programs/suexec.html">suexec</a></code> 3126 or <code>cgiwrapper</code>).</p> 3127 </div> 3128 </li> 3129 3130 <li><code>sem</code> 3131 <p>This selects the "best" available semaphore implementation, choosing 3132 between Posix and SystemV IPC semaphores, in that order.</p></li> 3133 3134 <li><code>pthread</code> 3135 <p>This is a mutex variant based on cross-process Posix thread 3136 mutexes.</p> 3137 3138 <div class="warning"><h3>Warning</h3> 3139 <p>On most systems, if a child process terminates abnormally while 3140 holding a mutex that uses this implementation, the server will deadlock 3141 and stop responding to requests. When this occurs, the server will 3142 require a manual restart to recover.</p> 3143 <p>Solaris is a notable exception as it provides a mechanism which 3144 usually allows the mutex to be recovered after a child process 3145 terminates abnormally while holding a mutex.</p> 3146 <p>If your system implements the 3147 <code>pthread_mutexattr_setrobust_np()</code> function, you may be able 3148 to use the <code>pthread</code> option safely.</p> 3149 </div> 3150 </li> 3151 3152 <li><code>fcntl:/path/to/mutex</code> 3153 <p>This is a mutex variant where a physical (lock-)file and the 3154 <code>fcntl()</code> function are used as the mutex.</p> 3155 3156 <div class="warning"><h3>Warning</h3> 3157 <p>When multiple mutexes based on this mechanism are used within 3158 multi-threaded, multi-process environments, deadlock errors (EDEADLK) 3159 can be reported for valid mutex operations if <code>fcntl()</code> 3160 is not thread-aware, such as on Solaris.</p> 3161 </div> 3162 </li> 3163 3164 <li><code>flock:/path/to/mutex</code> 3165 <p>This is similar to the <code>fcntl:/path/to/mutex</code> method 3166 with the exception that the <code>flock()</code> function is used to 3167 provide file locking.</p></li> 3168 3169 <li><code>file:/path/to/mutex</code> 3170 <p>This selects the "best" available file locking implementation, 3171 choosing between <code>fcntl</code> and <code>flock</code>, in that 3172 order.</p></li> 3173 </ul> 3174 3175 <p>Most mechanisms are only available on selected platforms, where the 3176 underlying platform and <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a> support it. Mechanisms 3177 which aren't available on all platforms are <em>posixsem</em>, 3178 <em>sysvsem</em>, <em>sem</em>, <em>pthread</em>, <em>fcntl</em>, 3179 <em>flock</em>, and <em>file</em>.</p> 3180 3181 <p>With the file-based mechanisms <em>fcntl</em> and <em>flock</em>, 3182 the path, if provided, is a directory where the lock file will be created. 3183 The default directory is httpd's run-time file directory relative to 3184 <code class="directive"><a href="#serverroot">ServerRoot</a></code>. Always use a local disk 3185 filesystem for <code>/path/to/mutex</code> and never a directory residing 3186 on a NFS- or AFS-filesystem. The basename of the file will be the mutex 3187 type, an optional instance string provided by the module, and unless the 3188 <code>OmitPID</code> keyword is specified, the process id of the httpd 3189 parent process will be appended to to make the file name unique, avoiding 3190 conflicts when multiple httpd instances share a lock file directory. For 3191 example, if the mutex name is <code>mpm-accept</code> and the lock file 3192 directory is <code>/var/httpd/locks</code>, the lock file name for the 3193 httpd instance with parent process id 12345 would be 3194 <code>/var/httpd/locks/mpm-accept.12345</code>.</p> 3195 3196 <div class="warning"><h3>Security</h3> 3197 <p>It is best to <em>avoid</em> putting mutex files in a world-writable 3198 directory such as <code>/var/tmp</code> because someone could create 3199 a denial of service attack and prevent the server from starting by 3200 creating a lockfile with the same name as the one the server will try 3201 to create.</p> 3202 </div> 3203 3204 <p>The following table documents the names of mutexes used by httpd 3205 and bundled modules.</p> 3206 3207 <table class="bordered"><tr class="header"> 3208 <th>Mutex name</th> 3209 <th>Module(s)</th> 3210 <th>Protected resource</th> 3211 </tr> 3212<tr> 3213 <td><code>mpm-accept</code></td> 3214 <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> 3215 <td>incoming connections, to avoid the thundering herd problem; 3216 for more information, refer to the 3217 <a href="/misc/perf-tuning.html">performance tuning</a> 3218 documentation</td> 3219 </tr> 3220<tr class="odd"> 3221 <td><code>authdigest-client</code></td> 3222 <td><code class="module"><a href="/mod/mod_auth_digest.html">mod_auth_digest</a></code></td> 3223 <td>client list in shared memory</td> 3224 </tr> 3225<tr> 3226 <td><code>authdigest-opaque</code></td> 3227 <td><code class="module"><a href="/mod/mod_auth_digest.html">mod_auth_digest</a></code></td> 3228 <td>counter in shared memory</td> 3229 </tr> 3230<tr class="odd"> 3231 <td><code>ldap-cache</code></td> 3232 <td><code class="module"><a href="/mod/mod_ldap.html">mod_ldap</a></code></td> 3233 <td>LDAP result cache</td> 3234 </tr> 3235<tr> 3236 <td><code>rewrite-map</code></td> 3237 <td><code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code></td> 3238 <td>communication with external mapping programs, to avoid 3239 intermixed I/O from multiple requests</td> 3240 </tr> 3241<tr class="odd"> 3242 <td><code>ssl-cache</code></td> 3243 <td><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code></td> 3244 <td>SSL session cache</td> 3245 </tr> 3246<tr> 3247 <td><code>ssl-stapling</code></td> 3248 <td><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code></td> 3249 <td>OCSP stapling response cache</td> 3250 </tr> 3251<tr class="odd"> 3252 <td><code>watchdog-callback</code></td> 3253 <td><code class="module"><a href="/mod/mod_watchdog.html">mod_watchdog</a></code></td> 3254 <td>callback function of a particular client module</td> 3255 </tr> 3256</table> 3257 3258 <p>The <code>OmitPID</code> keyword suppresses the addition of the httpd 3259 parent process id from the lock file name.</p> 3260 3261 <p>In the following example, the mutex mechanism for the MPM accept 3262 mutex will be changed from the compiled-in default to <code>fcntl</code>, 3263 with the associated lock file created in directory 3264 <code>/var/httpd/locks</code>. The mutex mechanism for all other mutexes 3265 will be changed from the compiled-in default to <code>sysvsem</code>.</p> 3266 3267 <pre class="prettyprint lang-config">Mutex sysvsem default 3268Mutex fcntl:/var/httpd/locks mpm-accept</pre> 3269 3270 3271</div> 3272<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3273<div class="directive-section"><h2><a name="NameVirtualHost" id="NameVirtualHost">NameVirtualHost</a> <a name="namevirtualhost" id="namevirtualhost">Directive</a></h2> 3274<table class="directive"> 3275<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>DEPRECATED: Designates an IP address for name-virtual 3276hosting</td></tr> 3277<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NameVirtualHost <var>addr</var>[:<var>port</var>]</code></td></tr> 3278<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 3279<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3280<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3281</table> 3282 3283<p>Prior to 2.3.11, <code class="directive">NameVirtualHost</code> was required 3284to instruct the server that a particular IP address and port combination 3285was usable as a name-based virtual host. In 2.3.11 and later, 3286any time an IP address and port combination is used in multiple virtual 3287hosts, name-based virtual hosting is automatically enabled for that address.</p> 3288 3289<p>This directive currently has no effect.</p> 3290 3291<h3>See also</h3> 3292<ul> 3293<li><a href="/vhosts/">Virtual Hosts 3294documentation</a></li> 3295</ul> 3296</div> 3297<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3298<div class="directive-section"><h2><a name="Options" id="Options">Options</a> <a name="options" id="options">Directive</a></h2> 3299<table class="directive"> 3300<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures what features are available in a particular 3301directory</td></tr> 3302<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Options 3303 [+|-]<var>option</var> [[+|-]<var>option</var>] ...</code></td></tr> 3304<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Options FollowSymlinks</code></td></tr> 3305<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3306<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 3307<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3308<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3309<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> 3310</table> 3311 <p>The <code class="directive">Options</code> directive controls which 3312 server features are available in a particular directory.</p> 3313 3314 <p><var>option</var> can be set to <code>None</code>, in which 3315 case none of the extra features are enabled, or one or more of 3316 the following:</p> 3317 3318 <dl> 3319 <dt><code>All</code></dt> 3320 3321 <dd>All options except for <code>MultiViews</code>.</dd> 3322 3323 <dt><code>ExecCGI</code></dt> 3324 3325 <dd> 3326 Execution of CGI scripts using <code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code> 3327 is permitted.</dd> 3328 3329 <dt><code>FollowSymLinks</code></dt> 3330 3331 <dd> 3332 The server will follow symbolic links in this directory. This is 3333 the default setting. 3334 <div class="note"> 3335 <p>Even though the server follows the symlink it does <em>not</em> 3336 change the pathname used to match against <code class="directive"><a href="#directory"><Directory></a></code> sections.</p> 3337 3338 <p>The <code>FollowSymLinks</code> and 3339 <code>SymLinksIfOwnerMatch</code> <code class="directive"><a href="#options">Options</a></code> work only in <code class="directive"><a href="#directory"><Directory></a></code> sections or 3340 <code>.htaccess</code> files.</p> 3341 3342 <p>Omitting this option should not be considered a security restriction, 3343 since symlink testing is subject to race conditions that make it 3344 circumventable.</p> 3345 </div></dd> 3346 3347 <dt><code>Includes</code></dt> 3348 3349 <dd> 3350 Server-side includes provided by <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> 3351 are permitted.</dd> 3352 3353 <dt><code>IncludesNOEXEC</code></dt> 3354 3355 <dd> 3356 3357 Server-side includes are permitted, but the <code>#exec 3358 cmd</code> and <code>#exec cgi</code> are disabled. It is still 3359 possible to <code>#include virtual</code> CGI scripts from 3360 <code class="directive"><a href="/mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed 3361 directories.</dd> 3362 3363 <dt><code>Indexes</code></dt> 3364 3365 <dd> 3366 If a URL which maps to a directory is requested, and there 3367 is no <code class="directive"><a href="/mod/mod_dir.html#directoryindex">DirectoryIndex</a></code> 3368 (<em>e.g.</em>, <code>index.html</code>) in that directory, then 3369 <code class="module"><a href="/mod/mod_autoindex.html">mod_autoindex</a></code> will return a formatted listing 3370 of the directory.</dd> 3371 3372 <dt><code>MultiViews</code></dt> 3373 3374 <dd> 3375 <a href="/content-negotiation.html">Content negotiated</a> 3376 "MultiViews" are allowed using 3377 <code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code>. 3378 <div class="note"><h3>Note</h3> <p>This option gets ignored if set 3379 anywhere other than <code class="directive"><a href="#directory"><Directory></a></code>, as <code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code> 3380 needs real resources to compare against and evaluate from.</p></div> 3381 </dd> 3382 3383 <dt><code>SymLinksIfOwnerMatch</code></dt> 3384 3385 <dd>The server will only follow symbolic links for which the 3386 target file or directory is owned by the same user id as the 3387 link. 3388 3389 <div class="note"><h3>Note</h3> 3390 <p>The <code>FollowSymLinks</code> and 3391 <code>SymLinksIfOwnerMatch</code> <code class="directive"><a href="#options">Options</a></code> work only in <code class="directive"><a href="#directory"><Directory></a></code> sections or 3392 <code>.htaccess</code> files.</p> 3393 3394 <p>This option should not be considered a security restriction, 3395 since symlink testing is subject to race conditions that make it 3396 circumventable.</p> 3397 </div> </dd> 3398 </dl> 3399 3400 <p>Normally, if multiple <code class="directive">Options</code> could 3401 apply to a directory, then the most specific one is used and 3402 others are ignored; the options are not merged. (See <a href="/sections.html#mergin">how sections are merged</a>.) 3403 However if <em>all</em> the options on the 3404 <code class="directive">Options</code> directive are preceded by a 3405 <code>+</code> or <code>-</code> symbol, the options are 3406 merged. Any options preceded by a <code>+</code> are added to the 3407 options currently in force, and any options preceded by a 3408 <code>-</code> are removed from the options currently in 3409 force. </p> 3410 3411 <div class="note"><h3>Note</h3> 3412 <p>Mixing <code class="directive">Options</code> with a <code>+</code> or 3413 <code>-</code> with those without is not valid syntax, and will be 3414 rejected during server startup by the syntax check with an abort.</p> 3415 </div> 3416 3417 <p>For example, without any <code>+</code> and <code>-</code> symbols:</p> 3418 3419 <pre class="prettyprint lang-config"><Directory "/web/docs"> 3420 Options Indexes FollowSymLinks 3421</Directory> 3422 3423<Directory "/web/docs/spec"> 3424 Options Includes 3425</Directory></pre> 3426 3427 3428 <p>then only <code>Includes</code> will be set for the 3429 <code>/web/docs/spec</code> directory. However if the second 3430 <code class="directive">Options</code> directive uses the <code>+</code> and 3431 <code>-</code> symbols:</p> 3432 3433 <pre class="prettyprint lang-config"><Directory "/web/docs"> 3434 Options Indexes FollowSymLinks 3435</Directory> 3436 3437<Directory "/web/docs/spec"> 3438 Options +Includes -Indexes 3439</Directory></pre> 3440 3441 3442 <p>then the options <code>FollowSymLinks</code> and 3443 <code>Includes</code> are set for the <code>/web/docs/spec</code> 3444 directory.</p> 3445 3446 <div class="note"><h3>Note</h3> 3447 <p>Using <code>-IncludesNOEXEC</code> or 3448 <code>-Includes</code> disables server-side includes completely 3449 regardless of the previous setting.</p> 3450 </div> 3451 3452 <p>The default in the absence of any other settings is 3453 <code>FollowSymlinks</code>.</p> 3454 3455</div> 3456<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3457<div class="directive-section"><h2><a name="Protocol" id="Protocol">Protocol</a> <a name="protocol" id="protocol">Directive</a></h2> 3458<table class="directive"> 3459<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Protocol for a listening socket</td></tr> 3460<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Protocol <var>protocol</var></code></td></tr> 3461<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 3462<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3463<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3464<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1.5 and later. 3465On Windows from Apache 2.3.3 and later.</td></tr> 3466</table> 3467 <p>This directive specifies the protocol used for a specific listening socket. 3468 The protocol is used to determine which module should handle a request, and 3469 to apply protocol specific optimizations with the <code class="directive">AcceptFilter</code> 3470 directive.</p> 3471 3472 <p>You only need to set the protocol if you are running on non-standard ports, otherwise <code>http</code> is assumed for port 80 and <code>https</code> for port 443.</p> 3473 3474 <p>For example, if you are running <code>https</code> on a non-standard port, specify the protocol explicitly:</p> 3475 3476 <pre class="prettyprint lang-config">Protocol https</pre> 3477 3478 3479 <p>You can also specify the protocol using the <code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code> directive.</p> 3480 3481<h3>See also</h3> 3482<ul> 3483<li><code class="directive"><a href="#acceptfilter">AcceptFilter</a></code></li> 3484<li><code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code></li> 3485</ul> 3486</div> 3487<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3488<div class="directive-section"><h2><a name="RLimitCPU" id="RLimitCPU">RLimitCPU</a> <a name="rlimitcpu" id="rlimitcpu">Directive</a></h2> 3489<table class="directive"> 3490<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the CPU consumption of processes launched 3491by Apache httpd children</td></tr> 3492<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> 3493<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr> 3494<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3495<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 3496<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3497<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3498</table> 3499 <p>Takes 1 or 2 parameters. The first parameter sets the soft 3500 resource limit for all processes and the second parameter sets 3501 the maximum resource limit. Either parameter can be a number, 3502 or <code>max</code> to indicate to the server that the limit should 3503 be set to the maximum allowed by the operating system 3504 configuration. Raising the maximum resource limit requires that 3505 the server is running as <code>root</code>, or in the initial startup 3506 phase.</p> 3507 3508 <p>This applies to processes forked off from Apache httpd children 3509 servicing requests, not the Apache httpd children themselves. This 3510 includes CGI scripts and SSI exec commands, but not any 3511 processes forked off from the Apache httpd parent such as piped 3512 logs.</p> 3513 3514 <p>CPU resource limits are expressed in seconds per 3515 process.</p> 3516 3517<h3>See also</h3> 3518<ul> 3519<li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li> 3520<li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li> 3521</ul> 3522</div> 3523<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3524<div class="directive-section"><h2><a name="RLimitMEM" id="RLimitMEM">RLimitMEM</a> <a name="rlimitmem" id="rlimitmem">Directive</a></h2> 3525<table class="directive"> 3526<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the memory consumption of processes launched 3527by Apache httpd children</td></tr> 3528<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> 3529<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr> 3530<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3531<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 3532<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3533<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3534</table> 3535 <p>Takes 1 or 2 parameters. The first parameter sets the soft 3536 resource limit for all processes and the second parameter sets 3537 the maximum resource limit. Either parameter can be a number, 3538 or <code>max</code> to indicate to the server that the limit should 3539 be set to the maximum allowed by the operating system 3540 configuration. Raising the maximum resource limit requires that 3541 the server is running as <code>root</code>, or in the initial startup 3542 phase.</p> 3543 3544 <p>This applies to processes forked off from Apache httpd children 3545 servicing requests, not the Apache httpd children themselves. This 3546 includes CGI scripts and SSI exec commands, but not any 3547 processes forked off from the Apache httpd parent such as piped 3548 logs.</p> 3549 3550 <p>Memory resource limits are expressed in bytes per 3551 process.</p> 3552 3553<h3>See also</h3> 3554<ul> 3555<li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li> 3556<li><code class="directive"><a href="#rlimitnproc">RLimitNPROC</a></code></li> 3557</ul> 3558</div> 3559<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3560<div class="directive-section"><h2><a name="RLimitNPROC" id="RLimitNPROC">RLimitNPROC</a> <a name="rlimitnproc" id="rlimitnproc">Directive</a></h2> 3561<table class="directive"> 3562<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limits the number of processes that can be launched by 3563processes launched by Apache httpd children</td></tr> 3564<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> 3565<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Unset; uses operating system defaults</code></td></tr> 3566<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3567<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 3568<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3569<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3570</table> 3571 <p>Takes 1 or 2 parameters. The first parameter sets the soft 3572 resource limit for all processes and the second parameter sets 3573 the maximum resource limit. Either parameter can be a number, 3574 or <code>max</code> to indicate to the server that the limit 3575 should be set to the maximum allowed by the operating system 3576 configuration. Raising the maximum resource limit requires that 3577 the server is running as <code>root</code>, or in the initial startup 3578 phase.</p> 3579 3580 <p>This applies to processes forked off from Apache httpd children 3581 servicing requests, not the Apache httpd children themselves. This 3582 includes CGI scripts and SSI exec commands, but not any 3583 processes forked off from the Apache httpd parent such as piped 3584 logs.</p> 3585 3586 <p>Process limits control the number of processes per user.</p> 3587 3588 <div class="note"><h3>Note</h3> 3589 <p>If CGI processes are <strong>not</strong> running 3590 under user ids other than the web server user id, this directive 3591 will limit the number of processes that the server itself can 3592 create. Evidence of this situation will be indicated by 3593 <strong><code>cannot fork</code></strong> messages in the 3594 <code>error_log</code>.</p> 3595 </div> 3596 3597<h3>See also</h3> 3598<ul> 3599<li><code class="directive"><a href="#rlimitmem">RLimitMEM</a></code></li> 3600<li><code class="directive"><a href="#rlimitcpu">RLimitCPU</a></code></li> 3601</ul> 3602</div> 3603<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3604<div class="directive-section"><h2><a name="ScriptInterpreterSource" id="ScriptInterpreterSource">ScriptInterpreterSource</a> <a name="scriptinterpretersource" id="scriptinterpretersource">Directive</a></h2> 3605<table class="directive"> 3606<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Technique for locating the interpreter for CGI 3607scripts</td></tr> 3608<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptInterpreterSource Registry|Registry-Strict|Script</code></td></tr> 3609<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptInterpreterSource Script</code></td></tr> 3610<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3611<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 3612<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3613<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3614<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Win32 only.</td></tr> 3615</table> 3616 <p>This directive is used to control how Apache httpd finds the 3617 interpreter used to run CGI scripts. The default setting is 3618 <code>Script</code>. This causes Apache httpd to use the interpreter pointed to 3619 by the shebang line (first line, starting with <code>#!</code>) in the 3620 script. On Win32 systems this line usually looks like:</p> 3621 3622 <pre class="prettyprint lang-perl">#!C:/Perl/bin/perl.exe</pre> 3623 3624 3625 <p>or, if <code>perl</code> is in the <code>PATH</code>, simply:</p> 3626 3627 <pre class="prettyprint lang-perl">#!perl</pre> 3628 3629 3630 <p>Setting <code>ScriptInterpreterSource Registry</code> will 3631 cause the Windows Registry tree <code>HKEY_CLASSES_ROOT</code> to be 3632 searched using the script file extension (e.g., <code>.pl</code>) as a 3633 search key. The command defined by the registry subkey 3634 <code>Shell\ExecCGI\Command</code> or, if it does not exist, by the subkey 3635 <code>Shell\Open\Command</code> is used to open the script file. If the 3636 registry keys cannot be found, Apache httpd falls back to the behavior of the 3637 <code>Script</code> option.</p> 3638 3639 <div class="warning"><h3>Security</h3> 3640 <p>Be careful when using <code>ScriptInterpreterSource 3641 Registry</code> with <code class="directive"><a href="/mod/mod_alias.html#scriptalias">ScriptAlias</a></code>'ed directories, because 3642 Apache httpd will try to execute <strong>every</strong> file within this 3643 directory. The <code>Registry</code> setting may cause undesired 3644 program calls on files which are typically not executed. For 3645 example, the default open command on <code>.htm</code> files on 3646 most Windows systems will execute Microsoft Internet Explorer, so 3647 any HTTP request for an <code>.htm</code> file existing within the 3648 script directory would start the browser in the background on the 3649 server. This is a good way to crash your system within a minute or 3650 so.</p> 3651 </div> 3652 3653 <p>The option <code>Registry-Strict</code> which is new in Apache HTTP Server 3654 2.0 does the same thing as <code>Registry</code> but uses only the 3655 subkey <code>Shell\ExecCGI\Command</code>. The 3656 <code>ExecCGI</code> key is not a common one. It must be 3657 configured manually in the windows registry and hence prevents 3658 accidental program calls on your system.</p> 3659 3660</div> 3661<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3662<div class="directive-section"><h2><a name="SeeRequestTail" id="SeeRequestTail">SeeRequestTail</a> <a name="seerequesttail" id="seerequesttail">Directive</a></h2> 3663<table class="directive"> 3664<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine if mod_status displays the first 63 characters 3665of a request or the last 63, assuming the request itself is greater than 366663 chars.</td></tr> 3667<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SeeRequestTail On|Off</code></td></tr> 3668<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SeeRequestTail Off</code></td></tr> 3669<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 3670<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3671<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3672<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache httpd 2.2.7 and later.</td></tr> 3673</table> 3674 <p>mod_status with <code>ExtendedStatus On</code> 3675 displays the actual request being handled. 3676 For historical purposes, only 63 characters of the request 3677 are actually stored for display purposes. This directive 3678 controls whether the 1st 63 characters are stored (the previous 3679 behavior and the default) or if the last 63 characters are. This 3680 is only applicable, of course, if the length of the request is 3681 64 characters or greater.</p> 3682 3683 <p>If Apache httpd is handling <code>GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</code> mod_status displays as follows: 3684 </p> 3685 3686 <table class="bordered"> 3687 <tr> 3688 <th>Off (default)</th> 3689 <td>GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples</td> 3690 </tr> 3691 <tr> 3692 <th>On</th> 3693 <td>orage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</td> 3694 </tr> 3695 </table> 3696 3697 3698</div> 3699<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3700<div class="directive-section"><h2><a name="ServerAdmin" id="ServerAdmin">ServerAdmin</a> <a name="serveradmin" id="serveradmin">Directive</a></h2> 3701<table class="directive"> 3702<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Email address that the server includes in error 3703messages sent to the client</td></tr> 3704<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAdmin <var>email-address</var>|<var>URL</var></code></td></tr> 3705<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 3706<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3707<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3708</table> 3709 <p>The <code class="directive">ServerAdmin</code> sets the contact address 3710 that the server includes in any error messages it returns to the 3711 client. If the <code>httpd</code> doesn't recognize the supplied argument 3712 as an URL, it 3713 assumes, that it's an <var>email-address</var> and prepends it with 3714 <code>mailto:</code> in hyperlink targets. However, it's recommended to 3715 actually use an email address, since there are a lot of CGI scripts that 3716 make that assumption. If you want to use an URL, it should point to another 3717 server under your control. Otherwise users may not be able to contact you in 3718 case of errors.</p> 3719 3720 <p>It may be worth setting up a dedicated address for this, e.g.</p> 3721 3722 <pre class="prettyprint lang-config">ServerAdmin www-admin@foo.example.com</pre> 3723 3724 <p>as users do not always mention that they are talking about the 3725 server!</p> 3726 3727</div> 3728<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3729<div class="directive-section"><h2><a name="ServerAlias" id="ServerAlias">ServerAlias</a> <a name="serveralias" id="serveralias">Directive</a></h2> 3730<table class="directive"> 3731<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Alternate names for a host used when matching requests 3732to name-virtual hosts</td></tr> 3733<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerAlias <var>hostname</var> [<var>hostname</var>] ...</code></td></tr> 3734<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr> 3735<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3736<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3737</table> 3738 <p>The <code class="directive">ServerAlias</code> directive sets the 3739 alternate names for a host, for use with <a href="/vhosts/name-based.html">name-based virtual hosts</a>. The 3740 <code class="directive">ServerAlias</code> may include wildcards, if appropriate.</p> 3741 3742 <pre class="prettyprint lang-config"><VirtualHost *:80> 3743 ServerName server.example.com 3744 ServerAlias server server2.example.com server2 3745 ServerAlias *.example.com 3746 UseCanonicalName Off 3747 # ... 3748</VirtualHost></pre> 3749 3750 3751 <p>Name-based virtual hosts for the best-matching set of <code class="directive"><a href="#virtualhost"><virtualhost></a></code>s are processed 3752 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 3753 (nor for ServerName vs. ServerAlias). </p> 3754 3755 <p>The complete list of names in the <code class="directive">VirtualHost</code> 3756 directive are treated just like a (non wildcard) 3757 <code class="directive">ServerAlias</code>.</p> 3758 3759 3760<h3>See also</h3> 3761<ul> 3762<li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li> 3763<li><a href="/vhosts/">Apache HTTP Server Virtual Host documentation</a></li> 3764</ul> 3765</div> 3766<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3767<div class="directive-section"><h2><a name="ServerName" id="ServerName">ServerName</a> <a name="servername" id="servername">Directive</a></h2> 3768<table class="directive"> 3769<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hostname and port that the server uses to identify 3770itself</td></tr> 3771<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerName [<var>scheme</var>://]<var>fully-qualified-domain-name</var>[:<var>port</var>]</code></td></tr> 3772<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 3773<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3774<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3775</table> 3776 <p>The <code class="directive">ServerName</code> directive sets the 3777 request scheme, hostname and 3778 port that the server uses to identify itself. This is used when 3779 creating redirection URLs.</p> 3780 3781 <p>Additionally, <code class="directive">ServerName</code> is used (possibly 3782 in conjunction with <code class="directive">ServerAlias</code>) to uniquely 3783 identify a virtual host, when using <a href="/vhosts/name-based.html">name-based virtual hosts</a>.</p> 3784 3785 <p>For example, if the name of the 3786 machine hosting the web server is <code>simple.example.com</code>, 3787 but the machine also has the DNS alias <code>www.example.com</code> 3788 and you wish the web server to be so identified, the following 3789 directive should be used:</p> 3790 3791 <pre class="prettyprint lang-config">ServerName www.example.com</pre> 3792 3793 3794 <p>The <code class="directive">ServerName</code> directive 3795 may appear anywhere within the definition of a server. However, 3796 each appearance overrides the previous appearance (within that 3797 server).</p> 3798 3799 <p>If no <code class="directive">ServerName</code> is specified, then the 3800 server attempts to deduce the hostname by performing a reverse 3801 lookup on the IP address. If no port is specified in the 3802 <code class="directive">ServerName</code>, then the server will use the 3803 port from the incoming request. For optimal reliability and 3804 predictability, you should specify an explicit hostname and port 3805 using the <code class="directive">ServerName</code> directive.</p> 3806 3807 <p>If you are using <a href="/vhosts/name-based.html">name-based virtual hosts</a>, 3808 the <code class="directive">ServerName</code> inside a 3809 <code class="directive"><a href="#virtualhost"><VirtualHost></a></code> 3810 section specifies what hostname must appear in the request's 3811 <code>Host:</code> header to match this virtual host.</p> 3812 3813 <p>Sometimes, the server runs behind a device that processes SSL, 3814 such as a reverse proxy, load balancer or SSL offload 3815 appliance. When this is the case, specify the 3816 <code>https://</code> scheme and the port number to which the 3817 clients connect in the <code class="directive">ServerName</code> directive 3818 to make sure that the server generates the correct 3819 self-referential URLs. 3820 </p> 3821 3822 <p>See the description of the 3823 <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> and 3824 <code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code> directives for 3825 settings which determine whether self-referential URLs (e.g., by the 3826 <code class="module"><a href="/mod/mod_dir.html">mod_dir</a></code> module) will refer to the 3827 specified port, or to the port number given in the client's request. 3828 </p> 3829 3830 <div class="warning"> 3831 <p>Failure to set <code class="directive">ServerName</code> to a name that 3832 your server can resolve to an IP address will result in a startup 3833 warning. <code>httpd</code> will then use whatever hostname it can 3834 determine, using the system's <code>hostname</code> command. This 3835 will almost never be the hostname you actually want.</p> 3836 <div class="example"><p><code> 3837 httpd: Could not reliably determine the server's fully qualified domain name, using rocinante.local for ServerName 3838 </code></p></div> 3839 </div> 3840 3841 3842<h3>See also</h3> 3843<ul> 3844<li><a href="/dns-caveats.html">Issues Regarding DNS and 3845 Apache HTTP Server</a></li> 3846<li><a href="/vhosts/">Apache HTTP Server virtual host 3847 documentation</a></li> 3848<li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li> 3849<li><code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code></li> 3850<li><code class="directive"><a href="#serveralias">ServerAlias</a></code></li> 3851</ul> 3852</div> 3853<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3854<div class="directive-section"><h2><a name="ServerPath" id="ServerPath">ServerPath</a> <a name="serverpath" id="serverpath">Directive</a></h2> 3855<table class="directive"> 3856<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Legacy URL pathname for a name-based virtual host that 3857is accessed by an incompatible browser</td></tr> 3858<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerPath <var>URL-path</var></code></td></tr> 3859<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr> 3860<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3861<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3862</table> 3863 <p>The <code class="directive">ServerPath</code> directive sets the legacy 3864 URL pathname for a host, for use with <a href="/vhosts/">name-based virtual hosts</a>.</p> 3865 3866<h3>See also</h3> 3867<ul> 3868<li><a href="/vhosts/">Apache HTTP Server Virtual Host documentation</a></li> 3869</ul> 3870</div> 3871<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3872<div class="directive-section"><h2><a name="ServerRoot" id="ServerRoot">ServerRoot</a> <a name="serverroot" id="serverroot">Directive</a></h2> 3873<table class="directive"> 3874<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the server installation</td></tr> 3875<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerRoot <var>directory-path</var></code></td></tr> 3876<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerRoot /usr/local/apache</code></td></tr> 3877<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 3878<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3879<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3880</table> 3881 <p>The <code class="directive">ServerRoot</code> directive sets the 3882 directory in which the server lives. Typically it will contain the 3883 subdirectories <code>conf/</code> and <code>logs/</code>. Relative 3884 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 3885 relative to this directory.</p> 3886 3887 <pre class="prettyprint lang-config">ServerRoot "/home/httpd"</pre> 3888 3889 3890 <p>The default location of <code class="directive">ServerRoot</code> may be 3891 modified by using the <code>--prefix</code> argument to 3892 <a href="/programs/configure.html"><code>configure</code></a>, and 3893 most third-party distributions of the server have a different 3894 default location from the one listed above.</p> 3895 3896 3897<h3>See also</h3> 3898<ul> 3899<li><a href="/invoking.html">the <code>-d</code> 3900 option to <code>httpd</code></a></li> 3901<li><a href="/misc/security_tips.html#serverroot">the 3902 security tips</a> for information on how to properly set 3903 permissions on the <code class="directive">ServerRoot</code></li> 3904</ul> 3905</div> 3906<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3907<div class="directive-section"><h2><a name="ServerSignature" id="ServerSignature">ServerSignature</a> <a name="serversignature" id="serversignature">Directive</a></h2> 3908<table class="directive"> 3909<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the footer on server-generated documents</td></tr> 3910<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ServerSignature On|Off|EMail</code></td></tr> 3911<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerSignature Off</code></td></tr> 3912<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 3913<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> 3914<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3915<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3916</table> 3917 <p>The <code class="directive">ServerSignature</code> directive allows the 3918 configuration of a trailing footer line under server-generated 3919 documents (error messages, <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> ftp directory 3920 listings, <code class="module"><a href="/mod/mod_info.html">mod_info</a></code> output, ...). The reason why you 3921 would want to enable such a footer line is that in a chain of proxies, 3922 the user often has no possibility to tell which of the chained servers 3923 actually produced a returned error message.</p> 3924 3925 <p>The <code>Off</code> 3926 setting, which is the default, suppresses the footer line (and is 3927 therefore compatible with the behavior of Apache-1.2 and 3928 below). The <code>On</code> setting simply adds a line with the 3929 server version number and <code class="directive"><a href="#servername">ServerName</a></code> of the serving virtual host, 3930 and the <code>EMail</code> setting additionally creates a 3931 "mailto:" reference to the <code class="directive"><a href="#serveradmin">ServerAdmin</a></code> of the referenced 3932 document.</p> 3933 3934 <p>After version 2.0.44, the details of the server version number 3935 presented are controlled by the <code class="directive"><a href="#servertokens">ServerTokens</a></code> directive.</p> 3936 3937<h3>See also</h3> 3938<ul> 3939<li><code class="directive"><a href="#servertokens">ServerTokens</a></code></li> 3940</ul> 3941</div> 3942<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 3943<div class="directive-section"><h2><a name="ServerTokens" id="ServerTokens">ServerTokens</a> <a name="servertokens" id="servertokens">Directive</a></h2> 3944<table class="directive"> 3945<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the <code>Server</code> HTTP response 3946header</td></tr> 3947<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> 3948<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ServerTokens Full</code></td></tr> 3949<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 3950<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 3951<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 3952</table> 3953 <p>This directive controls whether <code>Server</code> response 3954 header field which is sent back to clients includes a 3955 description of the generic OS-type of the server as well as 3956 information about compiled-in modules.</p> 3957 3958 <dl> 3959 <dt><code>ServerTokens Full</code> (or not specified)</dt> 3960 3961 <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2 3962 (Unix) PHP/4.2.2 MyMod/1.2</code></dd> 3963 3964 <dt><code>ServerTokens Prod[uctOnly]</code></dt> 3965 3966 <dd>Server sends (<em>e.g.</em>): <code>Server: 3967 Apache</code></dd> 3968 3969 <dt><code>ServerTokens Major</code></dt> 3970 3971 <dd>Server sends (<em>e.g.</em>): <code>Server: 3972 Apache/2</code></dd> 3973 3974 <dt><code>ServerTokens Minor</code></dt> 3975 3976 <dd>Server sends (<em>e.g.</em>): <code>Server: 3977 Apache/2.4</code></dd> 3978 3979 <dt><code>ServerTokens Min[imal]</code></dt> 3980 3981 <dd>Server sends (<em>e.g.</em>): <code>Server: 3982 Apache/2.4.2</code></dd> 3983 3984 <dt><code>ServerTokens OS</code></dt> 3985 3986 <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2 3987 (Unix)</code></dd> 3988 3989 </dl> 3990 3991 <p>This setting applies to the entire server, and cannot be 3992 enabled or disabled on a virtualhost-by-virtualhost basis.</p> 3993 3994 <p>After version 2.0.44, this directive also controls the 3995 information presented by the <code class="directive"><a href="#serversignature">ServerSignature</a></code> directive.</p> 3996 3997 <div class="note">Setting <code class="directive">ServerTokens</code> to less than 3998 <code>minimal</code> is not recommended because it makes it more 3999 difficult to debug interoperational problems. Also note that 4000 disabling the Server: header does nothing at all to make your 4001 server more secure; the idea of "security through obscurity" 4002 is a myth and leads to a false sense of safety.</div> 4003 4004 4005<h3>See also</h3> 4006<ul> 4007<li><code class="directive"><a href="#serversignature">ServerSignature</a></code></li> 4008</ul> 4009</div> 4010<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4011<div class="directive-section"><h2><a name="SetHandler" id="SetHandler">SetHandler</a> <a name="sethandler" id="sethandler">Directive</a></h2> 4012<table class="directive"> 4013<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forces all matching files to be processed by a 4014handler</td></tr> 4015<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetHandler <var>handler-name</var>|None</code></td></tr> 4016<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 4017<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 4018<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4019<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4020</table> 4021 <p>When placed into an <code>.htaccess</code> file or a 4022 <code class="directive"><a href="#directory"><Directory></a></code> or 4023 <code class="directive"><a href="#location"><Location></a></code> 4024 section, this directive forces all matching files to be parsed 4025 through the <a href="/handler.html">handler</a> given by 4026 <var>handler-name</var>. For example, if you had a directory you 4027 wanted to be parsed entirely as imagemap rule files, regardless 4028 of extension, you might put the following into an 4029 <code>.htaccess</code> file in that directory:</p> 4030 4031 <pre class="prettyprint lang-config">SetHandler imap-file</pre> 4032 4033 4034 <p>Another example: if you wanted to have the server display a 4035 status report whenever a URL of 4036 <code>http://servername/status</code> was called, you might put 4037 the following into <code>httpd.conf</code>:</p> 4038 4039 <pre class="prettyprint lang-config"><Location "/status"> 4040 SetHandler server-status 4041</Location></pre> 4042 4043 4044 <p>You could also use this directive to configure a particular 4045 handler for files with a particular file extension. For example:</p> 4046 4047 <pre class="prettyprint lang-config"><FilesMatch \.php$> 4048 SetHandler application/x-httpd-php 4049</FilesMatch></pre> 4050 4051 4052 <p>You can override an earlier defined <code class="directive">SetHandler</code> 4053 directive by using the value <code>None</code>.</p> 4054 4055 <div class="note"><h3>Note</h3> 4056 <p>Because <code class="directive">SetHandler</code> overrides default handlers, 4057 normal behavior such as handling of URLs ending in a slash (/) as 4058 directories or index files is suppressed.</p></div> 4059 4060<h3>See also</h3> 4061<ul> 4062<li><code class="directive"><a href="/mod/mod_mime.html#addhandler">AddHandler</a></code></li> 4063</ul> 4064</div> 4065<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4066<div class="directive-section"><h2><a name="SetInputFilter" id="SetInputFilter">SetInputFilter</a> <a name="setinputfilter" id="setinputfilter">Directive</a></h2> 4067<table class="directive"> 4068<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process client requests and POST 4069input</td></tr> 4070<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetInputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr> 4071<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 4072<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 4073<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4074<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4075</table> 4076 <p>The <code class="directive">SetInputFilter</code> directive sets the 4077 filter or filters which will process client requests and POST 4078 input when they are received by the server. This is in addition to 4079 any filters defined elsewhere, including the 4080 <code class="directive"><a href="/mod/mod_mime.html#addinputfilter">AddInputFilter</a></code> 4081 directive.</p> 4082 4083 <p>If more than one filter is specified, they must be separated 4084 by semicolons in the order in which they should process the 4085 content.</p> 4086 4087<h3>See also</h3> 4088<ul> 4089<li><a href="/filter.html">Filters</a> documentation</li> 4090</ul> 4091</div> 4092<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4093<div class="directive-section"><h2><a name="SetOutputFilter" id="SetOutputFilter">SetOutputFilter</a> <a name="setoutputfilter" id="setoutputfilter">Directive</a></h2> 4094<table class="directive"> 4095<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the filters that will process responses from the 4096server</td></tr> 4097<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SetOutputFilter <var>filter</var>[;<var>filter</var>...]</code></td></tr> 4098<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 4099<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 4100<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4101<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4102</table> 4103 <p>The <code class="directive">SetOutputFilter</code> directive sets the filters 4104 which will process responses from the server before they are 4105 sent to the client. This is in addition to any filters defined 4106 elsewhere, including the 4107 <code class="directive"><a href="/mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> 4108 directive.</p> 4109 4110 <p>For example, the following configuration will process all files 4111 in the <code>/www/data/</code> directory for server-side 4112 includes.</p> 4113 4114 <pre class="prettyprint lang-config"><Directory "/www/data/"> 4115 SetOutputFilter INCLUDES 4116</Directory></pre> 4117 4118 4119 <p>If more than one filter is specified, they must be separated 4120 by semicolons in the order in which they should process the 4121 content.</p> 4122 4123<h3>See also</h3> 4124<ul> 4125<li><a href="/filter.html">Filters</a> documentation</li> 4126</ul> 4127</div> 4128<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4129<div class="directive-section"><h2><a name="TimeOut" id="TimeOut">TimeOut</a> <a name="timeout" id="timeout">Directive</a></h2> 4130<table class="directive"> 4131<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Amount of time the server will wait for 4132certain events before failing a request</td></tr> 4133<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TimeOut <var>seconds</var></code></td></tr> 4134<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>TimeOut 60</code></td></tr> 4135<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 4136<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4137<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4138</table> 4139 <p>The <code class="directive">TimeOut</code> directive defines the length 4140 of time Apache httpd will wait for I/O in various circumstances:</p> 4141 4142 <ol> 4143 <li>When reading data from the client, the length of time to 4144 wait for a TCP packet to arrive if the read buffer is 4145 empty.</li> 4146 4147 <li>When writing data to the client, the length of time to wait 4148 for an acknowledgement of a packet if the send buffer is 4149 full.</li> 4150 4151 <li>In <code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code>, the length of time to wait for 4152 output from a CGI script.</li> 4153 4154 <li>In <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>, the length of time to 4155 wait for output from a filtering process.</li> 4156 4157 <li>In <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code>, the default timeout value if 4158 <code class="directive"><a href="/mod/mod_proxy.html#proxytimeout">ProxyTimeout</a></code> is not 4159 configured.</li> 4160 </ol> 4161 4162 4163</div> 4164<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4165<div class="directive-section"><h2><a name="TraceEnable" id="TraceEnable">TraceEnable</a> <a name="traceenable" id="traceenable">Directive</a></h2> 4166<table class="directive"> 4167<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines the behavior on <code>TRACE</code> requests</td></tr> 4168<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TraceEnable <var>[on|off|extended]</var></code></td></tr> 4169<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>TraceEnable on</code></td></tr> 4170<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 4171<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4172<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4173</table> 4174 <p>This directive overrides the behavior of <code>TRACE</code> for both 4175 the core server and <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code>. The default 4176 <code>TraceEnable on</code> permits <code>TRACE</code> requests per 4177 RFC 2616, which disallows any request body to accompany the request. 4178 <code>TraceEnable off</code> causes the core server and 4179 <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> to return a <code>405</code> (Method not 4180 allowed) error to the client.</p> 4181 4182 <p>Finally, for testing and diagnostic purposes only, request 4183 bodies may be allowed using the non-compliant <code>TraceEnable 4184 extended</code> directive. The core (as an origin server) will 4185 restrict the request body to 64k (plus 8k for chunk headers if 4186 <code>Transfer-Encoding: chunked</code> is used). The core will 4187 reflect the full headers and all chunk headers with the response 4188 body. As a proxy server, the request body is not restricted to 64k.</p> 4189 4190 <div class="note"><h3>Note</h3> 4191 <p>Despite claims to the contrary, <code>TRACE</code> is not 4192 a security vulnerability and there is no viable reason for 4193 it to be disabled. Doing so necessarily makes your server 4194 non-compliant.</p> 4195 </div> 4196 4197</div> 4198<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4199<div class="directive-section"><h2><a name="UnDefine" id="UnDefine">UnDefine</a> <a name="undefine" id="undefine">Directive</a></h2> 4200<table class="directive"> 4201<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine the existence of a variable</td></tr> 4202<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UnDefine <var>parameter-name</var></code></td></tr> 4203<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 4204<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4205<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4206</table> 4207 <p>Undoes the effect of a <code class="directive"><a href="#define">Define</a></code> or 4208 of passing a <code>-D</code> argument to <code class="program"><a href="/programs/httpd.html">httpd</a></code>.</p> 4209 <p>This directive can be used to toggle the use of <code class="directive"><a href="#ifdefine"><IfDefine></a></code> sections without needing to alter 4210 <code>-D</code> arguments in any startup scripts.</p> 4211 4212</div> 4213<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4214<div class="directive-section"><h2><a name="UseCanonicalName" id="UseCanonicalName">UseCanonicalName</a> <a name="usecanonicalname" id="usecanonicalname">Directive</a></h2> 4215<table class="directive"> 4216<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures how the server determines its own name and 4217port</td></tr> 4218<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UseCanonicalName On|Off|DNS</code></td></tr> 4219<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>UseCanonicalName Off</code></td></tr> 4220<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 4221<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4222<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4223</table> 4224 <p>In many situations Apache httpd must construct a <em>self-referential</em> 4225 URL -- that is, a URL that refers back to the same server. With 4226 <code>UseCanonicalName On</code> Apache httpd will use the hostname and port 4227 specified in the <code class="directive"><a href="#servername">ServerName</a></code> 4228 directive to construct the canonical name for the server. This name 4229 is used in all self-referential URLs, and for the values of 4230 <code>SERVER_NAME</code> and <code>SERVER_PORT</code> in CGIs.</p> 4231 4232 <p>With <code>UseCanonicalName Off</code> Apache httpd will form 4233 self-referential URLs using the hostname and port supplied by 4234 the client if any are supplied (otherwise it will use the 4235 canonical name, as defined above). These values are the same 4236 that are used to implement <a href="/vhosts/name-based.html">name-based virtual hosts</a>, 4237 and are available with the same clients. The CGI variables 4238 <code>SERVER_NAME</code> and <code>SERVER_PORT</code> will be 4239 constructed from the client supplied values as well.</p> 4240 4241 <p>An example where this may be useful is on an intranet server 4242 where you have users connecting to the machine using short 4243 names such as <code>www</code>. You'll notice that if the users 4244 type a shortname, and a URL which is a directory, such as 4245 <code>http://www/splat</code>, <em>without the trailing 4246 slash</em> then Apache httpd will redirect them to 4247 <code>http://www.example.com/splat/</code>. If you have 4248 authentication enabled, this will cause the user to have to 4249 authenticate twice (once for <code>www</code> and once again 4250 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"> 4251 the FAQ on this subject for more information</a>). But if 4252 <code class="directive">UseCanonicalName</code> is set <code>Off</code>, then 4253 Apache httpd will redirect to <code>http://www/splat/</code>.</p> 4254 4255 <p>There is a third option, <code>UseCanonicalName DNS</code>, 4256 which is intended for use with mass IP-based virtual hosting to 4257 support ancient clients that do not provide a 4258 <code>Host:</code> header. With this option Apache httpd does a 4259 reverse DNS lookup on the server IP address that the client 4260 connected to in order to work out self-referential URLs.</p> 4261 4262 <div class="warning"><h3>Warning</h3> 4263 <p>If CGIs make assumptions about the values of <code>SERVER_NAME</code> 4264 they may be broken by this option. The client is essentially free 4265 to give whatever value they want as a hostname. But if the CGI is 4266 only using <code>SERVER_NAME</code> to construct self-referential URLs 4267 then it should be just fine.</p> 4268 </div> 4269 4270<h3>See also</h3> 4271<ul> 4272<li><code class="directive"><a href="#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code></li> 4273<li><code class="directive"><a href="#servername">ServerName</a></code></li> 4274<li><code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code></li> 4275</ul> 4276</div> 4277<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4278<div class="directive-section"><h2><a name="UseCanonicalPhysicalPort" id="UseCanonicalPhysicalPort">UseCanonicalPhysicalPort</a> <a name="usecanonicalphysicalport" id="usecanonicalphysicalport">Directive</a></h2> 4279<table class="directive"> 4280<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures how the server determines its own port</td></tr> 4281<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UseCanonicalPhysicalPort On|Off</code></td></tr> 4282<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>UseCanonicalPhysicalPort Off</code></td></tr> 4283<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 4284<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4285<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4286</table> 4287 <p>In many situations Apache httpd must construct a <em>self-referential</em> 4288 URL -- that is, a URL that refers back to the same server. With 4289 <code>UseCanonicalPhysicalPort On</code> Apache httpd will, when 4290 constructing the canonical port for the server to honor 4291 the <code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code> directive, 4292 provide the actual physical port number being used by this request 4293 as a potential port. With <code>UseCanonicalPhysicalPort Off</code> 4294 Apache httpd will not ever use the actual physical port number, instead 4295 relying on all configured information to construct a valid port number.</p> 4296 4297 <div class="note"><h3>Note</h3> 4298 <p>The ordering of the lookup when the physical port is used is as 4299 follows:</p> 4300 <dl> 4301 <dt><code>UseCanonicalName On</code></dt> 4302 <dd> 4303 <ol> 4304 <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li> 4305 <li>Physical port</li> 4306 <li>Default port</li> 4307 </ol> 4308 </dd> 4309 <dt><code>UseCanonicalName Off | DNS</code></dt> 4310 <dd> 4311 <ol> 4312 <li>Parsed port from <code>Host:</code> header</li> 4313 <li>Physical port</li> 4314 <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li> 4315 <li>Default port</li> 4316 </ol> 4317 </dd> 4318 </dl> 4319 4320 <p>With <code>UseCanonicalPhysicalPort Off</code>, the 4321 physical ports are removed from the ordering.</p> 4322 </div> 4323 4324 4325<h3>See also</h3> 4326<ul> 4327<li><code class="directive"><a href="#usecanonicalname">UseCanonicalName</a></code></li> 4328<li><code class="directive"><a href="#servername">ServerName</a></code></li> 4329<li><code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code></li> 4330</ul> 4331</div> 4332<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 4333<div class="directive-section"><h2><a name="VirtualHost" id="VirtualHost"><VirtualHost></a> <a name="virtualhost" id="virtualhost">Directive</a></h2> 4334<table class="directive"> 4335<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contains directives that apply only to a specific 4336hostname or IP address</td></tr> 4337<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><VirtualHost 4338 <var>addr</var>[:<var>port</var>] [<var>addr</var>[:<var>port</var>]] 4339 ...> ... </VirtualHost></code></td></tr> 4340<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 4341<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr> 4342<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr> 4343</table> 4344 <p><code class="directive"><VirtualHost></code> and 4345 <code></VirtualHost></code> are used to enclose a group of 4346 directives that will apply only to a particular virtual host. Any 4347 directive that is allowed in a virtual host context may be 4348 used. When the server receives a request for a document on a 4349 particular virtual host, it uses the configuration directives 4350 enclosed in the <code class="directive"><VirtualHost></code> 4351 section. <var>Addr</var> can be any of the following, optionally followed by 4352 a colon and a port number (or *):</p> 4353 4354 <ul> 4355 <li>The IP address of the virtual host;</li> 4356 4357 <li>A fully qualified domain name for the IP address of the 4358 virtual host (not recommended);</li> 4359 4360 <li>The character <code>*</code>, which acts as a wildcard and matches 4361 any IP address.</li> 4362 4363 <li>The string <code>_default_</code>, which is an alias for <code>*</code></li> 4364 4365 </ul> 4366 4367 <pre class="prettyprint lang-config"><VirtualHost 10.1.2.3:80> 4368 ServerAdmin webmaster@host.example.com 4369 DocumentRoot /www/docs/host.example.com 4370 ServerName host.example.com 4371 ErrorLog logs/host.example.com-error_log 4372 TransferLog logs/host.example.com-access_log 4373</VirtualHost></pre> 4374 4375 4376 4377 <p>IPv6 addresses must be specified in square brackets because 4378 the optional port number could not be determined otherwise. An 4379 IPv6 example is shown below:</p> 4380 4381 <pre class="prettyprint lang-config"><VirtualHost [2001:db8::a00:20ff:fea7:ccea]:80> 4382 ServerAdmin webmaster@host.example.com 4383 DocumentRoot /www/docs/host.example.com 4384 ServerName host.example.com 4385 ErrorLog logs/host.example.com-error_log 4386 TransferLog logs/host.example.com-access_log 4387</VirtualHost></pre> 4388 4389 4390 <p>Each Virtual Host must correspond to a different IP address, 4391 different port number or a different host name for the server, 4392 in the former case the server machine must be configured to 4393 accept IP packets for multiple addresses. (If the machine does 4394 not have multiple network interfaces, then this can be 4395 accomplished with the <code>ifconfig alias</code> command -- if 4396 your OS supports it).</p> 4397 4398 <div class="note"><h3>Note</h3> 4399 <p>The use of <code class="directive"><VirtualHost></code> does 4400 <strong>not</strong> affect what addresses Apache httpd listens on. You 4401 may need to ensure that Apache httpd is listening on the correct addresses 4402 using <code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code>.</p> 4403 </div> 4404 4405 <p>A <code class="directive"><a href="#servername">ServerName</a></code> should be 4406 specified inside each <code class="directive"><VirtualHost></code> block. If it is absent, the 4407 <code class="directive"><a href="#servername">ServerName</a></code> from the "main" 4408 server configuration will be inherited.</p> 4409 4410 <p>When a request is received, the server first maps it to the best matching 4411 <code class="directive"><VirtualHost></code> based on the local 4412 IP address and port combination only. Non-wildcards have a higher 4413 precedence. If no match based on IP and port occurs at all, the 4414 "main" server configuration is used.</p> 4415 4416 <p>If multiple virtual hosts contain the best matching IP address and port, 4417 the server selects from these virtual hosts the best match based on the 4418 requested hostname. If no matching name-based virtual host is found, 4419 then the first listed virtual host that matched the IP address will be 4420 used. As a consequence, the first listed virtual host for a given IP address 4421 and port combination is default virtual host for that IP and port 4422 combination.</p> 4423 4424 <div class="warning"><h3>Security</h3> 4425 <p>See the <a href="/misc/security_tips.html">security tips</a> 4426 document for details on why your security could be compromised if the 4427 directory where log files are stored is writable by anyone other 4428 than the user that starts the server.</p> 4429 </div> 4430 4431<h3>See also</h3> 4432<ul> 4433<li><a href="/vhosts/">Apache HTTP Server Virtual Host documentation</a></li> 4434<li><a href="/dns-caveats.html">Issues Regarding DNS and 4435 Apache HTTP Server</a></li> 4436<li><a href="/bind.html">Setting 4437 which addresses and ports Apache HTTP Server uses</a></li> 4438<li><a href="/sections.html">How <Directory>, <Location> 4439 and <Files> sections work</a> for an explanation of how these 4440 different sections are combined when a request is received</li> 4441</ul> 4442</div> 4443</div> 4444<div class="bottomlang"> 4445<p><span>Available Languages: </span><a href="/de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> | 4446<a href="/en/mod/core.html" title="English"> en </a> | 4447<a href="/es/mod/core.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> | 4448<a href="/fr/mod/core.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 4449<a href="/ja/mod/core.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 4450<a href="/tr/mod/core.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 4451</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&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> 4452<script type="text/javascript"><!--//--><![CDATA[//><!-- 4453var comments_shortname = 'httpd'; 4454var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/core.html'; 4455(function(w, d) { 4456 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 4457 d.write('<div id="comments_thread"><\/div>'); 4458 var s = d.createElement('script'); 4459 s.type = 'text/javascript'; 4460 s.async = true; 4461 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 4462 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 4463 } 4464 else { 4465 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 4466 } 4467})(window, document); 4468//--><!]]></script></div><div id="footer"> 4469<p class="apache">Copyright 2014 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> 4470<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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[//><!-- 4471if (typeof(prettyPrint) !== 'undefined') { 4472 prettyPrint(); 4473} 4474//--><!]]></script> 4475</body></html>
