mod_dir.xml revision 3b2d0dc9701458b42e573190ffe7344315d7bd31
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder<!-- $Revision: 1.10 $ -->
61328b63a7bc34f56018344d4610f7cc2f848577Till Mossakowski Copyright 2002-2004 The Apache Software Foundation
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder Licensed under the Apache License, Version 2.0 (the "License");
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder you may not use this file except in compliance with the License.
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder You may obtain a copy of the License at
21e62e01f2c46f78112a9a0c5f3673390f244f0fChristian Maeder Unless required by applicable law or agreed to in writing, software
21e62e01f2c46f78112a9a0c5f3673390f244f0fChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
21e62e01f2c46f78112a9a0c5f3673390f244f0fChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21e62e01f2c46f78112a9a0c5f3673390f244f0fChristian Maeder See the License for the specific language governing permissions and
21e62e01f2c46f78112a9a0c5f3673390f244f0fChristian Maeder limitations under the License.
333dc30374fd35849cb12145b97c9ee7d5c815dbChristian Maeder<modulesynopsis metafile="mod_dir.xml.meta">
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<description>Provides for "trailing slash" redirects and
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder serving directory index files</description>
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder <p>The index of a directory can come from one of two sources:</p>
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder <li>A file written by the user, typically called
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder <code>index.html</code>. The <directive module="mod_dir"
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder >DirectoryIndex</directive> directive sets the
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder name of this file. This is controlled by
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder <li>Otherwise, a listing generated by the server. This is
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder provided by <module>mod_autoindex</module>.</li>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <p>The two functions are separated so that you can completely
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder remove (or replace) automatic index generation should you want
e899b993b4f642217274fda6f462fe1318ae3626Christian Maeder <p>A "trailing slash" redirect is issued when the server
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder receives a request for a URL
04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder <code>http://servername/foo/dirname</code> where
04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder <code>dirname</code> is a directory. Directories require a
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder trailing slash, so <module>mod_dir</module> issues a redirect to
2afae0880da7ca73c9376fd4d653ab19833fe858Christian Maeder <code>http://servername/foo/dirname/</code>.</p>
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder<directivesynopsis>
f69416aa2b00518744d25a93aefbdb778f399787Cui Jian<description>List of resources to look for when the client requests
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maedera directory</description>
04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder<syntax>DirectoryIndex
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder <var>local-url</var> [<var>local-url</var>] ...</syntax>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<default>DirectoryIndex index.html</default>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<contextlist><context>server config</context><context>virtual host</context>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<context>directory</context><context>.htaccess</context></contextlist>
04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder <p>The <directive>DirectoryIndex</directive> directive sets the
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder list of resources to look for, when the client requests an index
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder of the directory by specifying a / at the end of the directory
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder name. <var>Local-url</var> is the (%-encoded) URL of a document on
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder the server relative to the requested directory; it is usually the
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder name of a file in the directory. Several URLs may be given, in
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder which case the server will return the first one that it finds. If
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder none of the resources exist and the <code>Indexes</code> option is
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder set, the server will generate its own listing of the
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder directory.</p>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <p>then a request for <code>http://myserver/docs/</code> would
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder return <code>http://myserver/docs/index.html</code> if it
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder exists, or would list the directory if it did not.</p>
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder <p>Note that the documents do not need to be relative to the
333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder directory;</p>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder DirectoryIndex index.html index.txt /cgi-bin/index.pl
e899b993b4f642217274fda6f462fe1318ae3626Christian Maeder <p>would cause the CGI script <code>/cgi-bin/index.pl</code> to be
e899b993b4f642217274fda6f462fe1318ae3626Christian Maeder executed if neither <code>index.html</code> or <code>index.txt</code>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder existed in a directory.</p>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder</directivesynopsis>
2afae0880da7ca73c9376fd4d653ab19833fe858Christian Maeder<directivesynopsis>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<description>Toggle trailing slash redirects on or off</description>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<contextlist><context>server config</context><context>virtual host</context>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder<context>directory</context><context>.htaccess</context></contextlist>
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder<compatibility>Available in version 2.1 and later</compatibility>
e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder <p>The <directive>DirectorySlash</directive> directive determines, whether
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <module>mod_dir</module> should fixup URLs pointing to a directory or
e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder <p>Typically if a user requests a resource without a trailing slash, which
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder points to a directory, <module>mod_dir</module> redirects him to the same
e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder ressource, but <em>with</em> trailing slash for some good reasons:</p>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <li>The user is finally requesting the canonical URL of the resource</li>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <li><module>mod_autoindex</module> works correctly. Since it doesn't emit
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder the path in the link, it would point to the wrong path.</li>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <li><directive module="mod_dir">DirectoryIndex</directive> will be evaluated
5c9cb88c054c2f3439f6bff063eb39091e0094d3Christian Maeder <em>only</em> for directories requested with trailing slash.</li>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <p>Well, if you don't want this effect <em>and</em> the reasons above don't
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder apply to you, you can turn off the redirect with:</p>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder # see security warning below!<br />
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder DirectorySlash Off<br />
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder SetHandler some-handler<br />
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski </Location>
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <note type="warning"><title>Security Warning</title>
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder <p>Turning off the trailing slash redirect may result in an information
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski disclosure. Consider a situation where <module>mod_autoindex</module> is
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski active (<code>Options +Indexes</code>) and <directive module="mod_dir"
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski >DirectoryIndex</directive> is set to a valid resource (say,
120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <code>index.html</code>) and there's no other special handler defined for
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski that URL. In this case a request with a trailing slash would show the
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder <code>index.html</code> file. <strong>But a request without trailing slash
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski would list the directory contents</strong>.</p>
57d320fc4d0fe1a1c08cfe6cd9ebec09b86c2cbfTill Mossakowski</directivesynopsis>
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder</modulesynopsis>