mod_info.xml revision 3d636d91428f2c0a74012c89a94ec7d5b40aa52e
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe<?xml version="1.0"?>
19d8729755d7f4d9503029a628dacbbdabcd2264wrowe<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<!-- $LastChangedRevision$ -->
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<!--
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe Licensed to the Apache Software Foundation (ASF) under one or more
167c53d624e82d105b1517e9599195a30ddb5de8stoddard contributor license agreements. See the NOTICE file distributed with
167c53d624e82d105b1517e9599195a30ddb5de8stoddard this work for additional information regarding copyright ownership.
167c53d624e82d105b1517e9599195a30ddb5de8stoddard The ASF licenses this file to You under the Apache License, Version 2.0
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe (the "License"); you may not use this file except in compliance with
167c53d624e82d105b1517e9599195a30ddb5de8stoddard the License. You may obtain a copy of the License at
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard http://www.apache.org/licenses/LICENSE-2.0
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe Unless required by applicable law or agreed to in writing, software
167c53d624e82d105b1517e9599195a30ddb5de8stoddard distributed under the License is distributed on an "AS IS" BASIS,
167c53d624e82d105b1517e9599195a30ddb5de8stoddard WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
167c53d624e82d105b1517e9599195a30ddb5de8stoddard See the License for the specific language governing permissions and
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe limitations under the License.
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe-->
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<modulesynopsis metafile="mod_info.xml.meta">
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
19d8729755d7f4d9503029a628dacbbdabcd2264wrowe<name>mod_info</name>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<description>Provides a comprehensive overview of the server
167c53d624e82d105b1517e9599195a30ddb5de8stoddardconfiguration</description>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<status>Extension</status>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<sourcefile>mod_info.c</sourcefile>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<identifier>info_module</identifier>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe<summary>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <p>To configure <module>mod_info</module>, add the following to your
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <code>httpd.conf</code> file.</p>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <example>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard &lt;Location /server-info&gt;<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <indent>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard SetHandler server-info<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard </indent>
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe &lt;/Location&gt;
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe </example>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <p>You may wish to use <module>mod_access</module> inside the
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe <directive type="section" module="core">Location</directive>
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe directive to limit access to your server configuration
1f2f357528d122de2c7886a073b4eee8766d5c95wrowe information:</p>
1f2f357528d122de2c7886a073b4eee8766d5c95wrowe
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <example>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard &lt;Location /server-info&gt;<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <indent>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard SetHandler server-info<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard Require host example.com<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard </indent>
5a58a10705b7b154b53294e0c0283d64eabdcb7fstoddard &lt;/Location&gt;
5a58a10705b7b154b53294e0c0283d64eabdcb7fstoddard </example>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe <p>Once configured, the server information is obtained by
167c53d624e82d105b1517e9599195a30ddb5de8stoddard accessing <code>http://your.host.example.com/server-info</code></p>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard</summary>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard<section id="security"><title>Security Issues</title>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <p>Once <module>mod_info</module> is loaded into the server, its
167c53d624e82d105b1517e9599195a30ddb5de8stoddard handler capability is available in <em>all</em> configuration
167c53d624e82d105b1517e9599195a30ddb5de8stoddard files, including per-directory files (<em>e.g.</em>,
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <code>.htaccess</code>). This may have security-related
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe ramifications for your site.</p>
9ec65cbae2f760e485a1c54df5b19853688d5c91wrowe
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <p>In particular, this module can leak sensitive information
167c53d624e82d105b1517e9599195a30ddb5de8stoddard from the configuration directives of other Apache modules such as
19d8729755d7f4d9503029a628dacbbdabcd2264wrowe system paths, usernames/passwords, database names, etc. Therefore,
19d8729755d7f4d9503029a628dacbbdabcd2264wrowe this module should <strong>only</strong> be
1f2f357528d122de2c7886a073b4eee8766d5c95wrowe used in a controlled environment and always with caution.</p>
1f2f357528d122de2c7886a073b4eee8766d5c95wrowe
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <p>You will probably want to use <module>mod_authz_host</module>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard to limit access to your server configuration information.</p>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <example><title>Access control</title>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard &lt;Location /server-info&gt;<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <indent>
5a58a10705b7b154b53294e0c0283d64eabdcb7fstoddard SetHandler server-info<br />
5a58a10705b7b154b53294e0c0283d64eabdcb7fstoddard Order allow,deny<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard # Allow access from server itself<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard Allow from 127.0.0.1<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard # Additionally, allow access from local workstation<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard Allow from 192.168.1.17<br />
167c53d624e82d105b1517e9599195a30ddb5de8stoddard </indent>
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe &lt;/Location&gt;
4e8732935d428b2a70151b178a95cbba5d3839f5wrowe </example>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard</section>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard
990e1969a428b8844e07aad088df41340cd009d4wrowe<section id="queries"><title>Selecting the information shown</title>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <p>By default, the server information includes a list of
4439ba95daf7b82794fe338726790e2dab89d119wrowe all enabled modules, and for each module, a description of
4439ba95daf7b82794fe338726790e2dab89d119wrowe the directives understood by that module, the hooks implemented
4439ba95daf7b82794fe338726790e2dab89d119wrowe by that module, and the relevant directives from the current
4439ba95daf7b82794fe338726790e2dab89d119wrowe configuration.</p>
4439ba95daf7b82794fe338726790e2dab89d119wrowe
4439ba95daf7b82794fe338726790e2dab89d119wrowe <p>Other views of the configuration information are available by
4439ba95daf7b82794fe338726790e2dab89d119wrowe appending a query to the <code>server-info</code> request. For
4439ba95daf7b82794fe338726790e2dab89d119wrowe example, <code>http://your.host.example.com/server-info?config</code>
4439ba95daf7b82794fe338726790e2dab89d119wrowe will show all configuration directives.</p>
4439ba95daf7b82794fe338726790e2dab89d119wrowe
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dl>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dt><code>?&lt;module-name&gt;</code></dt>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dd>Only information relevant to the named module</dd>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dt><code>?config</code></dt>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dd>Just the configuration directives, not sorted by module</dd>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dt><code>?hooks</code></dt>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dd>Only the list of Hooks each module is attached to</dd>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dt><code>?list</code></dt>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dd>Only a simple list of enabled modules</dd>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dt><code>?server</code></dt>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <dd>Only the basic server information</dd>
4439ba95daf7b82794fe338726790e2dab89d119wrowe </dl>
4439ba95daf7b82794fe338726790e2dab89d119wrowe</section>
4439ba95daf7b82794fe338726790e2dab89d119wrowe
4439ba95daf7b82794fe338726790e2dab89d119wrowe<section id="startup"><title>Dumping the configuration on startup</title>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <p>If the config define <code>-DDUMP_CONFIG</code> is set,
4439ba95daf7b82794fe338726790e2dab89d119wrowe <module>mod_info</module> will dump the pre-parsed configuration to
4439ba95daf7b82794fe338726790e2dab89d119wrowe <code>stdout</code> during server startup. This is roughly equivalent
4439ba95daf7b82794fe338726790e2dab89d119wrowe to the <code>?config</code> query.</p>
4439ba95daf7b82794fe338726790e2dab89d119wrowe</section>
4439ba95daf7b82794fe338726790e2dab89d119wrowe
4439ba95daf7b82794fe338726790e2dab89d119wrowe<section id="limitations"><title>Known Limitations</title>
4439ba95daf7b82794fe338726790e2dab89d119wrowe <p><module>mod_info</module> provides its information by reading the
4439ba95daf7b82794fe338726790e2dab89d119wrowe parsed configuration, rather than reading the original configuration
167c53d624e82d105b1517e9599195a30ddb5de8stoddard file. There are a few limitations as a result of the way the parsed
167c53d624e82d105b1517e9599195a30ddb5de8stoddard configuration tree is created:</p>
167c53d624e82d105b1517e9599195a30ddb5de8stoddard <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 module="core">&lt;IfModule&gt;</directive> and
<directive module="core">&lt;IfDefine&gt;</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 module="core">&lt;Directory&gt;</directive>
are listed normally, but <module>mod_info</module> cannot figure
out the line number for the closing
<directive module="core">&lt;/Directory&gt;</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>
<example>
AddModuleInfo mod_deflate.c 'See &lt;a \<br />
<indent>
href="http://www.apache.org/docs/&httpd.docs;/mod/mod_deflate.html"&gt;\<br />
http://www.apache.org/docs/&httpd.docs;/mod/mod_deflate.html&lt;/a&gt;'
</indent>
</example>
</usage>
</directivesynopsis>
</modulesynopsis>