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 <!-- $Revision: 1.11 $ -->
7 Copyright 2002-2004 The Apache Software Foundation
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
22 <manualpage metafile="sections.xml.meta">
24 <title>Configuration Sections</title>
26 <summary> <p>Directives in the <a
27 href="configuring.html">configuration files</a> may apply to the
28 entire server, or they may be restricted to apply only to particular
29 directories, files, hosts, or URLs. This document describes how to
30 use configuration section containers or <code>.htaccess</code> files
31 to change the scope of other configuration directives.</p>
34 <section id="types"><title>Types of Configuration Section Containers</title>
39 <module>mod_proxy</module>
42 <directive type="section" module="core">Directory</directive>
43 <directive type="section" module="core">DirectoryMatch</directive>
44 <directive type="section" module="core">Files</directive>
45 <directive type="section" module="core">FilesMatch</directive>
46 <directive type="section" module="core">IfDefine</directive>
47 <directive type="section" module="core">IfModule</directive>
48 <directive type="section" module="core">Location</directive>
49 <directive type="section" module="core">LocationMatch</directive>
50 <directive type="section" module="mod_proxy">Proxy</directive>
51 <directive type="section" module="mod_proxy">ProxyMatch</directive>
52 <directive type="section" module="core">VirtualHost</directive>
56 <p>There are two basic types of containers. Most containers are
57 evaluated for each request. The enclosed directives are applied only
58 for those requests that match the containers. The <directive
59 type="section" module="core">IfDefine</directive> and <directive
60 type="section" module="core">IfModule</directive> containers, on the
61 other hand, are evaluated only at server startup and restart. If
62 their conditions are true at startup, then the enclosed directives
63 will apply to all requests. If the conditions are not true, the
64 enclosed directives will be ignored.</p>
66 <p>The <directive type="section" module="core">IfDefine</directive> directive
67 encloses directives that will only be applied if an appropriate
68 parameter is defined on the <code>httpd</code> command line. For example,
69 with the following configuration, all requests will be redirected
70 to another site only if the server is started using
71 <code>httpd -DClosedForNow</code>:</p>
74 <IfDefine ClosedForNow><br />
75 Redirect / http://otherserver.example.com/<br />
79 <p>The <directive type="section" module="core">IfModule</directive>
80 directive is very similar, except it encloses directives that will
81 only be applied if a particular module is available in the server.
82 The module must either be statically compiled in the server, or it
83 must be dynamically compiled and its <directive
84 module="mod_so">LoadModule</directive> line must be earlier in the
85 configuration file. This directive should only be used if you need
86 your configuration file to work whether or not certain modules are
87 installed. It should not be used to enclose directives that you want
88 to work all the time, because it can suppress useful error messages
89 about missing modules.</p>
91 <p>In the following example, the <directive
92 module="mod_mime_magic">MimeMagicFiles</directive> directive will be
93 applied only if <module>mod_mime_magic</module> is available.</p>
96 <IfModule mod_mime_magic.c><br />
97 MimeMagicFile conf/magic<br />
101 <p>Both <directive type="section" module="core">IfDefine</directive>
102 and <directive type="section" module="core">IfModule</directive>
103 can apply negative conditions by preceding their test with "!".
104 Also, these sections can be nested to achieve more complex
108 <section id="file-and-web"><title>Filesystem and Webspace</title>
110 <p>The most commonly used configuration section containers are the
111 ones that change the configuration of particular places in the
112 filesystem or webspace. First, it is important to understand the
113 difference between the two. The filesystem is the view of your disks
114 as seen by your operating system. For example, in a default install,
115 Apache resides at <code>/usr/local/apache2</code> in the Unix
116 filesystem or <code>"c:/Program Files/Apache Group/Apache2"</code> in
117 the Windows filesystem. (Note that forward slashes should always be
118 used as the path separator in Apache, even for Windows.) In contrast,
119 the webspace is the view of your site as delivered by the web server
120 and seen by the client. So the path <code>/dir/</code> in the
121 webspace corresponds to the path
122 <code>/usr/local/apache2/htdocs/dir/</code> in the filesystem of a
123 default Apache install on Unix. The webspace need not map directly to
124 the filesystem, since webpages may be generated dynamically
125 from databases or other locations.</p>
127 <section id="filesystem"><title>Filesystem Containers</title>
129 <p>The <directive type="section" module="core">Directory</directive>
130 and <directive type="section" module="core">Files</directive>
131 directives, along with their regex counterparts, apply directives to
132 parts of the filesystem. Directives enclosed in a <directive
133 type="section" module="core">Directory</directive> section apply to
134 the named filesystem directory and all subdirectories of that
135 directory. The same effect can be obtained using <a
136 href="howto/htaccess.html">.htaccess files</a>. For example, in the
137 following configuration, directory indexes will be enabled for the
138 <code>/var/web/dir1</code> directory and all subdirectories.</p>
141 <Directory /var/web/dir1><br />
142 Options +Indexes<br />
146 <p>Directives enclosed in a <directive type="section"
147 module="core">Files</directive> section apply to any file with
148 the specified name, regardless of what directory it lies in.
149 So for example, the following configuration directives will,
150 when placed in the main section of the configuration file,
151 deny access to any file named <code>private.html</code> regardless
152 of where it is found.</p>
155 <Files private.html><br />
156 Order allow,deny<br />
161 <p>To address files found in a particular part of the filesystem, the
162 <directive type="section" module="core">Files</directive> and
163 <directive type="section" module="core">Directory</directive> sections
164 can be combined. For example, the following configuration will deny
165 access to <code>/var/web/dir1/private.html</code>,
166 <code>/var/web/dir1/subdir2/private.html</code>,
167 <code>/var/web/dir1/subdir3/private.html</code>, and any other instance
168 of <code>private.html</code> found under the <code>/var/web/dir1/</code>
172 <Directory /var/web/dir1><br />
173 <Files private.html><br />
174 Order allow,deny<br />
181 <section id="webspace"><title>Webspace Containers</title>
183 <p>The <directive type="section" module="core">Location</directive>
184 directive and its regex counterpart, on the other hand, change the
185 configuration for content in the webspace. For example, the following
186 configuration prevents access to any URL-path that begins in /private.
187 In particular, it will apply to requests for
188 <code>http://yoursite.example.com/private</code>,
189 <code>http://yoursite.example.com/private123</code>, and
190 <code>http://yoursite.example.com/private/dir/file.html</code> as well
191 as any other requests starting with the <code>/private</code> string.</p>
194 <Location /private><br />
195 Order Allow,Deny<br />
200 <p>The <directive type="section" module="core">Location</directive>
201 directive need not have anything to do with the filesystem.
202 For example, the following example shows how to map a particular
203 URL to an internal Apache handler provided by <module>mod_status</module>.
204 No file called <code>server-status</code> needs to exist in the
208 <Location /server-status><br />
209 SetHandler server-status<br />
214 <section id="wildcards"><title>Wildcards and Regular Expressions</title>
216 <p>The <directive type="section" module="core">Directory</directive>,
217 <directive type="section" module="core">Files</directive>, and
218 <directive type="section" module="core">Location</directive>
219 directives can each use shell-style wildcard characters as in
220 <code>fnmatch</code> from the C standard library. The character "*"
221 matches any sequence of characters, "?" matches any single character,
222 and "[<em>seq</em>]" matches any character in <em>seq</em>. The "/"
223 character will not be matched by any wildcard; it must be specified
226 <p>If even more flexible matching is required, each
227 container has a regular-expression (regex) counterpart <directive
228 type="section" module="core">DirectoryMatch</directive>, <directive
229 type="section" module="core">FilesMatch</directive>, and <directive
230 type="section" module="core">LocationMatch</directive> that allow
232 <a href="glossary.html#regex">regular expressions</a>
233 to be used in choosing the matches. But see the section below on
234 configuration merging to find out how using regex sections will change
235 how directives are applied.</p>
237 <p>A non-regex wildcard section that changes the configuration of
238 all user directories could look as follows:</p>
241 <Directory /home/*/public_html><br />
242 Options Indexes<br />
246 <p>Using regex sections, we can deny access to many types of image files
249 <FilesMatch \.(?i:gif|jpe?g|png)$><br />
250 Order allow,deny<br />
257 <section id="whichwhen"><title>What to use When</title>
259 <p>Choosing between filesystem containers and webspace containers is
260 actually quite easy. When applying directives to objects that reside
261 in the filesystem always use <directive type="section"
262 module="core">Directory</directive> or <directive type="section"
263 module="core">Files</directive>. When applying directives to objects
264 that do not reside in the filesystem (such as a webpage generated from
265 a database), use <directive type="section"
266 module="core">Location</directive>.</p>
268 <p>It is important to never use <directive type="section"
269 module="core">Location</directive> when trying to restrict
270 access to objects in the filesystem. This is because many
271 different webspace locations (URLs) could map to the same filesystem
272 location, allowing your restrictions to be circumvented.
273 For example, consider the following configuration:</p>
276 <Location /dir/><br />
277 Order allow,deny<br />
282 <p>This works fine if the request is for
283 <code>http://yoursite.example.com/dir/</code>. But what if you are on
284 a case-insensitive filesystem? Then your restriction could be easily
285 circumvented by requesting
286 <code>http://yoursite.example.com/DIR/</code>. The <directive
287 type="section" module="core">Directory</directive> directive, in
288 contrast, will apply to any content served from that location,
289 regardless of how it is called. (An exception is filesystem links.
290 The same directory can be placed in more than one part of the
291 filesystem using symbolic links. The <directive type="section"
292 module="core">Directory</directive> directive will follow the symbolic
293 link without resetting the pathname. Therefore, for the highest level
294 of security, symbolic links should be disabled with the appropriate
295 <directive module="core">Options</directive> directive.)</p>
297 <p>If you are, perhaps, thinking that none of this applies to you
298 because you use a case-sensitive filesystem, remember that there are
299 many other ways to map multiple webspace locations to the same
300 filesystem location. Therefore you should always use the filesystem
301 containers when you can. There is, however, one exception to this
302 rule. Putting configuration restrictions in a <code><Location
303 /></code> section is perfectly safe because this section will apply
304 to all requests regardless of the specific URL.</p>
309 <section id="virtualhost"><title>Virtual Hosts</title>
311 <p>The <directive type="section" module="core">VirtualHost</directive>
312 container encloses directives that apply to specific hosts.
313 This is useful when serving multiple hosts from the same machine
314 with a different configuration for each. For more information,
315 see the <a href="vhosts/">Virtual Host Documentation</a>.</p>
318 <section id="proxy"><title>Proxy</title>
320 <p>The <directive type="section" module="mod_proxy">Proxy</directive>
321 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
322 containers apply enclosed configuration directives only
323 to sites accessed through <module>mod_proxy</module>'s proxy server
324 that match the specified URL. For example, the following configuration
325 will prevent the proxy server from being used to access the
326 <code>cnn.com</code> website.</p>
329 <Proxy http://cnn.com/*><br />
330 Order allow,deny<br />
336 <section id="whatwhere"><title>What Directives are Allowed?</title>
338 <p>To find out what directives are allowed in what types of
339 configuration sections, check the <a
340 href="mod/directive-dict.html#Context">Context</a> of the directive.
341 Everything that is allowed in
342 <directive type="section" module="core">Directory</directive>
343 sections is also syntactically allowed in
344 <directive type="section" module="core">DirectoryMatch</directive>,
345 <directive type="section" module="core">Files</directive>,
346 <directive type="section" module="core">FilesMatch</directive>,
347 <directive type="section" module="core">Location</directive>,
348 <directive type="section" module="core">LocationMatch</directive>,
349 <directive type="section" module="mod_proxy">Proxy</directive>,
350 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
351 sections. There are some exceptions, however:</p>
354 <li>The <directive module="core">AllowOverride</directive> directive
355 works only in <directive type="section" module="core">Directory</directive>
358 <li>The <code>FollowSymLinks</code> and
359 <code>SymLinksIfOwnerMatch</code> <directive
360 module="core">Options</directive> work only in <directive
361 type="section" module="core">Directory</directive> sections or
362 <code>.htaccess</code> files.</li>
364 <li>The <directive module="core">Options</directive> directive cannot
365 be used in <directive type="section" module="core">Files</directive>
366 and <directive type="section" module="core">FilesMatch</directive>
371 <section id="mergin"><title>How the sections are merged</title>
373 <p>The configuration sections are applied in a very particular order.
374 Since this can have important effects on how configuration directives
375 are interpreted, it is important to understand how this works.</p>
377 <p>The order of merging is:</p>
380 <li> <directive type="section"
381 module="core">Directory</directive> (except regular expressions)
382 and <code>.htaccess</code> done simultaneously (with
383 <code>.htaccess</code>, if allowed, overriding
384 <directive type="section" module="core">Directory</directive>)</li>
386 <li><directive type="section" module="core">DirectoryMatch</directive>
387 (and <code><Directory ~></code>)</li>
389 <li><directive type="section"
390 module="core">Files</directive> and <directive
391 type="section" module="core">FilesMatch</directive> done
394 <li><directive type="section" module="core">Location</directive>
395 and <directive type="section"
396 module="core">LocationMatch</directive> done simultaneously</li>
399 <p>Apart from <directive type="section"
400 module="core">Directory</directive>, each group is processed in
401 the order that they appear in the configuration files. <directive
402 type="section" module="core">Directory</directive> (group 1 above)
403 is processed in the order shortest directory component to longest.
404 So for example, <code><Directory /var/web/dir></code> will
405 be processed before <code><Directory
406 /var/web/dir/subdir></code>. If multiple <directive
407 type="section" module="core">Directory</directive> sections apply
408 to the same directory they are processed in the configuration file
409 order. Configurations included via the <directive
410 module="core">Include</directive> directive will be treated as if
411 they were inside the including file at the location of the
412 <directive module="core">Include</directive> directive.</p>
414 <p>Sections inside <directive type="section"
415 module="core">VirtualHost</directive> sections
416 are applied <em>after</em> the corresponding sections outside
417 the virtual host definition. This allows virtual hosts to
418 override the main server configuration.</p>
420 <p>When the request is served by <module>mod_proxy</module>, the
421 <directive module="mod_proxy" type="section">Proxy</directive>
422 container takes the place of the <directive module="core"
423 type="section">Directory</directive> container in the processing
426 <p>Later sections override earlier ones.</p>
428 <note><title>Technical Note</title>
430 <code><Location></code>/<code><LocationMatch></code>
431 sequence performed just before the name translation phase
432 (where <code>Aliases</code> and <code>DocumentRoots</code>
433 are used to map URLs to filenames). The results of this
434 sequence are completely thrown away after the translation has
438 <section id="merge-examples"><title>Some Examples</title>
440 <p>Below is an artificial example to show the order of
441 merging. Assuming they all apply to the request, the directives in
442 this example will be applied in the order A > B > C > D >
446 <Location /><br />
448 </Location><br />
450 <Files f.html><br />
454 <VirtualHost *><br />
455 <Directory /a/b><br />
457 </Directory><br />
458 </VirtualHost><br />
460 <DirectoryMatch "^.*b$"><br />
462 </DirectoryMatch><br />
464 <Directory /a/b><br />
466 </Directory><br />
470 <p>For a more concrete example, consider the following. Regardless of
471 any access restrictions placed in <directive module="core"
472 type="section">Directory</directive> sections, the <directive
473 module="core" type="section">Location</directive> section will be
474 evaluated last and will allow unrestricted access to the server. In
475 other words, order of merging is important, so be careful!</p>
478 <Location /><br />
479 Order deny,allow<br />
481 </Location><br />
483 # Woops! This <Directory> section will have no effect<br />
484 <Directory /><br />
485 Order allow,deny<br />
487 Deny from badguy.example.com<br />