]> granicus.if.org Git - apache/commitdiff
Clarification of mod_access_compact and mod_authz_host usage.
authorLuca Toscano <elukey@apache.org>
Fri, 8 Apr 2016 08:06:40 +0000 (08:06 +0000)
committerLuca Toscano <elukey@apache.org>
Fri, 8 Apr 2016 08:06:40 +0000 (08:06 +0000)
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/trunk@1738217 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/mod/mod_access_compat.xml
docs/manual/upgrading.xml

index c16faf2baf87d6d8a88250c042e83310e4942ca1..f68ac36ad3c693e2f7c14ce406b568e211b68282 100644 (file)
@@ -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>,
index 3468695776d1b6b54bb8429cfe04eefe788f5282..705c47731140c467b16482523f3afcbdf99d3c01 100644 (file)
       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>