<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

<!-- $LastChangedRevision$ -->

<!--

Licensed to the Apache Software Foundation (ASF) under one or more

contributor license agreements. See the NOTICE file distributed with

this work for additional information regarding copyright ownership.

The ASF licenses this file to You under the Apache License, Version 2.0

(the "License"); you may not use this file except in compliance with

the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

-->

<modulesynopsis metafile="core.xml.meta">

<name>core</name>

<description>Core Apache HTTP Server features that are always

available</description>

<status>Core</status>

<directivesynopsis>

<name>AcceptFilter</name>

<description>Configures optimizations for a Protocol's Listener Sockets</description>

<syntax>AcceptFilter <var>protocol</var> <var>accept_filter</var></syntax>

<contextlist><context>server config</context></contextlist>

<compatibility>Available in Apache httpd 2.1.5 and later.

On Windows from Apache httpd 2.3.3 and later.</compatibility>

<usage>

<p>This directive enables operating system specific optimizations for a

listening socket by the <directive>Protocol</directive>type.

The basic premise is for the kernel to not send a socket to the server

process until either data is received or an entire HTTP Request is buffered.

Only <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&amp;sektion=9">

FreeBSD's Accept Filters</a>, Linux's more primitive

<code>TCP_DEFER_ACCEPT</code>, and Windows' optimized AcceptEx()

are currently supported.</p>

<p>Using <code>none</code> for an argument will disable any accept filters

for that protocol. This is useful for protocols that require a server

send data first, such as <code>ftp:</code> or <code>nntp</code>:</p>

<example>AcceptFilter nntp none</example>

<p>The default protocol names are <code>https</code> for port 443

and <code>http</code> for all other ports. To specify another protocol

is being used with a listening port, add the <var>protocol</var>

argument to the <directive module="mpm_common">Listen</directive>

directive.</p>

<p>The default values on FreeBSD are:</p>

<example>

AcceptFilter http httpready <br/>

AcceptFilter https dataready

</example>

<p>The <code>httpready</code> accept filter buffers entire HTTP requests at

the kernel level. Once an entire request is received, the kernel then

sends it to the server. See the

<a href="http://www.freebsd.org/cgi/man.cgi?query=accf_http&amp;sektion=9">

accf_http(9)</a> man page for more details. Since HTTPS requests are

encrypted only the <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_data&amp;sektion=9">

accf_data(9)</a> filter is used.</p>

<p>The default values on Linux are:</p>

<example>

AcceptFilter http data <br/>

AcceptFilter https data

</example>

<p>Linux's <code>TCP_DEFER_ACCEPT</code> does not support buffering http

requests. Any value besides <code>none</code> will enable

<code>TCP_DEFER_ACCEPT</code> on that listener. For more details

see the Linux

<a href="http://homepages.cwi.nl/~aeb/linux/man2html/man7/tcp.7.html">

tcp(7)</a> man page.</p>

<p>The default values on Windows are:</p>

<example>

AcceptFilter http data <br/>

AcceptFilter https data

</example>

<p>Window's mpm_winnt interprets the AcceptFilter to toggle the AcceptEx()

API, and does not support http protocol buffering. There are two values

which utilize the Windows AcceptEx() API and will recycle network

sockets between connections. <code>data</code> waits until data has

been transmitted as documented above, and the initial data buffer and

network endpoint addresses are all retrieved from the single AcceptEx()

invocation. <code>connect</code> will use the AcceptEx() API, also

retrieve the network endpoint addresses, but like <code>none</code>

the <code>connect</code> option does not wait for the initial data

transmission.</p>

<p>On Windows, <code>none</code> uses accept() rather than AcceptEx()

and will not recycle sockets between connections. This is useful for

network adapters with broken driver support, as well as some virtual

network providers such as vpn drivers, or spam, virus or spyware

filters.</p>

</usage>

<seealso><directive>Protocol</directive></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AcceptPathInfo</name>

<description>Resources accept trailing pathname information</description>

<syntax>AcceptPathInfo On|Off|Default</syntax>

<default>AcceptPathInfo Default</default>

<contextlist><context>server config</context>

<context>virtual host</context><context>directory</context>

<context>.htaccess</context></contextlist>

<override>FileInfo</override>

<compatibility>Available in Apache httpd 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 <code>PATH_INFO</code> environment

variable.</p>

<p>For example, assume the location <code>/test/</code> points to

a directory that contains only the single file

<code>here.html</code>. Then requests for

<code>/test/here.html/more</code> and

<code>/test/nothere.html/more</code> both collect

<code>/more</code> as <code>PATH_INFO</code>.</p>

<p>The three possible arguments for the

<directive>AcceptPathInfo</directive> directive are:</p>

<dl>

<dt><code>Off</code></dt><dd>A request will only be accepted if it

maps to a literal path that exists. Therefore a request with

trailing pathname information after the true filename such as

<code>/test/here.html/more</code> in the above example will return

a 404 NOT FOUND error.</dd>

<dt><code>On</code></dt><dd>A request will be accepted if a

leading path component maps to a file that exists. The above

example <code>/test/here.html/more</code> will be accepted if

<code>/test/here.html</code> maps to a valid file.</dd>

<dt><code>Default</code></dt><dd>The treatment of requests with

trailing pathname information is determined by the <a

href="../handler.html">handler</a> responsible for the request.

The core handler for normal files defaults to rejecting

<code>PATH_INFO</code> requests. Handlers that serve scripts, such as <a

href="mod_cgi.html">cgi-script</a> and <a

href="mod_isapi.html">isapi-handler</a>, generally accept

<code>PATH_INFO</code> by default.</dd>

</dl>

<p>The primary purpose of the <code>AcceptPathInfo</code>

directive is to allow you to override the handler's choice of

accepting or rejecting <code>PATH_INFO</code>. This override is required,

for example, when you use a <a href="../filter.html">filter</a>, such

as <a href="mod_include.html">INCLUDES</a>, to generate content

based on <code>PATH_INFO</code>. The core handler would usually reject

the request, so you can use the following configuration to enable

such a script:</p>

<example>

&lt;Files "mypaths.shtml"&gt;<br />

<indent>

Options +Includes<br />

SetOutputFilter INCLUDES<br />

AcceptPathInfo On<br />

</indent>

&lt;/Files&gt;

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AccessFileName</name>

<description>Name of the distributed configuration file</description>

<syntax>AccessFileName <var>filename</var> [<var>filename</var>] ...</syntax>

<default>AccessFileName .htaccess</default>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>While processing a request the server looks for

the first existing configuration file from this list of names in

every directory of the path to the document, if distributed

configuration files are <a href="#allowoverride">enabled for that

directory</a>. For example:</p>

<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>

&lt;Directory /&gt;<br />

<indent>

AllowOverride None<br />

</indent>

&lt;/Directory&gt;

</example>

</usage>

<seealso><directive module="core">AllowOverride</directive></seealso>

<seealso><a href="../configuring.html">Configuration Files</a></seealso>

<seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AddDefaultCharset</name>

<description>Default charset parameter to be added when a response

content-type is <code>text/plain</code> or <code>text/html</code></description>

<syntax>AddDefaultCharset On|Off|<var>charset</var></syntax>

<default>AddDefaultCharset Off</default>

<contextlist><context>server config</context>

<context>virtual host</context><context>directory</context>

<context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>This directive specifies a default value for the media type

charset parameter (the name of a character encoding) to be added

to a response if and only if the response's content-type is either

<code>text/plain</code> or <code>text/html</code>. This should override

any charset specified in the body of the response via a <code>META</code>

element, though the exact behavior is often dependent on the user's client

configuration. A setting of <code>AddDefaultCharset Off</code>

disables this functionality. <code>AddDefaultCharset On</code> enables

a default charset of <code>iso-8859-1</code>. Any other value is assumed

to be the <var>charset</var> to be used, which should be one of the

<a href="http://www.iana.org/assignments/character-sets">IANA registered

charset values</a> for use in Internet media types (MIME types).

For example:</p>

<example>

AddDefaultCharset utf-8

</example>

<p><directive>AddDefaultCharset</directive> should only be used when all

of the text resources to which it applies are known to be in that

character encoding and it is too inconvenient to label their charset

individually. One such example is to add the charset parameter

to resources containing generated content, such as legacy CGI

scripts, that might be vulnerable to cross-site scripting attacks

due to user-provided data being included in the output. Note, however,

that a better solution is to just fix (or delete) those scripts, since

setting a default charset does not protect users that have enabled

the "auto-detect character encoding" feature on their browser.</p>

</usage>

<seealso><directive module="mod_mime">AddCharset</directive></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AllowEncodedSlashes</name>

<description>Determines whether encoded path separators in URLs are allowed to

be passed through</description>

<syntax>AllowEncodedSlashes On|Off|NoDecode</syntax>

<default>AllowEncodedSlashes Off</default>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<compatibility>Available in Apache httpd 2.0.46 and later.

NoDecode option available in 2.3.12 and later.</compatibility>

<usage>

<p>The <directive>AllowEncodedSlashes</directive> directive allows URLs

which contain encoded path separators (<code>%2F</code> for <code>/</code>

and additionally <code>%5C</code> for <code>\</code> on according systems)

to be used in the path info.</p>

<p>With the default value, <code>Off</code>, such URLs are refused

with a 404 (Not found) error.</p>

<p>With the value <code>On</code>, such URLs are accepted, and encoded

slashes are decoded like all other encoded characters.</p>

<p>With the value <code>NoDecode</code>, such URLs are accepted, but

encoded slashes are not decoded but left in their encoded state.</p>

<p>Turning <directive>AllowEncodedSlashes</directive> <code>On</code> is

mostly useful when used in conjunction with <code>PATH_INFO</code>.</p>

<note><title>Note</title>

<p>If encoded slashes are needed in path info, use of <code>NoDecode</code> is

strongly recommended as a security measure. Allowing slashes

to be decoded could potentially allow unsafe paths.</p>

</note>

</usage>

<seealso><directive module="core">AcceptPathInfo</directive></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AllowOverride</name>

<description>Types of directives that are allowed in

<code>.htaccess</code> files</description>

<syntax>AllowOverride All|None|<var>directive-type</var>

[<var>directive-type</var>] ...</syntax>

<default>AllowOverride None (2.3.9 and later), AllowOverride All (2.3.8 and earlier)</default>

<contextlist><context>directory</context></contextlist>

<usage>

<p>When the server finds an <code>.htaccess</code> file (as

specified by <directive module="core">AccessFileName</directive>)

it needs to know which directives declared in that file can override

earlier configuration directives.</p>

<note><title>Only available in &lt;Directory&gt; sections</title>

<directive>AllowOverride</directive> is valid only in

<directive type="section" module="core">Directory</directive>

sections specified without regular expressions, not in <directive

type="section" module="core">Location</directive>, <directive

module="core" type="section">DirectoryMatch</directive> or

<directive type="section" module="core">Files</directive> sections.

</note>

<p>When this directive is set to <code>None</code> and <directive

module="core">AllowOverrideList</directive> is set to

<code>None</code> <a href="#accessfilename">.htaccess</a> files are

completely ignored. In this case, the server will not even attempt

to read <code>.htaccess</code> files in the filesystem.</p>

<p>When this directive is set to <code>All</code>, then any

directive which has the .htaccess <a

href="directive-dict.html#Context">Context</a> is allowed in

<code>.htaccess</code> files.</p>

<p>The <var>directive-type</var> can be one of the following

groupings of directives.</p>

<dl>

<dt>AuthConfig</dt>

<dd>

Allow use of the authorization directives (<directive

module="mod_authn_dbm">AuthDBMGroupFile</directive>,

<directive module="mod_authn_dbm">AuthDBMUserFile</directive>,

<directive module="mod_authz_groupfile">AuthGroupFile</directive>,

<directive module="mod_authn_core">AuthName</directive>,

<directive module="mod_authn_core">AuthType</directive>, <directive

module="mod_authn_file">AuthUserFile</directive>, <directive

module="mod_authz_core">Require</directive>, <em>etc.</em>).</dd>

<dt>FileInfo</dt>

<dd>

Allow use of the directives controlling document types

(<directive module="core">ErrorDocument</directive>,

<directive module="core">ForceType</directive>,

<directive module="mod_negotiation">LanguagePriority</directive>,

<directive module="core">SetHandler</directive>,

<directive module="core">SetInputFilter</directive>,

<directive module="core">SetOutputFilter</directive>, and

<module>mod_mime</module> Add* and Remove* directives),

document meta data (<directive

module="mod_headers">Header</directive>, <directive

module="mod_headers">RequestHeader</directive>, <directive

module="mod_setenvif">SetEnvIf</directive>, <directive

module="mod_setenvif">SetEnvIfNoCase</directive>, <directive

module="mod_setenvif">BrowserMatch</directive>, <directive

module="mod_usertrack">CookieExpires</directive>, <directive

module="mod_usertrack">CookieDomain</directive>, <directive

module="mod_usertrack">CookieStyle</directive>, <directive

module="mod_usertrack">CookieTracking</directive>, <directive

module="mod_usertrack">CookieName</directive>),

<module>mod_rewrite</module> directives <directive

module="mod_rewrite">RewriteEngine</directive>, <directive

module="mod_rewrite">RewriteOptions</directive>, <directive

module="mod_rewrite">RewriteBase</directive>, <directive

module="mod_rewrite">RewriteCond</directive>, <directive

module="mod_rewrite">RewriteRule</directive>) and

<directive module="mod_actions">Action</directive> from

<module>mod_actions</module>.

</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_authz_host">Allow</directive>, <directive

module="mod_authz_host">Deny</directive> and <directive

module="mod_authz_host">Order</directive>).</dd>

<dt>Options[=<var>Option</var>,...]</dt>

<dd>

Allow use of the directives controlling specific directory

features (<directive module="core">Options</directive> and

<directive module="mod_include">XBitHack</directive>).

An equal sign may be given followed by a comma (but no spaces)

separated lists of options that may be set using the <directive

module="core">Options</directive> command.

<note><title>Implicit disabling of Options</title>

<p>Even though the list of options that may be used in .htaccess files

can be limited with this directive, as long as any <directive

module="core">Options</directive> directive is allowed any

other inherited option can be disabled by using the non-relative

syntax. In other words, this mechanism cannot force a specific option

to remain <em>set</em> while allowing any others to be set.

</p></note>

</dd>

</dl>

<p>Example:</p>

<example>

AllowOverride AuthConfig Indexes

</example>

<p>In the example above all directives that are neither in the group

<code>AuthConfig</code> nor <code>Indexes</code> cause an internal

server error.</p>

<note><p>For security and performance reasons, do not set

<code>AllowOverride</code> to anything other than <code>None</code>

in your <code>&lt;Directory /&gt;</code> block. Instead, find (or

create) the <code>&lt;Directory&gt;</code> block that refers to the

directory where you're actually planning to place a

<code>.htaccess</code> file.</p>

</note>

</usage>

<seealso><directive module="core">AccessFileName</directive></seealso>

<seealso><directive module="core">AllowOverrideList</directive></seealso>

<seealso><a href="../configuring.html">Configuration Files</a></seealso>

<seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AllowOverrideList</name>

<description>Individual directives that are allowed in

<code>.htaccess</code> files</description>

<syntax>AllowOverrideList None|<var>directive</var>

[<var>directive-type</var>] ...</syntax>

<default>AllowOverrideList None</default>

<contextlist><context>directory</context></contextlist>

<usage>

<p>When the server finds an <code>.htaccess</code> file (as

specified by <directive module="core">AccessFileName</directive>)

it needs to know which directives declared in that file can override

earlier configuration directives.</p>

<note><title>Only available in &lt;Directory&gt; sections</title>

<directive>AllowOverrideList</directive> is valid only in

<directive type="section" module="core">Directory</directive>

sections specified without regular expressions, not in <directive

type="section" module="core">Location</directive>, <directive

module="core" type="section">DirectoryMatch</directive> or

<directive type="section" module="core">Files</directive> sections.

</note>

<p>When this directive is set to <code>None</code> and <directive

module="core">AllowOverride</directive> is set to <code>None</code>,

then <a href="#accessfilename">.htaccess</a> files are completely

ignored. In this case, the server will not even attempt to read

<code>.htaccess</code> files in the filesystem.</p>

<p>Example:</p>

<example>

AllowOverride None<br />

AllowOverrideList Redirect RedirectMatch

</example>

<p>In the example above only the <code>Redirect</code> and

<code>RedirectMatch</code> directives are allowed. All others will

cause an internal server error.</p>

<p>Example:</p>

<example>

AllowOverride AuthConfig<br />

AllowOverrideList CookieTracking CookieName

</example>

<p>In the example above <directive module="core">AllowOverride

</directive> grants permission to the <code>AuthConfig</code>

directive grouping and <directive>AllowOverrideList</directive> grants

permission to only two directves from the <code>FileInfo</code> directive

grouping. All others will cause an internal server error.</p>

</usage>

<seealso><directive module="core">AccessFileName</directive></seealso>

<seealso><directive module="core">AllowOverride</directive></seealso>

<seealso><a href="../configuring.html">Configuration Files</a></seealso>

<seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso>

</directivesynopsis>

<directivesynopsis>

<name>CGIMapExtension</name>

<description>Technique for locating the interpreter for CGI

scripts</description>

<syntax>CGIMapExtension <var>cgi-path</var> <var>.extension</var></syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>FileInfo</override>

<compatibility>NetWare only</compatibility>

<usage>

<p>This directive is used to control how Apache httpd finds the

interpreter used to run CGI scripts. For example, setting

<code>CGIMapExtension sys:\foo.nlm .foo</code> will

cause all CGI script files with a <code>.foo</code> extension to

be passed to the FOO interpreter.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ContentDigest</name>

<description>Enables the generation of <code>Content-MD5</code> HTTP Response

headers</description>

<syntax>ContentDigest On|Off</syntax>

<default>ContentDigest Off</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>Options</override>

<status>Experimental</status>

<usage>

<p>This directive enables the generation of

<code>Content-MD5</code> headers as defined in RFC1864

respectively RFC2616.</p>

<p>MD5 is an algorithm for computing a "message digest"

(sometimes called "fingerprint") of arbitrary-length data, with

a high degree of confidence that any alterations in the data

will be reflected in alterations in the message digest.</p>

<p>The <code>Content-MD5</code> header provides an end-to-end

message integrity check (MIC) of the entity-body. A proxy or

client may check this header for detecting accidental

modification of the entity-body in transit. Example header:</p>

<example>

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

</example>

<p>Note that this can cause performance problems on your server

since the message digest is computed on every request (the

values are not cached).</p>

<p><code>Content-MD5</code> is only sent for documents served

by the <module>core</module>, and not by any module. For example,

SSI documents, output from CGI scripts, and byte range responses

do not have this header.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DefaultType</name>

<description>This directive has no effect other than to emit warnings

if the value is not <code>none</code>. In prior versions, DefaultType

would specify a default media type to assign to response content for

which no other media type configuration could be found.

</description>

<syntax>DefaultType <var>media-type|none</var></syntax>

<default>DefaultType none</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>FileInfo</override>

<compatibility>The argument <code>none</code> is available in Apache httpd 2.2.7 and later. All other choices are DISABLED for 2.3.x and later.</compatibility>

<usage>

<p>This directive has been disabled. For backwards compatibility

of configuration files, it may be specified with the value

<code>none</code>, meaning no default media type. For example:</p>

<example>

DefaultType None

</example>

<p><code>DefaultType None</code> is only available in

httpd-2.2.7 and later.</p>

<p>Use the mime.types configuration file and the

<directive module="mod_mime">AddType</directive> to configure media

type assignments via file extensions, or the

<directive module="core">ForceType</directive> directive to configure

the media type for specific resources. Otherwise, the server will

send the response without a Content-Type header field and the

recipient may attempt to guess the media type.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Define</name>

<description>Define a variable</description>

<syntax>Define <var>parameter-name</var> [<var>parameter-value</var>]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<usage>

<p>In its one parameter form, <directive>Define</directive> is equivalent

to passing the <code>-D</code> argument to <program>httpd</program>. It

can be used to toggle the use of

<directive module="core" type="section">IfDefine</directive> sections

without needing to alter <code>-D</code> arguments in any startup

scripts.</p>

<p>In addition to that, if the second parameter is given, a config variable

is set to this value. The variable can be used in the configuration using

the <code>${VAR}</code> syntax. The variable is always globally defined

and not limited to the scope of the surrounding config section.</p>

<example>

&lt;IfDefine TEST&gt;<br/>

&nbsp;&nbsp;Define servername test.example.com<br/>

&lt;/IfDefine&gt;<br/>

&lt;IfDefine !TEST&gt;<br/>

&nbsp;&nbsp;Define servername www.example.com<br/>

&nbsp;&nbsp;Define SSL<br/>

&lt;/IfDefine&gt;<br/>

</example>

<p>Variable names may not contain colon ":" characters, to avoid clashes

with <directive module="mod_rewrite">RewriteMap</directive>'s syntax.</p>

</usage>

</directivesynopsis>

<directivesynopsis type="section">

<name>Directory</name>

<description>Enclose a group of directives that apply only to the

named file-system directory, sub-directories, and their contents.</description>

<syntax>&lt;Directory <var>directory-path</var>&gt;

... &lt;/Directory&gt;</syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p><directive type="section">Directory</directive> and

<code>&lt;/Directory&gt;</code> are used to enclose a group of

directives that will apply only to the named directory,

sub-directories of that directory, and the files within the respective

directories. Any directive that is allowed

in a directory context may be used. <var>Directory-path</var> is

either the full path to a directory, or a wild-card string using

Unix shell-style matching. In a wild-card string, <code>?</code> matches

any single character, and <code>*</code> matches any sequences of

characters. You may also use <code>[]</code> character ranges. None

of the wildcards match a `/' character, so <code>&lt;Directory

/*/public_html&gt;</code> will not match

<code>/home/user/public_html</code>, but <code>&lt;Directory

/home/*/public_html&gt;</code> will match. Example:</p>

<example>

&lt;Directory /usr/local/httpd/htdocs&gt;<br />

<indent>

Options Indexes FollowSymLinks<br />

</indent>

&lt;/Directory&gt;

</example>

<note>

<p>Be careful with the <var>directory-path</var> arguments:

They have to literally match the filesystem path which Apache httpd uses

to access the files. Directives applied to a particular

<code>&lt;Directory&gt;</code> will not apply to files accessed from

that same directory via a different path, such as via different symbolic

links.</p>

</note>

<p><glossary ref="regex">Regular

expressions</glossary> can also be used, with the addition of the

<code>~</code> character. For example:</p>

<example>

&lt;Directory ~ "^/www/.*/[0-9]{3}"&gt;

</example>

<p>would match directories in <code>/www/</code> that consisted of

three numbers.</p>

<p>If multiple (non-regular expression) <directive

type="section">Directory</directive> sections

match the directory (or one of its parents) containing a document,

then the directives are applied in the order of shortest match

first, interspersed with the directives from the <a

href="#accessfilename">.htaccess</a> files. For example,

with</p>

<example>

&lt;Directory /&gt;<br />

<indent>

AllowOverride None<br />

</indent>

&lt;/Directory&gt;<br />

<br />

&lt;Directory /home&gt;<br />

<indent>

AllowOverride FileInfo<br />

</indent>

&lt;/Directory&gt;

</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</code>).</li>

<li>Apply any <code>FileInfo</code> directives in

<code>/home/.htaccess</code>, <code>/home/web/.htaccess</code> and

<code>/home/web/dir/.htaccess</code> in that order.</li>

</ul>

<p>Regular expressions are not considered until after all of the

normal sections have been applied. Then all of the regular

expressions are tested in the order they appeared in the

configuration file. For example, with</p>

<example>

&lt;Directory ~ abc$&gt;<br />

<indent>

# ... directives here ...<br />

</indent>

&lt;/Directory&gt;

</example>

<p>the regular expression section won't be considered until after

all normal <directive type="section">Directory</directive>s and

<code>.htaccess</code> files have been applied. Then the regular

expression will match on <code>/home/abc/public_html/abc</code> and

the corresponding <directive type="section">Directory</directive> will

be applied.</p>

<p><strong>Note that the default access for

<code>&lt;Directory /&gt;</code> is to permit all access.

This means that Apache httpd will serve any file mapped from an URL. It is

recommended that you change this with a block such

as</strong></p>

<example>

&lt;Directory /&gt;<br />

<indent>

Require all denied<br />

</indent>

&lt;/Directory&gt;

</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 occur in the <code>httpd.conf</code> file.

<directive type="section">Directory</directive> directives

cannot nest, and cannot appear in a <directive module="core"

type="section">Limit</directive> or <directive module="core"

type="section">LimitExcept</directive> section.</p>

</usage>

<seealso><a href="../sections.html">How &lt;Directory&gt;,

&lt;Location&gt; and &lt;Files&gt; sections work</a> for an

explanation of how these different sections are combined when a

request is received</seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>DirectoryMatch</name>

<description>Enclose directives that apply to

the contents of file-system directories matching a regular expression.</description>

<syntax>&lt;DirectoryMatch <var>regex</var>&gt;

... &lt;/DirectoryMatch&gt;</syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p><directive type="section">DirectoryMatch</directive> and

<code>&lt;/DirectoryMatch&gt;</code> are used to enclose a group

of directives which will apply only to the named directory (and the files within),

the same as <directive module="core" type="section">Directory</directive>.

However, it takes as an argument a

<glossary ref="regex">regular expression</glossary>. For example:</p>

<example>

&lt;DirectoryMatch "^/www/(.+/)?[0-9]{3}"&gt;

</example>

<p>would match directories in <code>/www/</code> that consisted of three

numbers.</p>

<note><title>Compatability</title>

Prior to 2.3.9, this directive implicitly applied to sub-directories

(like <directive module="core" type="section">Directory</directive>) and

could not match the end of line symbol ($). In 2.3.9 and later,

only directories that match the expression are affected by the enclosed

directives.

</note>

<note><title>Trailing Slash</title>

This directive applies to requests for directories that may or may

not end in a trailing slash, so expressions that are anchored to the

end of line ($) must be written with care.

</note>

</usage>

<seealso><directive type="section" module="core">Directory</directive> for

a description of how regular expressions are mixed in with normal

<directive type="section">Directory</directive>s</seealso>

<seealso><a

href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt; and

&lt;Files&gt; sections work</a> for an explanation of how these different

sections are combined when a request is received</seealso>

</directivesynopsis>

<directivesynopsis>

<name>DocumentRoot</name>

<description>Directory that forms the main document tree visible

from the web</description>

<syntax>DocumentRoot <var>directory-path</var></syntax>

<default>DocumentRoot /usr/local/apache/htdocs</default>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>This directive sets the directory from which <program>httpd</program>

will serve files. Unless matched by a directive like <directive

module="mod_alias">Alias</directive>, the server appends the

path from the requested URL to the document root to make the

path to the document. Example:</p>

<example>

DocumentRoot /usr/web

</example>

<p>then an access to

<code>http://my.example.com/index.html</code> refers to

<code>/usr/web/index.html</code>. If the <var>directory-path</var> is

not absolute then it is assumed to be relative to the <directive

module="core">ServerRoot</directive>.</p>

<p>The <directive>DocumentRoot</directive> should be specified without

a trailing slash.</p>

</usage>

<seealso><a href="../urlmapping.html#documentroot">Mapping URLs to Filesystem

Locations</a></seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>Else</name>

<description>Contains directives that apply only if the condition of a

previous <directive type="section" module="core">If</directive> or

<directive type="section" module="core">ElseIf</directive> section is not

satisfied by a request at runtime</description>

<syntax>&lt;Else&gt; ... &lt;/Else&gt;</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage>

<p>The <directive type="section">Else</directive> applies the enclosed

directives if and only if the most recent

<directive type="section">If</directive> or

<directive type="section">ElseIf</directive> section

in the same scope has not been applied.

For example: In </p>

<example>

&lt;If "-z req('Host')"&gt;<br/>

...<br/>

&lt;/If&gt;<br/>

&lt;Else&gt;<br/>

...<br/>

&lt;/Else&gt;<br/>

</example>

<p> The <directive type="section">If</directive> would match HTTP/1.0

requests without a <var>Host:</var> header and the

<directive type="section">Else</directive> would match requests

with a <var>Host:</var> header.</p>

</usage>

<seealso><directive type="section" module="core">If</directive></seealso>

<seealso><directive type="section" module="core">ElseIf</directive></seealso>

<seealso><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;,

&lt;Files&gt; sections work</a> for an explanation of how these

different sections are combined when a request is received.

<directive type="section">If</directive>,

<directive type="section">ElseIf</directive>, and

<directive type="section">Else</directive> are applied last.</seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>ElseIf</name>

<description>Contains directives that apply only if a condition is satisfied

by a request at runtime while the condition of a previous

<directive type="section" module="core">If</directive> or

<directive type="section">ElseIf</directive> section is not

satisfied</description>

<syntax>&lt;ElseIf <var>expression</var>&gt; ... &lt;/ElseIf&gt;</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage>

<p>The <directive type="section">ElseIf</directive> applies the enclosed

directives if and only if both the given condition evaluates to true and

the most recent <directive type="section">If</directive> or

<directive type="section">ElseIf</directive> section in the same scope has

not been applied. For example: In </p>

<example>

&lt;If "-R '10.1.0.0/16'"&gt;<br/>

...<br/>

&lt;/If&gt;<br/>

&lt;ElseIf "-R '10.0.0.0/8'"&gt;<br/>

...<br/>

&lt;/ElseIf&gt;<br/>

&lt;Else&gt;<br/>

...<br/>

&lt;/Else&gt;<br/>

</example>

<p>The <directive type="section">ElseIf</directive> would match if

the remote address of a request belongs to the subnet 10.0.0.0/8 but

not to the subnet 10.1.0.0/16.</p>

</usage>

<seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>,

for a complete reference and more examples.</seealso>

<seealso><directive type="section" module="core">If</directive></seealso>

<seealso><directive type="section" module="core">Else</directive></seealso>

<seealso><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;,

&lt;Files&gt; sections work</a> for an explanation of how these

different sections are combined when a request is received.

<directive type="section">If</directive>,

<directive type="section">ElseIf</directive>, and

<directive type="section">Else</directive> are applied last.</seealso>

</directivesynopsis>

<directivesynopsis>

<name>EnableMMAP</name>

<description>Use memory-mapping to read files during delivery</description>

<syntax>EnableMMAP On|Off</syntax>

<default>EnableMMAP On</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>FileInfo</override>

<usage>

<p>This directive controls whether the <program>httpd</program> may use

memory-mapping if it needs to read the contents of a file during

delivery. By default, when the handling of a request requires

access to the data within a file -- for example, when delivering a

server-parsed file using <module>mod_include</module> -- Apache httpd

memory-maps the file if the OS supports it.</p>

<p>This memory-mapping sometimes yields a performance improvement.

But in some environments, it is better to disable the memory-mapping

to prevent operational problems:</p>

<ul>

<li>On some multiprocessor systems, memory-mapping can reduce the

performance of the <program>httpd</program>.</li>

<li>Deleting or truncating a file while <program>httpd</program>

has it memory-mapped can cause <program>httpd</program> to

crash with a segmentation fault.

</li>