1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Configuration Sections - Apache HTTP Server</title>
9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.1</p>
16 <img alt="" src="./images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="./">Version 2.1</a></div><div id="page-content"><div id="preamble"><h1>Configuration Sections</h1> <p>Directives in the <a href="configuring.html">configuration files</a> may apply to the
20 entire server, or they may be restricted to apply only to particular
21 directories, files, hosts, or URLs. This document describes how to
22 use configuration section containers or <code>.htaccess</code> files
23 to change the scope of other configuration directives.</p>
25 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#types">Types of Configuration Section Containers</a></li>
26 <li><img alt="" src="./images/down.gif" /> <a href="#file-and-web">Filesystem and Webspace</a></li>
27 <li><img alt="" src="./images/down.gif" /> <a href="#virtualhost">Virtual Hosts</a></li>
28 <li><img alt="" src="./images/down.gif" /> <a href="#proxy">Proxy</a></li>
29 <li><img alt="" src="./images/down.gif" /> <a href="#whatwhere">What Directives are Allowed?</a></li>
30 <li><img alt="" src="./images/down.gif" /> <a href="#mergin">How the sections are merged</a></li>
32 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
34 <h2><a name="types" id="types">Types of Configuration Section Containers</a></h2>
36 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/core.html">core</a></code></li><li><code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/core.html#directory"><Directory></a></code></li><li><code class="directive"><a href="./mod/core.html#directorymatch"><DirectoryMatch></a></code></li><li><code class="directive"><a href="./mod/core.html#files"><Files></a></code></li><li><code class="directive"><a href="./mod/core.html#filesmatch"><FilesMatch></a></code></li><li><code class="directive"><a href="./mod/core.html#ifdefine"><IfDefine></a></code></li><li><code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code></li><li><code class="directive"><a href="./mod/core.html#location"><Location></a></code></li><li><code class="directive"><a href="./mod/core.html#locationmatch"><LocationMatch></a></code></li><li><code class="directive"><a href="./mod/mod_proxy.html#proxy"><Proxy></a></code></li><li><code class="directive"><a href="./mod/mod_proxy.html#proxymatch"><ProxyMatch></a></code></li><li><code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code></li></ul></td></tr></table>
38 <p>There are two basic types of containers. Most containers are
39 evaluated for each request. The enclosed directives are applied only
40 for those requests that match the containers. The <code class="directive"><a href="./mod/core.html#ifdefine"><IfDefine></a></code> and <code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code> containers, on the
41 other hand, are evaluated only at server startup and restart. If
42 their conditions are true at startup, then the enclosed directives
43 will apply to all requests. If the conditions are not true, the
44 enclosed directives will be ignored.</p>
46 <p>The <code class="directive"><a href="./mod/core.html#ifdefine"><IfDefine></a></code> directive
47 encloses directives that will only be applied if an appropriate
48 parameter is defined on the <code>httpd</code> command line. For example,
49 with the following configuration, all requests will be redirected
50 to another site only if the server is started using
51 <code>httpd -DClosedForNow</code>:</p>
53 <div class="example"><p><code>
54 <IfDefine ClosedForNow><br />
55 Redirect / http://otherserver.example.com/<br />
59 <p>The <code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code>
60 directive is very similar, except it encloses directives that will
61 only be applied if a particular module is available in the server.
62 The module must either be statically compiled in the server, or it
63 must be dynamically compiled and its <code class="directive"><a href="./mod/mod_so.html#loadmodule">LoadModule</a></code> line must be earlier in the
64 configuration file. This directive should only be used if you need
65 your configuration file to work whether or not certain modules are
66 installed. It should not be used to enclose directives that you want
67 to work all the time, because it can suppress useful error messages
68 about missing modules.</p>
70 <p>In the following example, the <code class="directive"><a href="./mod/mod_mime_magic.html#mimemagicfiles">MimeMagicFiles</a></code> directive will be
71 applied only if <code class="module"><a href="./mod/mod_mime_magic.html">mod_mime_magic</a></code> is available.</p>
73 <div class="example"><p><code>
74 <IfModule mod_mime_magic.c><br />
75 MimeMagicFile conf/magic<br />
79 <p>Both <code class="directive"><a href="./mod/core.html#ifdefine"><IfDefine></a></code>
80 and <code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code>
81 can apply negative conditions by preceding their test with "!".
82 Also, these sections can be nested to achieve more complex
84 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
86 <h2><a name="file-and-web" id="file-and-web">Filesystem and Webspace</a></h2>
88 <p>The most commonly used configuration section containers are the
89 ones that change the configuration of particular places in the
90 filesystem or webspace. First, it is important to understand the
91 difference between the two. The filesystem is the view of your disks
92 as seen by your operating system. For example, in a default install,
93 Apache resides at <code>/usr/local/apache2</code> in the Unix
94 filesystem or <code>"c:/Program Files/Apache Group/Apache2"</code> in
95 the Windows filesystem. (Note that forward slashes should always be
96 used as the path separator in Apache, even for Windows.) In contrast,
97 the webspace is the view of your site as delivered by the web server
98 and seen by the client. So the path <code>/dir/</code> in the
99 webspace corresponds to the path
100 <code>/usr/local/apache2/htdocs/dir/</code> in the filesystem of a
101 default Apache install on Unix. The webspace need not map directly to
102 the filesystem, since webpages may be generated dynamically
103 from databases or other locations.</p>
105 <h3><a name="filesystem" id="filesystem">Filesystem Containers</a></h3>
107 <p>The <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>
108 and <code class="directive"><a href="./mod/core.html#files"><Files></a></code>
109 directives, along with their regex counterparts, apply directives to
110 parts of the filesystem. Directives enclosed in a <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> section apply to
111 the named filesystem directory and all subdirectories of that
112 directory. The same effect can be obtained using <a href="howto/htaccess.html">.htaccess files</a>. For example, in the
113 following configuration, directory indexes will be enabled for the
114 <code>/var/web/dir1</code> directory and all subdirectories.</p>
116 <div class="example"><p><code>
117 <Directory /var/web/dir1><br />
118 Options +Indexes<br />
122 <p>Directives enclosed in a <code class="directive"><a href="./mod/core.html#files"><Files></a></code> section apply to any file with
123 the specified name, regardless of what directory it lies in.
124 So for example, the following configuration directives will,
125 when placed in the main section of the configuration file,
126 deny access to any file named <code>private.html</code> regardless
127 of where it is found.</p>
129 <div class="example"><p><code>
130 <Files private.html><br />
131 Order allow,deny<br />
136 <p>To address files found in a particular part of the filesystem, the
137 <code class="directive"><a href="./mod/core.html#files"><Files></a></code> and
138 <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> sections
139 can be combined. For example, the following configuration will deny
140 access to <code>/var/web/dir1/private.html</code>,
141 <code>/var/web/dir1/subdir2/private.html</code>,
142 <code>/var/web/dir1/subdir3/private.html</code>, and any other instance
143 of <code>private.html</code> found under the <code>/var/web/dir1/</code>
146 <div class="example"><p><code>
147 <Directory /var/web/dir1><br />
148 <Files private.html><br />
149 Order allow,deny<br />
156 <h3><a name="webspace" id="webspace">Webspace Containers</a></h3>
158 <p>The <code class="directive"><a href="./mod/core.html#location"><Location></a></code>
159 directive and its regex counterpart, on the other hand, change the
160 configuration for content in the webspace. For example, the following
161 configuration prevents access to any URL-path that begins in /private.
162 In particular, it will apply to requests for
163 <code>http://yoursite.example.com/private</code>,
164 <code>http://yoursite.example.com/private123</code>, and
165 <code>http://yoursite.example.com/private/dir/file.html</code> as well
166 as any other requests starting with the <code>/private</code> string.</p>
168 <div class="example"><p><code>
169 <Location /private><br />
170 Order Allow,Deny<br />
175 <p>The <code class="directive"><a href="./mod/core.html#location"><Location></a></code>
176 directive need not have anything to do with the filesystem.
177 For example, the following example shows how to map a particular
178 URL to an internal Apache handler provided by <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>.
179 No file called <code>server-status</code> needs to exist in the
182 <div class="example"><p><code>
183 <Location /server-status><br />
184 SetHandler server-status<br />
189 <h3><a name="wildcards" id="wildcards">Wildcards and Regular Expressions</a></h3>
191 <p>The <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>,
192 <code class="directive"><a href="./mod/core.html#files"><Files></a></code>, and
193 <code class="directive"><a href="./mod/core.html#location"><Location></a></code>
194 directives can each use shell-style wildcard characters as in
195 <code>fnmatch</code> from the C standard library. The character "*"
196 matches any sequence of characters, "?" matches any single character,
197 and "[<em>seq</em>]" matches any character in <em>seq</em>. The "/"
198 character will not be matched by any wildcard; it must be specified
201 <p>If even more flexible matching is required, each
202 container has a regular-expression (regex) counterpart <code class="directive"><a href="./mod/core.html#directorymatch"><DirectoryMatch></a></code>, <code class="directive"><a href="./mod/core.html#filesmatch"><FilesMatch></a></code>, and <code class="directive"><a href="./mod/core.html#locationmatch"><LocationMatch></a></code> that allow
204 <a href="glossary.html#regex">regular expressions</a>
205 to be used in choosing the matches. But see the section below on
206 configuration merging to find out how using regex sections will change
207 how directives are applied.</p>
209 <p>A non-regex wildcard section that changes the configuration of
210 all user directories could look as follows:</p>
212 <div class="example"><p><code>
213 <Directory /home/*/public_html><br />
214 Options Indexes<br />
218 <p>Using regex sections, we can deny access to many types of image files
220 <div class="example"><p><code>
221 <FilesMatch \.(?i:gif|jpe?g|png)$><br />
222 Order allow,deny<br />
229 <h3><a name="whichwhen" id="whichwhen">What to use When</a></h3>
231 <p>Choosing between filesystem containers and webspace containers is
232 actually quite easy. When applying directives to objects that reside
233 in the filesystem always use <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="./mod/core.html#files"><Files></a></code>. When applying directives to objects
234 that do not reside in the filesystem (such as a webpage generated from
235 a database), use <code class="directive"><a href="./mod/core.html#location"><Location></a></code>.</p>
237 <p>It is important to never use <code class="directive"><a href="./mod/core.html#location"><Location></a></code> when trying to restrict
238 access to objects in the filesystem. This is because many
239 different webspace locations (URLs) could map to the same filesystem
240 location, allowing your restrictions to be circumvented.
241 For example, consider the following configuration:</p>
243 <div class="example"><p><code>
244 <Location /dir/><br />
245 Order allow,deny<br />
250 <p>This works fine if the request is for
251 <code>http://yoursite.example.com/dir/</code>. But what if you are on
252 a case-insensitive filesystem? Then your restriction could be easily
253 circumvented by requesting
254 <code>http://yoursite.example.com/DIR/</code>. The <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> directive, in
255 contrast, will apply to any content served from that location,
256 regardless of how it is called. (An exception is filesystem links.
257 The same directory can be placed in more than one part of the
258 filesystem using symbolic links. The <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> directive will follow the symbolic
259 link without resetting the pathname. Therefore, for the highest level
260 of security, symbolic links should be disabled with the appropriate
261 <code class="directive"><a href="./mod/core.html#options">Options</a></code> directive.)</p>
263 <p>If you are, perhaps, thinking that none of this applies to you
264 because you use a case-sensitive filesystem, remember that there are
265 many other ways to map multiple webspace locations to the same
266 filesystem location. Therefore you should always use the filesystem
267 containers when you can. There is, however, one exception to this
268 rule. Putting configuration restrictions in a <code><Location
269 /></code> section is perfectly safe because this section will apply
270 to all requests regardless of the specific URL.</p>
273 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
274 <div class="section">
275 <h2><a name="virtualhost" id="virtualhost">Virtual Hosts</a></h2>
277 <p>The <code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code>
278 container encloses directives that apply to specific hosts.
279 This is useful when serving multiple hosts from the same machine
280 with a different configuration for each. For more information,
281 see the <a href="vhosts/">Virtual Host Documentation</a>.</p>
282 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
283 <div class="section">
284 <h2><a name="proxy" id="proxy">Proxy</a></h2>
286 <p>The <code class="directive"><a href="./mod/mod_proxy.html#proxy"><Proxy></a></code>
287 and <code class="directive"><a href="./mod/mod_proxy.html#proxymatch"><ProxyMatch></a></code>
288 containers apply enclosed configuration directives only
289 to sites accessed through <code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code>'s proxy server
290 that match the specified URL. For example, the following configuration
291 will prevent the proxy server from being used to access the
292 <code>cnn.com</code> website.</p>
294 <div class="example"><p><code>
295 <Proxy http://cnn.com/*><br />
296 Order allow,deny<br />
300 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
301 <div class="section">
302 <h2><a name="whatwhere" id="whatwhere">What Directives are Allowed?</a></h2>
304 <p>To find out what directives are allowed in what types of
305 configuration sections, check the <a href="mod/directive-dict.html#Context">Context</a> of the directive.
306 Everything that is allowed in
307 <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>
308 sections is also syntactically allowed in
309 <code class="directive"><a href="./mod/core.html#directorymatch"><DirectoryMatch></a></code>,
310 <code class="directive"><a href="./mod/core.html#files"><Files></a></code>,
311 <code class="directive"><a href="./mod/core.html#filesmatch"><FilesMatch></a></code>,
312 <code class="directive"><a href="./mod/core.html#location"><Location></a></code>,
313 <code class="directive"><a href="./mod/core.html#locationmatch"><LocationMatch></a></code>,
314 <code class="directive"><a href="./mod/mod_proxy.html#proxy"><Proxy></a></code>,
315 and <code class="directive"><a href="./mod/mod_proxy.html#proxymatch"><ProxyMatch></a></code>
316 sections. There are some exceptions, however.</p>
319 <li>The <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> directive
320 works only in <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>
323 <li>The <code>FollowSymLinks</code> and
324 <code>SymLinksIfOwnerMatch</code> <code class="directive"><a href="./mod/core.html#options">Options</a></code> work only in <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> sections or
325 <code>.htaccess</code> files.</li>
327 <li>The <code class="directive"><a href="./mod/core.html#options">Options</a></code> directive cannot
328 be used in <code class="directive"><a href="./mod/core.html#files"><Files></a></code>
329 and <code class="directive"><a href="./mod/core.html#filesmatch"><FilesMatch></a></code>
332 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
333 <div class="section">
334 <h2><a name="mergin" id="mergin">How the sections are merged</a></h2>
336 <p>The configuration sections are applied in a very particular order.
337 Since this can have important effects on how configuration directives
338 are interpreted, it is important to understand how this works.</p>
340 <p>The order of merging is:</p>
343 <li> <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> (except regular expressions)
344 and .htaccess done simultaneously (with .htaccess, if allowed,
345 overriding <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>)</li>
347 <li><code class="directive"><a href="./mod/core.html#directorymatch"><DirectoryMatch></a></code>
348 (and <code><Directory ~></code>)</li>
350 <li><code class="directive"><a href="./mod/core.html#files"><Files></a></code> and <code class="directive"><a href="./mod/core.html#filesmatch"><FilesMatch></a></code> done
353 <li><code class="directive"><a href="./mod/core.html#location"><Location></a></code>
354 and <code class="directive"><a href="./mod/core.html#locationmatch"><LocationMatch></a></code> done simultaneously</li>
357 <p>Apart from <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code>, each group is processed in
358 the order that they appear in the configuration files. <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> (group 1 above)
359 is processed in the order shortest directory component to longest.
360 So for example, <code><Directory /var/web/dir></code> will
361 be processed before <code><Directory
362 /var/web/dir/subdir></code>. If multiple <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> sections apply
363 to the same directory they are processed in the configuration file
364 order. Configurations included via the <code class="directive"><a href="./mod/core.html#include">Include</a></code> directive will be treated as if
365 they were inside the including file at the location of the
366 <code class="directive"><a href="./mod/core.html#include">Include</a></code> directive.</p>
368 <p>Sections inside <code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code> sections
369 are applied <em>after</em> the corresponding sections outside
370 the virtual host definition. This allows virtual hosts to
371 override the main server configuration.</p>
373 <p>Later sections override earlier ones.</p>
375 <div class="note"><h3>Technical Note</h3>
377 <code><Location></code>/<code><LocationMatch></code>
378 sequence performed just before the name translation phase
379 (where <code>Aliases</code> and <code>DocumentRoots</code>
380 are used to map URLs to filenames). The results of this
381 sequence are completely thrown away after the translation has
385 <h3><a name="merge-examples" id="merge-examples">Some Examples</a></h3>
387 <p>Below is an artificial example to show the order of
388 merging. Assuming they all apply to the request, the directives in
389 this example will be applied in the order A > B > C > D >
392 <div class="example"><p><code>
393 <Location /><br />
395 </Location><br />
397 <Files f.html><br />
401 <VirtualHost *><br />
402 <Directory /a/b><br />
404 </Directory><br />
405 </VirtualHost><br />
407 <DirectoryMatch "^.*b$"><br />
409 </DirectoryMatch><br />
411 <Directory /a/b><br />
413 </Directory><br />
417 <p>For a more concrete example, consider the following. Regardless of
418 any access restrictions placed in <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> sections, the <code class="directive"><a href="./mod/core.html#location"><Location></a></code> section will be
419 evaluated last and will allow unrestricted access to the server. In
420 other words, order of merging is important, so be careful!</p>
422 <div class="example"><p><code>
423 <Location /><br />
424 Order deny,allow<br />
426 </Location><br />
428 # Woops! This <Directory> section will have no effect<br />
429 <Directory /><br />
430 Order allow,deny<br />
432 Deny from badguy.example.com<br />
440 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
441 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
projects / apache / blob