Apache HTTP Server Version 2.3
-
Apache HTTP Server Version 2.3
-Apache HTTP Server Version 2.5
+
Directives in the configuration files may apply to the entire server, or they may be restricted to apply only to particular @@ -36,8 +40,8 @@ to change the scope of other configuration directives.
Virtual Hosts Proxy What Directives are Allowed? How the sections are merged How the sections are merged
httpd -DClosedForNow:
-
-<IfDefine ClosedForNow>
-Redirect / http://otherserver.example.com/
-</IfDefine>
-
<IfDefine ClosedForNow> + Redirect "/" "http://otherserver.example.com/" +</IfDefine>+
The <IfModule>
directive is very similar, except it encloses directives that will
@@ -77,14 +80,13 @@ installed. It should not be used to enclose directives that you want
to work all the time, because it can suppress useful error messages
about missing modules.
In the following example, the MimeMagicFiles directive will be
+
In the following example, the MimeMagicFile directive will be
applied only if mod_mime_magic is available.
-<IfModule mod_mime_magic.c>
-MimeMagicFile conf/magic
-</IfModule>
-
<IfModule mod_mime_magic.c> + MimeMagicFile conf/magic +</IfModule>+
The <IfVersion>
directive is very similar to <IfDefine> and <IfModule>, except it encloses directives that will
@@ -92,14 +94,11 @@ only be applied if a particular version of the server is executing. This
module is designed for the use in test suites and large networks which have to
deal with different httpd versions and different configurations.
- <IfVersion >= 2.1>
-
- # this happens only in versions greater or
- # equal 2.1.0.
-
- </IfVersion>
-
<IfVersion >= 2.4> + # this happens only in versions greater or + # equal 2.4.0. +</IfVersion>+
<IfDefine>,
<IfModule>, and the
@@ -141,11 +140,10 @@ The same effect can be obtained using .htaccess fi
following configuration, directory indexes will be enabled for the
/var/web/dir1 directory and all subdirectories.
-<Directory /var/web/dir1>
-Options +Indexes
-</Directory>
-
<Directory "/var/web/dir1"> + Options +Indexes +</Directory>+
Directives enclosed in a <Files> section apply to any file with
the specified name, regardless of what directory it lies in.
@@ -154,12 +152,10 @@ when placed in the main section of the configuration file,
deny access to any file named private.html regardless
of where it is found.
-<Files private.html>
-Order allow,deny
-Deny from all
-</Files>
-
<Files "private.html"> + Require all denied +</Files>+
To address files found in a particular part of the filesystem, the
<Files> and
@@ -171,14 +167,12 @@ access to /var/web/dir1/private.html,
of private.html found under the /var/web/dir1/
directory.
-<Directory /var/web/dir1>
-<Files private.html>
-Order allow,deny
-Deny from all
-</Files>
-</Directory>
-
<Directory "/var/web/dir1"> + <Files "private.html"> + Require all denied + </Files> +</Directory>+
http://yoursite.example.com/private/dir/file.html as well
as any other requests starting with the /private string.
-
-<LocationMatch ^/private>
-Order Allow,Deny
-Deny from all
-</Location>
-
<LocationMatch "^/private"> + Require all denied +</LocationMatch>+
The <Location>
directive need not have anything to do with the filesystem.
@@ -208,35 +200,31 @@ URL to an internal Apache HTTP Server handler provided by <
No file called server-status needs to exist in the
filesystem.
-<Location /server-status>
-SetHandler server-status
-</Location>
-
<Location "/server-status"> + SetHandler server-status +</Location>+
In order to have two overlapping URLs one has to consider the order in which
certain sections or directives are evaluated. For
<Location> this would be:
-<Location /foo>
-</Location>
-<Location /foo/bar>
+<Location "/foo">
</Location>
-
<Alias>es on the other hand,
+<Location "/foo/bar">
+</Location>
+
+
<Alias>es on the other hand,
are mapped vice-versa:
-Alias /foo/bar /srv/www/uncommon/bar
-Alias /foo /srv/www/common/foo
-
Alias "/foo/bar" "/srv/www/uncommon/bar" +Alias "/foo" "/srv/www/common/foo"+
The same is true for the ProxyPass
directives:
-ProxyPass /special-area http://special.example.com smax=5 max=10
-ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On
-
ProxyPass "/special-area" "http://special.example.com" smax=5 max=10 +ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On+
A non-regex wildcard section that changes the configuration of all user directories could look as follows:
-
-<Directory /home/*/public_html>
-Options Indexes
-</Directory>
-
<Directory "/home/*/public_html"> + Options Indexes +</Directory>+
Using regex sections, we can deny access to many types of image files at once:
-
-<FilesMatch \.(?i:gif|jpe?g|png)$>
-Order allow,deny
-Deny from all
-</FilesMatch>
-
<FilesMatch "\.(?i:gif|jpe?g|png)$"> + Require all denied +</FilesMatch>+ + +
Regular expressions containing named groups and
+backreferences are added to the environment with the
+corresponding name in uppercase. This allows elements of filename paths
+and URLs to be referenced from within expressions
+and modules like mod_rewrite.
<DirectoryMatch "^/var/www/combined/(?<SITENAME>[^/]+)">
+ require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
+</DirectoryMatch>
+
@@ -285,11 +281,10 @@ directive change the configuration depending on a condition which can be
expressed by a boolean expression. For example, the following configuration
denies access if the HTTP Referer header does not start with
"http://www.example.com/".
-
-<If "!(%{HTTP_REFERER} -strmatch 'http://www.example.com/*')">
-Require all denied
-</If>
-
<If "!(%{HTTP_REFERER} -strmatch 'http://www.example.com/*')">
+ Require all denied
+</If>
+
@@ -307,12 +302,10 @@ different webspace locations (URLs) could map to the same filesystem
location, allowing your restrictions to be circumvented.
For example, consider the following configuration:
-
-<Location /dir/>
-Order allow,deny
-Deny from all
-</Location>
-
<Location "/dir/"> + Require all denied +</Location>+
This works fine if the request is for
http://yoursite.example.com/dir/. But what if you are on
@@ -333,14 +326,14 @@ many other ways to map multiple webspace locations to the same
filesystem location. Therefore you should always use the filesystem
containers when you can. There is, however, one exception to this
rule. Putting configuration restrictions in a <Location
-/> section is perfectly safe because this section will apply
+"/"> section is perfectly safe because this section will apply
to all requests regardless of the specific URL.
Some section types can be nested inside other section types. One the one
-hand, <File> can be used
+
Some section types can be nested inside other section types. On the one
+hand, <Files> can be used
inside <Directory>. On
the other hand, <If> can
be used inside <Directory>,
@@ -368,16 +361,14 @@ see the Virtual Host Documentation.
<ProxyMatch>
containers apply enclosed configuration directives only
to sites accessed through mod_proxy's proxy server
-that match the specified URL. For example, the following configuration
-will prevent the proxy server from being used to access the
-www.example.com website.
-
-
-<Proxy http://www.example.com/*>
-Order allow,deny
-Deny from all
-</Proxy>
-
www.example.com website using the proxy server:
+
+<Proxy http://www.example.com/*> + Require host yournetwork.example.com +</Proxy>+
The configuration sections are applied in a very particular order. Since this can have important effects on how configuration directives @@ -443,9 +434,9 @@ are interpreted, it is important to understand how this works.
Apart from <Directory>, each group is processed in
the order that they appear in the configuration files. <Directory> (group 1 above)
is processed in the order shortest directory component to longest.
- So for example, <Directory /var/web/dir> will
+ So for example, <Directory "/var/web/dir"> will
be processed before <Directory
- /var/web/dir/subdir>. If multiple <Directory> sections apply
+ "/var/web/dir/subdir">. If multiple <Directory> sections apply
to the same directory they are processed in the configuration file
order. Configurations included via the Include directive will be treated as if
they were inside the including file at the location of the
@@ -461,9 +452,7 @@ are interpreted, it is important to understand how this works.
<Directory> container in the processing
order.
- Later sections override earlier ones.
- -<Location>/<LocationMatch>
sequence performed just before the name translation phase
@@ -471,58 +460,97 @@ are interpreted, it is important to understand how this works.
are used to map URLs to filenames). The results of this
sequence are completely thrown away after the translation has
completed.
-One question that often arises after reading how configuration sections are
+ merged is related to how and when directives of specific modules like mod_rewrite
+ are processed. The answer is not trivial and needs a bit of background.
+ Each httpd module manages its own configuration, and each of its directives in httpd.conf specify one piece
+ of configuration in a particular context. httpd does not execute a command as it is read.
At runtime, the core of httpd iterates over the defined configuration sections in the order + described above to determine which ones apply to the current request. When the first section matches, + it is considered the current configuration for this request. If a subsequent section matches too, + then each module with a directive in either of the sections is given a chance to merge its configuration between the two sections. The result is a third configuration, and the process goes on until all the configuration sections + are evaluated.
+After the above step, the "real" processing of the HTTP request begins: each module has a chance to run + and perform whatever tasks they like. They can retrieve their own final merged configuration from the core + of the httpd to determine how they should act.
+An example can help to visualize the whole process. The following configuration uses the
+ Header directive of mod_headers to set
+ a specific HTTP header. What value will httpd set in the CustomHeaderName header for a request to
+ /example/index.html ?
+
<Directory "/"> + Header set CustomHeaderName one + <FilesMatch ".*"> + Header set CustomHeaderName three + </FilesMatch> +</Directory> + +<Directory "/example"> + Header set CustomHeaderName two +</Directory>+ +
Directory "/" matches and an initial configuration to set the CustomHeaderName header with the value one is created.Directory "/example" matches, and since mod_headers specifies in its code to override in case of a merge, a new configuration is created to set the CustomHeaderName header with the value two.FilesMatch ".*" matches and another merge opportunity arises, causing the CustomHeaderName header to be set with the value three.mod_headers will be called and it will receive the configuration to set the CustomHeaderName header with the value three. mod_headers normally uses this configuration to perfom its job, namely setting the foo header. This does not mean that a module can't perform a more complex action like discarding directives because not needed or deprecated, etc..This is true for .htaccess too since they have the same priority as Directory in the merge order. The important concept to understand is that configuration sections like Directory and FilesMatch are not comparable to module specific directives like Header or RewriteRule because they operate on different levels.
+
Below is an artificial example to show the order of merging. Assuming they all apply to the request, the directives in this example will be applied in the order A > B > C > D > E.
-
-<Location />
-E
-</Location>
-
-<Files f.html>
-D
-</Files>
-
-<VirtualHost *>
-<Directory /a/b>
-B
-</Directory>
-</VirtualHost>
-
-<DirectoryMatch "^.*b$">
-C
-</DirectoryMatch>
-
-<Directory /a/b>
-A
-</Directory>
-
-
<Location "/"> + E +</Location> + +<Files "f.html"> + D +</Files> + +<VirtualHost *> +<Directory "/a/emphasis role="bold""> + B +</Directory> +</VirtualHost> + +<DirectoryMatch "^.*b$"> + C +</DirectoryMatch> + +<Directory "/a/b> + A +</Directory>+ +
For a more concrete example, consider the following. Regardless of
any access restrictions placed in <Directory> sections, the <Location> section will be
evaluated last and will allow unrestricted access to the server. In
other words, order of merging is important, so be careful!
-<Location />
-Order deny,allow
-Allow from all
-</Location>
-
-# Woops! This <Directory> section will have no effect
-<Directory />
-Order allow,deny
-Allow from all
-Deny from badguy.example.com
-</Directory>
-
<Location "/"> + Require all granted +</Location> + +# Whoops! This <Directory> section will have no effect +<Directory "/"> + <RequireAll> + Require all granted + Require not host badguy.example.com + </RequireAll> +</Directory>+ @@ -532,9 +560,29 @@ Deny from badguy.example.com