add/enhance some hints about configuration section merging (or lack of it in

the case of mod_access_compat)
PR52406



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1226477 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 99 insertions, 2 deletions

diff --git a/docs/manual/misc/security_tips.html.en b/docs/manual/misc/security_tips.html.en
index 84dcbf6fe1..6650636b2d 100644
--- a/docs/manual/misc/security_tips.html.en
+++ b/docs/manual/misc/security_tips.html.en
@@ -39,6 +39,7 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#systemsettings">Protecting System Settings</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#protectserverfiles">Protect Server Files by Default</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#watchyourlogs">Watching Your Logs</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#merging">Merging of configuration sections</a></li>
 </ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
@@ -445,6 +446,21 @@
       &lt;/Files&gt;
     </code></p></div>
 
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="merging" id="merging">Merging of configuration sections</a></h2>
+
+    
+
+    <p> The merging of configuration sections is complicated and sometimes
+    directive specific.  Always test your changes when creating dependencies
+    on how directives are merged.</p>
+
+    <p> For modules that don't implement any merging logic, such as 
+    <code class="directive">mod_access_compat</code>, the behavior in later sections
+    depends on whether the later section has any directives
+    from the module.  The configuration is inherited until a change is made, 
+    at which point the configuration is <em>replaced</em>.</p>
   </div></div>
 <div class="bottomlang">
 <p><span>Available Languages: </span><a href="../en/misc/security_tips.html" title="English">&nbsp;en&nbsp;</a> |
diff --git a/docs/manual/misc/security_tips.xml b/docs/manual/misc/security_tips.xml
index 543b4f65e7..43460a16d5 100644
--- a/docs/manual/misc/security_tips.xml
+++ b/docs/manual/misc/security_tips.xml
@@ -447,4 +447,19 @@
 
   </section>
 
+  <section id="merging">
+
+    <title>Merging of configuration sections</title>
+
+    <p> The merging of configuration sections is complicated and sometimes
+    directive specific.  Always test your changes when creating dependencies
+    on how directives are merged.</p>
+
+    <p> For modules that don't implement any merging logic, such as 
+    <directive>mod_access_compat</directive>, the behavior in later sections
+    depends on whether the later section has any directives
+    from the module.  The configuration is inherited until a change is made, 
+    at which point the configuration is <em>replaced</em> and not merged.</p>
+  </section>
+
 </manualpage>
diff --git a/docs/manual/mod/mod_access_compat.html.en b/docs/manual/mod/mod_access_compat.html.en
index 5908133b3d..af31e3adb9 100644
--- a/docs/manual/mod/mod_access_compat.html.en
+++ b/docs/manual/mod/mod_access_compat.html.en
@@ -67,6 +67,13 @@ have been deprecated by the new authz refactoring.  Please see
     cases. However, it is possible to restrict some methods, while
     leaving other methods unrestricted, by enclosing the directives
     in a <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> section.</p>
+
+    <div class="note"> <h3>Merging of configuration sections</h3>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </div>
+
 </div>
 <div id="quickview"><h3 class="directives">Directives</h3>
 <ul id="toc">
@@ -209,6 +216,13 @@ server</td></tr>
     with <code>KnockKnock/2.0</code> will be allowed access, and all
     others will be denied.</p>
 
+    <div class="note"> <h3>Merging of configuration sections</h3>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </div>
+
+
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="Deny" id="Deny">Deny</a> <a name="deny" id="deny">Directive</a></h2>
@@ -377,6 +391,13 @@ evaluated.</td></tr>
     of configuration sections, see the documentation on <a href="../sections.html">How Directory, Location and Files sections
     work</a>.</p>
 
+    <div class="note"> <h3>Merging of configuration sections</h3>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </div>
+
+
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="Satisfy" id="Satisfy">Satisfy</a> <a name="satisfy" id="satisfy">Directive</a></h2>
@@ -438,6 +459,13 @@ later</td></tr>
     <p>Since version 2.0.51 <code class="directive">Satisfy</code> directives can
     be restricted to particular methods by <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> and <code class="directive"><a href="../mod/core.html#limitexcept">&lt;LimitExcept&gt;</a></code> sections.</p>
 
+    <div class="note"> <h3>Merging of configuration sections</h3>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </div>
+
+
 <h3>See also</h3>
 <ul>
 <li><code class="directive"><a href="#allow">Allow</a></code></li>
diff --git a/docs/manual/mod/mod_access_compat.xml b/docs/manual/mod/mod_access_compat.xml
index a4b747a01f..4611412483 100644
--- a/docs/manual/mod/mod_access_compat.xml
+++ b/docs/manual/mod/mod_access_compat.xml
@@ -69,6 +69,13 @@ have been deprecated by the new authz refactoring.  Please see
     cases. However, it is possible to restrict some methods, while
     leaving other methods unrestricted, by enclosing the directives
     in a <directive module="core" type="section">Limit</directive> section.</p>
+
+    <note> <title>Merging of configuration sections</title>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </note>
+
 </summary>
 
 <seealso><directive module="mod_authz_core">Require</directive></seealso>
@@ -203,6 +210,13 @@ server</description>
     <p>In this case, browsers with a user-agent string beginning
     with <code>KnockKnock/2.0</code> will be allowed access, and all
     others will be denied.</p>
+
+    <note> <title>Merging of configuration sections</title>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </note>
+
 </usage>
 </directivesynopsis>
 
@@ -390,6 +404,13 @@ evaluated.</description>
     of configuration sections, see the documentation on <a
     href="../sections.html">How Directory, Location and Files sections
     work</a>.</p>
+
+    <note> <title>Merging of configuration sections</title>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </note>
+
 </usage>
 </directivesynopsis>
 
@@ -457,6 +478,13 @@ later</compatibility>
     be restricted to particular methods by <directive module="core"
     type="section">Limit</directive> and <directive module="core" type="section"
     >LimitExcept</directive> sections.</p>
+
+    <note> <title>Merging of configuration sections</title>
+      <p>When any directive provided by this module is used in a new 
+      configuration section, no directives provided by this module are
+      inherited from previous configuration sections.</p>
+    </note>
+
 </usage>
    <seealso><directive module="mod_access_compat">Allow</directive></seealso>
    <seealso><directive module="mod_authz_core">Require</directive></seealso>
diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en
index 9d7cfd6421..12a088ae2c 100644
--- a/docs/manual/sections.html.en
+++ b/docs/manual/sections.html.en
@@ -460,7 +460,12 @@ are interpreted, it is important to understand how this works.</p>
     container takes the place of the <code class="directive"><a href="./mod/core.html#directory">&lt;Directory&gt;</a></code> container in the processing
     order.</p>
 
-    <p>Later sections override earlier ones.</p>
+    <p>Later sections override earlier ones, however each module is responsible
+    for interpeting what form this override takes.  A later configuration section 
+    with directives from a given module might cause a conceptual "merge" of some
+    directives, all directives, or a complete replacement of the modules 
+    configuration with the module defaults and directives explicitly listed in 
+    the later context.</p>
 
 <div class="note"><h3>Technical Note</h3>
       There is actually a
diff --git a/docs/manual/sections.xml b/docs/manual/sections.xml
index 33de9b9bbb..c7fb4ac2df 100644
--- a/docs/manual/sections.xml
+++ b/docs/manual/sections.xml
@@ -506,7 +506,12 @@ are interpreted, it is important to understand how this works.</p>
     type="section">Directory</directive> container in the processing
     order.</p>
 
-    <p>Later sections override earlier ones.</p>
+    <p>Later sections override earlier ones, however each module is responsible
+    for interpeting what form this override takes.  A later configuration section 
+    with directives from a given module might cause a conceptual "merge" of some
+    directives, all directives, or a complete replacement of the modules 
+    configuration with the module defaults and directives explicitly listed in 
+    the later context.</p>
 
 <note><title>Technical Note</title>
       There is actually a