Return-Path: 
 <cvs-return-26078-apmail-httpd-cvs-archive=httpd.apache.org@httpd.apache.org>
Delivered-To: apmail-httpd-cvs-archive@www.apache.org
Received: (qmail 93272 invoked from network); 28 Nov 2006 04:38:05 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 28 Nov 2006 04:38:05 -0000
Received: (qmail 64108 invoked by uid 500); 28 Nov 2006 04:38:14 -0000
Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org
Received: (qmail 63903 invoked by uid 500); 28 Nov 2006 04:38:13 -0000
Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
list-help: <mailto:cvs-help@httpd.apache.org>
list-unsubscribe: <mailto:cvs-unsubscribe@httpd.apache.org>
List-Post: <mailto:cvs@httpd.apache.org>
List-Id: <cvs.httpd.apache.org>
Delivered-To: mailing list cvs@httpd.apache.org
Received: (qmail 63892 invoked by uid 99); 28 Nov 2006 04:38:13 -0000
Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 27 Nov 2006 20:38:12 -0800
X-ASF-Spam-Status: No, hits=-9.4 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 27 Nov 2006 20:38:00 -0800
Received: by eris.apache.org (Postfix, from userid 65534)
	id 63F211A984A; Mon, 27 Nov 2006 20:37:05 -0800 (PST)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r479896 -
 /httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml
Date: Tue, 28 Nov 2006 04:37:05 -0000
To: cvs@httpd.apache.org
From: pepper@apache.org
X-Mailer: svnmailer-1.1.0
Message-Id: <20061128043705.63F211A984A@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: pepper
Date: Mon Nov 27 20:37:04 2006
New Revision: 479896

URL: http://svn.apache.org/viewvc?view=rev&rev=479896
Log:
        Reword Order section to make 3-pass design clearer.
        Add table showing results of match combinations.
        Fix some tenses.
        Fix case of CENTER & IP Address.

Modified:
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml?view=diff&rev=479896&r1=479895&r2=479896
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authz_host.xml Mon Nov 27 20:37:04 2006
@@ -78,7 +78,7 @@
 <usage>
     <p>The <directive>Allow</directive> directive affects which hosts can
     access an area of the server. Access can be controlled by
-    hostname, IP Address, IP Address range, or by other
+    hostname, IP address, IP address range, or by other
     characteristics of the client request captured in environment
     variables.</p>
 
@@ -224,47 +224,89 @@
 <override>Limit</override>
 
 <usage>
-    <p>The <directive>Order</directive> directive controls the default
-    access state and the order in which <directive
+
+    <p>The <directive>Order</directive> directive, along with the
+    <directive module="mod_authz_host">Allow</directive> and <directive
+    module="mod_authz_host">Deny</directive> directives, controls a
+    three-pass access control system. The first pass processes either
+    all <directive module="mod_authz_host">Allow</directive> or all
+    <directive module="mod_authz_host">Deny</directive> directives, as
+    specified by the <directive>Order</directive> directive. The second
+    pass parses the rest of the directives (<directive
+    module="mod_authz_host">Deny</directive> or <directive
+    module="mod_authz_host">Allow</directive>). The third pass applies
+    to all requests which do not match either of the first two.</p>
+
+    <p>Note that all <directive
     module="mod_authz_host">Allow</directive> and <directive
-    module="mod_authz_host">Deny</directive> directives are evaluated.
-    <var>Ordering</var> is one of</p>
+    module="mod_authz_host">Deny</directive> directives are processed,
+    unlike a typical firewall, where only the first match is used. The
+    last match is effective (also unlike a typical firewall).
+    Additionally, the order in which lines appear in the configuration
+    files is not significant -- all <directive
+    module="mod_authz_host">Allow</directive> lines are processed as one
+    group, all <directive module="mod_authz_host">Deny</directive> lines
+    are considered as another, and the default state is considered by
+    itself.</p>
+
+    <p><em>Ordering</em> is one of:</p>
 
     <dl>
       <dt><code>Deny,Allow</code></dt>
 
-      <dd>The <directive module="mod_authz_host">Deny</directive> directives
-      are evaluated before the <directive
-      module="mod_authz_host">Allow</directive> directives. Access is
-      allowed by default. Any client which does not match a
-      <directive module="mod_authz_host">Deny</directive> directive or does
-      match an <directive module="mod_authz_host">Allow</directive>
-      directive will be allowed access to the server.</dd>
+      <dd>First, all <directive
+      module="mod_authz_host">Allow</directive> directives are
+      evaluated; at least one must match, or the request is rejected.
+      Next, all <directive module="mod_authz_host">Deny</directive>
+      directives are evaluated. If any matches, the request is rejected.
+      Last, any requests which do not match an <directive
+      module="mod_authz_host">Allow</directive> or a <directive
+      module="mod_authz_host">Deny</directive> directive are denied by
+      default.</dd>
 
       <dt><code>Allow,Deny</code></dt>
 
-      <dd>The <directive module="mod_authz_host">Allow</directive>
-      directives are evaluated before the <directive
-      module="mod_authz_host">Deny</directive> directives. Access is denied
-      by default. Any client which does not match an <directive
-      module="mod_authz_host">Allow</directive> directive or does match a
-      <directive module="mod_authz_host">Deny</directive> directive will be
-      denied access to the server.</dd>
+      <dd>First, all <directive module="mod_authz_host">Deny</directive>
+      directives are evaluated; if any match, the request is denied
+      <strong>unless</strong> it also matches an <directive
+      module="mod_authz_host">Allow</directive> directive. Any requests
+      which do not match any <directive
+      module="mod_authz_host">Allow</directive> or <directive
+      module="mod_authz_host">Deny</directive> directives are
+      permitted.</dd>
 
       <dt><code>Mutual-failure</code></dt>
 
-      <dd>Only those hosts which appear on the <directive
-      module="mod_authz_host">Allow</directive> list and do not appear on
-      the <directive module="mod_authz_host">Deny</directive> list are
-      granted access. This ordering has the same effect as <code>Order
-      Allow,Deny</code> and is deprecated in favor of that
-      configuration.</dd>
+      <dd>This order has the same effect as <code>Order
+      Allow,Deny</code> and is deprecated in its favor.</dd>
     </dl>
 
-    <p>Keywords may only be separated by a comma; <em>no whitespace</em> is
-    allowed between them. Note that in all cases every <directive
-    module="mod_authz_host">Allow</directive> and <directive
-    module="mod_authz_host">Deny</directive> statement is evaluated.</p>
+    <p>Keywords may only be separated by a comma; <em>no whitespace</em>
+    is allowed between them.</p>
+
+    <table border="1">
+      <tr>
+        <th>Match</th>
+        <th>Allow,Deny result</th>
+        <th>Deny,Allow result</th>
+      </tr><tr>
+        <th>Match Allow only</th>
+        <td>Request allowed</td>
+        <td>Request allowed</td>
+      </tr><tr>
+        <th>Match Deny only</th>
+        <td>Request denied</td>
+        <td>Request denied</td>
+      </tr><tr>
+        <th>No match</th>
+        <td>Default to second directive: Denied</td>
+        <td>Default to second directive: Allowed</td>
+      </tr><tr>
+        <th>Match both Allow &amp; Deny</th>
+        <td>Final match controls: Denied</td>
+        <td>Final match controls: Allowed</td>
+      </tr>
+    </table>
 
     <p>In the following example, all hosts in the apache.org domain
     are allowed access; all other hosts are denied access.</p>
@@ -276,10 +318,10 @@
     </example>
 
     <p>In the next example, all hosts in the apache.org domain are
-    allowed access, except for the hosts which are in the
-    foo.apache.org subdomain, who are denied access. All hosts not
-    in the apache.org domain are denied access because the default
-    state is to deny access to the server.</p>
+    allowed access, except for the hosts which are in the foo.apache.org
+    subdomain, who are denied access. All hosts not in the apache.org
+    domain are denied access because the default state is to <directive
+    module="mod_authz_host">Deny</directive> access to the server.</p>
 
     <example>
       Order Allow,Deny<br />
@@ -287,21 +329,21 @@
       Deny from foo.apache.org
     </example>
 
-    <p>On the other hand, if the <directive>Order</directive> in the last
-    example is changed to <code>Deny,Allow</code>, all hosts will
-    be allowed access. This happens because, regardless of the
-    actual ordering of the directives in the configuration file,
-    the <code>Allow from apache.org</code> will be evaluated last
-    and will override the <code>Deny from foo.apache.org</code>.
-    All hosts not in the <code>apache.org</code> domain will also
-    be allowed access because the default state will change to
-    <em>allow</em>.</p>
-
-    <p>The presence of an <directive>Order</directive> directive can affect
-    access to a part of the server even in the absence of accompanying
-    <directive module="mod_authz_host">Allow</directive> and <directive
-    module="mod_authz_host">Deny</directive> directives because of its effect
-    on the default access state. For example,</p>
+    <p>On the other hand, if the <directive>Order</directive> in the
+    last example is changed to <code>Deny,Allow</code>, all hosts will
+    be allowed access. This happens because, regardless of the actual
+    ordering of the directives in the configuration file, the
+    <code>Allow from apache.org</code> will be evaluated last and will
+    override the <code>Deny from foo.apache.org</code>. All hosts not in
+    the <code>apache.org</code> domain will also be allowed access
+    because the default state is <directive
+    module="mod_authz_host">Allow</directive>.</p>
+
+    <p>The presence of an <directive>Order</directive> directive can
+    affect access to a part of the server even in the absence of
+    accompanying <directive module="mod_authz_host">Allow</directive>
+    and <directive module="mod_authz_host">Deny</directive> directives
+    because of its effect on the default access state. For example,</p>
 
     <example>
       &lt;Directory /www&gt;<br />
@@ -311,23 +353,23 @@
       &lt;/Directory&gt;
     </example>
 
-    <p>will deny all access to the <code>/www</code> directory
-    because the default access state will be set to
-    <em>deny</em>.</p>
+    <p>will Deny all access to the <code>/www</code> directory
+    because the default access state is set to
+    <directive module="mod_authz_host">Deny</directive>.</p>
 
-    <p>The <directive>Order</directive> directive controls the order of access
-    directive processing only within each phase of the server's
+    <p>The <directive>Order</directive> directive controls the order of
+    access directive processing only within each phase of the server's
     configuration processing. This implies, for example, that an
     <directive module="mod_authz_host">Allow</directive> or <directive
     module="mod_authz_host">Deny</directive> directive occurring in a
-    <directive module="core" type="section">Location</directive> section will
-    always be evaluated after an <directive
+    <directive module="core" type="section">Location</directive> section
+    will always be evaluated after an <directive
     module="mod_authz_host">Allow</directive> or <directive
     module="mod_authz_host">Deny</directive> directive occurring in a
-    <directive module="core" type="section">Directory</directive> section or
-    <code>.htaccess</code> file, regardless of the setting of the
-    <directive>Order</directive> directive. For details on the merging
-    of configuration sections, see the documentation on <a
+    <directive module="core" type="section">Directory</directive>
+    section or <code>.htaccess</code> file, regardless of the setting of
+    the <directive>Order</directive> directive. For details on the
+    merging of configuration sections, see the documentation on <a
     href="../sections.html">How Directory, Location and Files sections
     work</a>.</p>
 </usage>