| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_info.xml.meta"> |
| |
| <name>mod_info</name> |
| <description>Provides a comprehensive overview of the server |
| configuration</description> |
| <status>Extension</status> |
| <sourcefile>mod_info.c</sourcefile> |
| <identifier>info_module</identifier> |
| |
| <summary> |
| <p>To configure <module>mod_info</module>, add the following to your |
| <code>httpd.conf</code> file.</p> |
| |
| <highlight language="config"> |
| <Location "/server-info"> |
| SetHandler server-info |
| </Location> |
| </highlight> |
| |
| <p>You may wish to use <module>mod_authz_host</module> inside the |
| <directive type="section" module="core">Location</directive> |
| directive to limit access to your server configuration |
| information:</p> |
| |
| <highlight language="config"> |
| <Location "/server-info"> |
| SetHandler server-info |
| Require host example.com |
| </Location> |
| </highlight> |
| |
| <p>Once configured, the server information is obtained by |
| accessing <code>http://your.host.example.com/server-info</code></p> |
| </summary> |
| |
| <section id="security"><title>Security Issues</title> |
| <p>Once <module>mod_info</module> 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 <module>mod_authz_host</module> |
| to limit access to your server configuration information.</p> |
| |
| <example><title>Access control</title> |
| <highlight language="config"> |
| <Location "/server-info"> |
| SetHandler server-info |
| # Allow access from server itself |
| Require ip 127.0.0.1 |
| |
| # Additionally, allow access from local workstation |
| Require ip 192.168.1.17 |
| </Location> |
| </highlight> |
| </example> |
| </section> |
| |
| <section id="queries"><title>Selecting the information shown</title> |
| <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.example.com/server-info?config</code> |
| will show all configuration directives.</p> |
| |
| <dl> |
| <dt><code>?<module-name></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>?hooks</code></dt> |
| <dd>Only the list of Hooks each module is attached to</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> |
| <dt><code>?providers</code></dt> |
| <dd>List the providers that are available on your server</dd> |
| </dl> |
| </section> |
| |
| <section id="startup"><title>Dumping the configuration on startup</title> |
| <p>If the config define <code>-DDUMP_CONFIG</code> is set, |
| <module>mod_info</module> will dump the pre-parsed configuration to |
| <code>stdout</code> during server startup.</p> |
| |
| <highlight language="sh"> |
| httpd -DDUMP_CONFIG -k start |
| </highlight> |
| |
| <p>Pre-parsed means that directives like |
| <directive type="section" module="core">IfDefine</directive> and |
| <directive type="section" module="core">IfModule</directive> are |
| evaluated and environment variables are replaced. However it does |
| not represent the final state of the configuration. In particular, |
| it does not represent the merging or overriding that may happen |
| for repeated directives.</p> |
| |
| <p>This is roughly equivalent to the <code>?config</code> query.</p> |
| </section> |
| |
| <section id="limitations"><title>Known Limitations</title> |
| <p><module>mod_info</module> 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 |
| <directive module="core">ServerRoot</directive>, |
| <directive module="mod_so">LoadModule</directive>, and |
| <directive module="mod_so">LoadFile</directive>.</li> |
| <li>Directives which control the configuration file itself, such as |
| <directive module="core">Include</directive>, |
| <directive type="section" module="core">IfModule</directive> and |
| <directive type="section" module="core">IfDefine</directive> 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 |
| <directive type="section" module="core">Directory</directive> |
| are listed normally, but <module>mod_info</module> cannot figure |
| out the line number for the closing |
| <directive type="section" module="core" name="Directory">/Directory</directive>.</li> |
| <li>Directives generated by third party modules such as <a href="http://perl.apache.org">mod_perl</a> |
| might not be listed.</li> |
| </ul> |
| </section> |
| |
| <directivesynopsis> |
| <name>AddModuleInfo</name> |
| <description>Adds additional information to the module |
| information displayed by the server-info handler</description> |
| <syntax>AddModuleInfo <var>module-name</var> <var>string</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>This allows the content of <var>string</var> to be shown as |
| HTML interpreted, <strong>Additional Information</strong> for |
| the module <var>module-name</var>. Example:</p> |
| |
| <highlight language="config"> |
| AddModuleInfo mod_deflate.c 'See <a \ |
| href="http://httpd.apache.org/docs/&httpd.docs;/mod/mod_deflate.html">\ |
| http://httpd.apache.org/docs/&httpd.docs;/mod/mod_deflate.html</a>' |
| </highlight> |
| </usage> |
| |
| </directivesynopsis> |
| </modulesynopsis> |