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 Copyright 2002-2005 The Apache Software Foundation or its licensors, as
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 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="sections.xml.meta">
25 <title>Configuration Sections</title>
27 <summary> <p>Directives in the <a
28 href="configuring.html">configuration files</a> may apply to the
29 entire server, or they may be restricted to apply only to particular
30 directories, files, hosts, or URLs. This document describes how to
31 use configuration section containers or <code>.htaccess</code> files
32 to change the scope of other configuration directives.</p>
35 <section id="types"><title>Types of Configuration Section Containers</title>
40 <module>mod_proxy</module>
43 <directive type="section" module="core">Directory</directive>
44 <directive type="section" module="core">DirectoryMatch</directive>
45 <directive type="section" module="core">Files</directive>
46 <directive type="section" module="core">FilesMatch</directive>
47 <directive type="section" module="core">IfDefine</directive>
48 <directive type="section" module="core">IfModule</directive>
49 <directive type="section" module="core">Location</directive>
50 <directive type="section" module="core">LocationMatch</directive>
51 <directive type="section" module="mod_proxy">Proxy</directive>
52 <directive type="section" module="mod_proxy">ProxyMatch</directive>
53 <directive type="section" module="core">VirtualHost</directive>
57 <p>There are two basic types of containers. Most containers are
58 evaluated for each request. The enclosed directives are applied only
59 for those requests that match the containers. The <directive
60 type="section" module="core">IfDefine</directive> and <directive
61 type="section" module="core">IfModule</directive> containers, on the
62 other hand, are evaluated only at server startup and restart. If
63 their conditions are true at startup, then the enclosed directives
64 will apply to all requests. If the conditions are not true, the
65 enclosed directives will be ignored.</p>
67 <p>The <directive type="section" module="core">IfDefine</directive> directive
68 encloses directives that will only be applied if an appropriate
69 parameter is defined on the <program>httpd</program> command line. For example,
70 with the following configuration, all requests will be redirected
71 to another site only if the server is started using
72 <code>httpd -DClosedForNow</code>:</p>
75 <IfDefine ClosedForNow><br />
76 Redirect / http://otherserver.example.com/<br />
80 <p>The <directive type="section" module="core">IfModule</directive>
81 directive is very similar, except it encloses directives that will
82 only be applied if a particular module is available in the server.
83 The module must either be statically compiled in the server, or it
84 must be dynamically compiled and its <directive
85 module="mod_so">LoadModule</directive> line must be earlier in the
86 configuration file. This directive should only be used if you need
87 your configuration file to work whether or not certain modules are
88 installed. It should not be used to enclose directives that you want
89 to work all the time, because it can suppress useful error messages
90 about missing modules.</p>
92 <p>In the following example, the <directive
93 module="mod_mime_magic">MimeMagicFiles</directive> directive will be
94 applied only if <module>mod_mime_magic</module> is available.</p>
97 <IfModule mod_mime_magic.c><br />
98 MimeMagicFile conf/magic<br />
102 <p>Both <directive type="section" module="core">IfDefine</directive>
103 and <directive type="section" module="core">IfModule</directive>
104 can apply negative conditions by preceding their test with "!".
105 Also, these sections can be nested to achieve more complex
109 <section id="file-and-web"><title>Filesystem and Webspace</title>
111 <p>The most commonly used configuration section containers are the
112 ones that change the configuration of particular places in the
113 filesystem or webspace. First, it is important to understand the
114 difference between the two. The filesystem is the view of your disks
115 as seen by your operating system. For example, in a default install,
116 Apache resides at <code>/usr/local/apache2</code> in the Unix
117 filesystem or <code>"c:/Program Files/Apache Group/Apache2"</code> in
118 the Windows filesystem. (Note that forward slashes should always be
119 used as the path separator in Apache, even for Windows.) In contrast,
120 the webspace is the view of your site as delivered by the web server
121 and seen by the client. So the path <code>/dir/</code> in the
122 webspace corresponds to the path
123 <code>/usr/local/apache2/htdocs/dir/</code> in the filesystem of a
124 default Apache install on Unix. The webspace need not map directly to
125 the filesystem, since webpages may be generated dynamically
126 from databases or other locations.</p>
128 <section id="filesystem"><title>Filesystem Containers</title>
130 <p>The <directive type="section" module="core">Directory</directive>
131 and <directive type="section" module="core">Files</directive>
132 directives, along with their regex counterparts, apply directives to
133 parts of the filesystem. Directives enclosed in a <directive
134 type="section" module="core">Directory</directive> section apply to
135 the named filesystem directory and all subdirectories of that
136 directory. The same effect can be obtained using <a
137 href="howto/htaccess.html">.htaccess files</a>. For example, in the
138 following configuration, directory indexes will be enabled for the
139 <code>/var/web/dir1</code> directory and all subdirectories.</p>
142 <Directory /var/web/dir1><br />
143 Options +Indexes<br />
147 <p>Directives enclosed in a <directive type="section"
148 module="core">Files</directive> section apply to any file with
149 the specified name, regardless of what directory it lies in.
150 So for example, the following configuration directives will,
151 when placed in the main section of the configuration file,
152 deny access to any file named <code>private.html</code> regardless
153 of where it is found.</p>
156 <Files private.html><br />
157 Order allow,deny<br />
162 <p>To address files found in a particular part of the filesystem, the
163 <directive type="section" module="core">Files</directive> and
164 <directive type="section" module="core">Directory</directive> sections
165 can be combined. For example, the following configuration will deny
166 access to <code>/var/web/dir1/private.html</code>,
167 <code>/var/web/dir1/subdir2/private.html</code>,
168 <code>/var/web/dir1/subdir3/private.html</code>, and any other instance
169 of <code>private.html</code> found under the <code>/var/web/dir1/</code>
173 <Directory /var/web/dir1><br />
174 <Files private.html><br />
175 Order allow,deny<br />
182 <section id="webspace"><title>Webspace Containers</title>
184 <p>The <directive type="section" module="core">Location</directive>
185 directive and its regex counterpart, on the other hand, change the
186 configuration for content in the webspace. For example, the following
187 configuration prevents access to any URL-path that begins in /private.
188 In particular, it will apply to requests for
189 <code>http://yoursite.example.com/private</code>,
190 <code>http://yoursite.example.com/private123</code>, and
191 <code>http://yoursite.example.com/private/dir/file.html</code> as well
192 as any other requests starting with the <code>/private</code> string.</p>
195 <Location /private><br />
196 Order Allow,Deny<br />
201 <p>The <directive type="section" module="core">Location</directive>
202 directive need not have anything to do with the filesystem.
203 For example, the following example shows how to map a particular
204 URL to an internal Apache handler provided by <module>mod_status</module>.
205 No file called <code>server-status</code> needs to exist in the
209 <Location /server-status><br />
210 SetHandler server-status<br />
215 <section id="wildcards"><title>Wildcards and Regular Expressions</title>
217 <p>The <directive type="section" module="core">Directory</directive>,
218 <directive type="section" module="core">Files</directive>, and
219 <directive type="section" module="core">Location</directive>
220 directives can each use shell-style wildcard characters as in
221 <code>fnmatch</code> from the C standard library. The character "*"
222 matches any sequence of characters, "?" matches any single character,
223 and "[<em>seq</em>]" matches any character in <em>seq</em>. The "/"
224 character will not be matched by any wildcard; it must be specified
227 <p>If even more flexible matching is required, each
228 container has a regular-expression (regex) counterpart <directive
229 type="section" module="core">DirectoryMatch</directive>, <directive
230 type="section" module="core">FilesMatch</directive>, and <directive
231 type="section" module="core">LocationMatch</directive> that allow
233 <a href="glossary.html#regex">regular expressions</a>
234 to be used in choosing the matches. But see the section below on
235 configuration merging to find out how using regex sections will change
236 how directives are applied.</p>
238 <p>A non-regex wildcard section that changes the configuration of
239 all user directories could look as follows:</p>
242 <Directory /home/*/public_html><br />
243 Options Indexes<br />
247 <p>Using regex sections, we can deny access to many types of image files
250 <FilesMatch \.(?i:gif|jpe?g|png)$><br />
251 Order allow,deny<br />
258 <section id="whichwhen"><title>What to use When</title>
260 <p>Choosing between filesystem containers and webspace containers is
261 actually quite easy. When applying directives to objects that reside
262 in the filesystem always use <directive type="section"
263 module="core">Directory</directive> or <directive type="section"
264 module="core">Files</directive>. When applying directives to objects
265 that do not reside in the filesystem (such as a webpage generated from
266 a database), use <directive type="section"
267 module="core">Location</directive>.</p>
269 <p>It is important to never use <directive type="section"
270 module="core">Location</directive> when trying to restrict
271 access to objects in the filesystem. This is because many
272 different webspace locations (URLs) could map to the same filesystem
273 location, allowing your restrictions to be circumvented.
274 For example, consider the following configuration:</p>
277 <Location /dir/><br />
278 Order allow,deny<br />
283 <p>This works fine if the request is for
284 <code>http://yoursite.example.com/dir/</code>. But what if you are on
285 a case-insensitive filesystem? Then your restriction could be easily
286 circumvented by requesting
287 <code>http://yoursite.example.com/DIR/</code>. The <directive
288 type="section" module="core">Directory</directive> directive, in
289 contrast, will apply to any content served from that location,
290 regardless of how it is called. (An exception is filesystem links.
291 The same directory can be placed in more than one part of the
292 filesystem using symbolic links. The <directive type="section"
293 module="core">Directory</directive> directive will follow the symbolic
294 link without resetting the pathname. Therefore, for the highest level
295 of security, symbolic links should be disabled with the appropriate
296 <directive module="core">Options</directive> directive.)</p>
298 <p>If you are, perhaps, thinking that none of this applies to you
299 because you use a case-sensitive filesystem, remember that there are
300 many other ways to map multiple webspace locations to the same
301 filesystem location. Therefore you should always use the filesystem
302 containers when you can. There is, however, one exception to this
303 rule. Putting configuration restrictions in a <code><Location
304 /></code> section is perfectly safe because this section will apply
305 to all requests regardless of the specific URL.</p>
310 <section id="virtualhost"><title>Virtual Hosts</title>
312 <p>The <directive type="section" module="core">VirtualHost</directive>
313 container encloses directives that apply to specific hosts.
314 This is useful when serving multiple hosts from the same machine
315 with a different configuration for each. For more information,
316 see the <a href="vhosts/">Virtual Host Documentation</a>.</p>
319 <section id="proxy"><title>Proxy</title>
321 <p>The <directive type="section" module="mod_proxy">Proxy</directive>
322 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
323 containers apply enclosed configuration directives only
324 to sites accessed through <module>mod_proxy</module>'s proxy server
325 that match the specified URL. For example, the following configuration
326 will prevent the proxy server from being used to access the
327 <code>cnn.com</code> website.</p>
330 <Proxy http://cnn.com/*><br />
331 Order allow,deny<br />
337 <section id="whatwhere"><title>What Directives are Allowed?</title>
339 <p>To find out what directives are allowed in what types of
340 configuration sections, check the <a
341 href="mod/directive-dict.html#Context">Context</a> of the directive.
342 Everything that is allowed in
343 <directive type="section" module="core">Directory</directive>
344 sections is also syntactically allowed in
345 <directive type="section" module="core">DirectoryMatch</directive>,
346 <directive type="section" module="core">Files</directive>,
347 <directive type="section" module="core">FilesMatch</directive>,
348 <directive type="section" module="core">Location</directive>,
349 <directive type="section" module="core">LocationMatch</directive>,
350 <directive type="section" module="mod_proxy">Proxy</directive>,
351 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
352 sections. There are some exceptions, however:</p>
355 <li>The <directive module="core">AllowOverride</directive> directive
356 works only in <directive type="section" module="core">Directory</directive>
359 <li>The <code>FollowSymLinks</code> and
360 <code>SymLinksIfOwnerMatch</code> <directive
361 module="core">Options</directive> work only in <directive
362 type="section" module="core">Directory</directive> sections or
363 <code>.htaccess</code> files.</li>
365 <li>The <directive module="core">Options</directive> directive cannot
366 be used in <directive type="section" module="core">Files</directive>
367 and <directive type="section" module="core">FilesMatch</directive>
372 <section id="mergin"><title>How the sections are merged</title>
374 <p>The configuration sections are applied in a very particular order.
375 Since this can have important effects on how configuration directives
376 are interpreted, it is important to understand how this works.</p>
378 <p>The order of merging is:</p>
381 <li> <directive type="section"
382 module="core">Directory</directive> (except regular expressions)
383 and <code>.htaccess</code> done simultaneously (with
384 <code>.htaccess</code>, if allowed, overriding
385 <directive type="section" module="core">Directory</directive>)</li>
387 <li><directive type="section" module="core">DirectoryMatch</directive>
388 (and <code><Directory ~></code>)</li>
390 <li><directive type="section"
391 module="core">Files</directive> and <directive
392 type="section" module="core">FilesMatch</directive> done
395 <li><directive type="section" module="core">Location</directive>
396 and <directive type="section"
397 module="core">LocationMatch</directive> done simultaneously</li>
400 <p>Apart from <directive type="section"
401 module="core">Directory</directive>, each group is processed in
402 the order that they appear in the configuration files. <directive
403 type="section" module="core">Directory</directive> (group 1 above)
404 is processed in the order shortest directory component to longest.
405 So for example, <code><Directory /var/web/dir></code> will
406 be processed before <code><Directory
407 /var/web/dir/subdir></code>. If multiple <directive
408 type="section" module="core">Directory</directive> sections apply
409 to the same directory they are processed in the configuration file
410 order. Configurations included via the <directive
411 module="core">Include</directive> directive will be treated as if
412 they were inside the including file at the location of the
413 <directive module="core">Include</directive> directive.</p>
415 <p>Sections inside <directive type="section"
416 module="core">VirtualHost</directive> sections
417 are applied <em>after</em> the corresponding sections outside
418 the virtual host definition. This allows virtual hosts to
419 override the main server configuration.</p>
421 <p>When the request is served by <module>mod_proxy</module>, the
422 <directive module="mod_proxy" type="section">Proxy</directive>
423 container takes the place of the <directive module="core"
424 type="section">Directory</directive> container in the processing
427 <p>Later sections override earlier ones.</p>
429 <note><title>Technical Note</title>
431 <code><Location></code>/<code><LocationMatch></code>
432 sequence performed just before the name translation phase
433 (where <code>Aliases</code> and <code>DocumentRoots</code>
434 are used to map URLs to filenames). The results of this
435 sequence are completely thrown away after the translation has
439 <section id="merge-examples"><title>Some Examples</title>
441 <p>Below is an artificial example to show the order of
442 merging. Assuming they all apply to the request, the directives in
443 this example will be applied in the order A > B > C > D >
447 <Location /><br />
449 </Location><br />
451 <Files f.html><br />
455 <VirtualHost *><br />
456 <Directory /a/b><br />
458 </Directory><br />
459 </VirtualHost><br />
461 <DirectoryMatch "^.*b$"><br />
463 </DirectoryMatch><br />
465 <Directory /a/b><br />
467 </Directory><br />
471 <p>For a more concrete example, consider the following. Regardless of
472 any access restrictions placed in <directive module="core"
473 type="section">Directory</directive> sections, the <directive
474 module="core" type="section">Location</directive> section will be
475 evaluated last and will allow unrestricted access to the server. In
476 other words, order of merging is important, so be careful!</p>
479 <Location /><br />
480 Order deny,allow<br />
482 </Location><br />
484 # Woops! This <Directory> section will have no effect<br />
485 <Directory /><br />
486 Order allow,deny<br />
488 Deny from badguy.example.com<br />