From: Eric Covener <covener@apache.org>
Date: Mon, 2 Jan 2012 17:18:39 +0000 (+0000)
Subject: add/enhance some hints about configuration section merging (or lack of it in
X-Git-Tag: 2.5.0-alpha~7610
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3098f24dcae3591a81df5760fb4812f402cff211;p=thirdparty%2Fapache%2Fhttpd.git

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
---

diff --git a/docs/manual/misc/security_tips.html.en b/docs/manual/misc/security_tips.html.en
index 84dcbf6fe1c..6650636b2d4 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 543b4f65e79..43460a16d5b 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 5908133b3d4..af31e3adb9e 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 a4b747a01fd..4611412483a 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 9d7cfd64217..12a088ae2c2 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 33de9b9bbbe..c7fb4ac2df0 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