6a7d71eb77725eb1b1091a94289696ab07946c7bslive<?xml version="1.0"?>

d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd

d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd

7db9f691a00ead175b03335457ca296a33ddf31bnd<modulesynopsis metafile="mod_dir.xml.meta">

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<name>mod_dir</name>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<description>Provides for "trailing slash" redirects and

d24d4c5159bcb11c25bb294926cfe7105c789ea9slive serving directory index files</description>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<status>Base</status>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<sourcefile>mod_dir.c</sourcefile>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<identifier>dir_module</identifier>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<summary>

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

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <ul>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <li>A file written by the user, typically called

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <code>index.html</code>. The <directive module="mod_dir"

6a7d71eb77725eb1b1091a94289696ab07946c7bslive >DirectoryIndex</directive> directive sets the

6a7d71eb77725eb1b1091a94289696ab07946c7bslive name of this file. This is controlled by

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <module>mod_dir</module>.</li>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <li>Otherwise, a listing generated by the server. This is

6a7d71eb77725eb1b1091a94289696ab07946c7bslive provided by <module>mod_autoindex</module>.</li>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive </ul>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <p>The two functions are separated so that you can completely

6a7d71eb77725eb1b1091a94289696ab07946c7bslive remove (or replace) automatic index generation should you want

6a7d71eb77725eb1b1091a94289696ab07946c7bslive to.</p>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <p>A "trailing slash" redirect is issued when the server

6a7d71eb77725eb1b1091a94289696ab07946c7bslive receives a request for a URL

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <code>http://servername/foo/dirname</code> where

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <code>dirname</code> is a directory. Directories require a

6a7d71eb77725eb1b1091a94289696ab07946c7bslive trailing slash, so <module>mod_dir</module> issues a redirect to

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <code>http://servername/foo/dirname/</code>.</p>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive</summary>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<directivesynopsis>

d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<name>DirectoryIndex</name>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<description>List of resources to look for when the client requests

6a7d71eb77725eb1b1091a94289696ab07946c7bslivea directory</description>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<syntax>DirectoryIndex

b6d2c204c150843e48f6787c1090ae75b718896ecovener disabled | <var>local-url</var> [<var>local-url</var>] ...</syntax>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<default>DirectoryIndex index.html</default>

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

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

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<override>Indexes</override>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive<usage>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <p>The <directive>DirectoryIndex</directive> directive sets the

6a7d71eb77725eb1b1091a94289696ab07946c7bslive list of resources to look for, when the client requests an index

1887c0b8ceab2c8d64a1e5b3aa512e77b86b49fayoshiki of the directory by specifying a / at the end of the directory

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

6a7d71eb77725eb1b1091a94289696ab07946c7bslive the server relative to the requested directory; it is usually the

6a7d71eb77725eb1b1091a94289696ab07946c7bslive name of a file in the directory. Several URLs may be given, in

6a7d71eb77725eb1b1091a94289696ab07946c7bslive which case the server will return the first one that it finds. If

6a7d71eb77725eb1b1091a94289696ab07946c7bslive none of the resources exist and the <code>Indexes</code> option is

6a7d71eb77725eb1b1091a94289696ab07946c7bslive set, the server will generate its own listing of the

6a7d71eb77725eb1b1091a94289696ab07946c7bslive directory.</p>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd <example><title>Example</title>

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd <highlight language="config">

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd DirectoryIndex index.html

6a7d71eb77725eb1b1091a94289696ab07946c7bslive </highlight>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive </example>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

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

6a7d71eb77725eb1b1091a94289696ab07946c7bslive return <code>http://example.com/docs/index.html</code> if it

6a7d71eb77725eb1b1091a94289696ab07946c7bslive exists, or would list the directory if it did not.</p>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

6a7d71eb77725eb1b1091a94289696ab07946c7bslive <p>Note that the documents do not need to be relative to the

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd directory;</p>

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd <highlight language="config">

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd DirectoryIndex index.html index.txt /cgi-bin/index.pl

6a7d71eb77725eb1b1091a94289696ab07946c7bslive </highlight>

f5cbf3a7818c08d2f19c04fdf4f47257eea7d3c6nd

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

63de18ba5e922ffaab500317d7d1d0ad6b27b7e2covener executed if neither <code>index.html</code> or <code>index.txt</code>

b6d2c204c150843e48f6787c1090ae75b718896ecovener existed in a directory.</p>

b6d2c204c150843e48f6787c1090ae75b718896ecovener

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

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

63de18ba5e922ffaab500317d7d1d0ad6b27b7e2covener literally if it has any arguments before or after it, even if they are "disabled"

6a7d71eb77725eb1b1091a94289696ab07946c7bslive as well.</p>

6a7d71eb77725eb1b1091a94289696ab07946c7bslive

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

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

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd </p>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd <highlight language="config">

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd&lt;Directory /foo&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex index.html

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex index.php

a7749772d764a29ed2376733f951c4c9a28b2121nd&lt;/Directory&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd&lt;Directory /foo&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex index.html index.php

3b2d0dc9701458b42e573190ffe7344315d7bd31nd&lt;/Directory&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

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

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

90361ddfb3a8abaa0f8fb1729732062c78d8dc50niq&lt;Directory /foo&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex index.html

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex disabled

3b2d0dc9701458b42e573190ffe7344315d7bd31nd DirectoryIndex index.php

3b2d0dc9701458b42e573190ffe7344315d7bd31nd&lt;/Directory&gt;

3b2d0dc9701458b42e573190ffe7344315d7bd31nd </highlight>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

3b2d0dc9701458b42e573190ffe7344315d7bd31nd</usage>

571d9bf2dccc0cb3d944fd06a96218ab49899513nd</directivesynopsis>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<directivesynopsis>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<name>DirectoryIndexRedirect</name>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<description>Configures an external redirect for directory indexes.

3b2d0dc9701458b42e573190ffe7344315d7bd31nd</description>

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<var>3xx-code</var>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd</syntax>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<default>DirectoryIndexRedirect off</default>

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

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<override>Indexes</override>

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<usage>

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd and returned transparently to the client. <directive

3b2d0dc9701458b42e573190ffe7344315d7bd31nd >DirectoryIndexRedirect</directive> causes an external redirect

3b2d0dc9701458b42e573190ffe7344315d7bd31nd to instead be issued.</p>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd

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

3b2d0dc9701458b42e573190ffe7344315d7bd31nd <ul>

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

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

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

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

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

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

a3de986b8f062c83ceda21a7389787712214b02cniq </ul>

a3de986b8f062c83ceda21a7389787712214b02cniq

a3de986b8f062c83ceda21a7389787712214b02cniq

a3de986b8f062c83ceda21a7389787712214b02cniq <example><title>Example</title>

a3de986b8f062c83ceda21a7389787712214b02cniq <highlight language="config">

a3de986b8f062c83ceda21a7389787712214b02cniq DirectoryIndexRedirect on

a3de986b8f062c83ceda21a7389787712214b02cniq </highlight>

a3de986b8f062c83ceda21a7389787712214b02cniq </example>

a3de986b8f062c83ceda21a7389787712214b02cniq

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

a3de986b8f062c83ceda21a7389787712214b02cniq return a temporary redirect to <code

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

a3de986b8f062c83ceda21a7389787712214b02cniq if it exists.</p>

a3de986b8f062c83ceda21a7389787712214b02cniq

a3de986b8f062c83ceda21a7389787712214b02cniq</usage>

a3de986b8f062c83ceda21a7389787712214b02cniq</directivesynopsis>

a3de986b8f062c83ceda21a7389787712214b02cniq

a3de986b8f062c83ceda21a7389787712214b02cniq

a3de986b8f062c83ceda21a7389787712214b02cniq<directivesynopsis>

3b2d0dc9701458b42e573190ffe7344315d7bd31nd<name>DirectorySlash</name>

7db9f691a00ead175b03335457ca296a33ddf31bnd<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>

<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>DirectorySlash 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 "DirectorySlash Off" 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,

such as <module>mod_rewrite</module> during per-directory substitutions.

</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 modules such as <directive>mod_rewrite</directive>.</p>

</usage>

</directivesynopsis>

</modulesynopsis>