| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="core.xml.meta"> |
| |
| <name>core</name> |
| <description>Core Apache HTTP Server features that are always |
| available</description> |
| <status>Core</status> |
| |
| <directivesynopsis> |
| <name>AcceptFilter</name> |
| <description>Configures optimizations for a Protocol's Listener Sockets</description> |
| <syntax>AcceptFilter <var>protocol</var> <var>accept_filter</var></syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive enables operating system specific optimizations for a |
| listening socket by the <directive>Protocol</directive> type. |
| The basic premise is for the kernel to not send a socket to the server |
| process until either data is received or an entire HTTP Request is buffered. |
| Only <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&sektion=9"> |
| FreeBSD's Accept Filters</a>, Linux's more primitive |
| <code>TCP_DEFER_ACCEPT</code>, and Windows' optimized AcceptEx() |
| are currently supported.</p> |
| |
| <p>Using <code>none</code> for an argument will disable any accept filters |
| for that protocol. This is useful for protocols that require a server |
| send data first, such as <code>ftp:</code> or <code>nntp</code>:</p> |
| <highlight language="config"> |
| AcceptFilter nntp none |
| </highlight> |
| |
| <p>The default protocol names are <code>https</code> for port 443 |
| and <code>http</code> for all other ports. To specify that another |
| protocol is being used with a listening port, add the <var>protocol</var> |
| argument to the <directive module="mpm_common">Listen</directive> |
| directive.</p> |
| |
| <p>The default values on FreeBSD are:</p> |
| <highlight language="config"> |
| AcceptFilter http httpready |
| AcceptFilter https dataready |
| </highlight> |
| |
| <p>The <code>httpready</code> accept filter buffers entire HTTP requests at |
| the kernel level. Once an entire request is received, the kernel then |
| sends it to the server. See the |
| <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_http&sektion=9"> |
| accf_http(9)</a> man page for more details. Since HTTPS requests are |
| encrypted, only the <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_data&sektion=9"> |
| accf_data(9)</a> filter is used.</p> |
| |
| <p>The default values on Linux are:</p> |
| <highlight language="config"> |
| AcceptFilter http data |
| AcceptFilter https data |
| </highlight> |
| |
| <p>Linux's <code>TCP_DEFER_ACCEPT</code> does not support buffering http |
| requests. Any value besides <code>none</code> will enable |
| <code>TCP_DEFER_ACCEPT</code> on that listener. For more details |
| see the Linux |
| <a href="http://man7.org/linux/man-pages/man7/tcp.7.html"> |
| tcp(7)</a> man page.</p> |
| |
| <p>The default values on Windows are:</p> |
| <highlight language="config"> |
| AcceptFilter http connect |
| AcceptFilter https connect |
| </highlight> |
| |
| <p>Window's mpm_winnt interprets the AcceptFilter to toggle the AcceptEx() |
| API, and does not support http protocol buffering. <code>connect</code> |
| will use the AcceptEx() API, also retrieve the network endpoint |
| addresses, but like <code>none</code> the <code>connect</code> option |
| does not wait for the initial data transmission.</p> |
| |
| <p>On Windows, <code>none</code> uses accept() rather than AcceptEx() |
| and will not recycle sockets between connections. This is useful for |
| network adapters with broken driver support, as well as some virtual |
| network providers such as vpn drivers, or spam, virus or spyware |
| filters.</p> |
| |
| <note type="warning"> |
| <title>The <code>data</code> AcceptFilter (Windows)</title> |
| |
| <p>For versions 2.4.23 and prior, the Windows <code>data</code> accept |
| filter waited until data had been transmitted and the initial data |
| buffer and network endpoint addresses had been retrieved from the |
| single AcceptEx() invocation. This implementation was subject to a |
| denial of service attack and has been disabled.</p> |
| |
| <p>Current releases of httpd default to the <code>connect</code> filter |
| on Windows, and will fall back to <code>connect</code> if |
| <code>data</code> is specified. Users of prior releases are encouraged |
| to add an explicit setting of <code>connect</code> for their |
| AcceptFilter, as shown above.</p> |
| </note> |
| |
| </usage> |
| <seealso><directive module="core">Protocol</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AcceptPathInfo</name> |
| <description>Resources accept trailing pathname information</description> |
| <syntax>AcceptPathInfo On|Off|Default</syntax> |
| <default>AcceptPathInfo Default</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| |
| <p>This directive controls whether requests that contain trailing |
| pathname information that follows an actual filename (or |
| non-existent file in an existing directory) will be accepted or |
| rejected. The trailing pathname information can be made |
| available to scripts in the <code>PATH_INFO</code> environment |
| variable.</p> |
| |
| <p>For example, assume the location <code>/test/</code> points to |
| a directory that contains only the single file |
| <code>here.html</code>. Then requests for |
| <code>/test/here.html/more</code> and |
| <code>/test/nothere.html/more</code> both collect |
| <code>/more</code> as <code>PATH_INFO</code>.</p> |
| |
| <p>The three possible arguments for the |
| <directive>AcceptPathInfo</directive> directive are:</p> |
| <dl> |
| <dt><code>Off</code></dt><dd>A request will only be accepted if it |
| maps to a literal path that exists. Therefore a request with |
| trailing pathname information after the true filename such as |
| <code>/test/here.html/more</code> in the above example will return |
| a 404 NOT FOUND error.</dd> |
| |
| <dt><code>On</code></dt><dd>A request will be accepted if a |
| leading path component maps to a file that exists. The above |
| example <code>/test/here.html/more</code> will be accepted if |
| <code>/test/here.html</code> maps to a valid file.</dd> |
| |
| <dt><code>Default</code></dt><dd>The treatment of requests with |
| trailing pathname information is determined by the <a |
| href="../handler.html">handler</a> responsible for the request. |
| The core handler for normal files defaults to rejecting |
| <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 |
| <code>PATH_INFO</code> by default.</dd> |
| </dl> |
| |
| <p>The primary purpose of the <code>AcceptPathInfo</code> |
| directive is to allow you to override the handler's choice of |
| accepting or rejecting <code>PATH_INFO</code>. This override is required, |
| for example, when you use a <a href="../filter.html">filter</a>, such |
| as <a href="mod_include.html">INCLUDES</a>, to generate content |
| based on <code>PATH_INFO</code>. The core handler would usually reject |
| the request, so you can use the following configuration to enable |
| such a script:</p> |
| |
| <highlight language="config"> |
| <Files "mypaths.shtml"> |
| Options +Includes |
| SetOutputFilter INCLUDES |
| AcceptPathInfo On |
| </Files> |
| </highlight> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AccessFileName</name> |
| <description>Name of the distributed configuration file</description> |
| <syntax>AccessFileName <var>filename</var> [<var>filename</var>] ...</syntax> |
| <default>AccessFileName .htaccess</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>While processing a request, the server looks for |
| the first existing configuration file from this list of names in |
| every directory of the path to the document, if distributed |
| configuration files are <a href="#allowoverride">enabled for that |
| directory</a>. For example:</p> |
| |
| <highlight language="config"> |
| AccessFileName .acl |
| </highlight> |
| |
| <p>Before returning the document |
| <code>/usr/local/web/index.html</code>, the server will read |
| <code>/.acl</code>, <code>/usr/.acl</code>, |
| <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code> |
| for directives unless they have been disabled with:</p> |
| |
| <highlight language="config"> |
| <Directory "/"> |
| AllowOverride None |
| </Directory> |
| </highlight> |
| </usage> |
| <seealso><directive module="core">AllowOverride</directive></seealso> |
| <seealso><a href="../configuring.html">Configuration Files</a></seealso> |
| <seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AddDefaultCharset</name> |
| <description>Default charset parameter to be added when a response |
| content-type is <code>text/plain</code> or <code>text/html</code></description> |
| <syntax>AddDefaultCharset On|Off|<var>charset</var></syntax> |
| <default>AddDefaultCharset Off</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>This directive specifies a default value for the media type |
| charset parameter (the name of a character encoding) to be added |
| to a response if and only if the response's content-type is either |
| <code>text/plain</code> or <code>text/html</code>. This should override |
| any charset specified in the body of the response via a <code>META</code> |
| element, though the exact behavior is often dependent on the user's client |
| configuration. A setting of <code>AddDefaultCharset Off</code> |
| disables this functionality. <code>AddDefaultCharset On</code> enables |
| a default charset of <code>iso-8859-1</code>. Any other value is assumed |
| to be the <var>charset</var> to be used, which should be one of the |
| <a href="http://www.iana.org/assignments/character-sets">IANA registered |
| charset values</a> for use in Internet media types (MIME types). |
| For example:</p> |
| |
| <highlight language="config"> |
| AddDefaultCharset utf-8 |
| </highlight> |
| |
| <p><directive>AddDefaultCharset</directive> should only be used when all |
| of the text resources to which it applies are known to be in that |
| character encoding and it is too inconvenient to label their charset |
| individually. One such example is to add the charset parameter |
| to resources containing generated content, such as legacy CGI |
| scripts, that might be vulnerable to cross-site scripting attacks |
| due to user-provided data being included in the output. Note, however, |
| that a better solution is to just fix (or delete) those scripts, since |
| setting a default charset does not protect users that have enabled |
| the "auto-detect character encoding" feature on their browser.</p> |
| </usage> |
| <seealso><directive module="mod_mime">AddCharset</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AllowEncodedSlashes</name> |
| <description>Determines whether encoded path separators in URLs are allowed to |
| be passed through</description> |
| <syntax>AllowEncodedSlashes On|Off|NoDecode</syntax> |
| <default>AllowEncodedSlashes Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| <compatibility> |
| NoDecode option available in 2.3.12 and later.</compatibility> |
| |
| <usage> |
| <p>The <directive>AllowEncodedSlashes</directive> directive allows URLs |
| which contain encoded path separators (<code>%2F</code> for <code>/</code> |
| and additionally <code>%5C</code> for <code>\</code> on accordant systems) |
| to be used in the path info.</p> |
| |
| <p>With the default value, <code>Off</code>, such URLs are refused |
| with a 404 (Not found) error.</p> |
| |
| <p>With the value <code>On</code>, such URLs are accepted, and encoded |
| slashes are decoded like all other encoded characters.</p> |
| |
| <p>With the value <code>NoDecode</code>, such URLs are accepted, but |
| encoded slashes are not decoded but left in their encoded state.</p> |
| |
| <p>Turning <directive>AllowEncodedSlashes</directive> <code>On</code> is |
| mostly useful when used in conjunction with <code>PATH_INFO</code>.</p> |
| |
| <note><title>Note</title> |
| <p>If encoded slashes are needed in path info, use of <code>NoDecode</code> is |
| strongly recommended as a security measure. Allowing slashes |
| to be decoded could potentially allow unsafe paths.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">AcceptPathInfo</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AllowOverride</name> |
| <description>Types of directives that are allowed in |
| <code>.htaccess</code> files</description> |
| <syntax>AllowOverride All|None|<var>directive-type</var> |
| [<var>directive-type</var>] ...</syntax> |
| <default>AllowOverride None (2.3.9 and later), AllowOverride All (2.3.8 and earlier)</default> |
| <contextlist><context>directory</context></contextlist> |
| |
| <usage> |
| <p>When the server finds an <code>.htaccess</code> file (as |
| specified by <directive module="core">AccessFileName</directive>), |
| it needs to know which directives declared in that file can override |
| earlier configuration directives.</p> |
| |
| <note><title>Only available in <Directory> sections</title> |
| <directive>AllowOverride</directive> is valid only in |
| <directive type="section" module="core">Directory</directive> |
| sections specified without regular expressions, not in <directive |
| type="section" module="core">Location</directive>, <directive |
| module="core" type="section">DirectoryMatch</directive> or |
| <directive type="section" module="core">Files</directive> sections. |
| </note> |
| |
| <p>When this directive is set to <code>None</code> and <directive |
| module="core">AllowOverrideList</directive> is set to |
| <code>None</code>, <a href="#accessfilename">.htaccess</a> files are |
| completely ignored. In this case, the server will not even attempt |
| to read <code>.htaccess</code> files in the filesystem.</p> |
| |
| <p>When this directive is set to <code>All</code>, then any |
| directive which has the .htaccess <a |
| href="directive-dict.html#Context">Context</a> is allowed in |
| <code>.htaccess</code> files.</p> |
| |
| <p>The <var>directive-type</var> can be one of the following |
| groupings of directives. (See the <a href="overrides.html">override class |
| index</a> for an up-to-date listing of which directives are enabled by each |
| <var>directive-type</var>.)</p> |
| |
| <dl> |
| <dt><a href="overrides.html#override-authconfig">AuthConfig</a></dt> |
| |
| <dd> |
| |
| Allow use of the authorization directives (<directive |
| module="mod_authz_dbm">AuthDBMGroupFile</directive>, |
| <directive module="mod_authn_dbm">AuthDBMUserFile</directive>, |
| <directive module="mod_authz_groupfile">AuthGroupFile</directive>, |
| <directive module="mod_authn_core">AuthName</directive>, |
| <directive module="mod_authn_core">AuthType</directive>, <directive |
| module="mod_authn_file">AuthUserFile</directive>, <directive |
| module="mod_authz_core">Require</directive>, <em>etc.</em>).</dd> |
| |
| <dt><a href="overrides.html#override-fileinfo">FileInfo</a></dt> |
| |
| <dd> |
| Allow use of the directives controlling document types |
| (<directive module="core">ErrorDocument</directive>, |
| <directive module="core">ForceType</directive>, |
| <directive module="mod_negotiation">LanguagePriority</directive>, |
| <directive module="core">SetHandler</directive>, |
| <directive module="core">SetInputFilter</directive>, |
| <directive module="core">SetOutputFilter</directive>, and |
| <module>mod_mime</module> Add* and Remove* directives), |
| document meta data (<directive |
| module="mod_headers">Header</directive>, <directive |
| module="mod_headers">RequestHeader</directive>, <directive |
| module="mod_setenvif">SetEnvIf</directive>, <directive |
| module="mod_setenvif">SetEnvIfNoCase</directive>, <directive |
| module="mod_setenvif">BrowserMatch</directive>, <directive |
| module="mod_usertrack">CookieExpires</directive>, <directive |
| module="mod_usertrack">CookieDomain</directive>, <directive |
| module="mod_usertrack">CookieStyle</directive>, <directive |
| module="mod_usertrack">CookieTracking</directive>, <directive |
| module="mod_usertrack">CookieName</directive>), |
| <module>mod_rewrite</module> directives (<directive |
| module="mod_rewrite">RewriteEngine</directive>, <directive |
| module="mod_rewrite">RewriteOptions</directive>, <directive |
| module="mod_rewrite">RewriteBase</directive>, <directive |
| module="mod_rewrite">RewriteCond</directive>, <directive |
| module="mod_rewrite">RewriteRule</directive>), |
| <module>mod_alias</module> directives (<directive |
| module="mod_alias">Redirect</directive>, <directive |
| module="mod_alias">RedirectTemp</directive>, <directive |
| module="mod_alias">RedirectPermanent</directive>, <directive |
| module="mod_alias">RedirectMatch</directive>), and |
| <directive module="mod_actions">Action</directive> from |
| <module>mod_actions</module>. |
| </dd> |
| |
| <dt><a href="overrides.html#override-indexes">Indexes</a></dt> |
| |
| <dd> |
| Allow use of the directives controlling directory indexing |
| (<directive |
| module="mod_autoindex">AddDescription</directive>, |
| <directive module="mod_autoindex">AddIcon</directive>, <directive |
| module="mod_autoindex">AddIconByEncoding</directive>, |
| <directive module="mod_autoindex">AddIconByType</directive>, |
| <directive module="mod_autoindex">DefaultIcon</directive>, <directive |
| module="mod_dir">DirectoryIndex</directive>, <a href="mod_autoindex.html#indexoptions.fancyindexing" |
| ><code>FancyIndexing</code></a>, <directive |
| module="mod_autoindex">HeaderName</directive>, <directive |
| module="mod_autoindex">IndexIgnore</directive>, <directive |
| module="mod_autoindex">IndexOptions</directive>, <directive |
| module="mod_autoindex">ReadmeName</directive>, |
| <em>etc.</em>).</dd> |
| |
| <dt><a href="overrides.html#override-limit">Limit</a></dt> |
| |
| <dd> |
| Allow use of the directives controlling host access (<directive |
| module="mod_access_compat">Allow</directive>, <directive |
| module="mod_access_compat">Deny</directive> and <directive |
| module="mod_access_compat">Order</directive>).</dd> |
| |
| <dt>Nonfatal=[Override|Unknown|All]</dt> |
| |
| <dd> |
| Allow use of AllowOverride option to treat syntax errors in |
| .htaccess as nonfatal. Instead of causing an Internal Server |
| Error, disallowed or unrecognised directives will be ignored |
| and a warning logged: |
| <ul> |
| <li><strong>Nonfatal=Override</strong> treats directives |
| forbidden by AllowOverride as nonfatal.</li> |
| <li><strong>Nonfatal=Unknown</strong> treats unknown directives |
| as nonfatal. This covers typos and directives implemented |
| by a module that's not present.</li> |
| <li><strong>Nonfatal=All</strong> treats both the above as nonfatal.</li> |
| </ul> |
| <p>Note that a syntax error in a valid directive will still cause |
| an internal server error.</p> |
| <note type="warning"><title>Security</title> |
| Nonfatal errors may have security implications for .htaccess users. |
| For example, if AllowOverride disallows AuthConfig, users' |
| configuration designed to restrict access to a site will be disabled. |
| </note> |
| </dd> |
| |
| <dt><a href="overrides.html#override-options">Options</a>[=<var>Option</var>,...]</dt> |
| |
| <dd> |
| Allow use of the directives controlling specific directory |
| features (<directive module="core">Options</directive> and |
| <directive module="mod_include">XBitHack</directive>). |
| An equal sign may be given followed by a comma-separated list, without |
| spaces, of options that may be set using the <directive |
| module="core">Options</directive> command. |
| |
| <note><title>Implicit disabling of Options</title> |
| <p>Even though the list of options that may be used in .htaccess files |
| can be limited with this directive, as long as any <directive |
| module="core">Options</directive> directive is allowed any |
| other inherited option can be disabled by using the non-relative |
| syntax. In other words, this mechanism cannot force a specific option |
| to remain <em>set</em> while allowing any others to be set. |
| </p></note> |
| |
| <example> |
| AllowOverride Options=Indexes,MultiViews |
| </example> |
| </dd> |
| </dl> |
| |
| <p>Example:</p> |
| |
| <highlight language="config"> |
| AllowOverride AuthConfig Indexes |
| </highlight> |
| |
| <p>In the example above, all directives that are neither in the group |
| <code>AuthConfig</code> nor <code>Indexes</code> cause an internal |
| server error.</p> |
| |
| <note><p>For security and performance reasons, do not set |
| <code>AllowOverride</code> to anything other than <code>None</code> |
| in your <code><Directory "/"></code> block. Instead, find (or |
| create) the <code><Directory></code> block that refers to the |
| directory where you're actually planning to place a |
| <code>.htaccess</code> file.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">AccessFileName</directive></seealso> |
| <seealso><directive module="core">AllowOverrideList</directive></seealso> |
| <seealso><a href="../configuring.html">Configuration Files</a></seealso> |
| <seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso> |
| <seealso><a href="overrides.html">Override Class Index for .htaccess</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AllowOverrideList</name> |
| <description>Individual directives that are allowed in |
| <code>.htaccess</code> files</description> |
| <syntax>AllowOverrideList None|<var>directive</var> |
| [<var>directive-type</var>] ...</syntax> |
| <default>AllowOverrideList None</default> |
| <contextlist><context>directory</context></contextlist> |
| |
| <usage> |
| <p>When the server finds an <code>.htaccess</code> file (as |
| specified by <directive module="core">AccessFileName</directive>), |
| it needs to know which directives declared in that file can override |
| earlier configuration directives.</p> |
| |
| <note><title>Only available in <Directory> sections</title> |
| <directive>AllowOverrideList</directive> is valid only in |
| <directive type="section" module="core">Directory</directive> |
| sections specified without regular expressions, not in <directive |
| type="section" module="core">Location</directive>, <directive |
| module="core" type="section">DirectoryMatch</directive> or |
| <directive type="section" module="core">Files</directive> sections. |
| </note> |
| |
| <p>When this directive is set to <code>None</code> and <directive |
| module="core">AllowOverride</directive> is set to <code>None</code>, |
| then <a href="#accessfilename">.htaccess</a> files are completely |
| ignored. In this case, the server will not even attempt to read |
| <code>.htaccess</code> files in the filesystem.</p> |
| |
| <p>Example:</p> |
| |
| <highlight language="config"> |
| AllowOverride None |
| AllowOverrideList Redirect RedirectMatch |
| </highlight> |
| |
| <p>In the example above, only the <code>Redirect</code> and |
| <code>RedirectMatch</code> directives are allowed. All others will |
| cause an internal server error.</p> |
| |
| <p>Example:</p> |
| |
| <highlight language="config"> |
| AllowOverride AuthConfig |
| AllowOverrideList CookieTracking CookieName |
| </highlight> |
| |
| <p>In the example above, <directive module="core">AllowOverride |
| </directive> grants permission to the <code>AuthConfig</code> |
| directive grouping and <directive>AllowOverrideList</directive> grants |
| permission to only two directives from the <code>FileInfo</code> directive |
| grouping. All others will cause an internal server error.</p> |
| </usage> |
| |
| <seealso><directive module="core">AccessFileName</directive></seealso> |
| <seealso><directive module="core">AllowOverride</directive></seealso> |
| <seealso><a href="../configuring.html">Configuration Files</a></seealso> |
| <seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CGIMapExtension</name> |
| <description>Technique for locating the interpreter for CGI |
| scripts</description> |
| <syntax>CGIMapExtension <var>cgi-path</var> <var>.extension</var></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>NetWare only</compatibility> |
| |
| <usage> |
| <p>This directive is used to control how Apache httpd finds the |
| interpreter used to run CGI scripts. For example, setting |
| <code>CGIMapExtension sys:\foo.nlm .foo</code> will |
| cause all CGI script files with a <code>.foo</code> extension to |
| be passed to the FOO interpreter.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CGIPassAuth</name> |
| <description>Enables passing HTTP authorization headers to scripts as CGI |
| variables</description> |
| <syntax>CGIPassAuth On|Off</syntax> |
| <default>CGIPassAuth Off</default> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>AuthConfig</override> |
| <compatibility>Available in Apache HTTP Server 2.4.13 and later</compatibility> |
| |
| <usage> |
| <p><directive>CGIPassAuth</directive> allows scripts access to HTTP |
| authorization headers such as <code>Authorization</code>, which is |
| required for scripts that implement HTTP Basic authentication. |
| Normally these HTTP headers are hidden from scripts. This is to disallow |
| scripts from seeing user ids and passwords used to access the server when |
| HTTP Basic authentication is enabled in the web server. This directive |
| should be used when scripts are allowed to implement HTTP Basic |
| authentication.</p> |
| |
| <p>This directive can be used instead of the compile-time setting |
| <code>SECURITY_HOLE_PASS_AUTHORIZATION</code> which has been available |
| in previous versions of Apache HTTP Server.</p> |
| |
| <p>The setting is respected by any modules which use |
| <code>ap_add_common_vars()</code>, such as <module>mod_cgi</module>, |
| <module>mod_cgid</module>, <module>mod_proxy_fcgi</module>, |
| <module>mod_proxy_scgi</module>, and so on. Notably, it affects |
| modules which don't handle the request in the usual sense but |
| still use this API; examples of this are <module>mod_include</module> |
| and <module>mod_ext_filter</module>. Third-party modules that don't |
| use <code>ap_add_common_vars()</code> may choose to respect the setting |
| as well.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CGIVar</name> |
| <description>Controls how some CGI variables are set</description> |
| <syntax>CGIVar <var>variable</var> <var>rule</var></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>Available in Apache HTTP Server 2.4.21 and later</compatibility> |
| |
| <usage> |
| <p>This directive controls how some CGI variables are set.</p> |
| |
| <p><strong>REQUEST_URI</strong> rules:</p> |
| <dl> |
| <dt><code>original-uri</code> (default)</dt> |
| <dd>The value is taken from the original request line, and will not |
| reflect internal redirects or subrequests which change the requested |
| resource.</dd> |
| <dt><code>current-uri</code></dt> |
| <dd>The value reflects the resource currently being processed, |
| which may be different than the original request from the client |
| due to internal redirects or subrequests.</dd> |
| </dl> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ContentDigest</name> |
| <description>Enables the generation of <code>Content-MD5</code> HTTP Response |
| headers</description> |
| <syntax>ContentDigest On|Off</syntax> |
| <default>ContentDigest Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>Options</override> |
| <status>Experimental</status> |
| |
| <usage> |
| <p>This directive enables the generation of |
| <code>Content-MD5</code> headers as defined in RFC1864 |
| respectively RFC2616.</p> |
| |
| <p>MD5 is an algorithm for computing a "message digest" |
| (sometimes called "fingerprint") of arbitrary-length data, with |
| a high degree of confidence that any alterations in the data |
| will be reflected in alterations in the message digest.</p> |
| |
| <p>The <code>Content-MD5</code> header provides an end-to-end |
| message integrity check (MIC) of the entity-body. A proxy or |
| client may check this header for detecting accidental |
| modification of the entity-body in transit. Example header:</p> |
| |
| <example> |
| Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA== |
| </example> |
| |
| <p>Note that this can cause performance problems on your server |
| since the message digest is computed on every request (the |
| values are not cached).</p> |
| |
| <p><code>Content-MD5</code> is only sent for documents served |
| by the <module>core</module>, and not by any module. For example, |
| SSI documents, output from CGI scripts, and byte range responses |
| do not have this header.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DefaultRuntimeDir</name> |
| <description>Base directory for the server run-time files</description> |
| <syntax>DefaultRuntimeDir <var>directory-path</var></syntax> |
| <default>DefaultRuntimeDir DEFAULT_REL_RUNTIMEDIR (logs/)</default> |
| <contextlist><context>server config</context></contextlist> |
| <compatibility>Available in Apache 2.4.2 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>DefaultRuntimeDir</directive> directive sets the |
| directory in which the server will create various run-time files |
| (shared memory, locks, etc.). If set as a relative path, the full path |
| will be relative to <directive>ServerRoot</directive>.</p> |
| |
| <p><strong>Example</strong></p> |
| <highlight language="config"> |
| DefaultRuntimeDir scratch/ |
| </highlight> |
| |
| <p>The default location of <directive>DefaultRuntimeDir</directive> may be |
| modified by changing the <code>DEFAULT_REL_RUNTIMEDIR</code> #define |
| at build time.</p> |
| |
| <p>Note: <directive>ServerRoot</directive> should be specified before this |
| directive is used. Otherwise, the default value of <directive>ServerRoot</directive> |
| would be used to set the base directory.</p> |
| |
| </usage> |
| <seealso><a href="../misc/security_tips.html#serverroot">the |
| security tips</a> for information on how to properly set |
| permissions on the <directive>ServerRoot</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DefaultType</name> |
| <description>This directive has no effect other than to emit warnings |
| if the value is not <code>none</code>. In prior versions, DefaultType |
| would specify a default media type to assign to response content for |
| which no other media type configuration could be found. |
| </description> |
| <syntax>DefaultType <var>media-type|none</var></syntax> |
| <default>DefaultType none</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>The argument <code>none</code> is available in Apache httpd 2.2.7 and later. All other choices are DISABLED for 2.3.x and later.</compatibility> |
| |
| <usage> |
| <p>This directive has been disabled. For backwards compatibility |
| of configuration files, it may be specified with the value |
| <code>none</code>, meaning no default media type. For example:</p> |
| |
| <highlight language="config"> |
| DefaultType None |
| </highlight> |
| |
| <p><code>DefaultType None</code> is only available in |
| httpd-2.2.7 and later.</p> |
| |
| <p>Use the mime.types configuration file and the |
| <directive module="mod_mime">AddType</directive> to configure media |
| type assignments via file extensions, or the |
| <directive module="core">ForceType</directive> directive to configure |
| the media type for specific resources. Otherwise, the server will |
| send the response without a Content-Type header field and the |
| recipient may attempt to guess the media type.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Define</name> |
| <description>Define a variable</description> |
| <syntax>Define <var>parameter-name</var> [<var>parameter-value</var>]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context></contextlist> |
| |
| <usage> |
| <p>In its one parameter form, <directive>Define</directive> is |
| equivalent to passing the <code>-D</code> argument to |
| <program>httpd</program>. It can be used to toggle the use of |
| <directive module="core" type="section">IfDefine</directive> |
| sections without needing to alter <code>-D</code> arguments in any |
| startup scripts.</p> |
| |
| <p>In addition to that, if the second parameter is given, a config variable |
| is set to this value. The variable can be used in the configuration using |
| the <code>${VAR}</code> syntax. The variable is always globally defined |
| and not limited to the scope of the surrounding config section.</p> |
| |
| <highlight language="config"> |
| <IfDefine TEST> |
| Define servername test.example.com |
| </IfDefine> |
| <IfDefine !TEST> |
| Define servername www.example.com |
| Define SSL |
| </IfDefine> |
| |
| DocumentRoot "/var/www/${servername}/htdocs" |
| </highlight> |
| |
| <p>Variable names may not contain colon ":" characters, to avoid clashes |
| with <directive module="mod_rewrite">RewriteMap</directive>'s syntax.</p> |
| |
| <note><title>Virtual Host scope and pitfalls</title> |
| <p>While this directive is supported in virtual host context, |
| the changes it makes are visible to any later configuration |
| directives, beyond any enclosing virtual host.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">UnDefine</directive></seealso> |
| <seealso><directive module="core">IfDefine</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Directory</name> |
| <description>Enclose a group of directives that apply only to the |
| named file-system directory, sub-directories, and their contents.</description> |
| <syntax><Directory <var>directory-path</var>> |
| ... </Directory></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p><directive type="section">Directory</directive> and |
| <code></Directory></code> are used to enclose a group of |
| directives that will apply only to the named directory, |
| sub-directories of that directory, and the files within the respective |
| directories. Any directive that is allowed |
| in a directory context may be used. <var>Directory-path</var> is |
| either the full path to a directory, or a wild-card string using |
| Unix shell-style matching. In a wild-card string, <code>?</code> matches |
| any single character, and <code>*</code> matches any sequences of |
| characters. You may also use <code>[]</code> character ranges. None |
| of the wildcards match a `/' character, so <code><Directory |
| "/*/public_html"></code> will not match |
| <code>/home/user/public_html</code>, but <code><Directory |
| "/home/*/public_html"></code> will match. Example:</p> |
| |
| <highlight language="config"> |
| <Directory "/usr/local/httpd/htdocs"> |
| Options Indexes FollowSymLinks |
| </Directory> |
| </highlight> |
| |
| <p>Directory paths <em>may</em> be quoted, if you like, however, it |
| <em>must</em> be quoted if the path contains spaces. This is because a |
| space would otherwise indicate the end of an argument.</p> |
| |
| <note> |
| <p>Be careful with the <var>directory-path</var> arguments: |
| They have to literally match the filesystem path which Apache httpd uses |
| to access the files. Directives applied to a particular |
| <code><Directory></code> will not apply to files accessed from |
| that same directory via a different path, such as via different symbolic |
| links.</p> |
| </note> |
| |
| <p><glossary ref="regex">Regular |
| expressions</glossary> can also be used, with the addition of the |
| <code>~</code> character. For example:</p> |
| |
| <highlight language="config"> |
| <Directory ~ "^/www/[0-9]{3}"> |
| |
| </Directory> |
| </highlight> |
| |
| <p>would match directories in <code>/www/</code> that consisted of |
| three numbers.</p> |
| |
| <p>If multiple (non-regular expression) <directive |
| type="section">Directory</directive> sections |
| match the directory (or one of its parents) containing a document, |
| then the directives are applied in the order of shortest match |
| first, interspersed with the directives from the <a |
| href="#accessfilename">.htaccess</a> files. For example, |
| with</p> |
| |
| <highlight language="config"> |
| <Directory "/"> |
| AllowOverride None |
| </Directory> |
| |
| <Directory "/home"> |
| AllowOverride FileInfo |
| </Directory> |
| </highlight> |
| |
| <p>for access to the document <code>/home/web/dir/doc.html</code> |
| the steps are:</p> |
| |
| <ul> |
| <li>Apply directive <code>AllowOverride None</code> |
| (disabling <code>.htaccess</code> files).</li> |
| |
| <li>Apply directive <code>AllowOverride FileInfo</code> (for |
| directory <code>/home</code>).</li> |
| |
| <li>Apply any <code>FileInfo</code> directives in |
| <code>/home/.htaccess</code>, <code>/home/web/.htaccess</code> and |
| <code>/home/web/dir/.htaccess</code> in that order.</li> |
| </ul> |
| |
| <p>Regular expressions are not considered until after all of the |
| normal sections have been applied. Then all of the regular |
| expressions are tested in the order they appeared in the |
| configuration file. For example, with</p> |
| |
| <highlight language="config"> |
| <Directory ~ "abc$"> |
| # ... directives here ... |
| </Directory> |
| </highlight> |
| |
| <p>the regular expression section won't be considered until after |
| all normal <directive type="section">Directory</directive>s and |
| <code>.htaccess</code> files have been applied. Then the regular |
| expression will match on <code>/home/abc/public_html/abc</code> and |
| the corresponding <directive type="section">Directory</directive> will |
| be applied.</p> |
| |
| <p><strong>Note that the default access for |
| <code><Directory "/"></code> is to permit all access. |
| This means that Apache httpd will serve any file mapped from an URL. It is |
| recommended that you change this with a block such |
| as</strong></p> |
| |
| <highlight language="config"> |
| <Directory "/"> |
| Require all denied |
| </Directory> |
| </highlight> |
| |
| <p><strong>and then override this for directories you |
| <em>want</em> accessible. See the <a |
| href="../misc/security_tips.html">Security Tips</a> page for more |
| details.</strong></p> |
| |
| <p>The directory sections occur in the <code>httpd.conf</code> file. |
| <directive type="section">Directory</directive> directives |
| cannot nest, and cannot appear in a <directive module="core" |
| type="section">Limit</directive> or <directive module="core" |
| type="section">LimitExcept</directive> section.</p> |
| </usage> |
| <seealso><a href="../sections.html">How <Directory>, |
| <Location> and <Files> sections work</a> for an |
| explanation of how these different sections are combined when a |
| request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>DirectoryMatch</name> |
| <description>Enclose directives that apply to |
| the contents of file-system directories matching a regular expression.</description> |
| <syntax><DirectoryMatch <var>regex</var>> |
| ... </DirectoryMatch></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p><directive type="section">DirectoryMatch</directive> and |
| <code></DirectoryMatch></code> are used to enclose a group |
| of directives which will apply only to the named directory (and the files within), |
| the same as <directive module="core" type="section">Directory</directive>. |
| However, it takes as an argument a |
| <glossary ref="regex">regular expression</glossary>. For example:</p> |
| |
| <highlight language="config"> |
| <DirectoryMatch "^/www/(.+/)?[0-9]{3}/"> |
| # ... |
| </DirectoryMatch> |
| </highlight> |
| |
| <p>matches directories in <code>/www/</code> (or any subdirectory thereof) |
| that consist of three numbers.</p> |
| |
| <note><title>Compatibility</title> |
| Prior to 2.3.9, this directive implicitly applied to sub-directories |
| (like <directive module="core" type="section">Directory</directive>) and |
| could not match the end of line symbol ($). In 2.3.9 and later, |
| only directories that match the expression are affected by the enclosed |
| directives. |
| </note> |
| |
| <note><title>Trailing Slash</title> |
| This directive applies to requests for directories that may or may |
| not end in a trailing slash, so expressions that are anchored to the |
| end of line ($) must be written with care. |
| </note> |
| |
| <p>From 2.4.8 onwards, named groups and backreferences are captured and |
| written to the environment with the corresponding name prefixed with |
| "MATCH_" and in upper case. This allows elements of paths to be referenced |
| from within <a href="../expr.html">expressions</a> and modules like |
| <module>mod_rewrite</module>. In order to prevent confusion, numbered |
| (unnamed) backreferences are ignored. Use named groups instead.</p> |
| |
| <highlight language="config"> |
| <DirectoryMatch "^/var/www/combined/(?<sitename>[^/]+)"> |
| Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example |
| </DirectoryMatch> |
| </highlight> |
| </usage> |
| <seealso><directive type="section" module="core">Directory</directive> for |
| a description of how regular expressions are mixed in with normal |
| <directive type="section">Directory</directive>s</seealso> |
| <seealso><a |
| href="../sections.html">How <Directory>, <Location> and |
| <Files> sections work</a> for an explanation of how these different |
| sections are combined when a request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DocumentRoot</name> |
| <description>Directory that forms the main document tree visible |
| from the web</description> |
| <syntax>DocumentRoot <var>directory-path</var></syntax> |
| <default>DocumentRoot "/usr/local/apache/htdocs"</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>This directive sets the directory from which <program>httpd</program> |
| will serve files. Unless matched by a directive like <directive |
| module="mod_alias">Alias</directive>, the server appends the |
| path from the requested URL to the document root to make the |
| path to the document. Example:</p> |
| |
| <highlight language="config"> |
| DocumentRoot "/usr/web" |
| </highlight> |
| |
| <p>then an access to |
| <code>http://my.example.com/index.html</code> refers to |
| <code>/usr/web/index.html</code>. If the <var>directory-path</var> is |
| not absolute then it is assumed to be relative to the <directive |
| module="core">ServerRoot</directive>.</p> |
| |
| <p>The <directive>DocumentRoot</directive> should be specified without |
| a trailing slash.</p> |
| </usage> |
| <seealso><a href="../urlmapping.html#documentroot">Mapping URLs to Filesystem |
| Locations</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Else</name> |
| <description>Contains directives that apply only if the condition of a |
| previous <directive type="section" module="core">If</directive> or |
| <directive type="section" module="core">ElseIf</directive> section is not |
| satisfied by a request at runtime</description> |
| <syntax><Else> ... </Else></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Nested conditions are evaluated in 2.4.26 and later</compatibility> |
| |
| <usage> |
| <p>The <directive type="section">Else</directive> applies the enclosed |
| directives if and only if the most recent |
| <directive type="section">If</directive> or |
| <directive type="section">ElseIf</directive> section |
| in the same scope has not been applied. |
| For example: In </p> |
| |
| <highlight language="config"> |
| <If "-z req('Host')"> |
| # ... |
| </If> |
| <Else> |
| # ... |
| </Else> |
| </highlight> |
| |
| <p> The <directive type="section">If</directive> would match HTTP/1.0 |
| requests without a <var>Host:</var> header and the |
| <directive type="section">Else</directive> would match requests |
| with a <var>Host:</var> header.</p> |
| |
| </usage> |
| <seealso><directive type="section" module="core">If</directive></seealso> |
| <seealso><directive type="section" module="core">ElseIf</directive></seealso> |
| <seealso><a href="../sections.html">How <Directory>, <Location>, |
| <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received. |
| <directive type="section">If</directive>, |
| <directive type="section">ElseIf</directive>, and |
| <directive type="section">Else</directive> are applied last.</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>ElseIf</name> |
| <description>Contains directives that apply only if a condition is satisfied |
| by a request at runtime while the condition of a previous |
| <directive type="section" module="core">If</directive> or |
| <directive type="section">ElseIf</directive> section is not |
| satisfied</description> |
| <syntax><ElseIf <var>expression</var>> ... </ElseIf></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Nested conditions are evaluated in 2.4.26 and later</compatibility> |
| |
| <usage> |
| <p>The <directive type="section">ElseIf</directive> applies the enclosed |
| directives if and only if both the given condition evaluates to true and |
| the most recent <directive type="section">If</directive> or |
| <directive type="section">ElseIf</directive> section in the same scope has |
| not been applied. For example: In </p> |
| |
| <highlight language="config"> |
| <If "-R '10.1.0.0/16'"> |
| #... |
| </If> |
| <ElseIf "-R '10.0.0.0/8'"> |
| #... |
| </ElseIf> |
| <Else> |
| #... |
| </Else> |
| </highlight> |
| |
| <p>The <directive type="section">ElseIf</directive> would match if |
| the remote address of a request belongs to the subnet 10.0.0.0/8 but |
| not to the subnet 10.1.0.0/16.</p> |
| |
| </usage> |
| <seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>, |
| for a complete reference and more examples.</seealso> |
| <seealso><directive type="section" module="core">If</directive></seealso> |
| <seealso><directive type="section" module="core">Else</directive></seealso> |
| <seealso><a href="../sections.html">How <Directory>, <Location>, |
| <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received. |
| <directive type="section">If</directive>, |
| <directive type="section">ElseIf</directive>, and |
| <directive type="section">Else</directive> are applied last.</seealso> |
| </directivesynopsis> |
| |
| |
| |
| <directivesynopsis> |
| <name>EnableMMAP</name> |
| <description>Use memory-mapping to read files during delivery</description> |
| <syntax>EnableMMAP On|Off</syntax> |
| <default>EnableMMAP On</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>This directive controls whether the <program>httpd</program> may use |
| memory-mapping if it needs to read the contents of a file during |
| delivery. By default, when the handling of a request requires |
| access to the data within a file -- for example, when delivering a |
| server-parsed file using <module>mod_include</module> -- Apache httpd |
| memory-maps the file if the OS supports it.</p> |
| |
| <p>This memory-mapping sometimes yields a performance improvement. |
| But in some environments, it is better to disable the memory-mapping |
| to prevent operational problems:</p> |
| |
| <ul> |
| <li>On some multiprocessor systems, memory-mapping can reduce the |
| performance of the <program>httpd</program>.</li> |
| <li>Deleting or truncating a file while <program>httpd</program> |
| has it memory-mapped can cause <program>httpd</program> to |
| crash with a segmentation fault. |
| </li> |
| </ul> |
| |
| <p>For server configurations that are vulnerable to these problems, |
| you should disable memory-mapping of delivered files by specifying:</p> |
| |
| <highlight language="config"> |
| EnableMMAP Off |
| </highlight> |
| |
| <p>For NFS mounted files, this feature may be disabled explicitly for |
| the offending files by specifying:</p> |
| |
| <highlight language="config"> |
| <Directory "/path-to-nfs-files"> |
| EnableMMAP Off |
| </Directory> |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>EnableSendfile</name> |
| <description>Use the kernel sendfile support to deliver files to the client</description> |
| <syntax>EnableSendfile On|Off</syntax> |
| <default>EnableSendfile Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>Default changed to Off in |
| version 2.3.9.</compatibility> |
| |
| <usage> |
| <p>This directive controls whether <program>httpd</program> may use the |
| sendfile support from the kernel to transmit file contents to the client. |
| By default, when the handling of a request requires no access |
| to the data within a file -- for example, when delivering a |
| static file -- Apache httpd uses sendfile to deliver the file contents |
| without ever reading the file if the OS supports it.</p> |
| |
| <p>This sendfile mechanism avoids separate read and send operations, |
| and buffer allocations. But on some platforms or within some |
| filesystems, it is better to disable this feature to avoid |
| operational problems:</p> |
| |
| <ul> |
| <li>Some platforms may have broken sendfile support that the build |
| system did not detect, especially if the binaries were built on |
| another box and moved to such a machine with broken sendfile |
| support.</li> |
| <li>On Linux the use of sendfile triggers TCP-checksum |
| offloading bugs on certain networking cards when using IPv6.</li> |
| <li>On Linux on Itanium, <code>sendfile</code> may be unable to handle |
| files over 2GB in size.</li> |
| <li>With a network-mounted <directive |
| module="core">DocumentRoot</directive> (e.g., NFS, SMB, CIFS, FUSE), |
| the kernel may be unable to serve the network file through |
| its own cache.</li> |
| </ul> |
| |
| <p>For server configurations that are not vulnerable to these problems, |
| you may enable this feature by specifying:</p> |
| |
| <highlight language="config"> |
| EnableSendfile On |
| </highlight> |
| |
| <p>For network mounted files, this feature may be disabled explicitly |
| for the offending files by specifying:</p> |
| |
| <highlight language="config"> |
| <Directory "/path-to-nfs-files"> |
| EnableSendfile Off |
| </Directory> |
| </highlight> |
| <p>Please note that the per-directory and .htaccess configuration |
| of <directive>EnableSendfile</directive> is not supported by |
| <module>mod_cache_disk</module>. |
| Only global definition of <directive>EnableSendfile</directive> |
| is taken into account by the module. |
| </p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>HttpProtocolOptions</name> |
| <description>Modify restrictions on HTTP Request Messages</description> |
| <syntax>HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] |
| [Allow0.9|Require1.0]</syntax> |
| <default>HttpProtocolOptions Strict LenientMethods Allow0.9</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context></contextlist> |
| <compatibility>2.2.32 or 2.4.24 and later</compatibility> |
| |
| <usage> |
| <p>This directive changes the rules applied to the HTTP Request Line |
| (<a href="https://tools.ietf.org/html/rfc7230#section-3.1.1" |
| >RFC 7230 §3.1.1</a>) and the HTTP Request Header Fields |
| (<a href="https://tools.ietf.org/html/rfc7230#section-3.2" |
| >RFC 7230 §3.2</a>), which are now applied by default or using |
| the <code>Strict</code> option. Due to legacy modules, applications or |
| custom user-agents which must be deprecated the <code>Unsafe</code> |
| option has been added to revert to the legacy behaviors.</p> |
| |
| <p>These rules are applied prior to request processing, |
| so must be configured at the global or default (first) matching |
| virtual host section, by IP/port interface (and not by name) |
| to be honored.</p> |
| |
| <p>The directive accepts three parameters from the following list |
| of choices, applying the default to the ones not specified:</p> |
| |
| <dl> |
| <dt>Strict|Unsafe</dt> |
| <dd> |
| <p>Prior to the introduction of this directive, the Apache HTTP Server |
| request message parsers were tolerant of a number of forms of input |
| which did not conform to the protocol. |
| <a href="https://tools.ietf.org/html/rfc7230#section-9.4" |
| >RFC 7230 §9.4 Request Splitting</a> and |
| <a href="https://tools.ietf.org/html/rfc7230#section-9.5" |
| >§9.5 Response Smuggling</a> call out only two of the potential |
| risks of accepting non-conformant request messages, while |
| <a href="https://tools.ietf.org/html/rfc7230#section-3.5" |
| >RFC 7230 §3.5</a> "Message Parsing Robustness" identify the |
| risks of accepting obscure whitespace and request message formatting. |
| As of the introduction of this directive, all grammar rules of the |
| specification are enforced in the default <code>Strict</code> operating |
| mode, and the strict whitespace suggested by section 3.5 is enforced |
| and cannot be relaxed.</p> |
| |
| <note type="warning"><title>Security risks of Unsafe</title> |
| <p>Users are strongly cautioned against toggling the <code>Unsafe</code> |
| mode of operation, particularly on outward-facing, publicly accessible |
| server deployments. If an interface is required for faulty monitoring |
| or other custom service consumers running on an intranet, users should |
| toggle the Unsafe option only on a specific virtual host configured |
| to service their internal private network.</p> |
| </note> |
| |
| <example> |
| <title>Example of a request leading to HTTP 400 with Strict mode</title> |
| # Missing CRLF<br /> |
| GET / HTTP/1.0\n\n |
| </example> |
| <note type="warning"><title>Command line tools and CRLF</title> |
| <p>Some tools need to be forced to use CRLF, otherwise httpd will return |
| a HTTP 400 response like described in the above use case. For example, |
| the <strong>OpenSSL s_client needs the -crlf parameter to work |
| properly</strong>.</p> |
| <p>The <directive module="mod_dumpio">DumpIOInput</directive> directive |
| can help while reviewing the HTTP request to identify issues like the |
| absence of CRLF.</p> |
| </note> |
| </dd> |
| <dt>RegisteredMethods|LenientMethods</dt> |
| <dd> |
| <p><a href="https://tools.ietf.org/html/rfc7231#section-4.1" |
| >RFC 7231 §4.1</a> "Request Methods" "Overview" requires that |
| origin servers shall respond with a HTTP 501 status code when an |
| unsupported method is encountered in the request line. |
| This already happens when the <code>LenientMethods</code> option is used, |
| but administrators may wish to toggle the <code>RegisteredMethods</code> |
| option and register any non-standard methods using the |
| <directive module="core">RegisterHttpMethod</directive> |
| directive, particularly if the <code>Unsafe</code> |
| option has been toggled.</p> |
| |
| <note type="warning"><title>Forward Proxy compatibility</title> |
| <p>The <code>RegisteredMethods</code> option should <strong>not</strong> |
| be toggled for forward proxy hosts, as the methods supported by the |
| origin servers are unknown to the proxy server.</p> |
| </note> |
| |
| <example> |
| <title>Example of a request leading to HTTP 501 with LenientMethods mode</title> |
| # Unknown HTTP method<br /> |
| WOW / HTTP/1.0\r\n\r\n<br /><br /> |
| # Lowercase HTTP method<br /> |
| get / HTTP/1.0\r\n\r\n<br /> |
| </example> |
| </dd> |
| <dt>Allow0.9|Require1.0</dt> |
| <dd> |
| <p><a href="https://tools.ietf.org/html/rfc2616#section-19.6" |
| >RFC 2616 §19.6</a> "Compatibility With Previous Versions" had |
| encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230 |
| supersedes this with "The expectation to support HTTP/0.9 requests has |
| been removed" and offers additional comments in |
| <a href="https://tools.ietf.org/html/rfc7230#appendix-A" |
| >RFC 7230 Appendix A</a>. The <code>Require1.0</code> option allows |
| the user to remove support of the default <code>Allow0.9</code> option's |
| behavior.</p> |
| |
| <example> |
| <title>Example of a request leading to HTTP 400 with Require1.0 mode</title> |
| # Unsupported HTTP version<br /> |
| GET /\r\n\r\n |
| </example> |
| </dd> |
| </dl> |
| <p>Reviewing the messages logged to the |
| <directive module="core">ErrorLog</directive>, configured with |
| <directive module="core">LogLevel</directive> <code>debug</code> level, |
| can help identify such faulty requests along with their origin. |
| Users should pay particular attention to the 400 responses in the access |
| log for invalid requests which were unexpectedly rejected.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Error</name> |
| <description>Abort configuration parsing with a custom error message</description> |
| <syntax>Error <var>message</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <compatibility>2.3.9 and later</compatibility> |
| |
| <usage> |
| <p>If an error can be detected within the configuration, this |
| directive can be used to generate a custom error message, and halt |
| configuration parsing. The typical use is for reporting required |
| modules which are missing from the configuration.</p> |
| |
| <highlight language="config"> |
| # Example |
| # ensure that mod_include is loaded |
| <IfModule !include_module> |
| Error "mod_include is required by mod_foo. Load it with LoadModule." |
| </IfModule> |
| |
| # ensure that exactly one of SSL,NOSSL is defined |
| <IfDefine SSL> |
| <IfDefine NOSSL> |
| Error "Both SSL and NOSSL are defined. Define only one of them." |
| </IfDefine> |
| </IfDefine> |
| <IfDefine !SSL> |
| <IfDefine !NOSSL> |
| Error "Either SSL or NOSSL must be defined." |
| </IfDefine> |
| </IfDefine> |
| </highlight> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ErrorDocument</name> |
| <description>What the server will return to the client |
| in case of an error</description> |
| <syntax>ErrorDocument <var>error-code</var> <var>document</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>In the event of a problem or error, Apache httpd can be configured |
| to do one of four things,</p> |
| |
| <ol> |
| <li>output a simple hardcoded error message</li> |
| |
| <li>output a customized message</li> |
| |
| <li>internally redirect to a local <var>URL-path</var> to handle the |
| problem/error</li> |
| |
| <li>redirect to an external <var>URL</var> to handle the |
| problem/error</li> |
| </ol> |
| |
| <p>The first option is the default, while options 2-4 are |
| configured using the <directive>ErrorDocument</directive> |
| directive, which is followed by the HTTP response code and a URL |
| or a message. Apache httpd will sometimes offer additional information |
| regarding the problem/error.</p> |
| |
| <p>From 2.4.13, <a href="../expr.html">expression syntax</a> can be |
| used inside the directive to produce dynamic strings and URLs.</p> |
| |
| <p>URLs can begin with a slash (/) for local web-paths (relative |
| to the <directive module="core">DocumentRoot</directive>), or be a |
| full URL which the client can resolve. Alternatively, a message |
| can be provided to be displayed by the browser. Note that deciding |
| whether the parameter is an URL, a path or a message is performed |
| before any expression is parsed. Examples:</p> |
| |
| <highlight language="config"> |
| ErrorDocument 500 http://example.com/cgi-bin/server-error.cgi |
| ErrorDocument 404 /errors/bad_urls.php |
| ErrorDocument 401 /subscription_info.html |
| ErrorDocument 403 "Sorry, can't allow you access today" |
| ErrorDocument 403 Forbidden! |
| ErrorDocument 403 /errors/forbidden.py?referrer=%{escape:%{HTTP_REFERER}} |
| </highlight> |
| |
| <p>Additionally, the special value <code>default</code> can be used |
| to specify Apache httpd's simple hardcoded message. While not required |
| under normal circumstances, <code>default</code> will restore |
| Apache httpd's simple hardcoded message for configurations that would |
| otherwise inherit an existing <directive>ErrorDocument</directive>.</p> |
| |
| <highlight language="config"> |
| ErrorDocument 404 /cgi-bin/bad_urls.pl |
| |
| <Directory "/web/docs"> |
| ErrorDocument 404 default |
| </Directory> |
| </highlight> |
| |
| <p>Note that when you specify an <directive>ErrorDocument</directive> |
| that points to a remote URL (ie. anything with a method such as |
| <code>http</code> in front of it), Apache HTTP Server will send a redirect to the |
| client to tell it where to find the document, even if the |
| document ends up being on the same server. This has several |
| implications, the most important being that the client will not |
| receive the original error status code, but instead will |
| receive a redirect status code. This in turn can confuse web |
| robots and other clients which try to determine if a URL is |
| valid using the status code. In addition, if you use a remote |
| URL in an <code>ErrorDocument 401</code>, the client will not |
| know to prompt the user for a password since it will not |
| receive the 401 status code. Therefore, <strong>if you use an |
| <code>ErrorDocument 401</code> directive, then it must refer to a local |
| document.</strong></p> |
| |
| <p>Microsoft Internet Explorer (MSIE) will by default ignore |
| server-generated error messages when they are "too small" and substitute |
| its own "friendly" error messages. The size threshold varies depending on |
| the type of error, but in general, if you make your error document |
| greater than 512 bytes, then MSIE will show the server-generated |
| error rather than masking it. More information is available in |
| Microsoft Knowledge Base article <a |
| href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q294807" |
| >Q294807</a>.</p> |
| |
| <p>Although most error messages can be overridden, there are certain |
| circumstances where the internal messages are used regardless of the |
| setting of <directive module="core">ErrorDocument</directive>. In |
| particular, if a malformed request is detected, normal request processing |
| will be immediately halted and the internal error message returned. |
| This is necessary to guard against security problems caused by |
| bad requests.</p> |
| |
| <p>If you are using mod_proxy, you may wish to enable |
| <directive module="mod_proxy">ProxyErrorOverride</directive> so that you can provide |
| custom error messages on behalf of your Origin servers. If you don't enable ProxyErrorOverride, |
| Apache httpd will not generate custom error documents for proxied content.</p> |
| </usage> |
| |
| <seealso><a href="../custom-error.html">documentation of |
| customizable responses</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ErrorLog</name> |
| <description>Location where the server will log errors</description> |
| <syntax> ErrorLog <var>file-path</var>|syslog[:[<var>facility</var>][:<var>tag</var>]]</syntax> |
| <default>ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ErrorLog</directive> directive sets the name of |
| the file to which the server will log any errors it encounters. If |
| the <var>file-path</var> is not absolute then it is assumed to be |
| relative to the <directive module="core">ServerRoot</directive>.</p> |
| |
| <highlight language="config"> |
| ErrorLog "/var/log/httpd/error_log" |
| </highlight> |
| |
| <p>If the <var>file-path</var> |
| begins with a pipe character "<code>|</code>" then it is assumed to be a |
| command to spawn to handle the error log.</p> |
| |
| <highlight language="config"> |
| ErrorLog "|/usr/local/bin/httpd_errors" |
| </highlight> |
| |
| <p>See the notes on <a href="../logs.html#piped">piped logs</a> for |
| more information.</p> |
| |
| <p>Using <code>syslog</code> instead of a filename enables logging |
| via syslogd(8) if the system supports it. The default is to use |
| syslog facility <code>local7</code>, but you can override this by |
| using the <code>syslog:<var>facility</var></code> syntax where |
| <var>facility</var> can be one of the names usually documented in |
| syslog(1). The facility is effectively global, and if it is changed |
| in individual virtual hosts, the final facility specified affects the |
| entire server. Same rules apply for the syslog tag, which by default |
| uses the Apache binary name, <code>httpd</code> in most cases. You can |
| also override this by using the <code>syslog::<var>tag</var></code> |
| syntax.</p> |
| |
| <highlight language="config"> |
| ErrorLog syslog:user |
| ErrorLog syslog:user:httpd.srv1 |
| ErrorLog syslog::httpd.srv2 |
| </highlight> |
| |
| <p>Additional modules can provide their own ErrorLog providers. The syntax |
| is similar to the <code>syslog</code> example above.</p> |
| |
| <p>SECURITY: See the <a |
| href="../misc/security_tips.html#serverroot">security tips</a> |
| document for details on why your security could be compromised |
| if the directory where log files are stored is writable by |
| anyone other than the user that starts the server.</p> |
| <note type="warning"><title>Note</title> |
| <p>When entering a file path on non-Unix platforms, care should be taken |
| to make sure that only forward slashes are used even though the platform |
| may allow the use of back slashes. In general it is a good idea to always |
| use forward slashes throughout the configuration files.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">LogLevel</directive></seealso> |
| <seealso><a href="../logs.html">Apache HTTP Server Log Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ErrorLogFormat</name> |
| <description>Format specification for error log entries</description> |
| <syntax> ErrorLogFormat [connection|request] <var>format</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p><directive>ErrorLogFormat</directive> allows to specify what |
| supplementary information is logged in the error log in addition to the |
| actual log message.</p> |
| |
| <highlight language="config"> |
| #Simple example |
| ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M" |
| </highlight> |
| |
| <p>Specifying <code>connection</code> or <code>request</code> as first |
| parameter allows to specify additional formats, causing additional |
| information to be logged when the first message is logged for a specific |
| connection or request, respectively. This additional information is only |
| logged once per connection/request. If a connection or request is processed |
| without causing any log message, the additional information is not logged |
| either.</p> |
| |
| <p>It can happen that some format string items do not produce output. For |
| example, the Referer header is only present if the log message is |
| associated to a request and the log message happens at a time when the |
| Referer header has already been read from the client. If no output is |
| produced, the default behavior is to delete everything from the preceding |
| space character to the next space character. This means the log line is |
| implicitly divided into fields on non-whitespace to whitespace transitions. |
| If a format string item does not produce output, the whole field is |
| omitted. For example, if the remote address <code>%a</code> in the log |
| format <code>[%t] [%l] [%a] %M </code> is not available, the surrounding |
| brackets are not logged either. Space characters can be escaped with a |
| backslash to prevent them from delimiting a field. The combination '% ' |
| (percent space) is a zero-width field delimiter that does not produce any |
| output.</p> |
| |
| <p>The above behavior can be changed by adding modifiers to the format |
| string item. A <code>-</code> (minus) modifier causes a minus to be logged if the |
| respective item does not produce any output. In once-per-connection/request |
| formats, it is also possible to use the <code>+</code> (plus) modifier. If an |
| item with the plus modifier does not produce any output, the whole line is |
| omitted.</p> |
| |
| <p>A number as modifier can be used to assign a log severity level to a |
| format item. The item will only be logged if the severity of the log |
| message is not higher than the specified log severity level. The number can |
| range from 1 (alert) over 4 (warn) and 7 (debug) to 15 (trace8).</p> |
| |
| <p>For example, here's what would happen if you added modifiers to |
| the <code>%{Referer}i</code> token, which logs the |
| <code>Referer</code> request header.</p> |
| |
| <table border="1" style="zebra"> |
| <columnspec><column width=".3"/><column width=".7"/></columnspec> |
| |
| <tr><th>Modified Token</th><th>Meaning</th></tr> |
| |
| <tr> |
| <td><code>%-{Referer}i</code></td> |
| <td>Logs a <code>-</code> if <code>Referer</code> is not set.</td> |
| </tr> |
| |
| <tr> |
| <td><code>%+{Referer}i</code></td> |
| <td>Omits the entire line if <code>Referer</code> is not set.</td> |
| </tr> |
| |
| <tr> |
| <td><code>%4{Referer}i</code></td> |
| <td>Logs the <code>Referer</code> only if the log message severity |
| is higher than 4.</td> |
| </tr> |
| |
| </table> |
| |
| <p>Some format string items accept additional parameters in braces.</p> |
| |
| <table border="1" style="zebra"> |
| <columnspec><column width=".2"/><column width=".8"/></columnspec> |
| |
| <tr><th>Format String</th> <th>Description</th></tr> |
| |
| <tr><td><code>%%</code></td> |
| <td>The percent sign</td></tr> |
| |
| <tr><td><code>%a</code></td> |
| <td>Client IP address and port of the request</td></tr> |
| |
| <tr><td><code>%{c}a</code></td> |
| <td>Underlying peer IP address and port of the connection (see the |
| <module>mod_remoteip</module> module)</td></tr> |
| |
| <tr><td><code>%A</code></td> |
| <td>Local IP-address and port</td></tr> |
| |
| <tr><td><code>%{<em>name</em>}e</code></td> |
| <td>Request environment variable <em>name</em></td></tr> |
| |
| <tr><td><code>%E</code></td> |
| <td>APR/OS error status code and string</td></tr> |
| |
| <tr><td><code>%F</code></td> |
| <td>Source file name and line number of the log call</td></tr> |
| |
| <tr><td><code>%{<em>name</em>}i</code></td> |
| <td>Request header <em>name</em></td></tr> |
| |
| <tr><td><code>%k</code></td> |
| <td>Number of keep-alive requests on this connection</td></tr> |
| |
| <tr><td><code>%l</code></td> |
| <td>Loglevel of the message</td></tr> |
| |
| <tr><td><code>%L</code></td> |
| <td>Log ID of the request</td></tr> |
| |
| <tr><td><code>%{c}L</code></td> |
| <td>Log ID of the connection</td></tr> |
| |
| <tr><td><code>%{C}L</code></td> |
| <td>Log ID of the connection if used in connection scope, empty otherwise</td></tr> |
| |
| <tr><td><code>%m</code></td> |
| <td>Name of the module logging the message</td></tr> |
| |
| <tr><td><code>%M</code></td> |
| <td>The actual log message</td></tr> |
| |
| <tr><td><code>%{<em>name</em>}n</code></td> |
| <td>Request note <em>name</em></td></tr> |
| |
| <tr><td><code>%P</code></td> |
| <td>Process ID of current process</td></tr> |
| |
| <tr><td><code>%T</code></td> |
| <td>Thread ID of current thread</td></tr> |
| |
| <tr><td><code>%{g}T</code></td> |
| <td>System unique thread ID of current thread (the same ID as |
| displayed by e.g. <code>top</code>; currently Linux only)</td></tr> |
| |
| <tr><td><code>%t</code></td> |
| <td>The current time</td></tr> |
| |
| <tr><td><code>%{u}t</code></td> |
| <td>The current time including micro-seconds</td></tr> |
| |
| <tr><td><code>%{cu}t</code></td> |
| <td>The current time in compact ISO 8601 format, including |
| micro-seconds</td></tr> |
| |
| <tr><td><code>%v</code></td> |
| <td>The canonical <directive module="core">ServerName</directive> |
| of the current server.</td></tr> |
| |
| <tr><td><code>%V</code></td> |
| <td>The server name of the server serving the request according to the |
| <directive module="core" >UseCanonicalName</directive> |
| setting.</td></tr> |
| |
| <tr><td><code>\ </code> (backslash space)</td> |
| <td>Non-field delimiting space</td></tr> |
| |
| <tr><td><code>% </code> (percent space)</td> |
| <td>Field delimiter (no output)</td></tr> |
| </table> |
| |
| <p>The log ID format <code>%L</code> produces a unique id for a connection |
| or request. This can be used to correlate which log lines belong to the |
| same connection or request, which request happens on which connection. |
| A <code>%L</code> format string is also available in |
| <module>mod_log_config</module> to allow to correlate access log entries |
| with error log lines. If <module>mod_unique_id</module> is loaded, its |
| unique id will be used as log ID for requests.</p> |
| |
| <highlight language="config"> |
| #Example (default format for threaded MPMs) |
| ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P:tid %T] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i" |
| </highlight> |
| |
| <p>This would result in error messages such as:</p> |
| |
| <example> |
| [Thu May 12 08:28:57.652118 2011] [core:error] [pid 8777:tid 4326490112] [client ::1:58619] File does not exist: /usr/local/apache2/htdocs/favicon.ico |
| </example> |
| |
| <p>Notice that, as discussed above, some fields are omitted |
| entirely because they are not defined.</p> |
| |
| <highlight language="config"> |
| #Example (similar to the 2.2.x format) |
| ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i" |
| </highlight> |
| |
| <highlight language="config"> |
| #Advanced example with request/connection log IDs |
| ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M" |
| ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T" |
| ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'" |
| ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'" |
| ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A" |
| </highlight> |
| |
| </usage> |
| <seealso><directive module="core">ErrorLog</directive></seealso> |
| <seealso><directive module="core">LogLevel</directive></seealso> |
| <seealso><a href="../logs.html">Apache HTTP Server Log Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ExtendedStatus</name> |
| <description>Keep track of extended status information for each |
| request</description> |
| <syntax>ExtendedStatus On|Off</syntax> |
| <default>ExtendedStatus Off[*]</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This option tracks additional data per worker about the |
| currently executing request and creates a utilization summary. |
| You can see these variables during runtime by configuring |
| <module>mod_status</module>. Note that other modules may |
| rely on this scoreboard.</p> |
| |
| <p>This setting applies to the entire server and cannot be |
| enabled or disabled on a virtualhost-by-virtualhost basis. |
| The collection of extended status information can slow down |
| the server. Also note that this setting cannot be changed |
| during a graceful restart.</p> |
| |
| <note> |
| <p>Note that loading <module>mod_status</module> will change |
| the default behavior to ExtendedStatus On, while other |
| third party modules may do the same. Such modules rely on |
| collecting detailed information about the state of all workers. |
| The default is changed by <module>mod_status</module> beginning |
| with version 2.3.6. The previous default was always Off.</p> |
| </note> |
| |
| </usage> |
| |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>FileETag</name> |
| <description>File attributes used to create the ETag |
| HTTP response header for static files</description> |
| <syntax>FileETag <var>component</var> ...</syntax> |
| <default>FileETag MTime Size</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>The default used to be "INode MTime Size" in 2.3.14 and |
| earlier.</compatibility> |
| |
| <usage> |
| <p> |
| The <directive>FileETag</directive> directive configures the file |
| attributes that are used to create the <code>ETag</code> (entity |
| tag) response header field when the document is based on a static file. |
| (The <code>ETag</code> value is used in cache management to save |
| network bandwidth.) The |
| <directive>FileETag</directive> directive allows you to choose |
| which of these -- if any -- should be used. The recognized keywords are: |
| </p> |
| |
| <dl> |
| <dt><strong>INode</strong></dt> |
| <dd>The file's i-node number will be included in the calculation</dd> |
| <dt><strong>MTime</strong></dt> |
| <dd>The date and time the file was last modified will be included</dd> |
| <dt><strong>Size</strong></dt> |
| <dd>The number of bytes in the file will be included</dd> |
| <dt><strong>All</strong></dt> |
| <dd>All available fields will be used. This is equivalent to: |
| <highlight language="config"> |
| FileETag INode MTime Size |
| </highlight></dd> |
| <dt><strong>None</strong></dt> |
| <dd>If a document is file-based, no <code>ETag</code> field will be |
| included in the response</dd> |
| </dl> |
| |
| <p>The <code>INode</code>, <code>MTime</code>, and <code>Size</code> |
| keywords may be prefixed with either <code>+</code> or <code>-</code>, |
| which allow changes to be made to the default setting inherited |
| from a broader scope. Any keyword appearing without such a prefix |
| immediately and completely cancels the inherited setting.</p> |
| |
| <p>If a directory's configuration includes |
| <code>FileETag INode MTime Size</code>, and a |
| subdirectory's includes <code>FileETag -INode</code>, |
| the setting for that subdirectory (which will be inherited by |
| any sub-subdirectories that don't override it) will be equivalent to |
| <code>FileETag MTime Size</code>.</p> |
| <note type="warning"><title>Warning</title> |
| Do not change the default for directories or locations that have WebDAV |
| enabled and use <module>mod_dav_fs</module> as a storage provider. |
| <module>mod_dav_fs</module> uses <code>MTime Size</code> |
| as a fixed format for <code>ETag</code> comparisons on conditional requests. |
| These conditional requests will break if the <code>ETag</code> format is |
| changed via <directive>FileETag</directive>. |
| </note> |
| <note><title>Server Side Includes</title> |
| An ETag is not generated for responses parsed by <module>mod_include</module> |
| since the response entity can change without a change of the INode, MTime, or Size |
| of the static file with embedded SSI directives. |
| </note> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Files</name> |
| <description>Contains directives that apply to matched |
| filenames</description> |
| <syntax><Files <var>filename</var>> ... </Files></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive type="section">Files</directive> directive |
| limits the scope of the enclosed directives by filename. It is comparable |
| to the <directive module="core" type="section">Directory</directive> |
| and <directive module="core" type="section">Location</directive> |
| directives. It should be matched with a <code></Files></code> |
| directive. The directives given within this section will be applied to |
| any object with a basename (last component of filename) matching the |
| specified filename. <directive type="section">Files</directive> |
| sections are processed in the order they appear in the |
| configuration file, after the <directive module="core" |
| type="section">Directory</directive> sections and |
| <code>.htaccess</code> files are read, but before <directive |
| type="section" module="core">Location</directive> sections. Note |
| that <directive type="section">Files</directive> can be nested |
| inside <directive type="section" |
| module="core">Directory</directive> sections to restrict the |
| portion of the filesystem they apply to.</p> |
| |
| <p>The <var>filename</var> argument should include a filename, or |
| a wild-card string, where <code>?</code> matches any single character, |
| and <code>*</code> matches any sequences of characters.</p> |
| <highlight language="config"> |
| <Files "cat.html"> |
| # Insert stuff that applies to cat.html here |
| </Files> |
| |
| <Files "?at.*"> |
| # This would apply to cat.html, bat.html, hat.php and so on. |
| </Files> |
| </highlight> |
| <p><glossary ref="regex">Regular expressions</glossary> |
| can also be used, with the addition of the |
| <code>~</code> character. For example:</p> |
| |
| <highlight language="config"> |
| <Files ~ "\.(gif|jpe?g|png)$"> |
| #... |
| </Files> |
| </highlight> |
| |
| <p>would match most common Internet graphics formats. <directive |
| module="core" type="section">FilesMatch</directive> is preferred, |
| however.</p> |
| |
| <p>Note that unlike <directive type="section" |
| module="core">Directory</directive> and <directive type="section" |
| module="core">Location</directive> sections, <directive |
| type="section">Files</directive> sections can be used inside |
| <code>.htaccess</code> files. This allows users to control access to |
| their own files, at a file-by-file level.</p> |
| |
| </usage> |
| <seealso><a href="../sections.html">How <Directory>, <Location> |
| and <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>FilesMatch</name> |
| <description>Contains directives that apply to regular-expression matched |
| filenames</description> |
| <syntax><FilesMatch <var>regex</var>> ... </FilesMatch></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive type="section">FilesMatch</directive> directive |
| limits the scope of the enclosed directives by filename, just as the |
| <directive module="core" type="section">Files</directive> directive |
| does. However, it accepts a <glossary ref="regex">regular |
| expression</glossary>. For example:</p> |
| |
| <highlight language="config"> |
| <FilesMatch ".+\.(gif|jpe?g|png)$"> |
| # ... |
| </FilesMatch> |
| </highlight> |
| |
| <p>would match most common Internet graphics formats.</p> |
| |
| <note>The <code>.+</code> at the start of the regex ensures that |
| files named <code>.png</code>, or <code>.gif</code>, for example, |
| are not matched.</note> |
| |
| <p>From 2.4.8 onwards, named groups and backreferences are captured and |
| written to the environment with the corresponding name prefixed with |
| "MATCH_" and in upper case. This allows elements of files to be referenced |
| from within <a href="../expr.html">expressions</a> and modules like |
| <module>mod_rewrite</module>. In order to prevent confusion, numbered |
| (unnamed) backreferences are ignored. Use named groups instead.</p> |
| |
| <highlight language="config"> |
| <FilesMatch "^(?<sitename>[^/]+)"> |
| Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example |
| </FilesMatch> |
| </highlight> |
| </usage> |
| |
| <seealso><a href="../sections.html">How <Directory>, <Location> |
| and <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ForceType</name> |
| <description>Forces all matching files to be served with the specified |
| media type in the HTTP Content-Type header field</description> |
| <syntax>ForceType <var>media-type</var>|None</syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>When placed into an <code>.htaccess</code> file or a |
| <directive type="section" module="core">Directory</directive>, or |
| <directive type="section" module="core">Location</directive> or |
| <directive type="section" module="core">Files</directive> |
| section, this directive forces all matching files to be served |
| with the content type identification given by |
| <var>media-type</var>. For example, if you had a directory full of |
| GIF files, but did not want to label them all with <code>.gif</code>, |
| you might want to use:</p> |
| |
| <highlight language="config"> |
| ForceType image/gif |
| </highlight> |
| |
| <p>Note that this directive overrides other indirect media type |
| associations defined in mime.types or via the |
| <directive module="mod_mime">AddType</directive>.</p> |
| |
| <p>You can also override more general |
| <directive>ForceType</directive> settings |
| by using the value of <code>None</code>:</p> |
| |
| <highlight language="config"> |
| # force all files to be image/gif: |
| <Location "/images"> |
| ForceType image/gif |
| </Location> |
| |
| # but normal mime-type associations here: |
| <Location "/images/mixed"> |
| ForceType None |
| </Location> |
| </highlight> |
| |
| <p>This directive primarily overrides the content types generated for |
| static files served out of the filesystem. For resources other than |
| static files, where the generator of the response typically specifies |
| a Content-Type, this directive has no effect.</p> |
| |
| <note><title>Note</title> |
| <p>When explicit directives such as |
| <directive module="core" >SetHandler</directive> or |
| <directive module="mod_mime">AddHandler</directive> do not apply |
| to the current request, the internal handler name normally set by those |
| directives is set to match the content type specified by this directive. |
| This is a historical behavior that some third-party modules |
| (such as mod_php) may use "magic" content types used only to signal the |
| module to take responsibility for the matching request. Configurations |
| that rely on such "magic" types should be avoided by the use of |
| <directive module="core" >SetHandler</directive> or |
| <directive module="mod_mime">AddHandler</directive>. </p> |
| </note> |
| |
| </usage> |
| </directivesynopsis> |
| <directivesynopsis> |
| <name>GprofDir</name> |
| <description>Directory to write gmon.out profiling data to. </description> |
| <syntax>GprofDir <var>/tmp/gprof/</var>|<var>/tmp/gprof/</var>%</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>When the server has been compiled with gprof profiling support, |
| <directive>GprofDir</directive> causes <code>gmon.out</code> files to |
| be written to the specified directory when the process exits. If the |
| argument ends with a percent symbol ('%'), subdirectories are created |
| for each process id.</p> |
| |
| <p>This directive currently only works with the <module>prefork</module> |
| MPM.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>HostnameLookups</name> |
| <description>Enables DNS lookups on client IP addresses</description> |
| <syntax>HostnameLookups On|Off|Double</syntax> |
| <default>HostnameLookups Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context></contextlist> |
| |
| <usage> |
| <p>This directive enables DNS lookups so that host names can be |
| logged (and passed to CGIs/SSIs in <code>REMOTE_HOST</code>). |
| The value <code>Double</code> refers to doing double-reverse |
| DNS lookup. That is, after a reverse lookup is performed, a forward |
| lookup is then performed on that result. At least one of the IP |
| addresses in the forward lookup must match the original |
| address. (In "tcpwrappers" terminology this is called |
| <code>PARANOID</code>.)</p> |
| |
| <p>Regardless of the setting, when <module>mod_authz_host</module> is |
| used for controlling access by hostname, a double reverse lookup |
| will be performed. This is necessary for security. Note that the |
| result of this double-reverse isn't generally available unless you |
| set <code>HostnameLookups Double</code>. For example, if only |
| <code>HostnameLookups On</code> and a request is made to an object |
| that is protected by hostname restrictions, regardless of whether |
| the double-reverse fails or not, CGIs will still be passed the |
| single-reverse result in <code>REMOTE_HOST</code>.</p> |
| |
| <p>The default is <code>Off</code> in order to save the network |
| traffic for those sites that don't truly need the reverse |
| lookups done. It is also better for the end users because they |
| don't have to suffer the extra latency that a lookup entails. |
| Heavily loaded sites should leave this directive |
| <code>Off</code>, since DNS lookups can take considerable |
| amounts of time. The utility <program>logresolve</program>, compiled by |
| default to the <code>bin</code> subdirectory of your installation |
| directory, can be used to look up host names from logged IP addresses |
| offline.</p> |
| |
| <p>Finally, if you have <a |
| href="mod_authz_host.html#reqhost">hostname-based Require |
| directives</a>, a hostname lookup will be performed regardless of |
| the setting of <code>HostnameLookups</code>.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>If</name> |
| <description>Contains directives that apply only if a condition is |
| satisfied by a request at runtime</description> |
| <syntax><If <var>expression</var>> ... </If></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Nested conditions are evaluated in 2.4.26 and later</compatibility> |
| |
| <usage> |
| <p>The <directive type="section">If</directive> directive |
| evaluates an expression at runtime, and applies the enclosed |
| directives if and only if the expression evaluates to true. |
| For example:</p> |
| |
| <highlight language="config"> |
| <If "-z req('Host')"> |
| </highlight> |
| |
| <p>would match HTTP/1.0 requests without a <var>Host:</var> header. |
| Expressions may contain various shell-like operators for string |
| comparison (<code>==</code>, <code>!=</code>, <code><</code>, ...), |
| integer comparison (<code>-eq</code>, <code>-ne</code>, ...), |
| and others (<code>-n</code>, <code>-z</code>, <code>-f</code>, ...). |
| It is also possible to use regular expressions, </p> |
| |
| <highlight language="config"> |
| <If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/"> |
| </highlight> |
| |
| <p>shell-like pattern matches and many other operations. These operations |
| can be done on request headers (<code>req</code>), environment variables |
| (<code>env</code>), and a large number of other properties. The full |
| documentation is available in <a href="../expr.html">Expressions in |
| Apache HTTP Server</a>.</p> |
| |
| <p>Only directives that support the <a href="directive-dict.html#Context" |
| >directory context</a> can be used within this configuration section.</p> |
| |
| <note type="warning"> |
| Certain variables, such as <code>CONTENT_TYPE</code> and other |
| response headers, are set after <If> conditions have already |
| been evaluated, and so will not be available to use in this |
| directive. |
| </note> |
| |
| </usage> |
| |
| <seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>, |
| for a complete reference and more examples.</seealso> |
| <seealso><directive type="section" module="core">ElseIf</directive></seealso> |
| <seealso><directive type="section" module="core">Else</directive></seealso> |
| <seealso><a href="../sections.html">How <Directory>, <Location>, |
| <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received. |
| <directive type="section">If</directive>, |
| <directive type="section">ElseIf</directive>, and |
| <directive type="section">Else</directive> are applied last.</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfDefine</name> |
| <description>Encloses directives that will be processed only |
| if a test is true at startup</description> |
| <syntax><IfDefine [!]<var>parameter-name</var>> ... |
| </IfDefine></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <code><IfDefine <var>test</var>>...</IfDefine> |
| </code> section is used to mark directives that are conditional. The |
| directives within an <directive type="section">IfDefine</directive> |
| section are only processed if the <var>test</var> is true. If <var> |
| test</var> is false, everything between the start and end markers is |
| ignored.</p> |
| |
| <p>The <var>test</var> in the <directive type="section" |
| >IfDefine</directive> section directive can be one of two forms:</p> |
| |
| <ul> |
| <li><var>parameter-name</var></li> |
| |
| <li><code>!</code><var>parameter-name</var></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if the parameter named |
| <var>parameter-name</var> is defined. The second format reverses |
| the test, and only processes the directives if |
| <var>parameter-name</var> is <strong>not</strong> defined.</p> |
| |
| <p>The <var>parameter-name</var> argument is a define as given on the |
| <program>httpd</program> command line via <code>-D<var>parameter</var> |
| </code> at the time the server was started or by the <directive |
| module="core">Define</directive> directive.</p> |
| |
| <p><directive type="section">IfDefine</directive> sections are |
| nest-able, which can be used to implement simple |
| multiple-parameter tests. Example:</p> |
| |
| <example>httpd -DReverseProxy -DUseCache -DMemCache ...</example> |
| <highlight language="config"> |
| <IfDefine ReverseProxy> |
| LoadModule proxy_module modules/mod_proxy.so |
| LoadModule proxy_http_module modules/mod_proxy_http.so |
| <IfDefine UseCache> |
| LoadModule cache_module modules/mod_cache.so |
| <IfDefine MemCache> |
| LoadModule mem_cache_module modules/mod_mem_cache.so |
| </IfDefine> |
| <IfDefine !MemCache> |
| LoadModule cache_disk_module modules/mod_cache_disk.so |
| </IfDefine> |
| </IfDefine> |
| </IfDefine> |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfFile</name> |
| <description>Encloses directives that will be processed only |
| if file exists at startup</description> |
| <syntax><IfFile [!]<var>filename</var>> ... |
| </IfFile></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Available in 2.4.34 and later.</compatibility> |
| |
| <usage> |
| <p>The <code><IfFile <var>filename</var>>...</IfFile> |
| </code> section is used to mark directives that are conditional on |
| the existence of a file on disk. The directives within an |
| <directive type="section">IfFile</directive> section are only |
| processed if <var>filename</var> exists. If <var>filename</var> |
| doesn't exist, everything between the start and end markers is |
| ignored. <var>filename</var> can be an absolute path or a path |
| relative to the server root.</p> |
| |
| <p>The <var>filename</var> in the <directive type="section" |
| >IfFile</directive> section directive can take the same forms as the |
| <var>test</var> variable in the <directive type="section" module="core" |
| >IfDefine</directive> section, i.e. the test can be negated if the <code> |
| !</code> character is placed directly before <var>filename</var>. |
| </p> |
| |
| <p>If a relative <var>filename</var> is supplied, the check is |
| <directive module="core">ServerRoot</directive> relative. In the case where |
| this directive occurs before the <directive module="core">ServerRoot</directive>, |
| the path will be checked relative to the compiled-in server root or |
| the server root passed in on the command line via the <code>-d</code> |
| parameter.</p> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfModule</name> |
| <description>Encloses directives that are processed conditional on the |
| presence or absence of a specific module</description> |
| <syntax><IfModule [!]<var>module-file</var>|<var>module-identifier</var>> ... |
| </IfModule></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Module identifiers are available in version 2.1 and |
| later.</compatibility> |
| |
| <usage> |
| <p>The <code><IfModule <var>test</var>>...</IfModule></code> |
| section is used to mark directives that are conditional on the presence of |
| a specific module. The directives within an <directive type="section" |
| >IfModule</directive> section are only processed if the <var>test</var> |
| is true. If <var>test</var> is false, everything between the start and |
| end markers is ignored.</p> |
| |
| <p>The <var>test</var> in the <directive type="section" |
| >IfModule</directive> section directive can be one of two forms:</p> |
| |
| <ul> |
| <li><var>module</var></li> |
| |
| <li>!<var>module</var></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if the module named <var>module</var> |
| is included in Apache httpd -- either compiled in or |
| dynamically loaded using <directive module="mod_so" |
| >LoadModule</directive>. The second format reverses the test, |
| and only processes the directives if <var>module</var> is |
| <strong>not</strong> included.</p> |
| |
| <p>The <var>module</var> argument can be either the module identifier or |
| the file name of the module, at the time it was compiled. For example, |
| <code>rewrite_module</code> is the identifier and |
| <code>mod_rewrite.c</code> is the file name. If a module consists of |
| several source files, use the name of the file containing the string |
| <code>STANDARD20_MODULE_STUFF</code>.</p> |
| |
| <p><directive type="section">IfModule</directive> sections are |
| nest-able, which can be used to implement simple multiple-module |
| tests.</p> |
| |
| <note>This section should only be used if you need to have one |
| configuration file that works whether or not a specific module |
| is available. In normal operation, directives need not be |
| placed in <directive type="section">IfModule</directive> |
| sections.</note> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfDirective</name> |
| <description>Encloses directives that are processed conditional on the |
| presence or absence of a specific directive</description> |
| <syntax><IfDirective [!]<var>directive-name</var>> ... |
| </IfDirective></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Available in 2.4.34 and later.</compatibility> |
| |
| <usage> |
| <p>The <code><IfDirective <var>test</var>>...</IfDirective></code> |
| section is used to mark directives that are conditional on the presence of |
| a specific directive. The directives within an <directive type="section" |
| >IfDirective</directive> section are only processed if the <var>test</var> |
| is true. If <var>test</var> is false, everything between the start and |
| end markers is ignored.</p> |
| |
| <p>The <var>test</var> in the <directive type="section" |
| >IfDirective</directive> section can be one of two forms:</p> |
| |
| <ul> |
| <li><var>directive-name</var></li> |
| |
| <li>!<var>directive-name</var></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if a directive of the given name is |
| available at the time of processing. The second format reverses the test, |
| and only processes the directives if <var>directive-name</var> is |
| <strong>not</strong> available.</p> |
| |
| <note>This section should only be used if you need to have one |
| configuration file that works across multiple versions of |
| <program>httpd</program>, regardless of whether a particular |
| directive is available. In normal operation, directives need not |
| be placed in <directive type="section">IfDirective</directive> |
| sections.</note> |
| </usage> |
| <seealso><directive module="core" type="section">IfSection</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfSection</name> |
| <description>Encloses directives that are processed conditional on the |
| presence or absence of a specific section directive</description> |
| <syntax><IfSection [!]<var>section-name</var>> ... |
| </IfSection></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <compatibility>Available in 2.4.34 and later.</compatibility> |
| |
| <usage> |
| <p>The <code><IfSection |
| <var>test</var>>...</IfSection></code> section is used |
| to mark directives that are conditional on the presence of a |
| specific section directive. A section directive is any directive |
| such as <directive type="section">VirtualHost</directive> which |
| encloses other directives, and has a directive name with a leading |
| "<".</p> |
| |
| <p>The directives within an <directive type="section" |
| >IfSection</directive> section are only processed if the <var>test</var> |
| is true. If <var>test</var> is false, everything between the start and |
| end markers is ignored.</p> |
| |
| <p>The <var>section-name</var> must be specified without either |
| the leading "<" or closing ">". The <var>test</var> in the |
| <directive type="section">IfSection</directive> section can be one |
| of two forms:</p> |
| |
| <ul> |
| <li><var>section-name</var></li> |
| <li>!<var>section-name</var></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if a section directive of the given |
| name is available at the time of processing. The second format |
| reverses the test, and only processes the directives if |
| <var>section-name</var> is <strong>not</strong> an available |
| section directive.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| <IfSection VirtualHost> |
| ... |
| </IfSection> |
| </highlight> |
| |
| <note>This section should only be used if you need to have one |
| configuration file that works across multiple versions of <program>httpd</program>, |
| regardless of whether a particular section directive is |
| available. In normal operation, directives need not be placed in |
| <directive type="section">IfSection</directive> sections.</note> |
| </usage> |
| <seealso><directive module="core" type="section">IfDirective</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Include</name> |
| <description>Includes other configuration files from within |
| the server configuration files</description> |
| <syntax>Include <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Directory |
| wildcard matching available in 2.3.6 and later</compatibility> |
| |
| <usage> |
| <p>This directive allows inclusion of other configuration files |
| from within the server configuration files.</p> |
| |
| <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used |
| in the filename or directory parts of the path to include several files |
| at once, in alphabetical order. In addition, if |
| <directive>Include</directive> points to a directory, rather than a file, |
| Apache httpd will read all files in that directory and any subdirectory. |
| However, including entire directories is not recommended, because it is |
| easy to accidentally leave temporary files in a directory that can cause |
| <program>httpd</program> to fail. Instead, we encourage you to use the |
| wildcard syntax shown below, to include files that match a particular |
| pattern, such as *.conf, for example.</p> |
| |
| <p>The <directive module="core">Include</directive> directive will |
| <strong>fail with an error</strong> if a wildcard expression does not |
| match any file. The <directive module="core">IncludeOptional</directive> |
| directive can be used if non-matching wildcards should be ignored.</p> |
| |
| <p>The file path specified may be an absolute path, or may be relative |
| to the <directive module="core">ServerRoot</directive> directory.</p> |
| |
| <p>Examples:</p> |
| |
| <highlight language="config"> |
| Include /usr/local/apache2/conf/ssl.conf |
| Include /usr/local/apache2/conf/vhosts/*.conf |
| </highlight> |
| |
| <p>Or, providing paths relative to your <directive |
| module="core">ServerRoot</directive> directory:</p> |
| |
| <highlight language="config"> |
| Include conf/ssl.conf |
| Include conf/vhosts/*.conf |
| </highlight> |
| |
| <p>Wildcards may be included in the directory or file portion of the |
| path. This example will fail if there is no subdirectory in conf/vhosts |
| that contains at least one *.conf file:</p> |
| |
| <highlight language="config"> |
| Include conf/vhosts/*/*.conf |
| </highlight> |
| |
| <p>Alternatively, the following command will just be ignored in case of |
| missing files or directories:</p> |
| |
| <highlight language="config"> |
| IncludeOptional conf/vhosts/*/*.conf |
| </highlight> |
| |
| </usage> |
| |
| <seealso><directive module="core">IncludeOptional</directive></seealso> |
| <seealso><program>apachectl</program></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>IncludeOptional</name> |
| <description>Includes other configuration files from within |
| the server configuration files</description> |
| <syntax>IncludeOptional <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Available in 2.3.6 and later. Not existent file paths without wildcards |
| do not cause SyntaxError after 2.4.30</compatibility> |
| |
| <usage> |
| <p>This directive allows inclusion of other configuration files |
| from within the server configuration files. It works identically to the |
| <directive module="core">Include</directive> directive, but it will be |
| silently ignored (instead of causing an error) if wildcards are used and |
| they do not match any file or directory or if a file path does not exist |
| on the file system.</p> |
| </usage> |
| |
| <seealso><directive module="core">Include</directive></seealso> |
| <seealso><program>apachectl</program></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>KeepAlive</name> |
| <description>Enables HTTP persistent connections</description> |
| <syntax>KeepAlive On|Off</syntax> |
| <default>KeepAlive On</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The Keep-Alive extension to HTTP/1.0 and the persistent |
| connection feature of HTTP/1.1 provide long-lived HTTP sessions |
| which allow multiple requests to be sent over the same TCP |
| connection. In some cases this has been shown to result in an |
| almost 50% speedup in latency times for HTML documents with |
| many images. To enable Keep-Alive connections, set |
| <code>KeepAlive On</code>.</p> |
| |
| <p>For HTTP/1.0 clients, Keep-Alive connections will only be |
| used if they are specifically requested by a client. In |
| addition, a Keep-Alive connection with an HTTP/1.0 client can |
| only be used when the length of the content is known in |
| advance. This implies that dynamic content such as CGI output, |
| SSI pages, and server-generated directory listings will |
| generally not use Keep-Alive connections to HTTP/1.0 clients. |
| For HTTP/1.1 clients, persistent connections are the default |
| unless otherwise specified. If the client requests it, chunked |
| encoding will be used in order to send content of unknown |
| length over persistent connections.</p> |
| |
| <p>When a client uses a Keep-Alive connection, it will be counted |
| as a single "request" for the <directive module="mpm_common" |
| >MaxConnectionsPerChild</directive> directive, regardless |
| of how many requests are sent using the connection.</p> |
| </usage> |
| |
| <seealso><directive module="core">MaxKeepAliveRequests</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>KeepAliveTimeout</name> |
| <description>Amount of time the server will wait for subsequent |
| requests on a persistent connection</description> |
| <syntax>KeepAliveTimeout <var>num</var>[ms]</syntax> |
| <default>KeepAliveTimeout 5</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The number of seconds Apache httpd will wait for a subsequent |
| request before closing the connection. By adding a postfix of ms the |
| timeout can be also set in milliseconds. Once a request has been |
| received, the timeout value specified by the |
| <directive module="core">Timeout</directive> directive applies.</p> |
| |
| <p>Setting <directive>KeepAliveTimeout</directive> to a high value |
| may cause performance problems in heavily loaded servers. The |
| higher the timeout, the more server processes will be kept |
| occupied waiting on connections with idle clients.</p> |
| |
| <p>If <directive>KeepAliveTimeout</directive> is <strong>not</strong> |
| set for a name-based virtual host, the value of the first defined |
| virtual host best matching the local IP and port will be used.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Limit</name> |
| <description>Restrict enclosed access controls to only certain HTTP |
| methods</description> |
| <syntax><Limit <var>method</var> [<var>method</var>] ... > ... |
| </Limit></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>AuthConfig, Limit</override> |
| |
| <usage> |
| <p>Access controls are normally effective for |
| <strong>all</strong> access methods, and this is the usual |
| desired behavior. <strong>In the general case, access control |
| directives should not be placed within a |
| <directive type="section">Limit</directive> section.</strong></p> |
| |
| <p>The purpose of the <directive type="section">Limit</directive> |
| directive is to restrict the effect of the access controls to the |
| nominated HTTP methods. For all other methods, the access |
| restrictions that are enclosed in the <directive |
| type="section">Limit</directive> bracket <strong>will have no |
| effect</strong>. The following example applies the access control |
| only to the methods <code>POST</code>, <code>PUT</code>, and |
| <code>DELETE</code>, leaving all other methods unprotected:</p> |
| |
| <highlight language="config"> |
| <Limit POST PUT DELETE> |
| Require valid-user |
| </Limit> |
| </highlight> |
| |
| <p>The method names listed can be one or more of: <code>GET</code>, |
| <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, |
| <code>CONNECT</code>, <code>OPTIONS</code>, |
| <code>PATCH</code>, <code>PROPFIND</code>, <code>PROPPATCH</code>, |
| <code>MKCOL</code>, <code>COPY</code>, <code>MOVE</code>, |
| <code>LOCK</code>, and <code>UNLOCK</code>. <strong>The method name is |
| case-sensitive.</strong> If <code>GET</code> is used, it will also |
| restrict <code>HEAD</code> requests. The <code>TRACE</code> method |
| cannot be limited (see <directive module="core" |
| >TraceEnable</directive>).</p> |
| |
| <note type="warning">A <directive type="section" |
| module="core">LimitExcept</directive> section should always be |
| used in preference to a <directive type="section">Limit</directive> |
| section when restricting access, since a <directive type="section" |
| module="core">LimitExcept</directive> section provides protection |
| against arbitrary methods.</note> |
| |
| <p>The <directive type="section">Limit</directive> and |
| <directive type="section" module="core">LimitExcept</directive> |
| directives may be nested. In this case, each successive level of |
| <directive type="section">Limit</directive> or <directive |
| type="section" module="core">LimitExcept</directive> directives must |
| further restrict the set of methods to which access controls apply.</p> |
| |
| <note type="warning">When using |
| <directive type="section">Limit</directive> or |
| <directive type="section">LimitExcept</directive> directives with |
| the <directive module="mod_authz_core">Require</directive> directive, |
| note that the first <directive module="mod_authz_core">Require</directive> |
| to succeed authorizes the request, regardless of the presence of other |
| <directive module="mod_authz_core">Require</directive> directives.</note> |
| |
| <p>For example, given the following configuration, all users will |
| be authorized for <code>POST</code> requests, and the |
| <code>Require group editors</code> directive will be ignored |
| in all cases:</p> |
| |
| <highlight language="config"> |
| <LimitExcept GET> |
| Require valid-user |
| </LimitExcept> |
| <Limit POST> |
| Require group editors |
| </Limit> |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>LimitExcept</name> |
| <description>Restrict access controls to all HTTP methods |
| except the named ones</description> |
| <syntax><LimitExcept <var>method</var> [<var>method</var>] ... > ... |
| </LimitExcept></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>AuthConfig, Limit</override> |
| |
| <usage> |
| <p><directive type="section">LimitExcept</directive> and |
| <code></LimitExcept></code> are used to enclose |
| a group of access control directives which will then apply to any |
| HTTP access method <strong>not</strong> listed in the arguments; |
| i.e., it is the opposite of a <directive type="section" |
| module="core">Limit</directive> section and can be used to control |
| both standard and nonstandard/unrecognized methods. See the |
| documentation for <directive module="core" |
| type="section">Limit</directive> for more details.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| <LimitExcept POST GET> |
| Require valid-user |
| </LimitExcept> |
| </highlight> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitInternalRecursion</name> |
| <description>Determine maximum number of internal redirects and nested |
| subrequests</description> |
| <syntax>LimitInternalRecursion <var>number</var> [<var>number</var>]</syntax> |
| <default>LimitInternalRecursion 10</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>An internal redirect happens, for example, when using the <directive |
| module="mod_actions">Action</directive> directive, which internally |
| redirects the original request to a CGI script. A subrequest is Apache httpd's |
| mechanism to find out what would happen for some URI if it were requested. |
| For example, <module>mod_dir</module> uses subrequests to look for the |
| files listed in the <directive module="mod_dir">DirectoryIndex</directive> |
| directive.</p> |
| |
| <p><directive>LimitInternalRecursion</directive> prevents the server |
| from crashing when entering an infinite loop of internal redirects or |
| subrequests. Such loops are usually caused by misconfigurations.</p> |
| |
| <p>The directive stores two different limits, which are evaluated on |
| per-request basis. The first <var>number</var> is the maximum number of |
| internal redirects that may follow each other. The second <var>number</var> |
| determines how deeply subrequests may be nested. If you specify only one |
| <var>number</var>, it will be assigned to both limits.</p> |
| |
| <highlight language="config"> |
| LimitInternalRecursion 5 |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestBody</name> |
| <description>Restricts the total size of the HTTP request body sent |
| from the client</description> |
| <syntax>LimitRequestBody <var>bytes</var></syntax> |
| <default>LimitRequestBody 0</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>This directive specifies the number of <var>bytes</var> from 0 |
| (meaning unlimited) to 2147483647 (2GB) that are allowed in a |
| request body. See the note below for the limited applicability |
| to proxy requests.</p> |
| |
| <p>The <directive>LimitRequestBody</directive> directive allows |
| the user to set a limit on the allowed size of an HTTP request |
| message body within the context in which the directive is given |
| (server, per-directory, per-file or per-location). If the client |
| request exceeds that limit, the server will return an error |
| response instead of servicing the request. The size of a normal |
| request message body will vary greatly depending on the nature of |
| the resource and the methods allowed on that resource. CGI scripts |
| typically use the message body for retrieving form information. |
| Implementations of the <code>PUT</code> method will require |
| a value at least as large as any representation that the server |
| wishes to accept for that resource.</p> |
| |
| <p>This directive gives the server administrator greater |
| control over abnormal client request behavior, which may be |
| useful for avoiding some forms of denial-of-service |
| attacks.</p> |
| |
| <p>If, for example, you are permitting file upload to a particular |
| location and wish to limit the size of the uploaded file to 100K, |
| you might use the following directive:</p> |
| |
| <highlight language="config"> |
| LimitRequestBody 102400 |
| </highlight> |
| |
| <note><p>For a full description of how this directive is interpreted by |
| proxy requests, see the <module>mod_proxy</module> documentation.</p> |
| </note> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestFields</name> |
| <description>Limits the number of HTTP request header fields that |
| will be accepted from the client</description> |
| <syntax>LimitRequestFields <var>number</var></syntax> |
| <default>LimitRequestFields 100</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p><var>Number</var> is an integer from 0 (meaning unlimited) to |
| 32767. The default value is defined by the compile-time |
| constant <code>DEFAULT_LIMIT_REQUEST_FIELDS</code> (100 as |
| distributed).</p> |
| |
| <p>The <directive>LimitRequestFields</directive> directive allows |
| the server administrator to modify the limit on the number of |
| request header fields allowed in an HTTP request. A server needs |
| this value to be larger than the number of fields that a normal |
| client request might include. The number of request header fields |
| used by a client rarely exceeds 20, but this may vary among |
| different client implementations, often depending upon the extent |
| to which a user has configured their browser to support detailed |
| content negotiation. Optional HTTP extensions are often expressed |
| using request header fields.</p> |
| |
| <p>This directive gives the server administrator greater |
| control over abnormal client request behavior, which may be |
| useful for avoiding some forms of denial-of-service attacks. |
| The value should be increased if normal clients see an error |
| response from the server that indicates too many fields were |
| sent in the request.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| LimitRequestFields 50 |
| </highlight> |
| |
| <note type="warning"><title>Warning</title> |
| <p> When name-based virtual hosting is used, the value for this |
| directive is taken from the default (first-listed) virtual host for the |
| local IP and port combination.</p> |
| </note> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestFieldSize</name> |
| <description>Limits the size of the HTTP request header allowed from the |
| client</description> |
| <syntax>LimitRequestFieldSize <var>bytes</var></syntax> |
| <default>LimitRequestFieldSize 8190</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>This directive specifies the number of <var>bytes</var> |
| that will be allowed in an HTTP request header.</p> |
| |
| <p>The <directive>LimitRequestFieldSize</directive> directive |
| allows the server administrator to set the limit |
| on the allowed size of an HTTP request header field. A server |
| needs this value to be large enough to hold any one header field |
| from a normal client request. The size of a normal request header |
| field will vary greatly among different client implementations, |
| often depending upon the extent to which a user has configured |
| their browser to support detailed content negotiation. SPNEGO |
| authentication headers can be up to 12392 bytes.</p> |
| |
| <p>This directive gives the server administrator greater |
| control over abnormal client request behavior, which may be |
| useful for avoiding some forms of denial-of-service attacks.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| LimitRequestFieldSize 4094 |
| </highlight> |
| |
| <note>Under normal conditions, the value should not be changed from |
| the default.</note> |
| |
| <note type="warning"><title>Warning</title> |
| <p> When name-based virtual hosting is used, the value for this |
| directive is taken from the default (first-listed) virtual host best |
| matching the current IP address and port combination.</p> |
| </note> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestLine</name> |
| <description>Limit the size of the HTTP request line that will be accepted |
| from the client</description> |
| <syntax>LimitRequestLine <var>bytes</var></syntax> |
| <default>LimitRequestLine 8190</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>This directive sets the number of <var>bytes</var> that will be |
| allowed on the HTTP request-line.</p> |
| |
| <p>The <directive>LimitRequestLine</directive> directive allows |
| the server administrator to set the limit on the allowed size |
| of a client's HTTP request-line. Since the request-line consists of the |
| HTTP method, URI, and protocol version, the |
| <directive>LimitRequestLine</directive> directive places a |
| restriction on the length of a request-URI allowed for a request |
| on the server. A server needs this value to be large enough to |
| hold any of its resource names, including any information that |
| might be passed in the query part of a <code>GET</code> request.</p> |
| |
| <p>This directive gives the server administrator greater |
| control over abnormal client request behavior, which may be |
| useful for avoiding some forms of denial-of-service attacks.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| LimitRequestLine 4094 |
| </highlight> |
| |
| <note>Under normal conditions, the value should not be changed from |
| the default.</note> |
| |
| <note type="warning"><title>Warning</title> |
| <p> When name-based virtual hosting is used, the value for this |
| directive is taken from the default (first-listed) virtual host best |
| matching the current IP address and port combination.</p> |
| </note> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitXMLRequestBody</name> |
| <description>Limits the size of an XML-based request body</description> |
| <syntax>LimitXMLRequestBody <var>bytes</var></syntax> |
| <default>LimitXMLRequestBody 1000000</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>Limit (in bytes) on maximum size of an XML-based request |
| body. A value of <code>0</code> will disable any checking.</p> |
| |
| <p>Example:</p> |
| |
| <highlight language="config"> |
| LimitXMLRequestBody 0 |
| </highlight> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Location</name> |
| <description>Applies the enclosed directives only to matching |
| URLs</description> |
| <syntax><Location |
| <var>URL-path</var>|<var>URL</var>> ... </Location></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">Location</directive> directive |
| limits the scope of the enclosed directives by URL. It is similar to the |
| <directive type="section" module="core">Directory</directive> |
| directive, and starts a subsection which is terminated with a |
| <code></Location></code> directive. <directive |
| type="section">Location</directive> sections are processed in the |
| order they appear in the configuration file, after the <directive |
| type="section" module="core">Directory</directive> sections and |
| <code>.htaccess</code> files are read, and after the <directive |
| type="section" module="core">Files</directive> sections.</p> |
| |
| <p><directive type="section">Location</directive> sections operate |
| completely outside the filesystem. This has several consequences. |
| Most importantly, <directive type="section">Location</directive> |
| directives should not be used to control access to filesystem |
| locations. Since several different URLs may map to the same |
| filesystem location, such access controls may by circumvented.</p> |
| |
| <p>The enclosed directives will be applied to the request if the path component |
| of the URL meets <em>any</em> of the following criteria: |
| </p> |
| <ul> |
| <li>The specified location matches exactly the path component of the URL. |
| </li> |
| <li>The specified location, which ends in a forward slash, is a prefix |
| of the path component of the URL (treated as a context root). |
| </li> |
| <li>The specified location, with the addition of a trailing slash, is a |
| prefix of the path component of the URL (also treated as a context root). |
| </li> |
| </ul> |
| <p> |
| In the example below, where no trailing slash is used, requests to |
| /private1, /private1/ and /private1/file.txt will have the enclosed |
| directives applied, but /private1other would not. |
| </p> |
| <highlight language="config"> |
| <Location "/private1"> |
| # ... |
| </Location> |
| </highlight> |
| <p> |
| In the example below, where a trailing slash is used, requests to |
| /private2/ and /private2/file.txt will have the enclosed |
| directives applied, but /private2 and /private2other would not. |
| </p> |
| <highlight language="config"> |
| <Location "/private2<em>/</em>"> |
| # ... |
| </Location> |
| </highlight> |
| |
| <note><title>When to use <directive |
| type="section">Location</directive></title> |
| |
| <p>Use <directive type="section">Location</directive> to apply |
| directives to content that lives outside the filesystem. For |
| content that lives in the filesystem, use <directive |
| type="section" module="core">Directory</directive> and <directive |
| type="section" module="core">Files</directive>. An exception is |
| <code><Location "/"></code>, which is an easy way to |
| apply a configuration to the entire server.</p> |
| </note> |
| |
| <p>For all origin (non-proxy) requests, the URL to be matched is a |
| URL-path of the form <code>/path/</code>. <em>No scheme, hostname, |
| port, or query string may be included.</em> For proxy requests, the |
| URL to be matched is of the form |
| <code>scheme://servername/path</code>, and you must include the |
| prefix.</p> |
| |
| <p>The URL may use wildcards. In a wild-card string, <code>?</code> matches |
| any single character, and <code>*</code> matches any sequences of |
| characters. Neither wildcard character matches a / in the URL-path.</p> |
| |
| <p><glossary ref="regex">Regular expressions</glossary> |
| can also be used, with the addition of the <code>~</code> |
| character. For example:</p> |
| |
| <highlight language="config"> |
| <Location ~ "/(extra|special)/data"> |
| #... |
| </Location> |
| </highlight> |
| |
| <p>would match URLs that contained the substring <code>/extra/data</code> |
| or <code>/special/data</code>. The directive <directive |
| type="section" module="core">LocationMatch</directive> behaves |
| identical to the regex version of <directive |
| type="section">Location</directive>, and is preferred, for the |
| simple reason that <code>~</code> is hard to distinguish from |
| <code>-</code> in many fonts.</p> |
| |
| <p>The <directive type="section">Location</directive> |
| functionality is especially useful when combined with the |
| <directive module="core">SetHandler</directive> |
| directive. For example, to enable status requests but allow them |
| only from browsers at <code>example.com</code>, you might use:</p> |
| |
| <highlight language="config"> |
| <Location "/status"> |
| SetHandler server-status |
| Require host example.com |
| </Location> |
| </highlight> |
| |
| <note><title>Note about / (slash)</title> |
| <p>The slash character has special meaning depending on where in a |
| URL it appears. People may be used to its behavior in the filesystem |
| where multiple adjacent slashes are frequently collapsed to a single |
| slash (<em>i.e.</em>, <code>/home///foo</code> is the same as |
| <code>/home/foo</code>). In URL-space this is not necessarily true. |
| The <directive type="section" module="core">LocationMatch</directive> |
| directive and the regex version of <directive type="section" |
| >Location</directive> require you to explicitly specify multiple |
| slashes if that is your intention.</p> |
| |
| <p>For example, <code><LocationMatch "^/abc"></code> would match |
| the request URL <code>/abc</code> but not the request URL <code> |
| //abc</code>. The (non-regex) <directive type="section" |
| >Location</directive> directive behaves similarly when used for |
| proxy requests. But when (non-regex) <directive type="section" |
| >Location</directive> is used for non-proxy requests it will |
| implicitly match multiple slashes with a single slash. For example, |
| if you specify <code><Location "/abc/def"></code> and the |
| request is to <code>/abc//def</code> then it will match.</p> |
| </note> |
| </usage> |
| <seealso><a href="../sections.html">How <Directory>, <Location> |
| and <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received.</seealso> |
| <seealso><directive module="core">LocationMatch</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>LocationMatch</name> |
| <description>Applies the enclosed directives only to regular-expression |
| matching URLs</description> |
| <syntax><LocationMatch |
| <var>regex</var>> ... </LocationMatch></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">LocationMatch</directive> directive |
| limits the scope of the enclosed directives by URL, in an identical manner |
| to <directive module="core" type="section">Location</directive>. However, |
| it takes a <glossary ref="regex">regular expression</glossary> |
| as an argument instead of a simple string. For example:</p> |
| |
| <highlight language="config"> |
| <LocationMatch "/(extra|special)/data"> |
| # ... |
| </LocationMatch> |
| </highlight> |
| |
| <p>would match URLs that contained the substring <code>/extra/data</code> |
| or <code>/special/data</code>.</p> |
| |
| <note><p>If the intent is that a URL <strong>starts with</strong> |
| <code>/extra/data</code>, rather than merely |
| <strong>contains</strong> <code>/extra/data</code>, prefix the |
| regular expression with a <code>^</code> to require this.</p> |
| |
| <highlight language="config"> |
| <LocationMatch "^/(extra|special)/data"> |
| </highlight> |
| </note> |
| |
| <p>From 2.4.8 onwards, named groups and backreferences are captured and |
| written to the environment with the corresponding name prefixed with |
| "MATCH_" and in upper case. This allows elements of URLs to be referenced |
| from within <a href="../expr.html">expressions</a> and modules like |
| <module>mod_rewrite</module>. In order to prevent confusion, numbered |
| (unnamed) backreferences are ignored. Use named groups instead.</p> |
| |
| <highlight language="config"> |
| <LocationMatch "^/combined/(?<sitename>[^/]+)"> |
| Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example |
| </LocationMatch> |
| </highlight> |
| </usage> |
| |
| <seealso><a href="../sections.html">How <Directory>, <Location> |
| and <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LogLevel</name> |
| <description>Controls the verbosity of the ErrorLog</description> |
| <syntax>LogLevel [<var>module</var>:]<var>level</var> |
| [<var>module</var>:<var>level</var>] ... |
| </syntax> |
| <default>LogLevel warn</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Per-module and per-directory configuration is available in |
| Apache HTTP Server 2.3.6 and later</compatibility> |
| |
| <usage> |
| <p><directive>LogLevel</directive> adjusts the verbosity of the |
| messages recorded in the error logs (see <directive |
| module="core">ErrorLog</directive> directive). The following |
| <var>level</var>s are available, in order of decreasing |
| significance:</p> |
| |
| <table border="1"> |
| <columnspec><column width=".2"/><column width=".3"/><column width=".5"/> |
| </columnspec> |
| <tr> |
| <th><strong>Level</strong> </th> |
| |
| <th><strong>Description</strong> </th> |
| |
| <th><strong>Example</strong> </th> |
| </tr> |
| |
| <tr> |
| <td><code>emerg</code> </td> |
| |
| <td>Emergencies - system is unusable.</td> |
| |
| <td>"Child cannot open lock file. Exiting"</td> |
| </tr> |
| |
| <tr> |
| <td><code>alert</code> </td> |
| |
| <td>Action must be taken immediately.</td> |
| |
| <td>"getpwuid: couldn't determine user name from uid"</td> |
| </tr> |
| |
| <tr> |
| <td><code>crit</code> </td> |
| |
| <td>Critical Conditions.</td> |
| |
| <td>"socket: Failed to get a socket, exiting child"</td> |
| </tr> |
| |
| <tr> |
| <td><code>error</code> </td> |
| |
| <td>Error conditions.</td> |
| |
| <td>"Premature end of script headers"</td> |
| </tr> |
| |
| <tr> |
| <td><code>warn</code> </td> |
| |
| <td>Warning conditions.</td> |
| |
| <td>"child process 1234 did not exit, sending another |
| SIGHUP"</td> |
| </tr> |
| |
| <tr> |
| <td><code>notice</code> </td> |
| |
| <td>Normal but significant condition.</td> |
| |
| <td>"httpd: caught SIGBUS, attempting to dump core in |
| ..."</td> |
| </tr> |
| |
| <tr> |
| <td><code>info</code> </td> |
| |
| <td>Informational.</td> |
| |
| <td>"Server seems busy, (you may need to increase |
| StartServers, or Min/MaxSpareServers)..."</td> |
| </tr> |
| |
| <tr> |
| <td><code>debug</code> </td> |
| |
| <td>Debug-level messages</td> |
| |
| <td>"Opening config file ..."</td> |
| </tr> |
| <tr> |
| <td><code>trace1</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"proxy: FTP: control connection complete"</td> |
| </tr> |
| <tr> |
| <td><code>trace2</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"proxy: CONNECT: sending the CONNECT request to the remote proxy"</td> |
| </tr> |
| <tr> |
| <td><code>trace3</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"openssl: Handshake: start"</td> |
| </tr> |
| <tr> |
| <td><code>trace4</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"read from buffered SSL brigade, mode 0, 17 bytes"</td> |
| </tr> |
| <tr> |
| <td><code>trace5</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"map lookup FAILED: map=rewritemap key=keyname"</td> |
| </tr> |
| <tr> |
| <td><code>trace6</code> </td> |
| |
| <td>Trace messages</td> |
| |
| <td>"cache lookup FAILED, forcing new map lookup"</td> |
| </tr> |
| <tr> |
| <td><code>trace7</code> </td> |
| |
| <td>Trace messages, dumping large amounts of data</td> |
| |
| <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td> |
| </tr> |
| <tr> |
| <td><code>trace8</code> </td> |
| |
| <td>Trace messages, dumping large amounts of data</td> |
| |
| <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td> |
| </tr> |
| </table> |
| |
| <p>When a particular level is specified, messages from all |
| other levels of higher significance will be reported as well. |
| <em>E.g.</em>, when <code>LogLevel info</code> is specified, |
| then messages with log levels of <code>notice</code> and |
| <code>warn</code> will also be posted.</p> |
| |
| <p>Using a level of at least <code>crit</code> is |
| recommended.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| LogLevel notice |
| </highlight> |
| |
| <note><title>Note</title> |
| <p>When logging to a regular file, messages of the level |
| <code>notice</code> cannot be suppressed and thus are always |
| logged. However, this doesn't apply when logging is done |
| using <code>syslog</code>.</p> |
| </note> |
| |
| <p>Specifying a level without a module name will reset the level |
| for all modules to that level. Specifying a level with a module |
| name will set the level for that module only. It is possible to |
| use the module source file name, the module identifier, or the |
| module identifier with the trailing <code>_module</code> omitted |
| as module specification. This means the following three specifications |
| are equivalent:</p> |
| |
| <highlight language="config"> |
| LogLevel info ssl:warn |
| LogLevel info mod_ssl.c:warn |
| LogLevel info ssl_module:warn |
| </highlight> |
| |
| <p>It is also possible to change the level per directory:</p> |
| |
| <highlight language="config"> |
| LogLevel info |
| <Directory "/usr/local/apache/htdocs/app"> |
| LogLevel debug |
| </Directory> |
| </highlight> |
| |
| <note> |
| Per directory loglevel configuration only affects messages that are |
| logged after the request has been parsed and that are associated with |
| the request. Log messages which are associated with the connection or |
| the server are not affected. |
| </note> |
| </usage> |
| <seealso><directive module="core">ErrorLog</directive></seealso> |
| <seealso><directive module="core">ErrorLogFormat</directive></seealso> |
| <seealso><a href="../logs.html">Apache HTTP Server Log Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MaxKeepAliveRequests</name> |
| <description>Number of requests allowed on a persistent |
| connection</description> |
| <syntax>MaxKeepAliveRequests <var>number</var></syntax> |
| <default>MaxKeepAliveRequests 100</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>MaxKeepAliveRequests</directive> directive |
| limits the number of requests allowed per connection when |
| <directive module="core" >KeepAlive</directive> is on. If it is |
| set to <code>0</code>, unlimited requests will be allowed. We |
| recommend that this setting be kept to a high value for maximum |
| server performance.</p> |
| |
| <p>For example:</p> |
| |
| <highlight language="config"> |
| MaxKeepAliveRequests 500 |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MaxRanges</name> |
| <description>Number of ranges allowed before returning the complete |
| resource </description> |
| <syntax>MaxRanges default | unlimited | none | <var>number-of-ranges</var></syntax> |
| <default>MaxRanges 200</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Available in Apache HTTP Server 2.3.15 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>MaxRanges</directive> directive |
| limits the number of HTTP ranges the server is willing to |
| return to the client. If more ranges than permitted are requested, |
| the complete resource is returned instead.</p> |
| |
| <dl> |
| <dt><strong>default</strong></dt> |
| <dd>Limits the number of ranges to a compile-time default of 200.</dd> |
| |
| <dt><strong>none</strong></dt> |
| <dd>Range headers are ignored.</dd> |
| |
| <dt><strong>unlimited</strong></dt> |
| <dd>The server does not limit the number of ranges it is |
| willing to satisfy.</dd> |
| |
| <dt><var>number-of-ranges</var></dt> |
| <dd>A positive number representing the maximum number of ranges the |
| server is willing to satisfy.</dd> |
| </dl> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MaxRangeOverlaps</name> |
| <description>Number of overlapping ranges (eg: <code>100-200,150-300</code>) allowed before returning the complete |
| resource </description> |
| <syntax>MaxRangeOverlaps default | unlimited | none | <var>number-of-ranges</var></syntax> |
| <default>MaxRangeOverlaps 20</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Available in Apache HTTP Server 2.3.15 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>MaxRangeOverlaps</directive> directive |
| limits the number of overlapping HTTP ranges the server is willing to |
| return to the client. If more overlapping ranges than permitted are requested, |
| the complete resource is returned instead.</p> |
| |
| <dl> |
| <dt><strong>default</strong></dt> |
| <dd>Limits the number of overlapping ranges to a compile-time default of 20.</dd> |
| |
| <dt><strong>none</strong></dt> |
| <dd>No overlapping Range headers are allowed.</dd> |
| |
| <dt><strong>unlimited</strong></dt> |
| <dd>The server does not limit the number of overlapping ranges it is |
| willing to satisfy.</dd> |
| |
| <dt><var>number-of-ranges</var></dt> |
| <dd>A positive number representing the maximum number of overlapping ranges the |
| server is willing to satisfy.</dd> |
| </dl> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MaxRangeReversals</name> |
| <description>Number of range reversals (eg: <code>100-200,50-70</code>) allowed before returning the complete |
| resource </description> |
| <syntax>MaxRangeReversals default | unlimited | none | <var>number-of-ranges</var></syntax> |
| <default>MaxRangeReversals 20</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Available in Apache HTTP Server 2.3.15 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>MaxRangeReversals</directive> directive |
| limits the number of HTTP Range reversals the server is willing to |
| return to the client. If more ranges reversals than permitted are requested, |
| the complete resource is returned instead.</p> |
| |
| <dl> |
| <dt><strong>default</strong></dt> |
| <dd>Limits the number of range reversals to a compile-time default of 20.</dd> |
| |
| <dt><strong>none</strong></dt> |
| <dd>No Range reversals headers are allowed.</dd> |
| |
| <dt><strong>unlimited</strong></dt> |
| <dd>The server does not limit the number of range reversals it is |
| willing to satisfy.</dd> |
| |
| <dt><var>number-of-ranges</var></dt> |
| <dd>A positive number representing the maximum number of range reversals the |
| server is willing to satisfy.</dd> |
| </dl> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Mutex</name> |
| <description>Configures mutex mechanism and lock file directory for all |
| or specified mutexes</description> |
| <syntax>Mutex <var>mechanism</var> [default|<var>mutex-name</var>] ... [OmitPID]</syntax> |
| <default>Mutex default</default> |
| <contextlist><context>server config</context></contextlist> |
| <compatibility>Available in Apache HTTP Server 2.3.4 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>Mutex</directive> directive sets the mechanism, |
| and optionally the lock file location, that httpd and modules use |
| to serialize access to resources. Specify <code>default</code> as |
| the second argument to change the settings for all mutexes; specify |
| a mutex name (see table below) as the second argument to override |
| defaults only for that mutex.</p> |
| |
| <p>The <directive>Mutex</directive> directive is typically used in |
| the following exceptional situations:</p> |
| |
| <ul> |
| <li>change the mutex mechanism when the default mechanism selected |
| by <glossary>APR</glossary> has a functional or performance |
| problem</li> |
| |
| <li>change the directory used by file-based mutexes when the |
| default directory does not support locking</li> |
| </ul> |
| |
| <note><title>Supported modules</title> |
| <p>This directive only configures mutexes which have been registered |
| with the core server using the <code>ap_mutex_register()</code> API. |
| All modules bundled with httpd support the <directive>Mutex</directive> |
| directive, but third-party modules may not. Consult the documentation |
| of the third-party module, which must indicate the mutex name(s) which |
| can be configured if this directive is supported.</p> |
| </note> |
| |
| <p>The following mutex <em>mechanisms</em> are available:</p> |
| <ul> |
| <li><code>default | yes</code> |
| <p>This selects the default locking implementation, as determined by |
| <glossary>APR</glossary>. The default locking implementation can |
| be displayed by running <program>httpd</program> with the |
| <code>-V</code> option.</p></li> |
| |
| <li><code>none | no</code> |
| <p>This effectively disables the mutex, and is only allowed for a |
| mutex if the module indicates that it is a valid choice. Consult the |
| module documentation for more information.</p></li> |
| |
| <li><code>posixsem</code> |
| <p>This is a mutex variant based on a Posix semaphore.</p> |
| |
| <note type="warning"><title>Warning</title> |
| <p>The semaphore ownership is not recovered if a thread in the process |
| holding the mutex segfaults, resulting in a hang of the web server.</p> |
| </note> |
| </li> |
| |
| <li><code>sysvsem</code> |
| <p>This is a mutex variant based on a SystemV IPC semaphore.</p> |
| |
| <note type="warning"><title>Warning</title> |
| <p>It is possible to "leak" SysV semaphores if processes crash |
| before the semaphore is removed.</p> |
| </note> |
| |
| <note type="warning"><title>Security</title> |
| <p>The semaphore API allows for a denial of service attack by any |
| CGIs running under the same uid as the webserver (<em>i.e.</em>, |
| all CGIs, unless you use something like <program>suexec</program> |
| or <code>cgiwrapper</code>).</p> |
| </note> |
| </li> |
| |
| <li><code>sem</code> |
| <p>This selects the "best" available semaphore implementation, choosing |
| between Posix and SystemV IPC semaphores, in that order.</p></li> |
| |
| <li><code>pthread</code> |
| <p>This is a mutex variant based on cross-process Posix thread |
| mutexes.</p> |
| |
| <note type="warning"><title>Warning</title> |
| <p>On most systems, if a child process terminates abnormally while |
| holding a mutex that uses this implementation, the server will deadlock |
| and stop responding to requests. When this occurs, the server will |
| require a manual restart to recover.</p> |
| <p>Solaris and Linux are notable exceptions as they provide a mechanism which |
| usually allows the mutex to be recovered after a child process |
| terminates abnormally while holding a mutex.</p> |
| <p>If your system is POSIX compliant or if it implements the |
| <code>pthread_mutexattr_setrobust_np()</code> function, you may be able |
| to use the <code>pthread</code> option safely.</p> |
| </note> |
| </li> |
| |
| <li><code>fcntl:/path/to/mutex</code> |
| <p>This is a mutex variant where a physical (lock-)file and the |
| <code>fcntl()</code> function are used as the mutex.</p> |
| |
| <note type="warning"><title>Warning</title> |
| <p>When multiple mutexes based on this mechanism are used within |
| multi-threaded, multi-process environments, deadlock errors (EDEADLK) |
| can be reported for valid mutex operations if <code>fcntl()</code> |
| is not thread-aware, such as on Solaris.</p> |
| </note> |
| </li> |
| |
| <li><code>flock:/path/to/mutex</code> |
| <p>This is similar to the <code>fcntl:/path/to/mutex</code> method |
| with the exception that the <code>flock()</code> function is used to |
| provide file locking.</p></li> |
| |
| <li><code>file:/path/to/mutex</code> |
| <p>This selects the "best" available file locking implementation, |
| choosing between <code>fcntl</code> and <code>flock</code>, in that |
| order.</p></li> |
| </ul> |
| |
| <p>Most mechanisms are only available on selected platforms, where the |
| underlying platform and <glossary>APR</glossary> support it. Mechanisms |
| which aren't available on all platforms are <em>posixsem</em>, |
| <em>sysvsem</em>, <em>sem</em>, <em>pthread</em>, <em>fcntl</em>, |
| <em>flock</em>, and <em>file</em>.</p> |
| |
| <p>With the file-based mechanisms <em>fcntl</em> and <em>flock</em>, |
| the path, if provided, is a directory where the lock file will be created. |
| The default directory is httpd's run-time file directory relative to |
| <directive module="core">ServerRoot</directive>. Always use a local disk |
| filesystem for <code>/path/to/mutex</code> and never a directory residing |
| on a NFS- or AFS-filesystem. The basename of the file will be the mutex |
| type, an optional instance string provided by the module, and unless the |
| <code>OmitPID</code> keyword is specified, the process id of the httpd |
| parent process will be appended to make the file name unique, avoiding |
| conflicts when multiple httpd instances share a lock file directory. For |
| example, if the mutex name is <code>mpm-accept</code> and the lock file |
| directory is <code>/var/httpd/locks</code>, the lock file name for the |
| httpd instance with parent process id 12345 would be |
| <code>/var/httpd/locks/mpm-accept.12345</code>.</p> |
| |
| <note type="warning"><title>Security</title> |
| <p>It is best to <em>avoid</em> putting mutex files in a world-writable |
| directory such as <code>/var/tmp</code> because someone could create |
| a denial of service attack and prevent the server from starting by |
| creating a lockfile with the same name as the one the server will try |
| to create.</p> |
| </note> |
| |
| <p>The following table documents the names of mutexes used by httpd |
| and bundled modules.</p> |
| |
| <table border="1" style="zebra"> |
| <tr> |
| <th>Mutex name</th> |
| <th>Module(s)</th> |
| <th>Protected resource</th> |
| </tr> |
| <tr> |
| <td><code>mpm-accept</code></td> |
| <td><module>prefork</module> and <module>worker</module> MPMs</td> |
| <td>incoming connections, to avoid the thundering herd problem; |
| for more information, refer to the |
| <a href="../misc/perf-tuning.html">performance tuning</a> |
| documentation</td> |
| </tr> |
| <tr> |
| <td><code>authdigest-client</code></td> |
| <td><module>mod_auth_digest</module></td> |
| <td>client list in shared memory</td> |
| </tr> |
| <tr> |
| <td><code>authdigest-opaque</code></td> |
| <td><module>mod_auth_digest</module></td> |
| <td>counter in shared memory</td> |
| </tr> |
| <tr> |
| <td><code>ldap-cache</code></td> |
| <td><module>mod_ldap</module></td> |
| <td>LDAP result cache</td> |
| </tr> |
| <tr> |
| <td><code>rewrite-map</code></td> |
| <td><module>mod_rewrite</module></td> |
| <td>communication with external mapping programs, to avoid |
| intermixed I/O from multiple requests</td> |
| </tr> |
| <tr> |
| <td><code>ssl-cache</code></td> |
| <td><module>mod_ssl</module></td> |
| <td>SSL session cache</td> |
| </tr> |
| <tr> |
| <td><code>ssl-stapling</code></td> |
| <td><module>mod_ssl</module></td> |
| <td>OCSP stapling response cache</td> |
| </tr> |
| <tr> |
| <td><code>watchdog-callback</code></td> |
| <td><module>mod_watchdog</module></td> |
| <td>callback function of a particular client module</td> |
| </tr> |
| </table> |
| |
| <p>The <code>OmitPID</code> keyword suppresses the addition of the httpd |
| parent process id from the lock file name.</p> |
| |
| <p>In the following example, the mutex mechanism for the MPM accept |
| mutex will be changed from the compiled-in default to <code>fcntl</code>, |
| with the associated lock file created in directory |
| <code>/var/httpd/locks</code>. The mutex mechanism for all other mutexes |
| will be changed from the compiled-in default to <code>sysvsem</code>.</p> |
| |
| <highlight language="config"> |
| Mutex sysvsem default |
| Mutex fcntl:/var/httpd/locks mpm-accept |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>NameVirtualHost</name> |
| <description>DEPRECATED: Designates an IP address for name-virtual |
| hosting</description> |
| <syntax>NameVirtualHost <var>addr</var>[:<var>port</var>]</syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| |
| <p>Prior to 2.3.11, <directive>NameVirtualHost</directive> was required |
| to instruct the server that a particular IP address and port combination |
| was usable as a name-based virtual host. In 2.3.11 and later, |
| any time an IP address and port combination is used in multiple virtual |
| hosts, name-based virtual hosting is automatically enabled for that address.</p> |
| |
| <p>This directive currently has no effect.</p> |
| </usage> |
| |
| <seealso><a href="../vhosts/">Virtual Hosts |
| documentation</a></seealso> |
| |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Options</name> |
| <description>Configures what features are available in a particular |
| directory</description> |
| <syntax>Options |
| [+|-]<var>option</var> [[+|-]<var>option</var>] ...</syntax> |
| <default>Options FollowSymlinks</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>Options</override> |
| <compatibility>The default was changed from All to FollowSymlinks in 2.3.11</compatibility> |
| |
| <usage> |
| <p>The <directive>Options</directive> directive controls which |
| server features are available in a particular directory.</p> |
| |
| <p><var>option</var> can be set to <code>None</code>, in which |
| case none of the extra features are enabled, or one or more of |
| the following:</p> |
| |
| <dl> |
| <dt><code>All</code></dt> |
| |
| <dd>All options except for <code>MultiViews</code>.</dd> |
| |
| <dt><code>ExecCGI</code></dt> |
| |
| <dd> |
| Execution of CGI scripts using <module>mod_cgi</module> |
| is permitted.</dd> |
| |
| <dt><code>FollowSymLinks</code></dt> |
| |
| <dd> |
| The server will follow symbolic links in this directory. This is |
| the default setting. |
| <note> |
| <p>Even though the server follows the symlink it does <em>not</em> |
| change the pathname used to match against <directive type="section" |
| module="core">Directory</directive> sections.</p> |
| |
| <p>The <code>FollowSymLinks</code> and |
| <code>SymLinksIfOwnerMatch</code> <directive |
| module="core">Options</directive> work only in <directive |
| type="section" module="core">Directory</directive> sections or |
| <code>.htaccess</code> files.</p> |
| |
| <p>Omitting this option should not be considered a security restriction, |
| since symlink testing is subject to race conditions that make it |
| circumventable.</p> |
| </note></dd> |
| |
| <dt><code>Includes</code></dt> |
| |
| <dd> |
| Server-side includes provided by <module>mod_include</module> |
| are permitted.</dd> |
| |
| <dt><code>IncludesNOEXEC</code></dt> |
| |
| <dd> |
| |
| Server-side includes are permitted, but the <code>#exec |
| cmd</code> and <code>#exec cgi</code> are disabled. It is still |
| possible to <code>#include virtual</code> CGI scripts from |
| <directive module="mod_alias">ScriptAlias</directive>ed |
| directories.</dd> |
| |
| <dt><code>Indexes</code></dt> |
| |
| <dd> |
| If a URL which maps to a directory is requested and there |
| is no <directive module="mod_dir">DirectoryIndex</directive> |
| (<em>e.g.</em>, <code>index.html</code>) in that directory, then |
| <module>mod_autoindex</module> will return a formatted listing |
| of the directory.</dd> |
| |
| <dt><code>MultiViews</code></dt> |
| |
| <dd> |
| <a href="../content-negotiation.html">Content negotiated</a> |
| "MultiViews" are allowed using |
| <module>mod_negotiation</module>. |
| <note><title>Note</title> <p>This option gets ignored if set |
| anywhere other than <directive module="core" type="section" |
| >Directory</directive>, as <module>mod_negotiation</module> |
| needs real resources to compare against and evaluate from.</p></note> |
| </dd> |
| |
| <dt><code>SymLinksIfOwnerMatch</code></dt> |
| |
| <dd>The server will only follow symbolic links for which the |
| target file or directory is owned by the same user id as the |
| link. |
| |
| <note><title>Note</title> |
| <p>The <code>FollowSymLinks</code> and |
| <code>SymLinksIfOwnerMatch</code> <directive |
| module="core">Options</directive> work only in <directive |
| type="section" module="core">Directory</directive> sections or |
| <code>.htaccess</code> files.</p> |
| |
| <p>This option should not be considered a security restriction, |
| since symlink testing is subject to race conditions that make it |
| circumventable.</p> |
| </note> </dd> |
| </dl> |
| |
| <p>Normally, if multiple <directive>Options</directive> could |
| apply to a directory, then the most specific one is used and |
| others are ignored; the options are not merged. (See <a |
| href="../sections.html#merging">how sections are merged</a>.) |
| However if <em>all</em> the options on the |
| <directive>Options</directive> directive are preceded by a |
| <code>+</code> or <code>-</code> symbol, the options are |
| merged. Any options preceded by a <code>+</code> are added to the |
| options currently in force, and any options preceded by a |
| <code>-</code> are removed from the options currently in |
| force. </p> |
| |
| <note><title>Note</title> |
| <p>Mixing <directive>Options</directive> with a <code>+</code> or |
| <code>-</code> with those without is not valid syntax and will be |
| rejected during server startup by the syntax check with an abort.</p> |
| </note> |
| |
| <p>For example, without any <code>+</code> and <code>-</code> symbols:</p> |
| |
| <highlight language="config"> |
| <Directory "/web/docs"> |
| Options Indexes FollowSymLinks |
| </Directory> |
| |
| <Directory "/web/docs/spec"> |
| Options Includes |
| </Directory> |
| </highlight> |
| |
| <p>then only <code>Includes</code> will be set for the |
| <code>/web/docs/spec</code> directory. However if the second |
| <directive>Options</directive> directive uses the <code>+</code> and |
| <code>-</code> symbols:</p> |
| |
| <highlight language="config"> |
| <Directory "/web/docs"> |
| Options Indexes FollowSymLinks |
| </Directory> |
| |
| <Directory "/web/docs/spec"> |
| Options +Includes -Indexes |
| </Directory> |
| </highlight> |
| |
| <p>then the options <code>FollowSymLinks</code> and |
| <code>Includes</code> are set for the <code>/web/docs/spec</code> |
| directory.</p> |
| |
| <note><title>Note</title> |
| <p>Using <code>-IncludesNOEXEC</code> or |
| <code>-Includes</code> disables server-side includes completely |
| regardless of the previous setting.</p> |
| </note> |
| |
| <p>The default in the absence of any other settings is |
| <code>FollowSymlinks</code>.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Protocol</name> |
| <description>Protocol for a listening socket</description> |
| <syntax>Protocol <var>protocol</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| <compatibility>Available in Apache 2.1.5 and later. |
| On Windows, from Apache 2.3.3 and later.</compatibility> |
| |
| <usage> |
| <p>This directive specifies the protocol used for a specific listening socket. |
| The protocol is used to determine which module should handle a request and |
| to apply protocol specific optimizations with the <directive>AcceptFilter</directive> |
| directive.</p> |
| |
| <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> |
| |
| <p>For example, if you are running <code>https</code> on a non-standard port, |
| specify the protocol explicitly:</p> |
| |
| <highlight language="config"> |
| Protocol https |
| </highlight> |
| |
| <p>You can also specify the protocol using the <directive module="mpm_common">Listen</directive> directive.</p> |
| </usage> |
| <seealso><directive module="core">AcceptFilter</directive></seealso> |
| <seealso><directive module="mpm_common">Listen</directive></seealso> |
| </directivesynopsis> |
| |
| |
| <directivesynopsis> |
| <name>Protocols</name> |
| <description>Protocols available for a server/virtual host</description> |
| <syntax>Protocols <var>protocol</var> ...</syntax> |
| <default>Protocols http/1.1</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| <compatibility>Only available from Apache 2.4.17 and later.</compatibility> |
| |
| <usage> |
| <p>This directive specifies the list of protocols supported for a |
| server/virtual host. The list determines the allowed protocols |
| a client may negotiate for this server/host.</p> |
| |
| <p>You need to set protocols if you want to extend the available |
| protocols for a server/host. By default, only the http/1.1 protocol |
| (which includes the compatibility with 1.0 and 0.9 clients) is |
| allowed.</p> |
| |
| <p>For example, if you want to support HTTP/2 for a server with TLS, |
| specify:</p> |
| |
| <highlight language="config"> |
| Protocols h2 http/1.1 |
| </highlight> |
| |
| <p>Valid protocols are <code>http/1.1</code> for http and https connections, |
| <code>h2</code> on https connections and <code>h2c</code> for http |
| connections. Modules may enable more protocols.</p> |
| |
| <p>It is safe to specify protocols that are unavailable/disabled. Such |
| protocol names will simply be ignored.</p> |
| |
| <p>Protocols specified in base servers are inherited for virtual hosts |
| only if the virtual host has no own Protocols directive. Or, the other |
| way around, Protocols directives in virtual hosts replace any |
| such directive in the base server. |
| </p> |
| |
| </usage> |
| <seealso><directive module="core">ProtocolsHonorOrder</directive></seealso> |
| </directivesynopsis> |
| |
| |
| <directivesynopsis> |
| <name>ProtocolsHonorOrder</name> |
| <description>Determines if order of Protocols determines precedence during negotiation</description> |
| <syntax>ProtocolsHonorOrder On|Off</syntax> |
| <default>ProtocolsHonorOrder On</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| <compatibility>Only available from Apache 2.4.17 and later.</compatibility> |
| |
| <usage> |
| <p>This directive specifies if the server should honor the order in which |
| the <directive>Protocols</directive> directive lists protocols.</p> |
| |
| <p>If configured Off, the client supplied list order of protocols has |
| precedence over the order in the server configuration.</p> |
| |
| <p>With <directive>ProtocolsHonorOrder</directive> set to <code>on</code> |
| (default), the client ordering does not matter and only the ordering |
| in the server settings influences the outcome of the protocol |
| negotiation.</p> |
| |
| </usage> |
| <seealso><directive module="core">Protocols</directive></seealso> |
| </directivesynopsis> |
| |
| |
| <directivesynopsis> |
| <name>RegexDefaultOptions</name> |
| <description>Allow to configure global/default options for regexes</description> |
| <syntax>RegexDefaultOptions [none] [+|-]<var>option</var> [[+|-]<var>option</var>] ...</syntax> |
| <default>RegexDefaultOptions DOLLAR_ENDONLY</default> |
| <contextlist><context>server config</context></contextlist> |
| <compatibility>Only available from Apache 2.4.30 and later.</compatibility> |
| |
| <usage> |
| <p>This directive adds some default behavior to ANY regular expression |
| used afterwards.</p> |
| |
| <p>Any option preceded by a '+' is added to the already set options.<br /> |
| Any option preceded by a '-' is removed from the already set options.<br /> |
| Any option without a '+' or a '-' will be set, removing any other |
| already set option.<br /> |
| The <code>none</code> keyword resets any already set options.</p> |
| |
| <p><var>option</var> can be:</p> |
| <dl> |
| <dt><code>ICASE</code></dt> |
| <dd>Use a case-insensitive match.</dd> |
| |
| <dt><code>DOTALL</code></dt> |
| <dd>Perl's /s flag.</dd> |
| |
| <dt><code>DOLLAR_ENDONLY</code></dt> |
| <dd>'$' matches at end of subject string only.</dd> |
| <dd>.</dd> |
| </dl> |
| <highlight language="config"> |
| # |
| RegexDefaultOptions +ICASE +DOLLAR_ENDONLY |
| ... |
| # Remove the ICASE option, but keep all the other already set options |
| RegexDefaultOptions -ICASE |
| ... |
| # Set the default option to DOTALL, resetting any other option |
| RegexDefaultOptions DOTALL |
| ... |
| # Reset all defined option |
| RegexDefaultOptions none |
| ... |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| |
| <directivesynopsis> |
| <name>RLimitCPU</name> |
| <description>Limits the CPU consumption of processes launched |
| by Apache httpd children</description> |
| <syntax>RLimitCPU <var>seconds</var>|max [<var>seconds</var>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>Takes 1 or 2 parameters. The first parameter sets the soft |
| resource limit for all processes and the second parameter sets |
| the maximum resource limit. Either parameter can be a number, |
| or <code>max</code> to indicate to the server that the limit should |
| be set to the maximum allowed by the operating system |
| configuration. Raising the maximum resource limit requires that |
| the server is running as <code>root</code> or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked from Apache httpd children |
| servicing requests, not the Apache httpd children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked from the Apache httpd parent, such as piped |
| logs.</p> |
| |
| <p>CPU resource limits are expressed in seconds per |
| process.</p> |
| </usage> |
| <seealso><directive module="core">RLimitMEM</directive></seealso> |
| <seealso><directive module="core">RLimitNPROC</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>RLimitMEM</name> |
| <description>Limits the memory consumption of processes launched |
| by Apache httpd children</description> |
| <syntax>RLimitMEM <var>bytes</var>|max [<var>bytes</var>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>Takes 1 or 2 parameters. The first parameter sets the soft |
| resource limit for all processes and the second parameter sets |
| the maximum resource limit. Either parameter can be a number, |
| or <code>max</code> to indicate to the server that the limit should |
| be set to the maximum allowed by the operating system |
| configuration. Raising the maximum resource limit requires that |
| the server is running as <code>root</code> or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked from Apache httpd children |
| servicing requests, not the Apache httpd children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked from the Apache httpd parent, such as piped |
| logs.</p> |
| |
| <p>Memory resource limits are expressed in bytes per |
| process.</p> |
| </usage> |
| <seealso><directive module="core">RLimitCPU</directive></seealso> |
| <seealso><directive module="core">RLimitNPROC</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>RLimitNPROC</name> |
| <description>Limits the number of processes that can be launched by |
| processes launched by Apache httpd children</description> |
| <syntax>RLimitNPROC <var>number</var>|max [<var>number</var>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>Takes 1 or 2 parameters. The first parameter sets the soft |
| resource limit for all processes, and the second parameter sets |
| the maximum resource limit. Either parameter can be a number, |
| or <code>max</code> to indicate to the server that the limit |
| should be set to the maximum allowed by the operating system |
| configuration. Raising the maximum resource limit requires that |
| the server is running as <code>root</code> or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked from Apache httpd children |
| servicing requests, not the Apache httpd children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked from the Apache httpd parent, such as piped |
| logs.</p> |
| |
| <p>Process limits control the number of processes per user.</p> |
| |
| <note><title>Note</title> |
| <p>If CGI processes are <strong>not</strong> running |
| under user ids other than the web server user id, this directive |
| will limit the number of processes that the server itself can |
| create. Evidence of this situation will be indicated by |
| <strong><code>cannot fork</code></strong> messages in the |
| <code>error_log</code>.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">RLimitMEM</directive></seealso> |
| <seealso><directive module="core">RLimitCPU</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ScriptInterpreterSource</name> |
| <description>Technique for locating the interpreter for CGI |
| scripts</description> |
| <syntax>ScriptInterpreterSource Registry|Registry-Strict|Script</syntax> |
| <default>ScriptInterpreterSource Script</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| <compatibility>Win32 only.</compatibility> |
| |
| <usage> |
| <p>This directive is used to control how Apache httpd finds the |
| interpreter used to run CGI scripts. The default setting is |
| <code>Script</code>. This causes Apache httpd to use the interpreter pointed to |
| by the shebang line (first line, starting with <code>#!</code>) in the |
| script. On Win32 systems this line usually looks like:</p> |
| |
| <highlight language="perl"> |
| #!C:/Perl/bin/perl.exe |
| </highlight> |
| |
| <p>or, if <code>perl</code> is in the <code>PATH</code>, simply:</p> |
| |
| <highlight language="perl"> |
| #!perl |
| </highlight> |
| |
| <p>Setting <code>ScriptInterpreterSource Registry</code> will |
| cause the Windows Registry tree <code>HKEY_CLASSES_ROOT</code> to be |
| searched using the script file extension (e.g., <code>.pl</code>) as a |
| search key. The command defined by the registry subkey |
| <code>Shell\ExecCGI\Command</code> or, if it does not exist, by the subkey |
| <code>Shell\Open\Command</code> is used to open the script file. If the |
| registry keys cannot be found, Apache httpd falls back to the behavior of the |
| <code>Script</code> option.</p> |
| |
| <note type="warning"><title>Security</title> |
| <p>Be careful when using <code>ScriptInterpreterSource |
| Registry</code> with <directive |
| module="mod_alias">ScriptAlias</directive>'ed directories, because |
| Apache httpd will try to execute <strong>every</strong> file within this |
| directory. The <code>Registry</code> setting may cause undesired |
| program calls on files which are typically not executed. For |
| example, the default open command on <code>.htm</code> files on |
| most Windows systems will execute Microsoft Internet Explorer, so |
| any HTTP request for an <code>.htm</code> file existing within the |
| script directory would start the browser in the background on the |
| server. This is a good way to crash your system within a minute or |
| so.</p> |
| </note> |
| |
| <p>The option <code>Registry-Strict</code> which is new in Apache HTTP Server |
| 2.0 does the same thing as <code>Registry</code> but uses only the |
| subkey <code>Shell\ExecCGI\Command</code>. The |
| <code>ExecCGI</code> key is not a common one. It must be |
| configured manually in the windows registry and hence prevents |
| accidental program calls on your system.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SeeRequestTail</name> |
| <description>Determine if mod_status displays the first 63 characters |
| of a request or the last 63, assuming the request itself is greater than |
| 63 chars.</description> |
| <syntax>SeeRequestTail On|Off</syntax> |
| <default>SeeRequestTail Off</default> |
| <contextlist><context>server config</context></contextlist> |
| <compatibility>Available in Apache httpd 2.2.7 and later.</compatibility> |
| |
| <usage> |
| <p>mod_status with <code>ExtendedStatus On</code> |
| displays the actual request being handled. |
| For historical purposes, only 63 characters of the request |
| are actually stored for display purposes. This directive |
| controls whether the 1st 63 characters are stored (the previous |
| behavior and the default) or if the last 63 characters are. This |
| is only applicable, of course, if the length of the request is |
| 64 characters or greater.</p> |
| |
| <p>If Apache httpd is handling <code |
| >GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</code |
| > mod_status displays as follows: |
| </p> |
| |
| <table border="1"> |
| <tr> |
| <th>Off (default)</th> |
| <td>GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples</td> |
| </tr> |
| <tr> |
| <th>On</th> |
| <td>orage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</td> |
| </tr> |
| </table> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerAdmin</name> |
| <description>Email address that the server includes in error |
| messages sent to the client</description> |
| <syntax>ServerAdmin <var>email-address</var>|<var>URL</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ServerAdmin</directive> sets the contact address |
| that the server includes in any error messages it returns to the |
| client. If the <code>httpd</code> doesn't recognize the supplied argument |
| as an URL, it |
| assumes, that it's an <var>email-address</var> and prepends it with |
| <code>mailto:</code> in hyperlink targets. However, it's recommended to |
| actually use an email address, since there are a lot of CGI scripts that |
| make that assumption. If you want to use an URL, it should point to another |
| server under your control. Otherwise users may not be able to contact you in |
| case of errors.</p> |
| |
| <p>It may be worth setting up a dedicated address for this, e.g.</p> |
| |
| <highlight language="config"> |
| ServerAdmin www-admin@foo.example.com |
| </highlight> |
| <p>as users do not always mention that they are talking about the |
| server!</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerAlias</name> |
| <description>Alternate names for a host used when matching requests |
| to name-virtual hosts</description> |
| <syntax>ServerAlias <var>hostname</var> [<var>hostname</var>] ...</syntax> |
| <contextlist><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>The <directive>ServerAlias</directive> directive sets the |
| alternate names for a host, for use with <a |
| href="../vhosts/name-based.html">name-based virtual hosts</a>. The |
| <directive>ServerAlias</directive> may include wildcards, if appropriate.</p> |
| |
| <highlight language="config"> |
| <VirtualHost *:80> |
| ServerName server.example.com |
| ServerAlias server server2.example.com server2 |
| ServerAlias *.example.com |
| UseCanonicalName Off |
| # ... |
| </VirtualHost> |
| </highlight> |
| |
| <p>Name-based virtual hosts for the best-matching set of <directive |
| type="section" module="core">virtualhost</directive>s are processed |
| in the order they appear in the configuration. The first matching <directive |
| module="core">ServerName</directive> or <directive module="core" |
| >ServerAlias</directive> is used, with no different precedence for wildcards |
| (nor for ServerName vs. ServerAlias). </p> |
| |
| <p>The complete list of names in the <directive type="section" module="core" |
| >VirtualHost</directive> |
| directive are treated just like a (non wildcard) |
| <directive>ServerAlias</directive>.</p> |
| |
| </usage> |
| <seealso><directive module="core">UseCanonicalName</directive></seealso> |
| <seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerName</name> |
| <description>Hostname and port that the server uses to identify |
| itself</description> |
| <syntax>ServerName [<var>scheme</var>://]<var>domain-name</var>|<var>ip-address</var>[:<var>port</var>]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ServerName</directive> directive sets the |
| request scheme, hostname and port that the server uses to identify itself. |
| </p> |
| |
| <p><directive>ServerName</directive> is used (possibly |
| in conjunction with <directive module="core">ServerAlias</directive>) to uniquely |
| identify a virtual host, when using <a |
| href="../vhosts/name-based.html">name-based virtual hosts</a>.</p> |
| |
| <p>Additionally, this is used when |
| creating self-referential redirection URLs when |
| <directive module="core">UseCanonicalName</directive> is set to a non-default |
| value.</p> |
| |
| <p>For example, if the name of the |
| machine hosting the web server is <code>simple.example.com</code>, |
| but the machine also has the DNS alias <code>www.example.com</code> |
| and you wish the web server to be so identified, the following |
| directive should be used:</p> |
| |
| <highlight language="config"> |
| ServerName www.example.com |
| </highlight> |
| |
| <p>The <directive>ServerName</directive> directive |
| may appear anywhere within the definition of a server. However, |
| each appearance overrides the previous appearance (within that |
| server).</p> |
| |
| <p>If no <directive>ServerName</directive> is specified, the |
| server attempts to deduce the client visible hostname by first asking |
| the operating system for the system hostname, and if that fails, |
| performing a reverse lookup on an IP address present on the system.</p> |
| |
| <p>If no port is specified in the |
| <directive>ServerName</directive>, then the server will use the |
| port from the incoming request. For optimal reliability and |
| predictability, you should specify an explicit hostname and port |
| using the <directive>ServerName</directive> directive.</p> |
| |
| <p>If you are using <a |
| href="../vhosts/name-based.html">name-based virtual hosts</a>, |
| the <directive>ServerName</directive> inside a |
| <directive type="section" module="core">VirtualHost</directive> |
| section specifies what hostname must appear in the request's |
| <code>Host:</code> header to match this virtual host.</p> |
| |
| <p>Sometimes, the server runs behind a device that processes SSL, |
| such as a reverse proxy, load balancer or SSL offload |
| appliance. When this is the case, specify the |
| <code>https://</code> scheme and the port number to which the |
| clients connect in the <directive>ServerName</directive> directive |
| to make sure that the server generates the correct |
| self-referential URLs. |
| </p> |
| |
| <p>See the description of the |
| <directive module="core">UseCanonicalName</directive> and |
| <directive module="core">UseCanonicalPhysicalPort</directive> directives for |
| settings which determine whether self-referential URLs (e.g., by the |
| <module>mod_dir</module> module) will refer to the |
| specified port, or to the port number given in the client's request. |
| </p> |
| |
| <note type="warning"> |
| <p>Failure to set <directive>ServerName</directive> to a name that |
| your server can resolve to an IP address will result in a startup |
| warning. <code>httpd</code> will then use whatever hostname it can |
| determine, using the system's <code>hostname</code> command. This |
| will almost never be the hostname you actually want.</p> |
| <example> |
| httpd: Could not reliably determine the server's fully qualified domain name, using rocinante.local for ServerName |
| </example> |
| </note> |
| |
| </usage> |
| |
| <seealso><a href="../dns-caveats.html">Issues Regarding DNS and |
| Apache HTTP Server</a></seealso> |
| <seealso><a href="../vhosts/">Apache HTTP Server virtual host |
| documentation</a></seealso> |
| <seealso><directive module="core">UseCanonicalName</directive></seealso> |
| <seealso><directive module="core">UseCanonicalPhysicalPort</directive></seealso> |
| <seealso><directive module="core">ServerAlias</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerPath</name> |
| <description>Legacy URL pathname for a name-based virtual host that |
| is accessed by an incompatible browser</description> |
| <syntax>ServerPath <var>URL-path</var></syntax> |
| <contextlist><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>The <directive>ServerPath</directive> directive sets the legacy |
| URL pathname for a host, for use with <a |
| href="../vhosts/">name-based virtual hosts</a>.</p> |
| </usage> |
| <seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerRoot</name> |
| <description>Base directory for the server installation</description> |
| <syntax>ServerRoot <var>directory-path</var></syntax> |
| <default>ServerRoot /usr/local/apache</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The <directive>ServerRoot</directive> directive sets the |
| directory in which the server lives. Typically it will contain the |
| subdirectories <code>conf/</code> and <code>logs/</code>. Relative |
| paths in other configuration directives (such as <directive |
| module="core">Include</directive> or <directive |
| module="mod_so">LoadModule</directive>, for example) are taken as |
| relative to this directory.</p> |
| |
| <highlight language="config"> |
| ServerRoot "/home/httpd" |
| </highlight> |
| |
| <p>The default location of <directive>ServerRoot</directive> may be |
| modified by using the <code>--prefix</code> argument to |
| <a href="../programs/configure.html"><code>configure</code></a>, and |
| most third-party distributions of the server have a different |
| default location from the one listed above.</p> |
| |
| </usage> |
| <seealso><a href="../invoking.html">the <code>-d</code> |
| option to <code>httpd</code></a></seealso> |
| <seealso><a href="../misc/security_tips.html#serverroot">the |
| security tips</a> for information on how to properly set |
| permissions on the <directive>ServerRoot</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerSignature</name> |
| <description>Configures the footer on server-generated documents</description> |
| <syntax>ServerSignature On|Off|EMail</syntax> |
| <default>ServerSignature Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive>ServerSignature</directive> directive allows the |
| configuration of a trailing footer line under server-generated |
| documents (error messages, <module>mod_proxy</module> ftp directory |
| listings, <module>mod_info</module> output, ...). The reason why you |
| would want to enable such a footer line is that in a chain of proxies, |
| the user often has no possibility to tell which of the chained servers |
| actually produced a returned error message.</p> |
| |
| <p>The <code>Off</code> |
| setting, which is the default, suppresses the footer line (and is |
| therefore compatible with the behavior of Apache-1.2 and |
| below). The <code>On</code> setting simply adds a line with the |
| server version number and <directive |
| module="core">ServerName</directive> of the serving virtual host, |
| and the <code>EMail</code> setting additionally creates a |
| "mailto:" reference to the <directive |
| module="core">ServerAdmin</directive> of the referenced |
| document.</p> |
| |
| <p>After version 2.0.44, the details of the server version number |
| presented are controlled by the <directive |
| module="core">ServerTokens</directive> directive.</p> |
| </usage> |
| <seealso><directive module="core">ServerTokens</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerTokens</name> |
| <description>Configures the <code>Server</code> HTTP response |
| header</description> |
| <syntax>ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full</syntax> |
| <default>ServerTokens Full</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive controls whether <code>Server</code> response |
| header field which is sent back to clients includes a |
| description of the generic OS-type of the server as well as |
| information about compiled-in modules.</p> |
| |
| <dl> |
| <dt><code>ServerTokens Full</code> (or not specified)</dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2 |
| (Unix) PHP/4.2.2 MyMod/1.2</code></dd> |
| |
| <dt><code>ServerTokens Prod[uctOnly]</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: |
| Apache</code></dd> |
| |
| <dt><code>ServerTokens Major</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: |
| Apache/2</code></dd> |
| |
| <dt><code>ServerTokens Minor</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: |
| Apache/2.4</code></dd> |
| |
| <dt><code>ServerTokens Min[imal]</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: |
| Apache/2.4.2</code></dd> |
| |
| <dt><code>ServerTokens OS</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.2 |
| (Unix)</code></dd> |
| |
| </dl> |
| |
| <p>This setting applies to the entire server, and cannot be |
| enabled or disabled on a virtualhost-by-virtualhost basis.</p> |
| |
| <p>After version 2.0.44, this directive also controls the |
| information presented by the <directive |
| module="core">ServerSignature</directive> directive.</p> |
| |
| <note>Setting <directive>ServerTokens</directive> to less than |
| <code>minimal</code> is not recommended because it makes it more |
| difficult to debug interoperational problems. Also note that |
| disabling the Server: header does nothing at all to make your |
| server more secure. The idea of "security through obscurity" |
| is a myth and leads to a false sense of safety.</note> |
| |
| </usage> |
| <seealso><directive module="core">ServerSignature</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SetHandler</name> |
| <description>Forces all matching files to be processed by a |
| handler</description> |
| <syntax>SetHandler <var>handler-name</var>|none|<var>expression</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>expression argument 2.4.19 and later</compatibility> |
| |
| <usage> |
| <p>When placed into an <code>.htaccess</code> file or a |
| <directive type="section" module="core">Directory</directive> or |
| <directive type="section" module="core">Location</directive> |
| section, this directive forces all matching files to be parsed |
| through the <a href="../handler.html">handler</a> given by |
| <var>handler-name</var>. For example, if you had a directory you |
| wanted to be parsed entirely as imagemap rule files, regardless |
| of extension, you might put the following into an |
| <code>.htaccess</code> file in that directory:</p> |
| |
| <highlight language="config"> |
| SetHandler imap-file |
| </highlight> |
| |
| <p>Another example: if you wanted to have the server display a |
| status report whenever a URL of |
| <code>http://servername/status</code> was called, you might put |
| the following into <code>httpd.conf</code>:</p> |
| |
| <highlight language="config"> |
| <Location "/status"> |
| SetHandler server-status |
| </Location> |
| </highlight> |
| |
| <p>You could also use this directive to configure a particular |
| handler for files with a particular file extension. For example:</p> |
| |
| <highlight language="config"> |
| <FilesMatch "\.php$"> |
| SetHandler application/x-httpd-php |
| </FilesMatch> |
| </highlight> |
| |
| <p>String-valued expressions can be used to reference per-request |
| variables, including backreferences to named regular expressions:</p> |
| |
| <highlight language="config"> |
| <LocationMatch ^/app/(?<sub>[^/]+)/> |
| SetHandler "proxy:unix:/var/run/app_%{env:MATCH_sub}.sock|fcgi://localhost:8080" |
| </LocationMatch> |
| </highlight> |
| |
| <p>You can override an earlier defined <directive>SetHandler</directive> |
| directive by using the value <code>None</code>.</p> |
| |
| <note><title>Note</title> |
| <p>Because <directive>SetHandler</directive> overrides default handlers, |
| normal behavior such as handling of URLs ending in a slash (/) as |
| directories or index files is suppressed.</p></note> |
| </usage> |
| |
| <seealso><directive module="mod_mime">AddHandler</directive></seealso> |
| |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SetInputFilter</name> |
| <description>Sets the filters that will process client requests and POST |
| input</description> |
| <syntax>SetInputFilter <var>filter</var>[;<var>filter</var>...]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>The <directive>SetInputFilter</directive> directive sets the |
| filter or filters which will process client requests and POST |
| input when they are received by the server. This is in addition to |
| any filters defined elsewhere, including the |
| <directive module="mod_mime">AddInputFilter</directive> |
| directive.</p> |
| |
| <p>If more than one filter is specified, they must be separated |
| by semicolons in the order in which they should process the |
| content.</p> |
| </usage> |
| <seealso><a href="../filter.html">Filters</a> documentation</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SetOutputFilter</name> |
| <description>Sets the filters that will process responses from the |
| server</description> |
| <syntax>SetOutputFilter <var>filter</var>[;<var>filter</var>...]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>The <directive>SetOutputFilter</directive> directive sets the filters |
| which will process responses from the server before they are |
| sent to the client. This is in addition to any filters defined |
| elsewhere, including the |
| <directive module="mod_mime">AddOutputFilter</directive> |
| directive.</p> |
| |
| <p>For example, the following configuration will process all files |
| in the <code>/www/data/</code> directory for server-side |
| includes.</p> |
| |
| <highlight language="config"> |
| <Directory "/www/data/"> |
| SetOutputFilter INCLUDES |
| </Directory> |
| </highlight> |
| |
| <p>If more than one filter is specified, they must be separated |
| by semicolons in the order in which they should process the |
| content.</p> |
| </usage> |
| <seealso><a href="../filter.html">Filters</a> documentation</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>TimeOut</name> |
| <description>Amount of time the server will wait for |
| certain events before failing a request</description> |
| <syntax>TimeOut <var>seconds</var></syntax> |
| <default>TimeOut 60</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>The <directive>TimeOut</directive> directive defines the length |
| of time Apache httpd will wait for I/O in various circumstances:</p> |
| |
| <ul> |
| <li><p>When reading data from the client, the length of time to |
| wait for a TCP packet to arrive if the read buffer is |
| empty.</p> |
| <p> For initial data on a new connection, this directive doesn't |
| take effect until after any configured <directive module="core"> |
| AcceptFilter</directive> has passed the new connection to the server.</p> |
| </li> |
| |
| <li>When writing data to the client, the length of time to wait |
| for an acknowledgement of a packet if the send buffer is |
| full.</li> |
| |
| <li>In <module>mod_cgi</module> and <module>mod_cgid</module>, |
| the length of time to wait for any individual block of output |
| from a CGI script.</li> |
| |
| <li>In <module>mod_ext_filter</module>, the length of time to |
| wait for output from a filtering process.</li> |
| |
| <li>In <module>mod_proxy</module>, the default timeout value if |
| <directive module="mod_proxy">ProxyTimeout</directive> is not |
| configured.</li> |
| </ul> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>TraceEnable</name> |
| <description>Determines the behavior on <code>TRACE</code> requests</description> |
| <syntax>TraceEnable <var>[on|off|extended]</var></syntax> |
| <default>TraceEnable on</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>This directive overrides the behavior of <code>TRACE</code> for both |
| the core server and <module>mod_proxy</module>. The default |
| <code>TraceEnable on</code> permits <code>TRACE</code> requests per |
| RFC 2616, which disallows any request body to accompany the request. |
| <code>TraceEnable off</code> causes the core server and |
| <module>mod_proxy</module> to return a <code>405</code> (Method not |
| allowed) error to the client.</p> |
| |
| <p>Finally, for testing and diagnostic purposes only, request |
| bodies may be allowed using the non-compliant <code>TraceEnable |
| extended</code> directive. The core (as an origin server) will |
| restrict the request body to 64Kb (plus 8Kb for chunk headers if |
| <code>Transfer-Encoding: chunked</code> is used). The core will |
| reflect the full headers and all chunk headers with the response |
| body. As a proxy server, the request body is not restricted to 64Kb.</p> |
| |
| <note><title>Note</title> |
| |
| <p>Despite claims to the contrary, enabling the <code>TRACE</code> |
| method does not expose any security vulnerability in Apache httpd. |
| The <code>TRACE</code> method is defined by the HTTP/1.1 |
| specification and implementations are expected to support it.</p> |
| |
| </note> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>UnDefine</name> |
| <description>Undefine the existence of a variable</description> |
| <syntax>UnDefine <var>parameter-name</var></syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>Undoes the effect of a <directive module="core">Define</directive> or |
| of passing a <code>-D</code> argument to <program>httpd</program>.</p> |
| <p>This directive can be used to toggle the use of <directive module="core" |
| type="section">IfDefine</directive> sections without needing to alter |
| <code>-D</code> arguments in any startup scripts.</p> |
| <p>While this directive is supported in virtual host context, |
| the changes it makes are visible to any later configuration |
| directives, beyond any enclosing virtual host.</p> |
| </usage> |
| <seealso><directive module="core">Define</directive></seealso> |
| <seealso><directive module="core">IfDefine</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>UseCanonicalName</name> |
| <description>Configures how the server determines its own name and |
| port</description> |
| <syntax>UseCanonicalName On|Off|DNS</syntax> |
| <default>UseCanonicalName Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context></contextlist> |
| |
| <usage> |
| <p>In many situations Apache httpd must construct a <em>self-referential</em> |
| URL -- that is, a URL that refers back to the same server. With |
| <code>UseCanonicalName On</code> Apache httpd will use the hostname and port |
| specified in the <directive module="core">ServerName</directive> |
| directive to construct the canonical name for the server. This name |
| is used in all self-referential URLs, and for the values of |
| <code>SERVER_NAME</code> and <code>SERVER_PORT</code> in CGIs.</p> |
| |
| <p>With <code>UseCanonicalName Off</code> Apache httpd will form |
| self-referential URLs using the hostname and port supplied by |
| the client if any are supplied (otherwise it will use the |
| canonical name, as defined above). These values are the same |
| that are used to implement <a |
| href="../vhosts/name-based.html">name-based virtual hosts</a> |
| and are available with the same clients. The CGI variables |
| <code>SERVER_NAME</code> and <code>SERVER_PORT</code> will be |
| constructed from the client supplied values as well.</p> |
| |
| <p>An example where this may be useful is on an intranet server |
| where you have users connecting to the machine using short |
| names such as <code>www</code>. You'll notice that if the users |
| type a shortname and a URL which is a directory, such as |
| <code>http://www/splat</code>, <em>without the trailing |
| slash</em>, then Apache httpd will redirect them to |
| <code>http://www.example.com/splat/</code>. If you have |
| authentication enabled, this will cause the user to have to |
| authenticate twice (once for <code>www</code> and once again |
| for <code>www.example.com</code> -- see <a |
| href="http://wiki.apache.org/httpd/FAQ#Why_does_Apache_ask_for_my_password_twice_before_serving_a_file.3F"> |
| the FAQ on this subject for more information</a>). But if |
| <directive>UseCanonicalName</directive> is set <code>Off</code>, then |
| Apache httpd will redirect to <code>http://www/splat/</code>.</p> |
| |
| <p>There is a third option, <code>UseCanonicalName DNS</code>, |
| which is intended for use with mass IP-based virtual hosting to |
| support ancient clients that do not provide a |
| <code>Host:</code> header. With this option, Apache httpd does a |
| reverse DNS lookup on the server IP address that the client |
| connected to in order to work out self-referential URLs.</p> |
| |
| <note type="warning"><title>Warning</title> |
| <p>If CGIs make assumptions about the values of <code>SERVER_NAME</code>, |
| they may be broken by this option. The client is essentially free |
| to give whatever value they want as a hostname. But if the CGI is |
| only using <code>SERVER_NAME</code> to construct self-referential URLs, |
| then it should be just fine.</p> |
| </note> |
| </usage> |
| <seealso><directive module="core">UseCanonicalPhysicalPort</directive></seealso> |
| <seealso><directive module="core">ServerName</directive></seealso> |
| <seealso><directive module="mpm_common">Listen</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>UseCanonicalPhysicalPort</name> |
| <description>Configures how the server determines its own port</description> |
| <syntax>UseCanonicalPhysicalPort On|Off</syntax> |
| <default>UseCanonicalPhysicalPort Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context></contextlist> |
| |
| <usage> |
| <p>In many situations Apache httpd must construct a <em>self-referential</em> |
| URL -- that is, a URL that refers back to the same server. With |
| <code>UseCanonicalPhysicalPort On</code>, Apache httpd will, when |
| constructing the canonical port for the server to honor |
| the <directive module="core">UseCanonicalName</directive> directive, |
| provide the actual physical port number being used by this request |
| as a potential port. With <code>UseCanonicalPhysicalPort Off</code>, |
| Apache httpd will not ever use the actual physical port number, instead |
| relying on all configured information to construct a valid port number.</p> |
| |
| <note><title>Note</title> |
| <p>The ordering of the lookup when the physical port is used is as |
| follows:</p> |
| <dl> |
| <dt><code>UseCanonicalName On</code></dt> |
| <dd> |
| <ol> |
| <li>Port provided in <directive module="core">Servername</directive></li> |
| <li>Physical port</li> |
| <li>Default port</li> |
| </ol> |
| </dd> |
| <dt><code>UseCanonicalName Off | DNS</code></dt> |
| <dd> |
| <ol> |
| <li>Parsed port from <code>Host:</code> header</li> |
| <li>Physical port</li> |
| <li>Port provided in <directive module="core">Servername</directive></li> |
| <li>Default port</li> |
| </ol> |
| </dd> |
| </dl> |
| |
| <p>With <code>UseCanonicalPhysicalPort Off</code>, the |
| physical ports are removed from the ordering.</p> |
| </note> |
| |
| </usage> |
| <seealso><directive module="core">UseCanonicalName</directive></seealso> |
| <seealso><directive module="core">ServerName</directive></seealso> |
| <seealso><directive module="mpm_common">Listen</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>VirtualHost</name> |
| <description>Contains directives that apply only to a specific |
| hostname or IP address</description> |
| <syntax><VirtualHost |
| <var>addr</var>[:<var>port</var>] [<var>addr</var>[:<var>port</var>]] |
| ...> ... </VirtualHost></syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p><directive type="section">VirtualHost</directive> and |
| <code></VirtualHost></code> are used to enclose a group of |
| directives that will apply only to a particular virtual host. Any |
| directive that is allowed in a virtual host context may be |
| used. When the server receives a request for a document on a |
| particular virtual host, it uses the configuration directives |
| enclosed in the <directive type="section">VirtualHost</directive> |
| section. <var>Addr</var> can be any of the following, optionally followed by |
| a colon and a port number (or *):</p> |
| |
| <ul> |
| <li>The IP address of the virtual host;</li> |
| |
| <li>A fully qualified domain name for the IP address of the |
| virtual host (not recommended);</li> |
| |
| <li>The character <code>*</code>, which acts as a wildcard and matches |
| any IP address.</li> |
| |
| <li>The string <code>_default_</code>, which is an alias for <code>*</code></li> |
| |
| </ul> |
| |
| <highlight language="config"> |
| <VirtualHost 10.1.2.3:80> |
| ServerAdmin webmaster@host.example.com |
| DocumentRoot "/www/docs/host.example.com" |
| ServerName host.example.com |
| ErrorLog "logs/host.example.com-error_log" |
| TransferLog "logs/host.example.com-access_log" |
| </VirtualHost> |
| </highlight> |
| |
| |
| <p>IPv6 addresses must be specified in square brackets because |
| the optional port number could not be determined otherwise. An |
| IPv6 example is shown below:</p> |
| |
| <highlight language="config"> |
| <VirtualHost [2001:db8::a00:20ff:fea7:ccea]:80> |
| ServerAdmin webmaster@host.example.com |
| DocumentRoot "/www/docs/host.example.com" |
| ServerName host.example.com |
| ErrorLog "logs/host.example.com-error_log" |
| TransferLog "logs/host.example.com-access_log" |
| </VirtualHost> |
| </highlight> |
| |
| <p>Each Virtual Host must correspond to a different IP address, |
| different port number, or a different host name for the server, |
| in the former case the server machine must be configured to |
| accept IP packets for multiple addresses. (If the machine does |
| not have multiple network interfaces, then this can be |
| accomplished with the <code>ifconfig alias</code> command -- if |
| your OS supports it).</p> |
| |
| <note><title>Note</title> |
| <p>The use of <directive type="section">VirtualHost</directive> does |
| <strong>not</strong> affect what addresses Apache httpd listens on. You |
| may need to ensure that Apache httpd is listening on the correct addresses |
| using <directive module="mpm_common">Listen</directive>.</p> |
| </note> |
| |
| <p>A <directive module="core">ServerName</directive> should be |
| specified inside each <directive |
| type="section">VirtualHost</directive> block. If it is absent, the |
| <directive module="core">ServerName</directive> from the "main" |
| server configuration will be inherited.</p> |
| |
| <p>When a request is received, the server first maps it to the best matching |
| <directive type="section">VirtualHost</directive> based on the local |
| IP address and port combination only. Non-wildcards have a higher |
| precedence. If no match based on IP and port occurs at all, the |
| "main" server configuration is used.</p> |
| |
| <p>If multiple virtual hosts contain the best matching IP address and port, |
| the server selects from these virtual hosts the best match based on the |
| requested hostname. If no matching name-based virtual host is found, |
| then the first listed virtual host that matched the IP address will be |
| used. As a consequence, the first listed virtual host for a given IP address |
| and port combination is the default virtual host for that IP and port |
| combination.</p> |
| |
| <note type="warning"><title>Security</title> |
| <p>See the <a href="../misc/security_tips.html">security tips</a> |
| document for details on why your security could be compromised if the |
| directory where log files are stored is writable by anyone other |
| than the user that starts the server.</p> |
| </note> |
| </usage> |
| <seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso> |
| <seealso><a href="../dns-caveats.html">Issues Regarding DNS and |
| Apache HTTP Server</a></seealso> |
| <seealso><a href="../bind.html">Setting |
| which addresses and ports Apache HTTP Server uses</a></seealso> |
| <seealso><a href="../sections.html">How <Directory>, <Location> |
| and <Files> sections work</a> for an explanation of how these |
| different sections are combined when a request is received</seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MergeTrailers</name> |
| <description>Determines whether trailers are merged into headers</description> |
| <syntax>MergeTrailers [on|off]</syntax> |
| <default>MergeTrailers off</default> |
| <contextlist><context>server config</context><context>virtual host</context></contextlist> |
| <compatibility>2.4.11 and later</compatibility> |
| |
| <usage> |
| <p>This directive controls whether HTTP trailers are copied into the |
| internal representation of HTTP headers. This merging occurs when the |
| request body has been completely consumed, long after most header |
| processing would have a chance to examine or modify request headers.</p> |
| <p>This option is provided for compatibility with releases prior to 2.4.11, |
| where trailers were always merged.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>QualifyRedirectURL</name> |
| <description>Controls whether the REDIRECT_URL environment variable is |
| fully qualified</description> |
| <syntax>QualifyRedirectURL ON|OFF</syntax> |
| <default>QualifyRedirectURL OFF</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>Directive supported in 2.4.18 and later. 2.4.17 acted |
| as if 'QualifyRedirectURL ON' was configured.</compatibility> |
| |
| <usage> |
| <p>This directive controls whether the server will ensure that the |
| REDIRECT_URL environment variable is fully qualified. By default, |
| the variable contains the verbatim URL requested by the client, |
| such as "/index.html". With <directive module="core" |
| >QualifyRedirectURL ON</directive>, the same request would result in a |
| value such as "http://www.example.com/index.html".</p> |
| <p>Even without this directive set, when a request is issued against a |
| fully qualified URL, REDIRECT_URL will remain fully qualified. |
| </p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>RegisterHttpMethod</name> |
| <description>Register non-standard HTTP methods</description> |
| <syntax>RegisterHttpMethod <var>method</var> [<var>method</var> [...]]</syntax> |
| <contextlist><context>server config</context></contextlist> |
| <compatibility>Available in Apache HTTP Server 2.4.24 and later</compatibility> |
| |
| <usage> |
| <p>This directive may be used to register additional HTTP methods. This is |
| necessary if non-standard methods need to be used with directives that accept |
| method names as parameters, or to allow particular non-standard methods to be |
| used via proxy or CGI script when the server has been configured to only pass |
| recognized methods to modules.</p> |
| </usage> |
| <seealso><directive module="core">HTTPProtocolOptions</directive></seealso> |
| <seealso><directive module="mod_allowmethods">AllowMethods</directive></seealso> |
| </directivesynopsis> |
| |
| </modulesynopsis> |