Clarification of mod_access_compact and mod_authz_host usage.

A recent email in docs@ brought up an interesting use case, namely mixing
mod_access_compact (Order, Deny, Allow) and mod_authz_host (Require) directives
while migrating from 2.2 to 2.4. This is technically possible but it leads
to a lot of confusion due to how config merge works between these modules. This change adds
some examples on the documentation about things that might go wrong when mixing
old and new directives, stating clearly that mod_access_compact or mod_authz_host
should not be used together.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1738542 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml
index 388e69eee652ce20e97ccf8fee43910f4ed1f21d..24ea18231945c764b35f7924bd4c9ce95cff7077 100644 (file)
--- a/docs/manual/howto/auth.xml
+++ b/docs/manual/howto/auth.xml
@@ -560,6 +560,21 @@ Require group GroupName
         <directive module="mod_access_compat">Satisfy</directive> are no longer needed.
         However to provide backwards compatibility for older configurations, these
         directives have been moved to the <module>mod_access_compat</module> module.</p>
+
+        <note type="warning"><title>Note</title>
+        <p>The directives provided by <module>mod_access_compat</module> have
+        been deprecated by <module>mod_authz_host</module>.
+        Mixing old directives like <directive
+        module="mod_access_compat">Order</directive>, <directive
+        module="mod_access_compat">Allow</directive> or <directive
+        module="mod_access_compat">Deny</directive> with new ones like
+        <directive module="mod_authz_core">Require</directive> is technically possible
+        but discouraged. The <module>mod_access_compat</module> module was created to support
+        configurations containing only old directives to facilitate the 2.4 upgrade.
+        Please check the <a href="../upgrading.html">upgrading</a> guide for more
+        information.
+        </p>
+        </note>
     </section>
 
 </section>

diff --git a/docs/manual/mod/mod_access_compat.xml b/docs/manual/mod/mod_access_compat.xml
index 5d5f4cee772c6445a71d3add2092c90d70ed2399..1feda128714d75418faf18b4874c36174e112861 100644 (file)
--- a/docs/manual/mod/mod_access_compat.xml
+++ b/docs/manual/mod/mod_access_compat.xml
@@ -59,9 +59,19 @@ have been deprecated by the new authz refactoring.  Please see
 
     <note type="warning"><title>Note</title>
       <p>The directives provided by <module>mod_access_compat</module> have
-      been deprecated by the new authz refactoring. Please see
-      <module>mod_authz_host</module>.</p>
-    </note>
+      been deprecated by <module>mod_authz_host</module>. 
+      Mixing old directives like <directive
+      module="mod_access_compat">Order</directive>, <directive
+      module="mod_access_compat">Allow</directive> or <directive
+      module="mod_access_compat">Deny</directive> with new ones like
+      <directive
+      module="mod_authz_core">Require</directive> is technically possible 
+      but discouraged. This module was created to support 
+      configurations containing only old directives to facilitate the 2.4 upgrade. 
+      Please check the <a href="../upgrading.html">upgrading</a> guide for more
+      information.
+      </p>
+      </note>
 
     <p>In general, access restriction directives apply to all
     access methods (<code>GET</code>, <code>PUT</code>,

diff --git a/docs/manual/upgrading.xml b/docs/manual/upgrading.xml
index 71ea9da5c87299dc2ceafa0b655baa23ded803c2..64580c69beb78c23d362320421e8d45037f40f4a 100644 (file)
--- a/docs/manual/upgrading.xml
+++ b/docs/manual/upgrading.xml
@@ -137,6 +137,19 @@
       although for compatibility with old configurations, the new
       module <module>mod_access_compat</module> is provided.</p>
 
+      <note><title>Mixing old and new directives</title>
+      <p>Mixing old directives like <directive
+      module="mod_access_compat">Order</directive>, <directive
+      module="mod_access_compat">Allow</directive> or <directive
+      module="mod_access_compat">Deny</directive> with new ones like
+      <directive
+      module="mod_authz_core">Require</directive> is technically possible 
+      but discouraged. <module>mod_access_compat</module> was created to support 
+      configurations containing only old directives to facilitate the 2.4 upgrade. 
+      Please check the examples below to get a better idea about issues that might arise.
+      </p>
+      </note>
+
       <p>Here are some examples of old and new ways to do the same
       access control.</p>
 
@@ -187,6 +200,61 @@ Allow from example.org
         Require host example.org
         </highlight>
       </example>
+
+      <p>In the following example, mixing old and new directives leads to 
+      unexpected results.</p>
+ 
+      <example>
+        <title>Mixing old and new directives: NOT WORKING AS EXPECTED</title>
+          <highlight language="config">
+DocumentRoot "/var/www/html"
+
+&lt;Directory "/"&gt;
+    AllowOverride None
+    Order deny,allow
+    Deny from all
+&lt;/Directory&gt;
+
+&lt;Location "/server-status"&gt;
+    SetHandler server-status
+    Require 127.0.0.1
+&lt;/Location&gt;
+
+access.log - GET /server-status 403 127.0.0.1
+error.log - AH01797: client denied by server configuration: /var/www/html/server-status
+          </highlight>
+      </example>
+      <p>Why httpd denies access to servers-status even if the configuration seems to allow it?
+        Because <module>mod_access_compat</module> directives take precedence
+        over the <module>mod_authz_host</module> one in this configuration 
+        <a href="sections.html#merging">merge</a> scenario.</p>
+
+      <p>This example conversely works as expected:</p>
+
+      <example>
+        <title>Mixing old and new directives: WORKING AS EXPECTED</title>
+        <highlight language="config">
+DocumentRoot "/var/www/html"
+
+&lt;Directory "/"&gt;
+    AllowOverride None
+    Require all denied
+&lt;/Directory&gt;
+
+&lt;Location "/server-status"&gt;
+    SetHandler server-status
+    Order deny,allow
+    Deny from all
+    Allow From 127.0.0.1
+&lt;/Location&gt;
+
+access.log - GET /server-status 200 127.0.0.1
+        </highlight>
+      </example> 
+      <p>So even if mixing configuration is still
+        possible, please try to avoid it when upgrading: either keep old directives and then migrate
+        to the new ones on a later stage or just migrate everything in bulk.  
+      </p>
     </section>
 
     </section>