a3128c1995310262648e575a9ff148d5741fd167Tinderbox User<?xml version="1.0"?>

bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<modulesynopsis metafile="mod_dir.xml.meta">

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<name>mod_dir</name>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<description>Provides for "trailing slash" redirects and

12178c86525332bb0ab66155feb61fbf32eca6acEvan Hunt serving directory index files</description>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<status>Base</status>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<sourcefile>mod_dir.c</sourcefile>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<identifier>dir_module</identifier>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉<summary>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <p>The index of a directory can come from one of two sources:</p>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <ul>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <li>A file written by the user, typically called

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <code>index.html</code>. The <directive module="mod_dir"

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt >DirectoryIndex</directive> directive sets the

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt name of this file. This is controlled by

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <module>mod_dir</module>.</li>

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉 <li>Otherwise, a listing generated by the server. This is

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt provided by <module>mod_autoindex</module>.</li>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt </ul>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <p>The two functions are separated so that you can completely

71ba75c604df3604673232828a68bb28c420e698Mark Andrews remove (or replace) automatic index generation should you want

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt to.</p>

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <p>A "trailing slash" redirect is issued when the server

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt receives a request for a URL

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code>http://servername/foo/dirname</code> where

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code>dirname</code> is a directory. Directories require a

71ba75c604df3604673232828a68bb28c420e698Mark Andrews trailing slash, so <module>mod_dir</module> issues a redirect to

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code>http://servername/foo/dirname/</code>.</p>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt</summary>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<directivesynopsis>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<name>DirectoryIndex</name>

31a641171249300e29a02a6a01aa32c2af875cadEvan Hunt<description>List of resources to look for when the client requests

31a641171249300e29a02a6a01aa32c2af875cadEvan Hunta directory</description>

71ba75c604df3604673232828a68bb28c420e698Mark Andrews<syntax>DirectoryIndex

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉 disabled | <var>local-url</var> [<var>local-url</var>] ...</syntax>

71ba75c604df3604673232828a68bb28c420e698Mark Andrews<default>DirectoryIndex index.html</default>

71ba75c604df3604673232828a68bb28c420e698Mark Andrews<contextlist><context>server config</context><context>virtual host</context>

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉<context>directory</context><context>.htaccess</context></contextlist>

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉<override>Indexes</override>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt<usage>

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉 <p>The <directive>DirectoryIndex</directive> directive sets the

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉 list of resources to look for, when the client requests an index

a27fe4c990f96bd792f2a07ca4d38c78d5b9df2cTatuya JINMEI 神明達哉 of the directory by specifying a / at the end of the directory

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt name. <var>Local-url</var> is the (%-encoded) URL of a document on

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt the server relative to the requested directory; it is usually the

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt name of a file in the directory. Several URLs may be given, in

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt which case the server will return the first one that it finds. If

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt none of the resources exist and the <code>Indexes</code> option is

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt set, the server will generate its own listing of the

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt directory.</p>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <example><title>Example</title>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <highlight language="config">

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt DirectoryIndex index.html

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt </highlight>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt </example>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <p>then a request for <code>http://example.com/docs/</code> would

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt return <code>http://example.com/docs/index.html</code> if it

620508359f9bb21cd5df7fdf2e6f4677903fb539Mark Andrews exists, or would list the directory if it did not.</p>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <p>Note that the documents do not need to be relative to the

97725b410a7a65cd300028996b01960393532822Mark Andrews directory;</p>

97725b410a7a65cd300028996b01960393532822Mark Andrews

71ba75c604df3604673232828a68bb28c420e698Mark Andrews <highlight language="config">

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt DirectoryIndex index.html index.txt /cgi-bin/index.pl

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt </highlight>

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt

8c5482b3ea502276bff2ce66b3de7265c81e8b37Evan Hunt <p>would cause the CGI script <code>/cgi-bin/index.pl</code> to be

0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt executed if neither <code>index.html</code> or <code>index.txt</code>

71ba75c604df3604673232828a68bb28c420e698Mark Andrews existed in a directory.</p>

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt <p>A single argument of "disabled" prevents <module>mod_dir</module> from

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt searching for an index. An argument of "disabled" will be interpreted

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt literally if it has any arguments before or after it, even if they are "disabled"

ca42dcc0686fefd3db202edab80e5adb09d6add5Evan Hunt as well.</p>

<p><strong>Note:</strong> Multiple <directive>DirectoryIndex</directive>

directives within the <a href="/sections.html"><em>same context</em></a> will add

to the list of resources to look for rather than replace:

</p>

<highlight language="config">

# Example A: Set index.html as an index page, then add index.php to that list as well.

&lt;Directory "/foo"&gt;

DirectoryIndex index.html

DirectoryIndex index.php

&lt;/Directory&gt;

# Example B: This is identical to example A, except it's done with a single directive.

&lt;Directory "/foo"&gt;

DirectoryIndex index.html index.php

&lt;/Directory&gt;

# Example C: To replace the list, you must explicitly reset it first:

# In this example, only index.php will remain as an index resource.

&lt;Directory "/foo"&gt;

DirectoryIndex index.html

DirectoryIndex disabled

DirectoryIndex index.php

&lt;/Directory&gt;

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DirectoryIndexRedirect</name>

<description>Configures an external redirect for directory indexes.

</description>

<syntax>DirectoryIndexRedirect on | off | permanent | temp | seeother |

<var>3xx-code</var>

</syntax>

<default>DirectoryIndexRedirect off</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>Indexes</override>

<compatibility>Available in version 2.3.14 and later</compatibility>

<usage>

<p>By default, the <directive>DirectoryIndex</directive> is selected

and returned transparently to the client. <directive

>DirectoryIndexRedirect</directive> causes an external redirect

to instead be issued.</p>

<p>The argument can be:</p>

<ul>

<li><code>on</code>: issues a 302 redirection to the index resource.</li>

<li><code>off</code>: does not issue a redirection. This is the legacy behaviour of mod_dir.</li>

<li><code>permanent</code>: issues a 301 (permanent) redirection to the index resource.</li>

<li><code>temp</code>: this has the same effect as <code>on</code></li>

<li><code>seeother</code>: issues a 303 redirection (also known as "See Other") to the index resource.</li>

<li><var>3xx-code</var>: issues a redirection marked by the chosen 3xx code.</li>

</ul>

<example><title>Example</title>

<highlight language="config">

DirectoryIndexRedirect on

</highlight>

</example>

<p>A request for <code>http://example.com/docs/</code> would

return a temporary redirect to <code

>http://example.com/docs/index.html</code>

if it exists.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DirectorySlash</name>

<description>Toggle trailing slash redirects on or off</description>

<syntax>DirectorySlash On|Off</syntax>

<default>DirectorySlash On</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>DirectorySlash</directive> directive determines whether

<module>mod_dir</module> should fixup URLs pointing to a directory or

not.</p>

<p>Typically if a user requests a resource without a trailing slash, which

points to a directory, <module>mod_dir</module> redirects him to the same

resource, but <em>with</em> trailing slash for some good reasons:</p>

<ul>

<li>The user is finally requesting the canonical URL of the resource</li>

<li><module>mod_autoindex</module> works correctly. Since it doesn't emit

the path in the link, it would point to the wrong path.</li>

<li><directive module="mod_dir">DirectoryIndex</directive> will be evaluated

<em>only</em> for directories requested with trailing slash.</li>

<li>Relative URL references inside html pages will work correctly.</li>

</ul>

<p>If you don't want this effect <em>and</em> the reasons above don't

apply to you, you can turn off the redirect as shown below. However,

be aware that there are possible security implications to doing

this.</p>

<highlight language="config">

# see security warning below!

&lt;Location "/some/path"&gt;

DirectorySlash Off

SetHandler some-handler

&lt;/Location&gt;

</highlight>

<note type="warning"><title>Security Warning</title>

<p>Turning off the trailing slash redirect may result in an information

disclosure. Consider a situation where <module>mod_autoindex</module> is

active (<code>Options +Indexes</code>) and <directive module="mod_dir"

>DirectoryIndex</directive> is set to a valid resource (say,

<code>index.html</code>) and there's no other special handler defined for

that URL. In this case a request with a trailing slash would show the

<code>index.html</code> file. <strong>But a request without trailing slash

would list the directory contents</strong>.</p>

</note>

<p>Also note that some browsers may erroneously change POST requests into GET

(thus discarding POST data) when a redirect is issued.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>FallbackResource</name>

<description>Define a default URL for requests that don't map to a file</description>

<syntax>FallbackResource disabled | <var>local-url</var></syntax>

<default>disabled - httpd will return 404 (Not Found)</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>Indexes</override>

<compatibility>The <code>disabled</code> argument is available in version 2.4.4 and

later</compatibility>

<usage>

<p>Use this to set a handler for any URL that doesn't map to anything

in your filesystem, and would otherwise return HTTP 404 (Not Found).

For example</p>

<highlight language="config">

FallbackResource /not-404.php

</highlight>

<p>will cause requests for non-existent files to be handled by

<code>not-404.php</code>, while requests for files that exist

are unaffected.</p>

<p>It is frequently desirable to have a single file or resource

handle all requests to a particular directory, except those requests

that correspond to an existing file or script. This is often

referred to as a 'front controller.'</p>

<p>In earlier versions of httpd, this effect typically required

<module>mod_rewrite</module>, and the use of the <code>-f</code> and

<code>-d</code> tests for file and directory existence. This now

requires only one line of configuration.</p>

<highlight language="config">

FallbackResource /index.php

</highlight>

<p>Existing files, such as images, css files, and so on, will be

served normally.</p>

<p>Use the <code>disabled</code> argument to disable that feature

if inheritance from a parent directory is not desired.</p>

<p>In a sub-URI, such as <em>http://example.com/blog/</em> this

<em>sub-URI</em> has to be supplied as <var>local-url</var>:</p>

<highlight language="config">

&lt;Directory "/web/example.com/htdocs/blog"&gt;

FallbackResource /blog/index.php

&lt;/Directory&gt;

&lt;Directory "/web/example.com/htdocs/blog/images"&gt;

FallbackResource disabled

&lt;/Directory&gt;

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DirectoryCheckHandler</name>

<description>Toggle how this module responds when another handler is configured</description>

<syntax>DirectoryCheckHandler On|Off</syntax>

<default>DirectoryCheckHandler Off</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>Indexes</override>

<compatibility>Available in 2.4.8 and later. Releases prior to 2.4 implicitly

act as if "DirectoryCheckHandler ON" was specified.</compatibility>

<usage>

<p>The <directive>DirectoryCheckHandler</directive> directive determines

whether <module>mod_dir</module> should check for directory indexes or

add trailing slashes when some other handler has been configured for

the current URL. Handlers can be set by directives such as

<directive module="core">SetHandler</directive> or by other modules at

runtime. </p>

<p> In releases prior to 2.4, this module did not take any action if any

other handler was configured for a URL. This allows directory indexes to

be served even when a <directive>SetHandler</directive> directive is

specified for an entire directory, but it can also result in some conflicts

with other modules.</p>

</usage>

</directivesynopsis>

</modulesynopsis>