httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elu...@apache.org
Subject svn commit: r1731240 - /httpd/httpd/branches/2.2.x/docs/manual/sections.xml
Date Fri, 19 Feb 2016 13:26:22 GMT
Author: elukey
Date: Fri Feb 19 13:26:22 2016
New Revision: 1731240

URL: http://svn.apache.org/viewvc?rev=1731240&view=rev
Log:
Backported Doc change for sections.html, moved example sections to highligh.

Modified:
    httpd/httpd/branches/2.2.x/docs/manual/sections.xml

Modified: httpd/httpd/branches/2.2.x/docs/manual/sections.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/sections.xml?rev=1731240&r1=1731239&r2=1731240&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/sections.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/sections.xml Fri Feb 19 13:26:22 2016
@@ -74,11 +74,11 @@ with the following configuration, all re
 to another site only if the server is started using
 <code>httpd -DClosedForNow</code>:</p>
 
-<example>
-&lt;IfDefine ClosedForNow&gt;<br />
-Redirect / http://otherserver.example.com/<br />
+<highlight language="config">
+&lt;IfDefine ClosedForNow&gt;
+    Redirect / http://otherserver.example.com/
 &lt;/IfDefine&gt;
-</example>
+</highlight>
 
 <p>The <directive type="section" module="core">IfModule</directive>
 directive is very similar, except it encloses directives that will
@@ -96,11 +96,11 @@ about missing modules.</p>
 module="mod_mime_magic">MimeMagicFile</directive> directive will be
 applied only if <module>mod_mime_magic</module> is available.</p>
 
-<example>
-&lt;IfModule mod_mime_magic.c&gt;<br />
-MimeMagicFile conf/magic<br />
+<highlight language="config">
+&lt;IfModule mod_mime_magic.c&gt;
+    MimeMagicFile conf/magic
 &lt;/IfModule&gt;
-</example>
+</highlight>
 
 <p>The <directive type="section" module="mod_version">IfVersion</directive>
 directive is very similar to <directive type="section"
@@ -110,14 +110,12 @@ 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>
 
-<example>
-  &lt;IfVersion >= 2.1&gt;<br />
-  <indent>
-    # this happens only in versions greater or<br />
-    # equal 2.1.0.<br />
-  </indent>
-  &lt;/IfVersion&gt;
-</example>
+<highlight language="config">
+&lt;IfVersion >= 2.1&gt;
+    # this happens only in versions greater or
+    # equal 2.1.0.
+&lt;/IfVersion&gt;
+</highlight>
 
 <p><directive type="section" module="core">IfDefine</directive>,
 <directive type="section" module="core">IfModule</directive>, and the
@@ -161,11 +159,11 @@ href="howto/htaccess.html">.htaccess fil
 following configuration, directory indexes will be enabled for the
 <code>/var/web/dir1</code> directory and all subdirectories.</p>
 
-<example>
-&lt;Directory /var/web/dir1&gt;<br />
-Options +Indexes<br />
+<highlight language="config">
+&lt;Directory /var/web/dir1&gt;
+    Options +Indexes
 &lt;/Directory&gt;
-</example>
+</highlight>
 
 <p>Directives enclosed in a <directive type="section"
 module="core">Files</directive> section apply to any file with
@@ -175,12 +173,12 @@ 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>
 
-<example>
-&lt;Files private.html&gt;<br />
-Order allow,deny<br />
-Deny from all<br />
+<highlight language="config">
+&lt;Files private.html&gt;
+    Order allow,deny
+    Deny from all
 &lt;/Files&gt;
-</example>
+</highlight>
 
 <p>To address files found in a particular part of the filesystem, the
 <directive type="section" module="core">Files</directive> and
@@ -192,14 +190,14 @@ access to <code>/var/web/dir1/private.ht
 of <code>private.html</code> found under the <code>/var/web/dir1/</code>
 directory.</p>
 
-<example>
-&lt;Directory /var/web/dir1&gt;<br />
-&lt;Files private.html&gt;<br />
-Order allow,deny<br />
-Deny from all<br />
-&lt;/Files&gt;<br />
+<highlight language="config">
+&lt;Directory /var/web/dir1&gt;
+    &lt;Files private.html&gt;
+        Order allow,deny
+        Deny from all
+    &lt;/Files&gt;
 &lt;/Directory&gt;
-</example>
+</highlight>
 </section>
 
 <section id="webspace"><title>Webspace Containers</title>
@@ -215,12 +213,12 @@ 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>
 
-<example>
-&lt;LocationMatch ^/private&gt;<br />
-Order Allow,Deny<br />
-Deny from all<br />
+<highlight language="config">
+&lt;LocationMatch ^/private&gt;
+    Order Allow,Deny
+    Deny from all
 &lt;/LocationMatch&gt;
-</example>
+</highlight>
 
 <p>The <directive type="section" module="core">Location</directive>
 directive need not have anything to do with the filesystem.
@@ -229,11 +227,11 @@ URL to an internal Apache handler provid
 No file called <code>server-status</code> needs to exist in the
 filesystem.</p>
 
-<example>
-&lt;Location /server-status&gt;<br />
-SetHandler server-status<br />
+<highlight language="config">
+&lt;Location /server-status&gt;
+    SetHandler server-status
 &lt;/Location&gt;
-</example>
+</highlight>
 </section>
 
 <section id="wildcards"><title>Wildcards and Regular Expressions</title>
@@ -262,20 +260,20 @@ how directives are applied.</p>
 <p>A non-regex wildcard section that changes the configuration of
 all user directories could look as follows:</p>
 
-<example>
-&lt;Directory /home/*/public_html&gt;<br />
-Options Indexes<br />
+<highlight language="config">
+&lt;Directory /home/*/public_html&gt;
+    Options Indexes
 &lt;/Directory&gt;
-</example>
+</highlight>
 
 <p>Using regex sections, we can deny access to many types of image files
 at once:</p>
-<example>
-&lt;FilesMatch \.(?i:gif|jpe?g|png)$&gt;<br />
-Order allow,deny<br />
-Deny from all<br />
+<highlight language="config">
+&lt;FilesMatch \.(?i:gif|jpe?g|png)$&gt;
+    Order allow,deny
+    Deny from all
 &lt;/FilesMatch&gt;
-</example>
+</highlight>
 
 </section>
 
@@ -297,12 +295,12 @@ different webspace locations (URLs) coul
 location, allowing your restrictions to be circumvented.
 For example, consider the following configuration:</p>
 
-<example>
-&lt;Location /dir/&gt;<br />
-Order allow,deny<br />
-Deny from all<br />
+<highlight language="config">
+&lt;Location /dir/&gt;
+    Order allow,deny
+    Deny from all
 &lt;/Location&gt;
-</example>
+</highlight>
 
 <p>This works fine if the request is for
 <code>http://yoursite.example.com/dir/</code>.  But what if you are on
@@ -346,16 +344,17 @@ see the <a href="vhosts/">Virtual Host D
 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
 containers apply enclosed configuration directives only
 to sites accessed through <module>mod_proxy</module>'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>
-
-<example>
-&lt;Proxy http://cnn.com/*&gt;<br />
-Order allow,deny<br />
-Deny from all<br />
+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>
+
+<highlight language="config">
+&lt;Proxy "http://www.example.com/*"&gt;
+    Order allow,deny
+    Allow from 192.168.1.104 192.168.1.205
+    Deny from all
 &lt;/Proxy&gt;
-</example>
+</highlight>
 </section>
 
 <section id="whatwhere"><title>What Directives are Allowed?</title>
@@ -448,9 +447,7 @@ are interpreted, it is important to unde
     type="section">Directory</directive> container in the processing
     order.</p>
 
-    <p>Later sections override earlier ones.</p>
-
-<note><title>Technical Note</title>
+    <note><title>Technical Note</title>
       There is actually a
       <code>&lt;Location&gt;</code>/<code>&lt;LocationMatch&gt;</code>
       sequence performed just before the name translation phase
@@ -458,7 +455,51 @@ 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.
-</note>
+    </note>
+
+<section id="relationship-module-configuration"><title>Relationship between modules
and configuration sections</title>
+    <p>One question that often arises after reading how configuration sections are
+    merged is related to how and when directives of specific modules like <module>mod_rewrite</module>
+    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 
+        <directive module="mod_headers">Header</directive> directive of <module>mod_headers</module>
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>
+    <highlight language="config">
+
+&lt;Directory "/"&gt;
+    Header set CustomHeaderName one
+    &lt;FilesMatch ".*"&gt;
+        Header set CustomHeaderName three
+    &lt;/FilesMatch&gt;
+&lt;/Directory&gt;
+
+&lt;Directory "/example"&gt;
+    Header set CustomHeaderName two
+&lt;/Directory&gt;
+     
+    </highlight>    
+    <ul>
+        <li><directive>Directory</directive> "/" matches and an initial
configuration to set the <code>CustomHeaderName</code> header with the value <code>one</code>
is created.</li>
+        <li><directive>Directory</directive> "/example" matches, and since
<module>mod_headers</module> 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><directive>FilesMatch</directive> ".*" 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 <module>mod_headers</module>
will be called and it will receive the configuration to set the <code>CustomHeaderName</code>
header with the value <code>three</code>. <module>mod_headers</module>
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 <directive>Directory</directive>
in the merge order. The important concept to understand is that configuration sections like
 <directive>Directory</directive> and <directive>FilesMatch</directive>
are not comparable to module specific directives like <directive module="mod_headers">Header</directive>
or <directive module="mod_rewrite">RewriteRule</directive> because they operate
on different levels.
+    </p>
+</section>
 
 <section id="merge-examples"><title>Some Examples</title>
 
@@ -467,30 +508,30 @@ merging. Assuming they all apply to the
 this example will be applied in the order A &gt; B &gt; C &gt; D &gt;
 E.</p>
 
-<example>
-&lt;Location /&gt;<br />
-E<br />
-&lt;/Location&gt;<br />
-<br />
-&lt;Files f.html&gt;<br />
-D<br />
-&lt;/Files&gt;<br />
-<br />
-&lt;VirtualHost *&gt;<br />
-&lt;Directory /a/b&gt;<br />
-B<br />
-&lt;/Directory&gt;<br />
-&lt;/VirtualHost&gt;<br />
-<br />
-&lt;DirectoryMatch "^.*b/"&gt;<br />
-C<br />
-&lt;/DirectoryMatch&gt;<br />
-<br />
-&lt;Directory /a/b&gt;<br />
-A<br />
-&lt;/Directory&gt;<br />
-<br />
-</example>
+<highlight language="config">
+&lt;Location "/"&gt;
+    E
+&lt;/Location&gt;
+
+&lt;Files "f.html"&gt;
+    D
+&lt;/Files&gt;
+
+&lt;VirtualHost *&gt;
+&lt;Directory "/a/b"&gt;
+    B
+&lt;/Directory&gt;
+&lt;/VirtualHost&gt;
+
+&lt;DirectoryMatch "^.*b$"&gt;
+    C
+&lt;/DirectoryMatch&gt;
+
+&lt;Directory "/a/b"&gt;
+    A
+&lt;/Directory&gt;
+
+</highlight>
 
 <p>For a more concrete example, consider the following.  Regardless of
 any access restrictions placed in <directive module="core"
@@ -499,19 +540,19 @@ module="core" type="section">Location</d
 evaluated last and will allow unrestricted access to the server.  In
 other words, order of merging is important, so be careful!</p>
 
-<example>
-&lt;Location /&gt;<br />
-Order deny,allow<br />
-Allow from all<br />
-&lt;/Location&gt;<br />
-<br />
-# Woops!  This &lt;Directory&gt; section will have no effect<br />
-&lt;Directory /&gt;<br />
-Order allow,deny<br />
-Allow from all<br />
-Deny from badguy.example.com<br />
+<highlight language="config">
+&lt;Location "/"&gt;
+    Require all granted
+&lt;/Location&gt;
+
+# Woops!  This &lt;Directory&gt; section will have no effect
+&lt;Directory "/"&gt;
+    &lt;RequireAll&gt;
+        Require all granted
+        Require not host badguy.example.com
+    &lt;/RequireAll&gt;
 &lt;/Directory&gt;
-</example>
+</highlight>
 
 </section>
 



Mime
View raw message