From 4add50908a90ccdd824a81a4d9360b22ff875305 Mon Sep 17 00:00:00 2001
From: Eric Covener <covener@apache.org>
Date: Mon, 5 Dec 2016 19:39:40 +0000
Subject: [PATCH] Merge r1772758 from trunk:

provide more access control migration hints

current examples don't account for when access control overlaps
with authentication.




git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1772762 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/upgrading.xml | 88 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 85 insertions(+), 3 deletions(-)

diff --git a/docs/manual/upgrading.xml b/docs/manual/upgrading.xml
index 64580c69beb..f340fa310cb 100644
--- a/docs/manual/upgrading.xml
+++ b/docs/manual/upgrading.xml
@@ -153,7 +153,7 @@
       <p>Here are some examples of old and new ways to do the same
       access control.</p>
 
-      <p>In this example, all requests are denied.</p>
+      <p>In this example, there is no authentication and all requests are denied.</p>
       <example>
         <title>2.2 configuration:</title>
         <highlight language="config">
@@ -168,7 +168,7 @@ Deny from all
         </highlight>
       </example>
 
-      <p>In this example, all requests are allowed.</p>
+      <p>In this example, there is no authentication and all requests are allowed.</p>
       <example>
         <title>2.2 configuration:</title>
         <highlight language="config">
@@ -183,7 +183,7 @@ Allow from all
         </highlight>
       </example>
 
-      <p>In the following example, all hosts in the example.org domain
+      <p>In the following example, there is no authentication and all hosts in the example.org domain
       are allowed access; all other hosts are denied access.</p>
 
       <example>
@@ -257,6 +257,88 @@ access.log - GET /server-status 200 127.0.0.1
       </p>
     </section>
 
+     <p>In many configurations with authentication, where the value of the
+     <directive>Satisfy</directive> was the default of <em>ALL</em>, snippets
+     that simply disabled host-based access control are omitted:</p>
+
+      <example>
+        <title>2.2 configuration:</title>
+        <highlight language="config">
+Order Deny,Allow
+Deny from all
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user
+        </highlight>
+      </example>
+      <example>
+        <title>2.4 configuration:</title>
+        <highlight language="config">
+# No replacement needed
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user
+        </highlight>
+      </example>
+
+     <p>In configurations where both authentication and access control were meaningfully combined, the 
+        access control directives should be migrated. This example allows requests meeting <em>both</em> criteria:</p>
+      <example>
+        <title>2.2 configuration:</title>
+        <highlight language="config">
+Order allow,deny
+Deny from all
+# Satisfy ALL is the default
+Satisfy ALL
+Allow from 127.0.0.1
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user
+        </highlight>
+      </example>
+      <example>
+        <title>2.4 configuration:</title>
+        <highlight language="config">
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+&lt;RequireAll&gt;
+  Require valid-user
+  require ip 127.0.0.1
+&lt;/RequireAll&gt;
+        </highlight>
+      </example>
+
+     <p>In configurations where both authentication and access control were meaningfully combined, the 
+        access control directives should be migrated. This example allows requests meeting <em>either</em> criteria:</p>
+      <example>
+        <title>2.2 configuration:</title>
+        <highlight language="config">
+Order allow,deny
+Deny from all
+Satisfy any
+Allow from 127.0.0.1
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user
+        </highlight>
+      </example>
+      <example>
+        <title>2.4 configuration:</title>
+        <highlight language="config">
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+# Implicitly &lt;RequireAny&gt;
+Require valid-user
+Require ip 127.0.0.1
+        </highlight>
+      </example>
+
     </section>
 
     <section id="config">
-- 
2.47.2