| <?xml version="1.0"?> |
| <!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> |
| <modulesynopsis> |
| |
| <name>core</name> |
| <status>Core</status> |
| <description>Core Apache HTTP Server features that are always |
| available</description> |
| |
| <directivesynopsis> |
| <name>AcceptPathInfo</name> |
| <description>Controls whether requests can contain 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> |
| <compatibility>Available in Apache 2.0.30 and later</compatibility> |
| |
| <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 PATH_INFO 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 PATH_INFO.</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 PATH_INFO. |
| Handlers that serve scripts, such as <a |
| href="mod_cgi.html">cgi-script</a> and <a |
| href="mod_isapi.html">isapi-isa</a>, generally accept PATH_INFO 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 PATH_INFO. 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 PATH_INFO. The core handler would usually reject the |
| request, so you can use the following configuration to enable |
| such a script:</p> |
| <example> |
| <Files "mypaths.shtml"><br /> |
| Options +Includes<br /> |
| SetOutputFilter INCLUDES<br /> |
| AcceptPathInfo on<br /> |
| </Files> |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AccessFileName</name> |
| <description>Sets the name of the .htaccess file</description> |
| <syntax>AccessFileName <em>filename</em> [<em>filename</em>] ...</syntax> |
| <default>AccessFileName .htaccess</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>When returning a document to the client the server looks for |
| the first existing access control file from this list of names |
| in every directory of the path to the document, if access |
| control files are enabled for that directory. For example:</p> |
| |
| <example> |
| AccessFileName .acl |
| </example> |
| |
| <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> |
| |
| <example> |
| <Directory /><br /> |
| AllowOverride None<br /> |
| </Directory> |
| </example> |
| </usage> |
| <seealso><directive module="core">AllowOverride</directive></seealso> |
| <seealso><a href="../configuring.html">Configuration Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AddDefaultCharset</name> |
| <description>Specifies the default character set to be added for a |
| response without an explicit character set</description> |
| <syntax>AddDefaultCharset On|Off|<em>charset</em></syntax> |
| <contextlist><context>server config</context> |
| <context>virtual host</context><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <default>AddDefaultCharset Off</default> |
| |
| <usage> |
| |
| <p>This directive specifies the name of the character set that |
| will be added to any response that does not have any parameter on |
| the content type in the HTTP headers. This will override any |
| character set specified in the body of the document via a |
| <code>META</code> tag. A setting of <code>AddDefaultCharset |
| Off</code> disables this |
| functionality. <code>AddDefaultCharset On</code> enables |
| Apache's internal default charset of <code>iso-8859-1</code> as |
| required by the directive. You can also specify an alternate |
| <em>charset</em> to be used. For example:</p> |
| |
| <example> |
| AddDefaultCharset utf-8 |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AddModule</name> |
| <syntax>AddModule <em>module</em> [<em>module</em>] ...</syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The server can have modules compiled in which are not |
| actively in use. This directive can be used to enable the use |
| of those modules. The server comes with a pre-loaded list of |
| active modules; this list can be cleared with the <directive |
| module="core">ClearModuleList</directive> directive.</p> |
| |
| <p>For example:</p> |
| <example> |
| AddDefaultCharset utf-8 |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AllowOverride</name> |
| <description>Sets the types of directives that are allowed in |
| .htaccess files</description> |
| <syntax>AllowOverride All|None|<em>directive-type</em> [<em>directive-type</em>] ...</syntax> |
| <default>AllowOverride All</default> |
| <contextlist><context>directory</context></contextlist> |
| |
| <usage> |
| <p>When the server finds an .htaccess file (as specified by <directive |
| module="core">AccessFileName</directive>) it needs to know |
| which directives declared in that file can override earlier |
| access information.</p> |
| |
| <p>When this directive is set to <code>None</code>, then |
| .htaccess files are completely ignored. In this case, the |
| server will not even attempt to read .htaccess 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 |
| .htaccess files.</p> |
| |
| <p>The <em>directive-type</em> can be one of the following |
| groupings of directives.</p> |
| |
| <dl> |
| <dt>AuthConfig</dt> |
| |
| <dd> |
| |
| Allow use of the authorization directives (<directive |
| module="mod_auth_dbm">AuthDBMGroupFile</directive>, |
| <directive module="mod_auth_dbm">AuthDBMUserFile</directive>, |
| <directive module="mod_auth">AuthGroupFile</directive>, |
| <directive module="core">AuthName</directive>, |
| <directive module="core">AuthType</directive>, <directive |
| module="mod_auth">AuthUserFile</directive>, <directive |
| module="core">Require</directive>, <em>etc.</em>).</dd> |
| |
| <dt>FileInfo</dt> |
| |
| <dd> |
| Allow use of the directives controlling document types (<directive |
| module="core">DefaultType</directive>, <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, <em>etc.</em>).</dd> |
| |
| <dt>Indexes</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>, <directive |
| module="mod_autoindex">FancyIndexing</directive>, <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>Limit</dt> |
| |
| <dd> |
| Allow use of the directives controlling host access (<directive |
| module="mod_access">Allow</directive>, <directive |
| module="mod_access">Deny</directive> and <directive |
| module="mod_access">Order</directive>).</dd> |
| |
| <dt>Options</dt> |
| |
| <dd> |
| Allow use of the directives controlling specific directory |
| features (<directive module="core">Options</directive> and |
| <directive module="mod_include">XBitHack</directive>).</dd> |
| </dl> |
| |
| <p>Example:</p> |
| |
| <example>AllowOverride AuthConfig Indexes</example> |
| </usage> |
| |
| <seealso><directive module="core">AccessFileName</directive></seealso> |
| <seealso><a href="../configuring.html">Configuration Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AuthName</name> |
| <description>Sets the authorization realm for use in HTTP |
| authentication</description> |
| <syntax>AuthName <em>auth-domain</em></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>AuthConfig</override> |
| |
| <usage> |
| <p>This directive sets the name of the authorization realm for a |
| directory. This realm is given to the client so that the user |
| knows which username and password to send. |
| <directive>AuthName</directive> takes a single argument; if the |
| realm name contains spaces, it must be enclosed in quotation |
| marks. It must be accompanied by <directive |
| module="core">AuthType</directive> and <directive |
| module="core">Require</directive> directives, and directives such |
| as <directive module="mod_auth">AuthUserFile</directive> and |
| <directive module="mod_auth">AuthGroupFile</directive> to |
| work.</p> |
| |
| <p>For example:</p> |
| |
| <example>AuthName "Top Secret"</example> |
| |
| <p>The string provided for the <code>AuthRealm</code> is what will |
| appear in the password dialog provided by most browsers.</p> |
| </usage> |
| <seealso><a |
| href="../howto/auth.html">Authentication, Authorization, and |
| Access Control</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>AuthType</name> |
| <description>Selects the type of user authentication</description> |
| <syntax>AuthType Basic|Digest</syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| <override>AuthConfig</override></contextlist> |
| |
| <usage> |
| <p>This directive selects the type of user authentication for a |
| directory. Only <code>Basic</code> and <code>Digest</code> are |
| currently implemented. |
| |
| It must be accompanied by <directive |
| module="core">AuthName</directive> and <directive |
| module="core">Require</directive> directives, and directives such |
| as <directive module="mod_auth">AuthUserFile</directive> and |
| <directive module="mod_auth">AuthGroupFile</directive> to |
| work.</p> |
| </usage> |
| <seealso><a href="../howto/auth.html">Authentication, Authorization, |
| and Access Control</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ContentDigest</name> |
| <description>Enables the generation of Content-MD5 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> |
| <compatibility>Available in Apache 1.1 and later</compatibility> |
| |
| <usage> |
| <p>This directive enables the generation of |
| <code>Content-MD5</code> headers as defined in RFC1864 |
| respectively RFC2068.</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 core, 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>DefaultType</name> |
| <description>Sets the MIME content-type that will be sent if the |
| server cannot determine a type in any other way</description> |
| <syntax>DefaultType <em>MIME-type</em></syntax> |
| <default>DefaultType text/html</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p>There will be times when the server is asked to provide a |
| document whose type cannot be determined by its MIME types |
| mappings.</p> |
| |
| <p>The server must inform the client of the content-type of the |
| document, so in the event of an unknown type it uses the |
| <code>DefaultType</code>. For example:</p> |
| |
| <example> |
| <code>DefaultType image/gif</code> |
| </example> |
| would be appropriate for a directory which contained many gif |
| images with filenames missing the .gif extension. |
| |
| <p>Note that unlike <directive |
| module="core">ForceType</directive>, this directive is only |
| provides the default mime-type. All other mime-type definitions, |
| including filename extensions, that might identify the media type |
| will override this default.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Directory</name> |
| <description>Enclose a group of directives that apply only to the |
| named file-system directory and sub-directories</description> |
| <syntax><Directory <em>directory-path</em>> |
| ... </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 which will apply only to the named directory and |
| sub-directories of that directory. Any directive which is allowed |
| in a directory context may be used. <em>Directory-path</em> is |
| either the full path to a directory, or a wild-card string. In a |
| wild-card string, `?' matches any single character, and `*' |
| matches any sequences of characters. You may |
| also use `[]' character ranges like in the shell. Also as of |
| Apache 1.3 none of the wildcards match a `/' character, which more |
| closely mimics the behavior of Unix shells. Example:</p> |
| <example> |
| <Directory /usr/local/httpd/htdocs><br /> |
| Options Indexes FollowSymLinks<br /> |
| </Directory><br /> |
| </example> |
| |
| <p>Extended regular |
| expressions can also be used, with the addition of the |
| <code>~</code> character. For example:</p> |
| <example> |
| <Directory ~ "^/www/.*/[0-9]{3}"> |
| </example> |
| would match directories in /www/ that consisted of three |
| numbers. |
| |
| <p>If multiple (non-regular expression) directory sections |
| match the directory (or 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> |
| |
| <example> |
| <Directory /><br /> |
| AllowOverride None<br /> |
| </Directory><br /> |
| <br /> |
| <Directory /home/*><br /> |
| AllowOverride FileInfo<br /> |
| </Directory> |
| </example> |
| <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/web</code>).</li> |
| |
| <li>Apply any FileInfo directives in |
| <code>/home/web/.htaccess</code></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> |
| |
| <example><Directory ~ abc$><br /> |
| ... directives here ...<br /> |
| </Directory><br /> |
| </example> |
| |
| <p>The regular expression section won't be considered until after |
| all normal <Directory>s and <code>.htaccess</code> files |
| have been applied. Then the regular expression will match on |
| <code>/home/abc/public_html/abc</code> and be applied.</p> |
| |
| <p><strong>Note that the default Apache access for |
| <Directory /> is <samp>Allow from All</samp>. This means |
| that Apache will serve any file mapped from an URL. It is |
| recommended that you change this with a block such |
| as</strong></p> |
| |
| <example> |
| <Directory /><br /> |
| Order Deny,Allow<br /> |
| Deny from All<br /> |
| </Directory> |
| </example> |
| |
| <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 typically occur in |
| the access.conf file, but they may appear in any configuration |
| 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 a group of directives that apply only to |
| file-system directories that match a regular expression and their |
| subdirectories</description> |
| <syntax><Directory <em>regex</em>> |
| ... </Directory></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 |
| sub-directories of that directory, the same as <directive |
| module="core" type="section">Directory</directive>. However, it |
| takes as an argument a regular expression. For example:</p> |
| <example> |
| <DirectoryMatch "^/www/.*/[0-9]{3}"> |
| </example> |
| |
| <p>would match directories in <code>/www/</code> that consisted of three |
| numbers.</p> |
| </usage> |
| <seealso><directive type="section" module="core">Directory</directive> for |
| a description of how regular expressions are mixed in with normal |
| <code><Directory></code>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>Sets the directory that forms the main document tree visible |
| from the web</description> |
| <syntax>DocumentRoot <em>directory-path</em></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 httpd will |
| serve files. Unless matched by a directive like Alias, the |
| server appends the path from the requested URL to the document |
| root to make the path to the document. Example:</p> |
| <example> |
| DocumentRoot /usr/web |
| </example> |
| <p>then an access to |
| <code>http://www.my.host.com/index.html</code> refers to |
| <code>/usr/web/index.html</code>.</p> |
| |
| <p>The <directive>DocumentRoot</directive> should be specified without |
| a trailing slash.</p> |
| </usage> |
| <seealso><a href="../urlmapping.html">Mapping URLs to Filesystem |
| Location</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ErrorDocument</name> |
| <description>Specifies what the server will return to the client |
| in case of an error</description> |
| <syntax>ErrorDocument <em>error-code document</em></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| <compatibility>Quoting syntax for text messages is different in Apache |
| 2.0</compatibility> |
| |
| <usage> |
| <p>In the event of a problem or error, Apache 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>redirect to a local <em>URL-path</em> to handle the |
| problem/error</li> |
| |
| <li>redirect to an external <em>URL</em> 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 will sometimes offer additional information |
| regarding the problem/error.</p> |
| |
| <p>URLs can begin with a slash (/) for local URLs, or be a full |
| URL which the client can resolve. Alternatively, a message can |
| be provided to be displayed by the browser. Examples:</p> |
| |
| <example> |
| ErrorDocument 500 |
| http://foo.example.com/cgi-bin/tester<br /> |
| ErrorDocument 404 /cgi-bin/bad_urls.pl<br /> |
| ErrorDocument 401 /subscription_info.html<br /> |
| ErrorDocument 403 "Sorry can't allow you access |
| today" |
| </example> |
| |
| <p>Note that when you specify an <directive>ErrorDocument</directive> |
| that points to a remote URL (ie. anything with a method such as |
| "http" in front of it), Apache 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 |
| "ErrorDocument 401" directive then it must refer to a local |
| document.</strong></p> |
| |
| <p>Prior to version 2.0, messages were indicated by prefixing |
| them with a single unmatched double quote character.</p> |
| </usage> |
| |
| <seealso><a href="../custom-error.html">documentation of |
| customizable responses</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ErrorLog</name> |
| <description>Sets the name of the file to which the server |
| will log errors</description> |
| <syntax> ErrorLog <em>file-path</em>|syslog[:<em>facility</em>]</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 <em>file-path</em> does not begin with a slash (/) then it is |
| assumed to be relative to the <directive |
| module="core">ServerRoot</directive>. If the <em>file-path</em> |
| begins with a pipe (|) then it is assumed to be a command to spawn |
| to handle the error log.</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:</code><em>facility</em> syntax where |
| <em>facility</em> can be one of the names usually documented in |
| syslog(1).</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 logfiles are stored is writable by |
| anyone other than the user that starts the server.</p> |
| </usage> |
| <seealso><directive module="core">LogLevel</directive></seealso> |
| <seealso><a href="../logs.html">Apache Log Files</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>FileETag</name> |
| <description>Configures the file attributes used to create the ETag |
| HTTP response header</description> |
| <syntax>FileETag <em>component</em> ...</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>FileInfo</override> |
| |
| <usage> |
| <p> |
| The <directive>FileETag</directive> directive configures the file |
| attributes that are used to create the ETag (entity tag) response |
| header field when the document is based on a file. (The ETag |
| value is used in cache management to save network bandwidth.) In |
| Apache 1.3.22 and earlier, the ETag value was <em>always</em> formed |
| from the file's inode, size, and last-modified time (mtime). The |
| FileETag directive allows you to choose which of these -- if any |
| -- should be used. The recognized keywords are: |
| </p> |
| <dl compact="compact"> |
| <dt><b>INode</b></dt> |
| <dd>The file's i-node number will be included in the calculation</dd> |
| <dt><b>MTime</b></dt> |
| <dd>The date and time the file was last modified will be included</dd> |
| <dt><b>Size</b></dt> |
| <dd>The number of bytes in the file will be included</dd> |
| <dt><b>All</b></dt> |
| <dd>All available fields will be used (equivalent to |
| '<code>FileETag INode MTime Size</code>')</dd> |
| <dt><b>None</b></dt> |
| <dd>If a document is file-based, no ETag field will be included in the |
| response</dd> |
| </dl> |
| <p> |
| The INode, MTime, and Size keywords may be prefixed with either '+' |
| or '-', 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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Files</name> |
| <description>Contains that directives that apply to matched |
| filenames</description> |
| <syntax><Files <em>filename</em>> ... </Files></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">Files</directive> directive |
| provides for access control by filename. It is comparable to the |
| <directive module="core" type="directive">Directory</directive> |
| directive and <directive module="core" |
| type="directive">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 <em>filename</em> argument should include a filename, or |
| a wild-card string, where `?' matches any single character, and |
| `*' matches any sequences of characters. Extended regular |
| expressions can also be used, with the addition of the |
| <code>~</code> character. For example:</p> |
| <example> |
| <Files ~ "\.(gif|jpe?g|png)$"> |
| </example> |
| <p>would match most common Internet graphics formats. In Apache 1.3 |
| and later, <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 |
| .htaccess 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 that directives that apply to regular-expression matched |
| filenames</description> |
| <syntax><FilesMatch <em>regex</em>> ... </FilesMatch></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">FilesMatch</directive> directive |
| provides for access control by filename, just as the <directive |
| module="core" type="section">Files</directive> directive |
| does. However, it accepts a regular expression. For example:</p> |
| <example> |
| <FilesMatch "\.(gif|jpe?g|png)$"> |
| </example> |
| |
| <p>would match most common Internet graphics formats.</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> |
| <name>ForceType</name> |
| <description>Forces all matching files to be served with the specified |
| MIME content-type</description> |
| <syntax>ForceType <em>mime-type</em></syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <compatibility>Moved to the core in Apache 2.0</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> 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 |
| <em>mime-type</em>. For example, if you had a directory full of |
| GIF files, but did not want to label them all with ".gif", you |
| might want to use:</p> |
| <example> |
| ForceType image/gif |
| </example> |
| |
| <p>Note that unlike <directive module="core">DefaultType</directive>, |
| this directive overrides all mime-type associations, including |
| filename extensions, that might identify the media type.</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. 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_access</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 off 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 <a |
| href="../programs/logresolve.html">logresolve</a>, provided in |
| the <em>/support</em> directory, can be used to look up host |
| names from logged IP addresses offline.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>IdentityCheck</name> |
| <description>Enables logging of the RFC1413 identity of the remote |
| user</description> |
| <syntax>IdentityCheck on|off</syntax> |
| <default>IdentityCheck off</default> |
| |
| <usage> |
| <p>This directive enables RFC1413-compliant logging of the |
| remote user name for each connection, where the client machine |
| runs identd or something similar. This information is logged in |
| the access log.</p> |
| |
| <p>The information should not be trusted in any way except for |
| rudimentary usage tracking.</p> |
| |
| <p>Note that this can cause serious latency problems accessing |
| your server since every request requires one of these lookups |
| to be performed. When firewalls are involved each lookup might |
| possibly fail and add 30 seconds of latency to each hit. So in |
| general this is not very useful on public servers accessible |
| from the Internet.</p> |
| </usage> |
| </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 [!]<em>parameter-name</em>> <em>...</em> |
| </IfDefine></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <code><IfDefine |
| <em>test</em>>...</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 <em>test</em> is true. If <em>test</em> is false, |
| everything between the start and end markers is ignored.</p> |
| |
| <p>The <em>test</em> in the <directive |
| type="section">IfDefine</directive> section directive can be one |
| of two forms:</p> |
| |
| <ul> |
| <li><em>parameter-name</em></li> |
| |
| <li><code>!</code><em>parameter-name</em></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if the parameter named |
| <em>parameter-name</em> is defined. The second format reverses |
| the test, and only processes the directives if |
| <em>parameter-name</em> is <strong>not</strong> defined.</p> |
| |
| <p>The <em>parameter-name</em> argument is a define as given on |
| the <code>httpd</code> command line via |
| <code>-D</code><em>parameter-</em>, at the time the server was |
| started.</p> |
| |
| <p><directive type="section">IfDefine</directive> sections are |
| nest-able, which can be used to implement simple |
| multiple-parameter tests. Example:</p> |
| <example><pre> |
| $ httpd -DReverseProxy ... |
| |
| # httpd.conf |
| <IfDefine ReverseProxy> |
| LoadModule rewrite_module modules/mod_rewrite.so |
| LoadModule proxy_module modules/libproxy.so |
| </IfDefine> |
| </pre></example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>IfModule</name> |
| <description>Encloses directives that are processed conditional on the |
| presence of absence of a specific module</description> |
| <syntax><IfModule [!]<em>module-name</em>> <em>...</em> |
| </IfModule></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <code><IfModule |
| <em>test</em>>...</IfModule></code> section is used to |
| mark directives that are conditional. The directives within an |
| <directive type="section">IfModule</directive> section are only |
| processed if the <em>test</em> is true. If <em>test</em> is false, |
| everything between the start and end markers is ignored.</p> |
| |
| <p>The <em>test</em> in the <directive |
| type="section">IfModule</directive> section directive can be one |
| of two forms:</p> |
| |
| <ul> |
| <li><em>module name</em></li> |
| |
| <li>!<em>module name</em></li> |
| </ul> |
| |
| <p>In the former case, the directives between the start and end |
| markers are only processed if the module named <em>module |
| name</em> is included in Apache -- 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 <em>module |
| name</em> is <strong>not</strong> included.</p> |
| |
| <p>The <em>module name</em> argument is the file name of the |
| module, at the time it was compiled. |
| For example, <code>mod_rewrite.c</code>.</p> |
| |
| <p><directive type="section">IfModule</directive> sections are |
| nest-able, which can be used to implement simple multiple-module |
| tests.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Include</name> |
| <description>Includes other configuration files from within |
| the server configuration files</description> |
| <syntax>Include <em>file-path</em>|<em>directory-path</em></syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive allows inclusion of other configuration files |
| from within the server configuration files.</p> |
| |
| <p>If <directive>Include</directive> points to a directory, rather than a |
| file, Apache will read all files in that directory, and any |
| subdirectory, and parse those as configuration files.</p> |
| |
| <p>The file path specified may be a fully qualified path (i.e. |
| starting with a slash), or may be relative to the |
| <directive module="core">ServerRoot</directive> directory.</p> |
| |
| <p>Examples:</p> |
| |
| <example> |
| Include /usr/local/apache/conf/ssl.conf<br /> |
| Include /usr/local/apache/conf/vhosts/ |
| </example> |
| |
| <p>Or, providing paths relative to your <code>ServerRoot</code> |
| directory:</p> |
| |
| <example> |
| Include conf/ssl.conf<br /> |
| Include conf/vhosts/ |
| </example> |
| |
| <p>Make sure that an included directory does not contain any stray |
| files, such as editor temporary files, for example, as Apache will |
| attempt to read them in and use the contents as configuration |
| directives, which may cause the server to fail on start up. |
| Running <code>apachectl configtest</code> will give you a list of |
| the files that are being processed during the configuration |
| check:</p> |
| |
| <example><pre> |
| root@host# apachectl configtest |
| Processing config directory: /usr/local/apache/conf/vhosts |
| Processing config file: /usr/local/apache/conf/vhosts/vhost1 |
| Processing config file: /usr/local/apache/conf/vhosts/vhost2 |
| Syntax OK |
| </pre></example> |
| |
| <p>This will help in verifying that you are getting only the files |
| that you intended as part of your configuration.</p> |
| </usage> |
| |
| <seealso><a href="../programs/apachectl.html">apachectl</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>KeepAlive</name> |
| <description>Turns on or off HTTP persistent connections.</description> |
| <syntax>KeepAlive on|off</syntax> |
| <default>KeepAlive On</default> |
| <contextlist><context>server config</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 in Apache 1.2 and |
| later, 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> |
| </usage> |
| |
| <seealso><directive module="core">MaxKeepAliveRequests</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>KeepAliveTimeout</name> |
| <description>Sets the amount of time the server will wait for subsequent |
| requests on a persistent connection</description> |
| <syntax>KeepAliveTimeout <em>seconds</em></syntax> |
| <default>KeepAliveTimeout 15</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The number of seconds Apache will wait for a subsequent |
| request before closing the connection. 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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Limit</name> |
| <description>Restrict access controls to only certain HTTP |
| methods</description> |
| <syntax><Limit <em>method</em> [<em>method</em>] ... > ... |
| </Limit></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <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 <code><Limit></code> |
| bracket <strong>will have no effect</strong>. The following |
| example applies the access control only to the methods POST, PUT, |
| and DELETE, leaving all other methods unprotected:</p> |
| |
| <example> |
| <code><Limit POST PUT DELETE><br /> |
| Require valid-user<br /> |
| </Limit></code> |
| </example> |
| <p>The method names listed can be one or more of: GET, POST, PUT, |
| DELETE, CONNECT, OPTIONS, TRACE, PATCH, PROPFIND, PROPPATCH, |
| MKCOL, COPY, MOVE, LOCK, and UNLOCK. <strong>The method name is |
| case-sensitive.</strong> If GET is used it will also restrict |
| HEAD requests.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>LimitExcept</name> |
| <description>Restrict access controls to all HTTP methods |
| except the named ones</description> |
| <syntax><LimitExcept <em>method</em> [<em>method</em>] ... > ... |
| </LimitExcept></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestBody</name> |
| <description>Restricts the total size of the HTTP request body sent |
| from the client</description> |
| <syntax>LimitRequestBody <em>bytes</em></syntax> |
| <default>LimitRequestBody 0</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>This directive specifies the number of <em>bytes</em> from 0 |
| (meaning unlimited) to 2147483647 (2GB) that are allowed in a |
| request body. The default value is defined by the compile-time |
| constant <code>DEFAULT_LIMIT_REQUEST_BODY</code> (0 as |
| distributed).</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 passing form information to the |
| server. Implementations of the PUT 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> |
| </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 <em>number</em></syntax> |
| <default>LimitRequestFields 100</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p><em>Number</em> 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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitRequestFieldSize</name> |
| <description>Limits the size of the HTTP request header allowed from the |
| client</description> |
| <syntax>LimitRequestFieldsize <em>bytes</em></syntax> |
| <default>LimitRequestFieldsize 8190</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive specifies the number of <em>bytes</em> from 0 |
| to the value of the compile-time constant |
| <code>DEFAULT_LIMIT_REQUEST_FIELDSIZE</code> (8190 as |
| distributed) that will be allowed in an HTTP request |
| header.</p> |
| |
| <p>The <directive>LimitRequestFieldsize</directive> directive |
| allows the server administrator to reduce the limit on the allowed |
| size of an HTTP request header field below the normal input buffer |
| size compiled with the server. 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.</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. |
| Under normal conditions, the value should not be changed from |
| the default.</p> |
| </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 <em>bytes</em></syntax> |
| <default>LimitRequestLine 8190</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive sets the number of <em>bytes</em> from 0 to |
| the value of the compile-time constant |
| <code>DEFAULT_LIMIT_REQUEST_LINE</code> (8190 as distributed) |
| that will be allowed on the HTTP request-line.</p> |
| |
| <p>The <directive>LimitRequestLine</directive> directive allows |
| the server administrator to reduce the limit on the allowed size |
| of a client's HTTP request-line below the normal input buffer size |
| compiled with the server. 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 GET 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. |
| Under normal conditions, the value should not be changed from |
| the default.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>LimitXMLRequestBody</name> |
| <description>Limits the size of an XML-based request body</description> |
| <syntax>LimitXMLRequestBody <em>number</em></syntax> |
| <default>LimitXMLRequestBody 1000000</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>Location</name> |
| <description>Applies the enclosed directives only to matching |
| URLs</description> |
| <syntax><Location |
| <em>URL-path</em>|<em>URL</em>> ... </Location></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">Location</directive> directive |
| provides for access control 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>Note that URLs do not have to line up with the filesystem at |
| all, it should be emphasized that <Location> operates |
| completely outside the filesystem.</p> |
| |
| <p>For all origin (non-proxy) requests, the URL to be matched |
| is of the form <code>/path/</code>, and you should not include |
| any <code>http://servername</code> prefix. 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, `?' matches |
| any single character, and `*' matches any sequences of |
| characters.</p> |
| |
| <p>Extended regular |
| expressions can also be used, with the addition of the |
| <code>~</code> character. For example:</p> |
| <example> |
| <Location ~ "/(extra|special)/data"> |
| </example> |
| |
| <p>would match URLs that contained the substring "/extra/data" or |
| "/special/data". In Apache 1.3 and above, a new directive |
| <directive type="section" module="core">LocationMatch</directive> |
| exists which behaves identical to the regex version of |
| <directive type="section">Location</directive>.</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 foo.com, you might use:</p> |
| <example> |
| <Location /status><br /> |
| SetHandler server-status<br /> |
| Order Deny,Allow<br /> |
| Deny from all<br /> |
| Allow from .foo.com<br /> |
| </Location> |
| </example> |
| |
| <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. 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> |
| </directivesynopsis> |
| |
| <directivesynopsis type="section"> |
| <name>LocationMatch</name> |
| <description>Applies the enclosed directives only to regular-expression |
| matching URLs</description> |
| <syntax><LocationMatch |
| <em>regex</em>> ... </Location></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive type="section">LocationMatch</directive> directive |
| provides for access control by URL, in an identical manner to |
| <directive module="core" |
| type="section">Location</directive>. However, it takes a regular |
| expression as an argument instead of a simple string. For |
| example:</p> |
| <example> |
| <LocationMatch "/(extra|special)/data"> |
| </example> |
| |
| <p>would match URLs that contained the substring "/extra/data" |
| or "/special/data".</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> |
| <name>LogLevel</name> |
| <description>Controls the verbosity of the ErrorLog</description> |
| <syntax>LogLevel <em>level</em></syntax> |
| <default>LogLevel warn</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <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 |
| <em>level</em>s are available, in order of decreasing |
| significance:</p> |
| |
| <table> |
| <tr> |
| <th align="LEFT"><strong>Level</strong> </th> |
| |
| <th align="LEFT"><strong>Description</strong> </th> |
| </tr> |
| |
| <tr> |
| <th> |
| </th> |
| |
| <th align="LEFT"><strong>Example</strong> </th> |
| </tr> |
| |
| <tr> |
| <td><code>emerg</code> </td> |
| |
| <td>Emergencies - system is unusable.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"Child cannot open lock file. Exiting"</td> |
| </tr> |
| |
| <tr> |
| <td><code>alert</code> </td> |
| |
| <td>Action must be taken immediately.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"getpwuid: couldn't determine user name from uid"</td> |
| </tr> |
| |
| <tr> |
| <td><code>crit</code> </td> |
| |
| <td>Critical Conditions.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"socket: Failed to get a socket, exiting child"</td> |
| </tr> |
| |
| <tr> |
| <td><code>error</code> </td> |
| |
| <td>Error conditions.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"Premature end of script headers"</td> |
| </tr> |
| |
| <tr> |
| <td><code>warn</code> </td> |
| |
| <td>Warning conditions.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </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> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"httpd: caught SIGBUS, attempting to dump core in |
| ..."</td> |
| </tr> |
| |
| <tr> |
| <td><code>info</code> </td> |
| |
| <td>Informational.</td> |
| </tr> |
| |
| <tr> |
| <td> |
| </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> |
| </tr> |
| |
| <tr> |
| <td> |
| </td> |
| |
| <td>"Opening config file ..."</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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>MaxKeepAliveRequests</name> |
| <description>Sets the number of requests allowed on a persistent |
| connection</description> |
| <syntax>MaxKeepAliveRequests <em>number</em></syntax> |
| <default>MaxKeepAliveRequests 100</default> |
| <contextlist><context>server config</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> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>NameVirtualHost</name> |
| <description>Configures an IP address for name-virtual |
| hosting</description> |
| <syntax>NameVirtualHost <em>addr</em>[:<em>port</em>]</syntax> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The <directive>NameVirtualHost</directive> directive is a |
| required directive if you want to configure <a |
| href="../vhosts/">name-based virtual hosts</a>.</p> |
| |
| <p>Although <em>addr</em> can be hostname it is recommended |
| that you always use an IP address, <em>e.g.</em></p> |
| |
| <example>NameVirtualHost 111.22.33.44</example> |
| |
| <p>With the <directive>NameVirtualHost</directive> directive you |
| specify the IP address on which the server will receive requests |
| for the name-based virtual hosts. This will usually be the address |
| to which your name-based virtual host names resolve. In cases |
| where a firewall or other proxy receives the requests and forwards |
| them on a different IP address to the server, you must specify the |
| IP address of the physical interface on the machine which will be |
| servicing the requests. If you have multiple name-based hosts on |
| multiple addresses, repeat the directive for each address.</p> |
| |
| <p>Note: the "main server" and any _default_ servers will |
| <strong>never</strong> be served for a request to a |
| <directive>NameVirtualHost</directive> IP Address (unless for some |
| reason you specify <directive>NameVirtualHost</directive> but then |
| don't define any VirtualHosts for that address).</p> |
| |
| <p>Optionally you can specify a port number on which the |
| name-based virtual hosts should be used, <em>e.g.</em></p> |
| |
| <example>NameVirtualHost 111.22.33.44:8080</example> |
| |
| <p>IPv6 addresses must be enclosed in square brackets, as shown |
| in the following example:</p> |
| |
| <example>NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080</example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Options</name> |
| <description>Configures what features are available in a particular |
| directory</description> |
| <syntax>Options |
| [+|-]<em>option</em> [[+|-]<em>option</em>] ...</syntax> |
| <default>Options All</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>Options</override> |
| |
| <usage> |
| <p>The <directive>Options</directive> directive controls which |
| server features are available in a particular directory.</p> |
| |
| <p><em>option</em> 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>All</dt> |
| |
| <dd>All options except for MultiViews. This is the default |
| setting.</dd> |
| |
| <dt>ExecCGI</dt> |
| |
| <dd> |
| Execution of CGI scripts is permitted.</dd> |
| |
| <dt>FollowSymLinks</dt> |
| |
| <dd> |
| |
| The server will follow symbolic links in this directory.<br /> |
| <strong>Note</strong>: 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.<br /> |
| <strong>Note</strong>: this option gets ignored if set inside a |
| <directive type="section" module="core">Location</directive> |
| section.</dd> |
| |
| <dt>Includes</dt> |
| |
| <dd> |
| Server-side includes are permitted.</dd> |
| |
| <dt>IncludesNOEXEC</dt> |
| |
| <dd> |
| |
| Server-side includes are permitted, but the #exec command and |
| #exec CGI are disabled. It is still possible to #include |
| virtual CGI scripts from ScriptAliase'd directories.</dd> |
| |
| <dt>Indexes</dt> |
| |
| <dd> |
| If a URL which maps to a directory is requested, and the |
| there is no DirectoryIndex (<em>e.g.</em>, index.html) in |
| that directory, then the server will return a formatted |
| listing of the directory.</dd> |
| |
| <dt>MultiViews</dt> |
| |
| <dd> |
| <a href="../content-negotiation.html">Content negotiated</a> |
| MultiViews are allowed.</dd> |
| |
| <dt>SymLinksIfOwnerMatch</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.<br |
| /> <strong>Note</strong>: this option gets ignored if set inside |
| a <directive module="core" type="section">Location</directive> |
| section.</dd> |
| </dl> |
| <p>Normally, if multiple <directive>Options</directive> could apply to a |
| directory, then the most specific one is taken complete; the |
| options are not merged. However if <em>all</em> the options on |
| the <directive>Options</directive> directive are preceded by a + or - |
| symbol, the options are merged. Any options preceded by a + are |
| added to the options currently in force, and any options |
| preceded by a - are removed from the options currently in |
| force. </p> |
| |
| <p>For example, without any + and - symbols:</p> |
| |
| |
| <example><Directory /web/docs><br /> |
| Options Indexes FollowSymLinks<br /> |
| </Directory><br /> |
| <Directory /web/docs/spec><br /> |
| Options Includes<br /> |
| </Directory> |
| </example> |
| <p>then only <code>Includes</code> will be set for the |
| /web/docs/spec directory. However if the second |
| <directive>Options</directive> directive uses the + and - symbols:</p> |
| |
| <example> |
| <Directory /web/docs><br /> |
| Options Indexes FollowSymLinks<br /> |
| </Directory><br /> |
| <Directory /web/docs/spec><br /> |
| Options +Includes -Indexes<br /> |
| </Directory> |
| </example> |
| <p>then the options <code>FollowSymLinks</code> and |
| <code>Includes</code> are set for the /web/docs/spec directory.</p> |
| |
| |
| <p><strong>Note:</strong> Using <code>-IncludesNOEXEC</code> or |
| <code>-Includes</code> disables server-side includes completely |
| regardless of the previous setting.</p> |
| |
| <p>The default in the absence of any other settings is |
| <code>All</code>.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Require</name> |
| <description>Selects which authenticated users can access |
| a resource</description> |
| <syntax>Require <em>entity-name</em> [<em>entity-name</em>] ...</syntax> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>AuthConfig</override> |
| |
| <usage> |
| <p>This directive selects which authenticated users can access |
| a directory. The allowed syntaxes are:</p> |
| |
| <ul> |
| <li> |
| Require user <em>userid</em> [<em>userid</em>] ... |
| |
| <p>Only the named users can access the directory.</p> |
| </li> |
| |
| <li> |
| Require group <em>group-name</em> [<em>group-name</em>] ... |
| |
| |
| <p>Only users in the named groups can access the |
| directory.</p> |
| </li> |
| |
| <li> |
| Require valid-user |
| |
| <p>All valid users can access the directory.</p> |
| </li> |
| </ul> |
| |
| <p><directive>Require</directive> must be accompanied by |
| <directive module="core">AuthName</directive> and <directive |
| module="core">AuthType</directive> directives, and directives such |
| as <directive module="mod_auth">AuthUserFile</directive> |
| and <directive module="mod_auth">AuthGroupFile</directive> (to |
| define users and groups) in order to work correctly. Example:</p> |
| |
| <example> |
| AuthType Basic<br /> |
| AuthName "Restricted Directory"<br /> |
| AuthUserFile /web/users<br /> |
| AuthGroupFile /web/groups<br /> |
| Require group admin<br /> |
| </example> |
| |
| <p>Access controls which are applied in this way are effective for |
| <strong>all</strong> methods. <strong>This is what is normally |
| desired.</strong> If you wish to apply access controls only to |
| specific methods, while leaving other methods unprotected, then |
| place the <directive>Require</directive> statement into a |
| <directive module="core" type="section">Limit</directive> |
| section.</p> |
| </usage> |
| <seealso><directive module="core">Satisfy</directive></seealso> |
| <seealso><module>mod_access</module></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>RLimitCPU</name> |
| <description>Limits the CPU consumption of processes launched |
| by Apache children</description> |
| <syntax>RLimitCPU <em>number</em>|max [<em>number</em>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist>><context>server config</context><context>virtual host</context> |
| </contextlist> |
| <compatibility>Moved in version 2.0 to |
| the <a href="../mpm.html">MPMs</a></compatibility> |
| |
| <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 <em>max</em> 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 root, or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked off from Apache children |
| servicing requests, not the Apache children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked off from the Apache 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 children</description> |
| <syntax>RLimitMEM <em>number</em>|max [<em>number</em>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| <compatibility>Moved in version 2.0 to the <a |
| href="../mpm.html">MPMs</a>.</compatibility> |
| |
| <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 <em>max</em> 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 root, or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked off from Apache children |
| servicing requests, not the Apache children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked off from the Apache 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 children</description> |
| <syntax>RLimitNPROC <em>number</em>|max [<em>number</em>|max]</syntax> |
| <default>Unset; uses operating system defaults</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| <compatibility>Moved in version 2.0 to the <a |
| href="../mpm.html">MPMs</a>.</compatibility> |
| |
| <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 root, or in the initial startup |
| phase.</p> |
| |
| <p>This applies to processes forked off from Apache children |
| servicing requests, not the Apache children themselves. This |
| includes CGI scripts and SSI exec commands, but not any |
| processes forked off from the Apache parent such as piped |
| logs.</p> |
| |
| <p>Process limits control the number of processes per user.</p> |
| |
| <p>Note: If CGI processes are <strong>not</strong> running |
| under userids other than the web server userid, this directive |
| will limit the number of processes that the server itself can |
| create. Evidence of this situation will be indicated by |
| <strong><em>cannot fork</em></strong> messages in the |
| error_log.</p> |
| </usage> |
| <seealso><directive module="core">RLimitMEM</directive></seealso> |
| <seealso><directive module="core">RLimitCPU</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>Satisfy</name> |
| <description>Configures how host-level access control and user authentication |
| interact</description> |
| <syntax>Satisfy any|all</syntax> |
| <default>Satisfy all</default> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>Access policy if both <directive |
| module="core">Allow</directive> and <directive |
| module="core">Require</directive> used. The parameter can be |
| either <em>'all'</em> or <em>'any'</em>. This directive is only |
| useful if access to a particular area is being restricted by both |
| username/password <em>and</em> client host address. In this case |
| the default behavior ("all") is to require that the client passes |
| the address access restriction <em>and</em> enters a valid |
| username and password. With the "any" option the client will be |
| granted access if they either pass the host restriction or enter a |
| valid username and password. This can be used to password restrict |
| an area, but to let clients from particular addresses in without |
| prompting for a password.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ScriptInterpreterSource</name> |
| <description>Controls how the interpreter for CGI scripts is |
| located</description> |
| <syntax>ScriptInterpreterSource registry|script</syntax> |
| <default>ScriptInterpreterSource script</default> |
| <contextlist><context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <compatibility>Win32 only</compatibility> |
| |
| <usage> |
| <p>This directive is used to control how Apache finds the |
| interpreter used to run CGI scripts. The default technique is to |
| use the interpreter pointed to by the #! line in the |
| script. Setting <code>ScriptInterpreterSource registry</code> will |
| cause the Windows Registry to be searched using the script file |
| extension (e.g., .pl) as a search key.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerAdmin</name> |
| <description>Sets the email address that the server includes in error |
| messages sent to the client</description> |
| <syntax>ServerAdmin <em>email-address</em></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ServerAdmin</directive> sets the e-mail address |
| that the server includes in any error messages it returns to the |
| client.</p> |
| |
| <p>It may be worth setting up a dedicated address for this, |
| <em>e.g.</em></p> |
| <example>ServerAdmin www-admin@foo.bar.com</example> |
| <p>as users do not always mention that they are talking about the |
| server!</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerAlias</name> |
| <description>Sets alternate names for a host used when matching requests |
| to name-virtual hosts</description> |
| <syntax>ServerAlias <em>hostname</em> [<em>hostname</em>] ...</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>.</p> |
| |
| <example> |
| <VirtualHost *><br /> |
| ServerName server.domain.com<br /> |
| ServerAlias server server2.domain.com server2<br /> |
| ...<br /> |
| </VirtualHost> |
| </example> |
| </usage> |
| <seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerName</name> |
| <description>Sets the hostname and port that the server uses to identify |
| itself</description> |
| <syntax>ServerName <em>fully-qualified-domain-name[:port]</em></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| <compatibility>In version 2.0, this |
| directive supersedes the functionality of the <directive>Port</directive> |
| directive from version 1.3.</compatibility> |
| |
| <usage> |
| <p>The <directive>ServerName</directive> directive sets the hostname and |
| port that the server uses to identify itself. This is used when |
| creating redirection URLs. For example, if the name of the |
| machine hosting the webserver is <code>simple.example.com</code>, |
| but the machine also has the DNS alias <code>www.example.com</code> |
| and you wish the webserver to be so identified, the following |
| directive should be used:</p> |
| |
| <example>ServerName www.example.com:80</example> |
| |
| <p>If no <directive>ServerName</directive> is specified, then the |
| server attempts to deduce the hostname by performing a reverse |
| lookup on the IP address. If no port is specified in the |
| servername, 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>See the description of the |
| <directive module="core">UseCanonicalName</directive> directive for |
| settings which determine whether self-referential URL's (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> |
| </usage> |
| |
| <seealso><a href="../dns-caveats.html">DNS Issues</a></seealso> |
| <seealso><a href="../vhosts/">Apache virtual host |
| documentation</a></seealso> |
| <seealso><directive module="core">UseCanonicalName</directive></seealso> |
| <seealso><directive module="core">NameVirtualHost</directive></seealso> |
| <seealso><directive module="core">ServerAlias</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerPath</name> |
| <description>Sets the legacy URL pathname for a name-virtual host that |
| is accessed by an incompatible browser</description> |
| <syntax>ServerPath <em>directory-path</em></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 Virtual Host documentation</a></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerRoot</name> |
| <description>Sets the base directory for the server installation</description> |
| <syntax>ServerRoot <em>directory-path</em></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 for other configuration files are taken as relative to this |
| directory.</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 ServerRoot</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> |
| |
| <usage> |
| <p>The <directive>ServerSignature</directive> directive allows the |
| configuration of a trailing footer line under server-generated |
| documents (error messages, mod_proxy ftp directory listings, |
| mod_info 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.<br /> The <samp>Off</samp> |
| setting, which is the default, suppresses the error line (and is |
| therefore compatible with the behavior of Apache-1.2 and |
| below). The <samp>On</samp> setting simply adds a line with the |
| server version number and <directive |
| module="core">ServerName</directive> of the serving virtual host, |
| and the <samp>EMail</samp> setting additionally creates a |
| "mailto:" reference to the <directive |
| module="core">ServerAdmin</directive> of the referenced |
| document.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ServerTokens</name> |
| <description>Configures the Server HTTP response header</description> |
| <syntax>ServerTokens Minimal|ProductOnly|OS|Full</syntax> |
| <default>ServerTokens Full</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>This directive controls whether <samp>Server</samp> 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 Prod[uctOnly]</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <samp>Server: |
| Apache</samp></dd> |
| |
| <dt><code>ServerTokens Min[imal]</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <samp>Server: |
| Apache/1.3.0</samp></dd> |
| |
| <dt><code>ServerTokens OS</code></dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <samp>Server: Apache/1.3.0 |
| (Unix)</samp></dd> |
| |
| <dt><code>ServerTokens Full</code> (or not specified)</dt> |
| |
| <dd>Server sends (<em>e.g.</em>): <samp>Server: Apache/1.3.0 |
| (Unix) PHP/3.0 MyMod/1.2</samp></dd> |
| </dl> |
| |
| <p>This setting applies to the entire server, and cannot be |
| enabled or disabled on a virtualhost-by-virtualhost basis.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SetHandler</name> |
| <description>Forces all matching files to be processed by a |
| handler</description> |
| <syntax>SetHandler <em>handler-name</em></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <compatibility>Moved into the core in Apache 2.0</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 |
| <em>handler-name</em>. 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> |
| <example> |
| SetHandler imap-file |
| </example> |
| |
| <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 httpd.conf:</p> |
| <example> |
| <Location /status><br /> |
| SetHandler server-status<br /> |
| </Location> |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SetInputFilter</name> |
| <description>Sets the filters that will process client requests and POST |
| input</description> |
| <syntax>SetInputFilter <em>filter</em>[<em>;filter</em>...]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <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 <em>filter</em> [<em>filter</em>] ...</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| |
| <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> |
| <example> |
| <Directory /www/data/><br /> |
| SetOutputFilter INCLUDES<br /> |
| </Directory> |
| </example> |
| |
| <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>Defines the amount of time the server will wait for |
| certain events before failing a request</description> |
| <syntax>TimeOut <em>number</em></syntax> |
| <default>TimeOut 300</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The <directive>TimeOut</directive> directive currently defines |
| the amount of time Apache will wait for three things:</p> |
| |
| <ol> |
| <li>The total amount of time it takes to receive a GET |
| request.</li> |
| |
| <li>The amount of time between receipt of TCP packets on a |
| POST or PUT request.</li> |
| |
| <li>The amount of time between ACKs on transmissions of TCP |
| packets in responses.</li> |
| </ol> |
| |
| <p>We plan on making these separately configurable at some point |
| down the road. The timer used to default to 1200 before 1.2, |
| but has been lowered to 300 which is still far more than |
| necessary in most situations. It is not set any lower by |
| default because there may still be odd places in the code where |
| the timer is not reset when a packet is sent. </p> |
| </usage> |
| </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 on</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>Options</override> |
| |
| <usage> |
| <p>In many situations Apache has to construct a |
| <em>self-referential</em> URL. That is, a URL which refers back to |
| the same server. With <code>UseCanonicalName on</code> Apache will |
| use the hostname and port specified in the <directive |
| module="core">ServerName</directive> directive to construct a 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 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). 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 will redirect them to |
| <code>http://www.domain.com/splat/</code>. If you have |
| authentication enabled, this will cause the user to have to |
| reauthenticate twice (once for <code>www</code> and once again |
| for <code>www.domain.com</code>). But if |
| <directive>UseCanonicalName</directive> is set off, then Apache 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 does a |
| reverse DNS lookup on the server IP address that the client |
| connected to in order to work out self-referential URLs.</p> |
| |
| <p><strong>Warning:</strong> 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> |
| </usage> |
| <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 |
| <em>addr</em>[:<em>port</em>] [<em>addr</em>[:<em>port</em>]] |
| ...> ... </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 which will apply only to a particular virtual host. Any |
| directive which 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. <em>Addr</em> can be</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.</li> |
| </ul> |
| Example: |
| |
| <example><VirtualHost 10.1.2.3><br /> |
| ServerAdmin webmaster@host.foo.com<br /> |
| DocumentRoot /www/docs/host.foo.com<br /> |
| ServerName host.foo.com<br /> |
| ErrorLog logs/host.foo.com-error_log<br /> |
| TransferLog logs/host.foo.com-access_log<br /> |
| </VirtualHost> |
| </example> |
| |
| |
| <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> |
| |
| <example> |
| <VirtualHost [fe80::a00:20ff:fea7:ccea]><br /> |
| ServerAdmin webmaster@host.foo.com<br /> |
| DocumentRoot /www/docs/host.foo.com<br /> |
| ServerName host.foo.com<br /> |
| ErrorLog logs/host.foo.com-error_log<br /> |
| TransferLog logs/host.foo.com-access_log<br /> |
| </VirtualHost> |
| </example> |
| |
| <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), or with kernel patches like <a |
| href="../misc/vif-info.html">VIF</a> (for SunOS(TM) 4.1.x)).</p> |
| |
| <p>The special name <code>_default_</code> can be specified in |
| which case this virtual host will match any IP address that is |
| not explicitly listed in another virtual host. In the absence |
| of any _default_ virtual host the "main" server config, |
| consisting of all those definitions outside any VirtualHost |
| section, is used when no match occurs.</p> |
| |
| <p>You can specify a <code>:port</code> to change the port that is |
| matched. If unspecified then it defaults to the same port as the |
| most recent <directive module="mpm_common">Listen</directive> |
| statement of the main server. You may also specify <code>:*</code> |
| to match all ports on that address. (This is recommended when used |
| with <code>_default_</code>.)</p> |
| |
| <p><strong>SECURITY</strong>: 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 logfiles are stored is writable by anyone other |
| than the user that starts the server.</p> |
| |
| <p><strong>NOTE</strong>: The use of <directive |
| type="section">VirtualHost</directive> does <strong>not</strong> |
| affect what addresses Apache listens on. You may need to ensure |
| that Apache is listening on the correct addresses using <directive |
| module="mpm_common">Listen</directive>.</p> |
| </usage> |
| <seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso> |
| <seealso><a href="../dns-caveats.html">Warnings about DNS and |
| Apache</a></seealso> |
| <seealso><a href="../bind.html">Setting |
| which addresses and ports Apache 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> |
| |
| </modulesynopsis> |