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