1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="directive-dict.xml.meta">
25 <title>Terms Used to Describe Directives</title>
28 <p>This document describes the terms that are used to describe
29 each Apache <a href="directives.html">configuration
32 <seealso><a href="../configuring.html">Configuration files</a></seealso>
34 <section id="Description"><title>Description</title>
36 <p>A brief description of the purpose of the directive.</p>
39 <section id="Syntax"><title>Syntax</title>
41 <p>This indicates the format of the directive as it would
42 appear in a configuration file. This syntax is extremely
43 directive-specific, and is described in detail in the
44 directive's definition. Generally, the directive name is
45 followed by a series of one or more space-separated arguments.
46 If an argument contains a space, the argument must be enclosed
47 in double quotes. Optional arguments are enclosed in square
48 brackets. Where an argument can take on more than one possible
49 value, the possible values are separated by vertical bars "|".
50 Literal text is presented in the default font, while
51 argument-types for which substitution is necessary are
52 <em>emphasized</em>. Directives which can take a variable
53 number of arguments will end in "..." indicating that the last
54 argument is repeated.</p>
56 <p>Directives use a great number of different argument types. A
57 few common ones are defined below.</p>
62 <dd>A complete Uniform Resource Locator including a scheme,
63 hostname, and optional pathname as in
64 <code>http://www.example.com/path/to/file.html</code></dd>
66 <dt><em>URL-path</em></dt>
68 <dd>The part of a <em>url</em> which follows the scheme and
69 hostname as in <code>/path/to/file.html</code>. The
70 <em>url-path</em> represents a web-view of a resource, as
71 opposed to a file-system view.</dd>
73 <dt><em>file-path</em></dt>
75 <dd>The path to a file in the local file-system beginning
76 with the root directory as in
77 <code>/usr/local/apache/htdocs/path/to/file.html</code>.
78 Unless otherwise specified, a <em>file-path</em> which does
79 not begin with a slash will be treated as relative to the <a
80 href="core.html#serverroot">ServerRoot</a>.</dd>
82 <dt><em>directory-path</em></dt>
84 <dd>The path to a directory in the local file-system
85 beginning with the root directory as in
86 <code>/usr/local/apache/htdocs/path/to/</code>.</dd>
88 <dt><em>filename</em></dt>
90 <dd>The name of a file with no accompanying path information
91 as in <code>file.html</code>.</dd>
93 <dt><em>regex</em></dt>
95 <dd>A Perl-compatible <glossary ref="regex">regular
96 expression</glossary>. The directive definition will specify what the
97 <em>regex</em> is matching against.</dd>
99 <dt><em>extension</em></dt>
101 <dd>In general, this is the part of the <em>filename</em>
102 which follows the last dot. However, Apache recognizes
103 multiple filename extensions, so if a <em>filename</em>
104 contains more than one dot, each dot-separated part of the
105 filename following the first dot is an <em>extension</em>.
106 For example, the <em>filename</em> <code>file.html.en</code>
107 contains two extensions: <code>.html</code> and
108 <code>.en</code>. For Apache directives, you may specify
109 <em>extension</em>s with or without the leading dot. In
110 addition, <em>extension</em>s are not case sensitive.</dd>
112 <dt><em>MIME-type</em></dt>
114 <dd>A method of describing the format of a file which
115 consists of a major format type and a minor format type,
116 separated by a slash as in <code>text/html</code>.</dd>
118 <dt><em>env-variable</em></dt>
120 <dd>The name of an <a href="../env.html">environment
121 variable</a> defined in the Apache configuration process.
122 Note this is not necessarily the same as an operating system
123 environment variable. See the <a
124 href="../env.html">environment variable documentation</a> for
129 <section id="Default"><title>Default</title>
131 <p>If the directive has a default value (<em>i.e.</em>, if you
132 omit it from your configuration entirely, the Apache Web server
133 will behave as though you set it to a particular value), it is
134 described here. If there is no default value, this section
135 should say "<em>None</em>". Note that the default listed here
136 is not necessarily the same as the value the directive takes in
137 the default httpd.conf distributed with the server.</p>
140 <section id="Context"><title>Context</title>
142 <p>This indicates where in the server's configuration files the
143 directive is legal. It's a comma-separated list of one or more
144 of the following values:</p>
147 <dt>server config</dt>
149 <dd>This means that the directive may be used in the server
150 configuration files (<em>e.g.</em>, <code>httpd.conf</code>), but
151 <strong>not</strong> within any
152 <directive module="core" type="section">VirtualHost</directive>
153 or <directive module="core" type="section">Directory</directive>
154 containers. It is not allowed in <code>.htaccess</code> files
157 <dt>virtual host</dt>
159 <dd>This context means that the directive may appear inside
160 <directive module="core" type="section">VirtualHost</directive>
161 containers in the server
162 configuration files.</dd>
166 <dd>A directive marked as being valid in this context may be
167 used inside <directive module="core"
168 type="section">Directory</directive>, <directive type="section"
169 module="core">Location</directive>, <directive module="core"
170 type="section">Files</directive>, and <directive
171 module="mod_proxy" type="section">Proxy</directive> containers
172 in the server configuration files, subject to the restrictions
173 outlined in <a href="../sections.html">Configuration
178 <dd>If a directive is valid in this context, it means that it
179 can appear inside <em>per</em>-directory
180 <code>.htaccess</code> files. It may not be processed, though
181 depending upon the <a href="#Override"
182 >overrides</a> currently active.</dd>
185 <p>The directive is <em>only</em> allowed within the designated
186 context; if you try to use it elsewhere, you'll get a
187 configuration error that will either prevent the server from
188 handling requests in that context correctly, or will keep the
189 server from operating at all -- <em>i.e.</em>, the server won't
192 <p>The valid locations for the directive are actually the
193 result of a Boolean OR of all of the listed contexts. In other
194 words, a directive that is marked as being valid in
195 "<code>server config, .htaccess</code>" can be used in the
196 <code>httpd.conf</code> file and in <code>.htaccess</code>
197 files, but not within any <directive module="core"
198 type="section">Directory</directive> or
199 <directive module="core" type="section">VirtualHost</directive>
203 <section id="Override"><title>Override</title>
205 <p>This directive attribute indicates which configuration
206 override must be active in order for the directive to be
207 processed when it appears in a <code>.htaccess</code> file. If
208 the directive's <a href="#Context" >context</a>
209 doesn't permit it to appear in <code>.htaccess</code> files,
210 then no context will be listed.</p>
212 <p>Overrides are activated by the <directive
213 module="core">AllowOverride</directive> directive, and apply
214 to a particular scope (such as a directory) and all
215 descendants, unless further modified by other
216 <directive module="core">AllowOverride</directive> directives at
217 lower levels. The documentation for that directive also lists the
218 possible override names available.</p>
221 <section id="Status"><title>Status</title>
223 <p>This indicates how tightly bound into the Apache Web server
224 the directive is; in other words, you may need to recompile the
225 server with an enhanced set of modules in order to gain access
226 to the directive and its functionality. Possible values for
227 this attribute are:</p>
232 <dd>If a directive is listed as having "Core" status, that
233 means it is part of the innermost portions of the Apache Web
234 server, and is always available.</dd>
238 <dd>A directive labeled as having "MPM" status is provided by
239 a <a href="../mpm.html">Multi-Processing Module</a>. This
240 type of directive will be available if and only if you are
241 using one of the MPMs listed on the <a
242 href="#Module">Module</a> line of the directive
247 <dd>A directive labeled as having "Base" status is supported
248 by one of the standard Apache modules which is compiled into
249 the server by default, and is therefore normally available
250 unless you've taken steps to remove the module from your
255 <dd>A directive with "Extension" status is provided by one of
256 the modules included with the Apache server kit, but the
257 module isn't normally compiled into the server. To enable the
258 directive and its functionality, you will need to change the
259 server build configuration files and re-compile Apache.</dd>
261 <dt>Experimental</dt>
263 <dd>"Experimental" status indicates that the directive is
264 available as part of the Apache kit, but you're on your own
265 if you try to use it. The directive is being documented for
266 completeness, and is not necessarily supported. The module
267 which provides the directive may or may not be compiled in by
268 default; check the top of the page which describes the
269 directive and its module to see if it remarks on the
274 <section id="Module"><title>Module</title>
276 <p>This quite simply lists the name of the source module which
277 defines the directive.</p>
280 <section id="Compatibility"><title>Compatibility</title>
282 <p>If the directive wasn't part of the original Apache version
283 2 distribution, the version in which it was introduced should
284 be listed here. In addition, if the directive is available
285 only on certain platforms, it will be noted here.</p>