granicus.if.org Git - apache/blob - docs/manual/mod/mod_info.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_info.xml.meta">
  24
  25 <name>mod_info</name>
  26 <description>Provides a comprehensive overview of the server
  27 configuration</description>
  28 <status>Extension</status>
  29 <sourcefile>mod_info.c</sourcefile>
  30 <identifier>info_module</identifier>
  31
  32 <summary>
  33     <p>To configure <module>mod_info</module>, add the following to your
  34     <code>httpd.conf</code> file.</p>
  35
  36     <highlight language="config">
  37 &lt;Location /server-info&gt;
  38     SetHandler server-info
  39 &lt;/Location&gt;
  40     </highlight>
  41
  42     <p>You may wish to use <module>mod_authz_host</module> inside the
  43     <directive type="section" module="core">Location</directive>
  44     directive to limit access to your server configuration
  45     information:</p>
  46
  47     <highlight language="config">
  48 &lt;Location /server-info&gt;
  49     SetHandler server-info
  50     Require host example.com
  51 &lt;/Location&gt;
  52     </highlight>
  53
  54     <p>Once configured, the server information is obtained by
  55     accessing <code>http://your.host.example.com/server-info</code></p>
  56 </summary>
  57
  58 <section id="security"><title>Security Issues</title>
  59     <p>Once <module>mod_info</module> is loaded into the server, its
  60     handler capability is available in <em>all</em> configuration
  61     files, including per-directory files (<em>e.g.</em>,
  62     <code>.htaccess</code>). This may have security-related
  63     ramifications for your site.</p>
  64
  65     <p>In particular, this module can leak sensitive information
  66     from the configuration directives of other Apache modules such as
  67     system paths, usernames/passwords, database names, etc. Therefore,
  68     this module should <strong>only</strong> be
  69     used in a controlled environment and always with caution.</p>
  70
  71     <p>You will probably want to use <module>mod_authz_host</module>
  72     to limit access to your server configuration information.</p>
  73
  74     <example><title>Access control</title>
  75     <highlight language="config">
  76 &lt;Location /server-info&gt;
  77     SetHandler server-info
  78     Order allow,deny
  79     # Allow access from server itself
  80     Allow from 127.0.0.1
  81     # Additionally, allow access from local workstation
  82     Allow from 192.168.1.17
  83 &lt;/Location&gt;
  84       </highlight>
  85     </example>
  86 </section>
  87
  88 <section id="queries"><title>Selecting the information shown</title>
  89     <p>By default, the server information includes a list of
  90     all enabled modules, and for each module, a description of
  91     the directives understood by that module, the hooks implemented
  92     by that module, and the relevant directives from the current
  93     configuration.</p>
  94
  95     <p>Other views of the configuration information are available by
  96     appending a query to the <code>server-info</code> request. For
  97     example, <code>http://your.host.example.com/server-info?config</code>
  98     will show all configuration directives.</p>
  99
 100     <dl>
 101         <dt><code>?&lt;module-name&gt;</code></dt>
 102             <dd>Only information relevant to the named module</dd>
 103         <dt><code>?config</code></dt>
 104             <dd>Just the configuration directives, not sorted by module</dd>
 105         <dt><code>?hooks</code></dt>
 106             <dd>Only the list of Hooks each module is attached to</dd>
 107         <dt><code>?list</code></dt>
 108             <dd>Only a simple list of enabled modules</dd>
 109         <dt><code>?server</code></dt>
 110             <dd>Only the basic server information</dd>
 111     </dl>
 112 </section>
 113
 114 <section id="startup"><title>Dumping the configuration on startup</title>
 115     <p>If the config define <code>-DDUMP_CONFIG</code> is set,
 116     <module>mod_info</module> will dump the pre-parsed configuration to
 117     <code>stdout</code> during server startup. Pre-parsed means that
 118     directives like
 119     <directive type="section" module="core">IfDefine</directive> and
 120     <directive type="section" module="core">IfModule</directive> are
 121     evaluated and environment varialbles are replaced. However it does
 122     not represent the final state of the configuration. In particular,
 123     it does not represent the merging or overriding that may happen
 124     for repeated directives.</p>
 125
 126     <p>This is roughly equivalent to the <code>?config</code> query.</p>
 127 </section>
 128
 129 <section id="limitations"><title>Known Limitations</title>
 130     <p><module>mod_info</module> provides its information by reading the
 131     parsed configuration, rather than reading the original configuration
 132     file. There are a few limitations as a result of the way the parsed
 133     configuration tree is created:</p>
 134     <ul>
 135       <li>Directives which are executed immediately rather than being
 136           stored in the parsed configuration are not listed. These include
 137           <directive module="core">ServerRoot</directive>,
 138           <directive module="mod_so">LoadModule</directive>, and
 139           <directive module="mod_so">LoadFile</directive>.</li>
 140       <li>Directives which control the configuration file itself, such as
 141           <directive module="core">Include</directive>,
 142           <directive module="core">&lt;IfModule&gt;</directive> and
 143           <directive module="core">&lt;IfDefine&gt;</directive> are not
 144           listed, but the included configuration directives are.</li>
 145       <li>Comments are not listed. (This may be considered a feature.)</li>
 146       <li>Configuration directives from <code>.htaccess</code> files are
 147           not listed (since they do not form part of the permanent server
 148           configuration).</li>
 149       <li>Container directives such as
 150           <directive module="core">&lt;Directory&gt;</directive>
 151           are listed normally, but <module>mod_info</module> cannot figure
 152           out the line number for the closing
 153           <directive module="core">&lt;/Directory&gt;</directive>.</li>
 154       <li>Directives generated by third party modules such as <a href="http://perl.apache.org">mod_perl</a>
 155           might not be listed.</li>
 156     </ul>
 157 </section>
 158
 159 <directivesynopsis>
 160 <name>AddModuleInfo</name>
 161 <description>Adds additional information to the module
 162 information displayed by the server-info handler</description>
 163 <syntax>AddModuleInfo <var>module-name</var> <var>string</var></syntax>
 164 <contextlist><context>server config</context><context>virtual host</context>
 165 </contextlist>
 166
 167 <usage>
 168     <p>This allows the content of <var>string</var> to be shown as
 169     HTML interpreted, <strong>Additional Information</strong> for
 170     the module <var>module-name</var>. Example:</p>
 171
 172     <highlight language="config">
 173 AddModuleInfo mod_deflate.c 'See &lt;a \
 174     href="http://httpd.apache.org/docs/&httpd.docs;/mod/mod_deflate.html"&gt;\
 175     http://httpd.apache.org/docs/&httpd.docs;/mod/mod_deflate.html&lt;/a&gt;'
 176     </highlight>
 177 </usage>
 178
 179 </directivesynopsis>
 180 </modulesynopsis>