<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed 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
+ 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
</ul>
<p>The two functions are separated so that you can completely
remove (or replace) automatic index generation should you want
- to.</p>
+ to.</p>
<p>A "trailing slash" redirect is issued when the server
receives a request for a URL
<description>List of resources to look for when the client requests
a directory</description>
<syntax>DirectoryIndex
- <var>local-url</var> [<var>local-url</var>] ...</syntax>
+ disabled | <var>local-url</var> [<var>local-url</var>] ...</syntax>
<default>DirectoryIndex index.html</default>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
directory.</p>
<example><title>Example</title>
+ <highlight language="config">
DirectoryIndex index.html
+ </highlight>
</example>
- <p>then a request for <code>http://myserver/docs/</code> would
- return <code>http://myserver/docs/index.html</code> if it
+ <p>then a request for <code>http://example.com/docs/</code> would
+ return <code>http://example.com/docs/index.html</code> if it
exists, or would list the directory if it did not.</p>
<p>Note that the documents do not need to be relative to the
directory;</p>
- <example>
+ <highlight language="config">
DirectoryIndex index.html index.txt /cgi-bin/index.pl
- </example>
+ </highlight>
<p>would cause the CGI script <code>/cgi-bin/index.pl</code> to be
executed if neither <code>index.html</code> or <code>index.txt</code>
existed in a directory.</p>
+
+ <p>A single argument of "disabled" prevents <module>mod_dir</module> from
+ searching for an index. An argument of "disabled" will be interpreted
+ literally if it has any arguments before or after it, even if they are "disabled"
+ 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.
+<Directory "/foo">
+ DirectoryIndex index.html
+ DirectoryIndex index.php
+</Directory>
+
+# Example B: This is identical to example A, except it's done with a single directive.
+<Directory "/foo">
+ DirectoryIndex index.html index.php
+</Directory>
+
+# Example C: To replace the list, you must explicitly reset it first:
+# In this example, only index.php will remain as an index resource.
+<Directory "/foo">
+ DirectoryIndex index.html
+ DirectoryIndex disabled
+ DirectoryIndex index.php
+</Directory>
+ </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!
+<Location "/some/path">
+ DirectorySlash Off
+ SetHandler some-handler
+</Location>
+ </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">
+<Directory "/web/example.com/htdocs/blog">
+ FallbackResource /blog/index.php
+</Directory>
+<Directory "/web/example.com/htdocs/blog/images">
+ FallbackResource disabled
+</Directory>
+ </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>
projects / apache / blobdiff