updated mod_info to include docs on the different arguments it can take.

Submitted By: Rici Lake


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

1 files changed, 92 insertions, 35 deletions

diff --git a/docs/manual/mod/mod_info.html.en b/docs/manual/mod/mod_info.html.en
index d3bbb503a0..c612e27f80 100644
--- a/docs/manual/mod/mod_info.html.en
+++ b/docs/manual/mod/mod_info.html.en
@@ -42,47 +42,104 @@ configuration</td></tr>
       &lt;/Location&gt;
     </code></p></div>
 
-    <p>You may wish to add a 
-    <code class="directive"><a href="../mod/core.html#limit">&lt;Limit&gt;</a></code> 
-    clause inside the 
-    <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code>
-    directive to limit access to your server configuration 
-    information.</p>
-
     <p>Once configured, the server information is obtained by
     accessing <code>http://your.host.dom/server-info</code></p>
-
-    <div class="note">
-      Note that the configuration files are read by the
-      module at run-time, and therefore the display may
-      <em>not</em> reflect the running server's active
-      configuration if the files have been changed since the server
-      was last reloaded. Also, the configuration files must be
-      readable by the user as which the server is running (see the
-      <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> directive), or
-      else the directive settings will not be listed.
-
-      <p>It should also be noted that if
-      <code class="module"><a href="../mod/mod_info.html">mod_info</a></code> is compiled into the server, its
-      handler capability is available in <em>all</em> configuration
-      files, including per-directory files (<em>e.g.</em>,
-      <code>.htaccess</code>). This may have security-related
-      ramifications for your site.</p>
-
-      <p>In particular, this module can leak sensitive information
-      from the configuration directives of other Apache modules such as
-      system paths, usernames/passwords, database names, etc.  Due to
-      the way this module works there is no way to block information
-      from it.  Therefore, this module should <strong>only</strong> be
-      used in a controlled environment and always with caution.</p>
-    </div>
 </div>
 <div id="quickview"><h3 class="directives">Directives</h3>
 <ul id="toc">
 <li><img alt="" src="../images/down.gif" /> <a href="#addmoduleinfo">AddModuleInfo</a></li>
 </ul>
-</div>
+<h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Issues</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#queries">Selecting the information shown</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#limitations">Known Limitations</a></li>
+</ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="security" id="security">Security Issues</a></h2>
+    <p>Once <code class="module"><a href="../mod/mod_info.html">mod_info</a></code> is loaded into the server, its
+    handler capability is available in <em>all</em> configuration
+    files, including per-directory files (<em>e.g.</em>,
+    <code>.htaccess</code>). This may have security-related
+    ramifications for your site.</p>
+
+    <p>In particular, this module can leak sensitive information
+    from the configuration directives of other Apache modules such as
+    system paths, usernames/passwords, database names, etc. Therefore,
+    this module should <strong>only</strong> be
+    used in a controlled environment and always with caution.</p>
 
+    <p>You will probably want to use <code class="module"><a href="../mod/mod_access.html">mod_access</a></code> 
+    to limit access to your server configuration information.</p>
+      
+    <div class="example"><h3>Access control</h3><p><code>
+      &lt;Location /server-info&gt;<br />
+      <span class="indent">
+        SetHandler server-info<br />
+        Order allow,deny
+        # Allow access from server itself
+        Allow from 127.0.0.1
+        # Additionally, allow access from local workstation
+        Allow from 192.168.1.17
+      </span>
+      &lt;/Location&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="queries" id="queries">Selecting the information shown</a></h2>
+    <p>By default, the server information includes a list of
+    all enabled modules, and for each module, a description of
+    the directives understood by that module, the hooks implemented
+    by that module, and the relevant directives from the current
+    configuration.</p>
+    
+    <p>Other views of the configuration information are available by
+    appending a query to the <code>server-info</code> request. For
+    example, <code>http://your.host.dom/server-info?config</code>
+    will show all configuration directives.</p>
+    
+    <dl>
+        <dt><code>?&lt;module-name&gt;</code></dt>
+            <dd>Only information relevant to the named module</dd>
+        <dt><code>?config</code></dt>
+            <dd>Just the configuration directives, not sorted by module</dd>
+        <dt><code>?list</code></dt>
+            <dd>Only a simple list of enabled modules</dd>
+        <dt><code>?server</code></dt>
+            <dd>Only the basic server information</dd>
+    </dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="limitations" id="limitations">Known Limitations</a></h2>
+    <p><code class="module"><a href="../mod/mod_info.html">mod_info</a></code> provides its information by reading the
+    parsed configuration, rather than reading the original configuration
+    file. There are a few limitations as a result of the way the parsed
+    configuration tree is created:</p>
+    <ul>
+      <li>Directives which are executed immediately rather than being
+          stored in the parsed configuration are not listed. These include
+          <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>,
+          <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>, and
+          <code class="directive"><a href="../mod/mod_so.html#loadfile">LoadFile</a></code>.</li>
+      <li>Directives which control the configuration file itself, such as
+          <code class="directive"><a href="../mod/core.html#include">Include</a></code>,
+          <code class="directive"><a href="../mod/core.html#&lt;ifmodule&gt;">&lt;IfModule&gt;</a></code> and
+          <code class="directive"><a href="../mod/core.html#&lt;ifdefine&gt;">&lt;IfDefine&gt;</a></code> are not
+          listed, but the included configuration directives are.</li>
+      <li>Comments are not listed. (This may be considered a feature.)</li>
+      <li>Configuration directives from <code>.htaccess</code> files are
+          not listed (since they do not form part of the permanent server
+          configuration).</li>
+      <li>Container directives such as
+          <code class="directive"><a href="../mod/core.html#&lt;directory&gt;">&lt;Directory&gt;</a></code>
+          are listed normally, but <code class="module"><a href="../mod/mod_info.html">mod_info</a></code> cannot figure
+          out the line number for the closing
+          <code class="directive"><a href="../mod/core.html#&lt;/directory&gt;">&lt;/Directory&gt;</a></code>.</li>
+      <li>Directives generated by third party modules such as <code class="module"><a href="../mod/mod_perl.html">mod_perl</a></code>
+          might not be listed.</li>
+    </ul>
+</div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="AddModuleInfo" id="AddModuleInfo">AddModuleInfo</a> <a name="addmoduleinfo" id="addmoduleinfo">Directive</a></h2>
 <table class="directive">
@@ -101,8 +158,8 @@ information displayed by the server-info handler</td></tr>
     <div class="example"><p><code>
       AddModuleInfo mod_deflate.c 'See &lt;a \<br />
       <span class="indent">
-      href="http://www.apache.org/docs-2.1/mod/mod_deflate.html"&gt;\<br />
-      http://www.apache.org/docs-2.1/mod/mod_deflate.html&lt;/a&gt;'
+        href="http://www.apache.org/docs-2.1/mod/mod_deflate.html"&gt;\<br />
+        http://www.apache.org/docs-2.1/mod/mod_deflate.html&lt;/a&gt;'
       </span>
     </code></p></div>