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