You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by el...@apache.org on 2016/02/19 14:26:48 UTC
svn commit: r1731241 -
/httpd/httpd/branches/2.2.x/docs/manual/sections.html.en
Author: elukey
Date: Fri Feb 19 13:26:48 2016
New Revision: 1731241
URL: http://svn.apache.org/viewvc?rev=1731241&view=rev
Log:
Documentation rebuild
Modified:
httpd/httpd/branches/2.2.x/docs/manual/sections.html.en
Modified: httpd/httpd/branches/2.2.x/docs/manual/sections.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/sections.html.en?rev=1731241&r1=1731240&r2=1731241&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/sections.html.en (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/sections.html.en Fri Feb 19 13:26:48 2016
@@ -64,11 +64,10 @@ with the following configuration, all re
to another site only if the server is started using
<code>httpd -DClosedForNow</code>:</p>
-<div class="example"><p><code>
-<IfDefine ClosedForNow><br />
-Redirect / http://otherserver.example.com/<br />
-</IfDefine>
-</code></p></div>
+<pre class="prettyprint lang-config"><IfDefine ClosedForNow>
+ Redirect / http://otherserver.example.com/
+</IfDefine></pre>
+
<p>The <code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code>
directive is very similar, except it encloses directives that will
@@ -84,11 +83,10 @@ about missing modules.</p>
<p>In the following example, the <code class="directive"><a href="./mod/mod_mime_magic.html#mimemagicfile">MimeMagicFile</a></code> directive will be
applied only if <code class="module"><a href="./mod/mod_mime_magic.html">mod_mime_magic</a></code> is available.</p>
-<div class="example"><p><code>
-<IfModule mod_mime_magic.c><br />
-MimeMagicFile conf/magic<br />
-</IfModule>
-</code></p></div>
+<pre class="prettyprint lang-config"><IfModule mod_mime_magic.c>
+ MimeMagicFile conf/magic
+</IfModule></pre>
+
<p>The <code class="directive"><a href="./mod/mod_version.html#ifversion"><IfVersion></a></code>
directive is very similar to <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>, except it encloses directives that will
@@ -96,14 +94,11 @@ only be applied if a particular version
module is designed for the use in test suites and large networks which have to
deal with different httpd versions and different configurations.</p>
-<div class="example"><p><code>
- <IfVersion >= 2.1><br />
- <span class="indent">
- # this happens only in versions greater or<br />
- # equal 2.1.0.<br />
- </span>
- </IfVersion>
-</code></p></div>
+<pre class="prettyprint lang-config"><IfVersion >= 2.1>
+ # this happens only in versions greater or
+ # equal 2.1.0.
+</IfVersion></pre>
+
<p><code class="directive"><a href="./mod/core.html#ifdefine"><IfDefine></a></code>,
<code class="directive"><a href="./mod/core.html#ifmodule"><IfModule></a></code>, and the
@@ -145,11 +140,10 @@ The same effect can be obtained using <a
following configuration, directory indexes will be enabled for the
<code>/var/web/dir1</code> directory and all subdirectories.</p>
-<div class="example"><p><code>
-<Directory /var/web/dir1><br />
-Options +Indexes<br />
-</Directory>
-</code></p></div>
+<pre class="prettyprint lang-config"><Directory /var/web/dir1>
+ Options +Indexes
+</Directory></pre>
+
<p>Directives enclosed in a <code class="directive"><a href="./mod/core.html#files"><Files></a></code> section apply to any file with
the specified name, regardless of what directory it lies in.
@@ -158,12 +152,11 @@ when placed in the main section of the c
deny access to any file named <code>private.html</code> regardless
of where it is found.</p>
-<div class="example"><p><code>
-<Files private.html><br />
-Order allow,deny<br />
-Deny from all<br />
-</Files>
-</code></p></div>
+<pre class="prettyprint lang-config"><Files private.html>
+ Order allow,deny
+ Deny from all
+</Files></pre>
+
<p>To address files found in a particular part of the filesystem, the
<code class="directive"><a href="./mod/core.html#files"><Files></a></code> and
@@ -175,14 +168,13 @@ access to <code>/var/web/dir1/private.ht
of <code>private.html</code> found under the <code>/var/web/dir1/</code>
directory.</p>
-<div class="example"><p><code>
-<Directory /var/web/dir1><br />
-<Files private.html><br />
-Order allow,deny<br />
-Deny from all<br />
-</Files><br />
-</Directory>
-</code></p></div>
+<pre class="prettyprint lang-config"><Directory /var/web/dir1>
+ <Files private.html>
+ Order allow,deny
+ Deny from all
+ </Files>
+</Directory></pre>
+
<h3><a name="webspace" id="webspace">Webspace Containers</a></h3>
@@ -198,12 +190,11 @@ In particular, it will apply to requests
<code>http://yoursite.example.com/private/dir/file.html</code> as well
as any other requests starting with the <code>/private</code> string.</p>
-<div class="example"><p><code>
-<LocationMatch ^/private><br />
-Order Allow,Deny<br />
-Deny from all<br />
-</LocationMatch>
-</code></p></div>
+<pre class="prettyprint lang-config"><LocationMatch ^/private>
+ Order Allow,Deny
+ Deny from all
+</LocationMatch></pre>
+
<p>The <code class="directive"><a href="./mod/core.html#location"><Location></a></code>
directive need not have anything to do with the filesystem.
@@ -212,11 +203,10 @@ URL to an internal Apache handler provid
No file called <code>server-status</code> needs to exist in the
filesystem.</p>
-<div class="example"><p><code>
-<Location /server-status><br />
-SetHandler server-status<br />
-</Location>
-</code></p></div>
+<pre class="prettyprint lang-config"><Location /server-status>
+ SetHandler server-status
+</Location></pre>
+
<h3><a name="wildcards" id="wildcards">Wildcards and Regular Expressions</a></h3>
@@ -242,20 +232,18 @@ how directives are applied.</p>
<p>A non-regex wildcard section that changes the configuration of
all user directories could look as follows:</p>
-<div class="example"><p><code>
-<Directory /home/*/public_html><br />
-Options Indexes<br />
-</Directory>
-</code></p></div>
+<pre class="prettyprint lang-config"><Directory /home/*/public_html>
+ Options Indexes
+</Directory></pre>
+
<p>Using regex sections, we can deny access to many types of image files
at once:</p>
-<div class="example"><p><code>
-<FilesMatch \.(?i:gif|jpe?g|png)$><br />
-Order allow,deny<br />
-Deny from all<br />
-</FilesMatch>
-</code></p></div>
+<pre class="prettyprint lang-config"><FilesMatch \.(?i:gif|jpe?g|png)$>
+ Order allow,deny
+ Deny from all
+</FilesMatch></pre>
+
@@ -273,12 +261,11 @@ different webspace locations (URLs) coul
location, allowing your restrictions to be circumvented.
For example, consider the following configuration:</p>
-<div class="example"><p><code>
-<Location /dir/><br />
-Order allow,deny<br />
-Deny from all<br />
-</Location>
-</code></p></div>
+<pre class="prettyprint lang-config"><Location /dir/>
+ Order allow,deny
+ Deny from all
+</Location></pre>
+
<p>This works fine if the request is for
<code>http://yoursite.example.com/dir/</code>. But what if you are on
@@ -320,16 +307,16 @@ see the <a href="vhosts/">Virtual Host D
and <code class="directive"><a href="./mod/mod_proxy.html#proxymatch"><ProxyMatch></a></code>
containers apply enclosed configuration directives only
to sites accessed through <code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code>'s proxy server
-that match the specified URL. For example, the following configuration
-will prevent the proxy server from being used to access the
-<code>cnn.com</code> website.</p>
-
-<div class="example"><p><code>
-<Proxy http://cnn.com/*><br />
-Order allow,deny<br />
-Deny from all<br />
-</Proxy>
-</code></p></div>
+that match the specified URL. For example, the following configuration
+will allow only a subset of clients to access the
+<code>www.example.com</code> website using the proxy server:</p>
+
+<pre class="prettyprint lang-config"><Proxy "http://www.example.com/*">
+ Order allow,deny
+ Allow from 192.168.1.104 192.168.1.205
+ Deny from all
+</Proxy></pre>
+
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
<div class="section">
<h2><a name="whatwhere" id="whatwhere">What Directives are Allowed?</a></h2>
@@ -409,9 +396,7 @@ are interpreted, it is important to unde
container takes the place of the <code class="directive"><a href="./mod/core.html#directory"><Directory></a></code> container in the processing
order.</p>
- <p>Later sections override earlier ones.</p>
-
-<div class="note"><h3>Technical Note</h3>
+ <div class="note"><h3>Technical Note</h3>
There is actually a
<code><Location></code>/<code><LocationMatch></code>
sequence performed just before the name translation phase
@@ -419,7 +404,48 @@ are interpreted, it is important to unde
are used to map URLs to filenames). The results of this
sequence are completely thrown away after the translation has
completed.
-</div>
+ </div>
+
+<h3><a name="relationship-module-configuration" id="relationship-module-configuration">Relationship between modules and configuration sections</a></h3>
+ <p>One question that often arises after reading how configuration sections are
+ merged is related to how and when directives of specific modules like <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>
+ 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.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>An example can help to visualize the whole process. The following configuration uses the
+ <code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code> directive of <code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code> to set
+ a specific HTTP header. What value will httpd set in the <code>CustomHeaderName</code> header for a request to
+ <code>/example/index.html</code> ?
+ </p>
+ <pre class="prettyprint lang-config"><Directory "/">
+ Header set CustomHeaderName one
+ <FilesMatch ".*">
+ Header set CustomHeaderName three
+ </FilesMatch>
+</Directory>
+
+<Directory "/example">
+ Header set CustomHeaderName two
+</Directory></pre>
+
+ <ul>
+ <li><code class="directive">Directory</code> "/" matches and an initial configuration to set the <code>CustomHeaderName</code> header with the value <code>one</code> is created.</li>
+ <li><code class="directive">Directory</code> "/example" matches, and since <code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code> specifies in its code to override in case of a merge, a new configuration is created to set the <code>CustomHeaderName</code> header with the value <code>two</code>.</li>
+ <li><code class="directive">FilesMatch</code> ".*" matches and another merge opportunity arises, causing the <code>CustomHeaderName</code> header to be set with the value <code>three</code>.</li>
+ <li>Eventually during the next steps of the HTTP request processing <code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code> will be called and it will receive the configuration to set the <code>CustomHeaderName</code> header with the value <code>three</code>. <code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code> 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..</li>
+ </ul>
+
+ <p>This is true for .htaccess too since they have the same priority as <code class="directive">Directory</code> in the merge order. The important concept to understand is that configuration sections like <code class="directive">Directory</code> and <code class="directive">FilesMatch</code> are not comparable to module specific directives like <code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code> or <code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> because they operate on different levels.
+ </p>
+
<h3><a name="merge-examples" id="merge-examples">Some Examples</a></h3>
@@ -428,49 +454,46 @@ merging. Assuming they all apply to the
this example will be applied in the order A > B > C > D >
E.</p>
-<div class="example"><p><code>
-<Location /><br />
-E<br />
-</Location><br />
-<br />
-<Files f.html><br />
-D<br />
-</Files><br />
-<br />
-<VirtualHost *><br />
-<Directory /a/b><br />
-B<br />
-</Directory><br />
-</VirtualHost><br />
-<br />
-<DirectoryMatch "^.*b/"><br />
-C<br />
-</DirectoryMatch><br />
-<br />
-<Directory /a/b><br />
-A<br />
-</Directory><br />
-<br />
-</code></p></div>
+<pre class="prettyprint lang-config"><Location "/">
+ E
+</Location>
+
+<Files "f.html">
+ D
+</Files>
+
+<VirtualHost *>
+<Directory "/a/b">
+ B
+</Directory>
+</VirtualHost>
+
+<DirectoryMatch "^.*b$">
+ C
+</DirectoryMatch>
+
+<Directory "/a/b">
+ A
+</Directory></pre>
+
<p>For a more concrete example, consider the following. Regardless of
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
evaluated last and will allow unrestricted access to the server. In
other words, order of merging is important, so be careful!</p>
-<div class="example"><p><code>
-<Location /><br />
-Order deny,allow<br />
-Allow from all<br />
-</Location><br />
-<br />
-# Woops! This <Directory> section will have no effect<br />
-<Directory /><br />
-Order allow,deny<br />
-Allow from all<br />
-Deny from badguy.example.com<br />
-</Directory>
-</code></p></div>
+<pre class="prettyprint lang-config"><Location "/">
+ Require all granted
+</Location>
+
+# Woops! This <Directory> section will have no effect
+<Directory "/">
+ <RequireAll>
+ Require all granted
+ Require not host badguy.example.com
+ </RequireAll>
+</Directory></pre>
+