e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<?xml version="1.0"?>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<modulesynopsis metafile="mod_autoindex.xml.meta">

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<name>mod_autoindex</name>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<description>Generates directory indexes,

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina automatically, similar to the Unix <code>ls</code> command or the

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina Win32 <code>dir</code> shell command</description>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<status>Base</status>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<sourcefile>mod_autoindex.c</sourcefile>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<identifier>autoindex_module</identifier>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina<summary>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <p>The index of a directory can come from one of two

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina sources:</p>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <ul>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <li>A file written by the user, typically called

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <code>index.html</code>. The <directive

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina module="mod_dir">DirectoryIndex</directive> directive sets the

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina name of this file. This is controlled by

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <module>mod_dir</module>.</li>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <li>Otherwise, a listing generated by the server. The other

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina directives control the format of this listing. The <directive

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina module="mod_autoindex">AddIcon</directive>, <directive

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina module="mod_autoindex">AddIconByEncoding</directive> and

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <directive module="mod_autoindex">AddIconByType</directive> are

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina used to set a list of icons to display for various file types;

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina for each file listed, the first icon listed that matches the

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina file is displayed. These are controlled by

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <module>mod_autoindex</module>.</li>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina </ul>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <p>The two functions are separated so that you can completely

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina remove (or replace) automatic index generation should you want

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina to.</p>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <p>Automatic index generation is enabled with using

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <code>Options +Indexes</code>. See the

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina <directive module="core">Options</directive> directive for

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina more details.</p>

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina <p>If the <code><a href="#indexoptions.fancyindexing"

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina >FancyIndexing</a></code> option is given with the <directive

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina module="mod_autoindex">IndexOptions</directive> directive,

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina the column headers are links that control the order of the

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina display. If you select a header link, the listing will be

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina regenerated, sorted by the values in that column. Selecting the

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina same header repeatedly toggles between ascending and descending

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina order. These column header links are suppressed with the

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina <directive module="mod_autoindex">IndexOptions</directive> directive's

9b74009c1260e6f3b1031a6ae110bf1d957cba81Pavel Březina <code>SuppressColumnSorting</code> option.</p>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <p>Note that when the display is sorted by "Size", it's the

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <em>actual</em> size of the files that's used, not the

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina displayed value - so a 1010-byte file will always be displayed

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina before a 1011-byte file (if in ascending order) even though

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina they both are shown as "1K".</p>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina</summary>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek<section id="query">

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <title>Autoindex Request Query Arguments</title>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <p>Apache HTTP Server 2.0.23 reorganized the Query Arguments for Column

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek Sorting, and introduced an entire group of new query options.

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek To effectively eliminate all client control over the output,

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek the <code><a href="#indexoptions.ignoreclient">IndexOptions

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek IgnoreClient</a></code> option was introduced.</p>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <p>The column sorting headers themselves are self-referencing

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina hyperlinks that add the sort query options shown below. Any

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina option below may be added to any request for the directory

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek resource.</p>

552390afcc81af96ca201fa6c25ddefbbecbeb4eJakub Hrozek

552390afcc81af96ca201fa6c25ddefbbecbeb4eJakub Hrozek <ul>

552390afcc81af96ca201fa6c25ddefbbecbeb4eJakub Hrozek <li><code>C=N</code> sorts the directory by file name</li>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <li><code>C=M</code> sorts the directory by last-modified

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina date, then file name</li>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <li><code>C=S</code> sorts the directory by size, then file

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina name</li>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <li class="separate"><code>C=D</code> sorts the directory by description, then

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek file name</li>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <li><code>O=A</code> sorts the listing in Ascending

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina Order</li>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <li class="separate"><code>O=D</code> sorts the listing in Descending

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek Order</li>

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek <li><code>F=0</code> formats the listing as a simple list

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek (not FancyIndexed)</li>

488b455f6b7881ec108a127840b1c1f1523d937fMichal Židek

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina <li><code>F=1</code> formats the listing as a FancyIndexed

e088912418fd4db750f2097dfde8ef9b77303f05Michal Židek list</li>

e088912418fd4db750f2097dfde8ef9b77303f05Michal Židek

e088912418fd4db750f2097dfde8ef9b77303f05Michal Židek <li class="separate"><code>F=2</code> formats the listing as an

e157b9f6cb370e1b94bcac2044d26ad66d640fbaPavel Březina HTMLTable FancyIndexed list</li>

<li><code>V=0</code> disables version sorting</li>

<li class="separate"><code>V=1</code> enables version sorting</li>

<li><code>P=<var>pattern</var></code> lists only files matching

the given <var>pattern</var></li>

</ul>

<p>Note that the 'P'attern query argument is tested

<em>after</em> the usual <directive module="mod_autoindex"

>IndexIgnore</directive> directives are processed,

and all file names are still subjected to the same criteria as

any other autoindex listing. The Query Arguments parser in

<module>mod_autoindex</module> will stop abruptly when an unrecognized

option is encountered. The Query Arguments must be well formed,

according to the table above.</p>

<p>The simple example below, which can be clipped and saved in

a header.html file, illustrates these query options. Note that

the unknown "X" argument, for the submit button, is listed last

to assure the arguments are all parsed before mod_autoindex

encounters the X=Go input.</p>

<example>

&lt;form action="" method="get"&gt;<br />

<indent>

Show me a &lt;select name="F"&gt;<br />

<indent>

&lt;option value="0"&gt; Plain list&lt;/option&gt;<br />

&lt;option value="1" selected="selected"&gt; Fancy list&lt;/option&gt;<br />

&lt;option value="2"&gt; Table list&lt;/option&gt;<br />

</indent>

&lt;/select&gt;<br />

Sorted by &lt;select name="C"&gt;<br />

<indent>

&lt;option value="N" selected="selected"&gt; Name&lt;/option&gt;<br />

&lt;option value="M"&gt; Date Modified&lt;/option&gt;<br />

&lt;option value="S"&gt; Size&lt;/option&gt;<br />

&lt;option value="D"&gt; Description&lt;/option&gt;<br />

</indent>

&lt;/select&gt;<br />

&lt;select name="O"&gt;<br />

<indent>

&lt;option value="A" selected="selected"&gt; Ascending&lt;/option&gt;<br />

&lt;option value="D"&gt; Descending&lt;/option&gt;<br />

</indent>

&lt;/select&gt;<br />

&lt;select name="V"&gt;<br />

<indent>

&lt;option value="0" selected="selected"&gt; in Normal order&lt;/option&gt;<br />

&lt;option value="1"&gt; in Version order&lt;/option&gt;<br />

</indent>

&lt;/select&gt;<br />

Matching &lt;input type="text" name="P" value="*" /&gt;<br />

&lt;input type="submit" name="X" value="Go" /&gt;<br />

</indent>

&lt;/form&gt;

</example>

</section>

<directivesynopsis>

<name>AddAlt</name>

<description>Alternate text to display for a file, instead of an

icon selected by filename</description>

<syntax>AddAlt <var>string</var> <var>file</var> [<var>file</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p><directive>AddAlt</directive> provides the alternate text to

display for a file, instead of an icon, for <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>File</var> is a file extension, partial filename, wild-card

expression or full filename for files to describe.

If <var>String</var> contains any whitespace, you have to enclose it

in quotes (<code>"</code> or <code>'</code>). This alternate text

is displayed if the client is image-incapable, has image loading

disabled, or fails to retrieve the icon.</p>

<example><title>Examples</title>

AddAlt "PDF file" *.pdf<br />

AddAlt Compressed *.gz *.zip *.Z

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddAltByEncoding</name>

<description>Alternate text to display for a file instead of an icon

selected by MIME-encoding</description>

<syntax>AddAltByEncoding <var>string</var> <var>MIME-encoding</var>

[<var>MIME-encoding</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p><directive>AddAltByEncoding</directive> provides the alternate

text to display for a file, instead of an icon, for <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>MIME-encoding</var> is a valid content-encoding, such as

<code>x-compress</code>. If <var>String</var> contains any whitespace,

you have to enclose it in quotes (<code>"</code> or <code>'</code>).

This alternate text is displayed if the client is image-incapable,

has image loading disabled, or fails to retrieve the icon.</p>

<example><title>Example</title>

AddAltByEncoding gzip x-gzip

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddAltByType</name>

<description>Alternate text to display for a file, instead of an

icon selected by MIME content-type</description>

<syntax>AddAltByType <var>string</var> <var>MIME-type</var>

[<var>MIME-type</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p><directive>AddAltByType</directive> sets the alternate text to

display for a file, instead of an icon, for <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>MIME-type</var> is a valid content-type, such as

<code>text/html</code>. If <var>String</var> contains any whitespace,

you have to enclose it in quotes (<code>"</code> or <code>'</code>).

This alternate text is displayed if the client is image-incapable,

has image loading disabled, or fails to retrieve the icon.</p>

<example><title>Example</title>

AddAltByType 'plain text' text/plain

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddDescription</name>

<description>Description to display for a file</description>

<syntax>AddDescription <var>string file</var> [<var>file</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>This sets the description to display for a file, for

<code><a href="#indexoptions.fancyindexing"

>FancyIndexing</a></code>.

<var>File</var> is a file extension, partial filename, wild-card

expression or full filename for files to describe.

<var>String</var> is enclosed in double quotes (<code>"</code>).</p>

<example><title>Example</title>

AddDescription "The planet Mars" mars.gif <br/>

AddDescription "My friend Marshall." friends/mars.gif

</example>

<p>The typical, default description field is 23 bytes wide. 6

more bytes are added by the <code><a href="#indexoptions.suppressicon"

>IndexOptions SuppressIcon</a></code> option, 7 bytes are

added by the <code><a href="#indexoptions.suppresssize"

>IndexOptions SuppressSize</a></code> option, and 19 bytes are

added by the <code><a href="#indexoptions.suppresslastmodified"

>IndexOptions SuppressLastModified</a></code> option.

Therefore, the widest default the description column is ever

assigned is 55 bytes.</p>

<p>Since the <var>File</var> argument may be a partial file name,

please remember that a too-short partial filename may match

unintended files. For example, <code>le.html</code> will match the

file <code>le.html</code> but will also match the file

<code>example.html</code>. In the event that there may be ambiguity,

use as complete a filename as you can, but keep in mind that the

first match encountered will be used, and order your list of

<code>AddDescription</code> directives accordingly.</p>

<p>See the <a href="#indexoptions.descriptionwidth"

>DescriptionWidth</a> <directive module="mod_autoindex"

>IndexOptions</directive> keyword for details on overriding the size

of this column, or allowing descriptions of unlimited length.</p>

<note><title>Caution</title>

<p>Descriptive text defined with <directive>AddDescription</directive>

may contain HTML markup, such as tags and character entities. If the

width of the description column should happen to truncate a tagged

element (such as cutting off the end of a bolded phrase), the

results may affect the rest of the directory listing.</p>

</note>

<note><title>Arguments with path information</title>

<p>Absolute paths are not currently supported and do not match

anything at runtime. Arguments with relative path information,

which would normally only be used in htaccess context, are implicitly

prefixed with '*/' to avoid matching partial directory names.</p>

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddIcon</name>

<description>Icon to display for a file selected by name</description>

<syntax>AddIcon <var>icon</var> <var>name</var> [<var>name</var>]

...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>This sets the icon to display next to a file ending in

<var>name</var> for <code><a href="#indexoptions.fancyindexing"

>FancyIndexing</a></code>. <var>Icon</var> is either a (%-escaped)

relative URL to the icon, a fully qualified remote URL, or of the format <code>

(<var>alttext</var>,<var>url</var>)</code> where <var>alttext</var>

is the text tag given for an icon for non-graphical browsers.</p>

<p><var>Name</var> is either <code>^^DIRECTORY^^</code> for directories,

<code>^^BLANKICON^^</code> for blank lines (to format the list

correctly), a file extension, a wildcard expression, a partial

filename or a complete filename.</p>

<p><code>^^BLANKICON^^</code> is only used for formatting, and so

is unnecessary if you're using <code>IndexOptions

HTMLTable</code>.</p>

<example><title>Examples</title>

AddIcon (IMG,/icons/image.png) .gif .jpg .png<br />

AddIcon /icons/dir.png ^^DIRECTORY^^<br />

AddIcon /icons/backup.png *~

</example>

<p><directive module="mod_autoindex">AddIconByType</directive>

should be used in preference to <directive>AddIcon</directive>,

when possible.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddIconByEncoding</name>

<description>Icon to display next to files selected by MIME

content-encoding</description>

<syntax>AddIconByEncoding <var>icon</var> <var>MIME-encoding</var>

[<var>MIME-encoding</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>This sets the icon to display next to files with <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>Icon</var> is either a (%-escaped) relative URL to the icon,

a fully qualified remote URL,

or of the format <code>(<var>alttext</var>,<var>url</var>)</code>

where <var>alttext</var> is the text tag given for an icon for

non-graphical browsers.</p>

<p><var>MIME-encoding</var> is a valid content-encoding, such as

<code>x-compress</code>.</p>

<example><title>Example</title>

AddIconByEncoding /icons/compress.png x-compress

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AddIconByType</name>

<description>Icon to display next to files selected by MIME

content-type</description>

<syntax>AddIconByType <var>icon</var> <var>MIME-type</var>

[<var>MIME-type</var>] ...</syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>This sets the icon to display next to files of type

<var>MIME-type</var> for <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>Icon</var> is either a (%-escaped) relative URL to the icon,

a fully qualified remote URL,

or of the format <code>(<var>alttext</var>,<var>url</var>)</code>

where <var>alttext</var> is the text tag given for an icon for

non-graphical browsers.</p>

<p><var>MIME-type</var> is a wildcard expression matching

required the mime types.</p>

<example><title>Example</title>

AddIconByType (IMG,/icons/image.png) image/*

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DefaultIcon</name>

<description>Icon to display for files when no specific icon is

configured</description>

<syntax>DefaultIcon <var>url-path</var></syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>DefaultIcon</directive> directive sets the icon

to display for files when no specific icon is known, for <code><a

href="#indexoptions.fancyindexing">FancyIndexing</a></code>.

<var>Url-path</var> is a (%-escaped) relative URL to the icon,

or a fully qualified remote URL.</p>

<example><title>Example</title>

DefaultIcon /icon/unknown.png

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>HeaderName</name>

<description>Name of the file that will be inserted at the top

of the index listing</description>

<syntax>HeaderName <var>filename</var></syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>HeaderName</directive> directive sets the name

of the file that will be inserted at the top of the index

listing. <var>Filename</var> is the name of the file to include.</p>

<example><title>Example</title>

HeaderName HEADER.html

</example>

<note>

<p>Both HeaderName and <directive

module="mod_autoindex">ReadmeName</directive> now treat

<var>Filename</var> as a URI path relative to the one used to

access the directory being indexed. If <var>Filename</var> begins

with a slash, it will be taken to be relative to the <directive

module="core">DocumentRoot</directive>.</p>

<example><title>Example</title>

HeaderName /include/HEADER.html

</example>

<p><var>Filename</var> must resolve to a document with a major

content type of <code>text/*</code> (<em>e.g.</em>,

<code>text/html</code>, <code>text/plain</code>, etc.). This means

that <var>filename</var> may refer to a CGI script if the script's

actual file type (as opposed to its output) is marked as

<code>text/html</code> such as with a directive like:</p>

<example>

AddType text/html .cgi

</example>

<p><a href="/content-negotiation.html">Content negotiation</a>

will be performed if <directive module="core">Options</directive>

<code>MultiViews</code> is in effect. If <var>filename</var> resolves

to a static <code>text/html</code> document (not a CGI script) and

either one of the <directive module="core">options</directive>

<code>Includes</code> or <code>IncludesNOEXEC</code> is enabled,

the file will be processed for server-side includes (see the

<module>mod_include</module> documentation).</p>

</note>

<p>If the file specified by <directive>HeaderName</directive> contains

the beginnings of an HTML document (&lt;html&gt;, &lt;head&gt;, etc.)

then you will probably want to set <a

href="#indexoptions.suppresshtmlpreamble"><code>IndexOptions

+SuppressHTMLPreamble</code></a>, so that these tags are not

repeated.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexIgnore</name>

<description>Adds to the list of files to hide when listing

a directory</description>

<syntax>IndexIgnore <var>file</var> [<var>file</var>] ...</syntax>

<default>IndexIgnore "."</default>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>IndexIgnore</directive> directive adds to the

list of files to hide when listing a directory. <var>File</var> is a

shell-style wildcard expression or full

filename. Multiple IndexIgnore directives add

to the list, rather than the replacing the list of ignored

files. By default, the list contains <code>.</code> (the current

directory).</p>

<example>

IndexIgnore .??* *~ *# HEADER* README* RCS CVS *,v *,t

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexIgnoreReset</name>

<description>Empties the list of files to hide when listing

a directory</description>

<syntax>IndexIgnoreReset ON|OFF</syntax>

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

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

</contextlist>

<override>Indexes</override>

<compatibility>2.3.10 and later</compatibility>

<usage>

<p>The <directive>IndexIgnoreReset</directive> directive removes

any files ignored by <directive>IndexIgnore</directive> otherwise

inherited from other configuration sections. </p>

<example>

&lt;Directory /var/www&gt;

IndexIgnore *.bak .??* *~ *# HEADER* README* RCS CVS *,v *,t

&lt;/Directory&gt;

&lt;Directory /var/www/backups&gt;

IndexIgnoreReset ON

IndexIgnore .??* *# HEADER* README* RCS CVS *,v *,t

&lt;/Directory&gt;

</example>

<note type="warning"><p> Review the default configuration for a list of

patterns that you might want to explicitly ignore after using this

directive.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexOptions</name>

<description>Various configuration settings for directory

indexing</description>

<syntax>IndexOptions [+|-]<var>option</var> [[+|-]<var>option</var>]

...</syntax>

<default>By default, no options are enabled.</default>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>IndexOptions</directive> directive specifies the

behavior of the directory indexing. <var>Option</var> can be one

of</p>

<dl>

<dt><a name="indexoptions.addaltclass"

id="indexoptions.addaltclass">AddAltClass</a></dt>

<dd>Adds an additional CSS class declaration to each row of the

directory listing table when <code>IndexOptions HTMLTable</code>

is in effect and an <code>IndexStyleSheet</code> is defined.

Rather than the standard <code>even</code> and <code>odd</code>

classes that would otherwise be applied to each row of the table,

a class of <code>even-<em>ALT</em></code> or

<code>odd-<em>ALT</em></code> where <em>ALT</em> is either the

standard alt text associated with the file style (eg. <em>snd</em>,

<em>txt</em>, <em>img</em>, etc) or the alt text defined by one of

the various <code>AddAlt*</code> directives.

</dd>

<dt><a name="indexoptions.charset"

id="indexoptions.charset"

>Charset=<var>character-set</var></a> (<em>Apache HTTP Server 2.0.61 and

later</em>)</dt>

<dd>The <code>Charset</code> keyword allows you to

specify the character set of the generated page. The

default is <code>UTF-8</code> on Windows and Mac OS X,

and <code>ISO-8859-1</code> elsewhere.

(It depends on whether the underlying file system

uses Unicode filenames or not.)

<example><title>Example:</title>

IndexOptions Charset=UTF-8

</example>

</dd>

<dt><a name="indexoptions.descriptionwidth"

id="indexoptions.descriptionwidth"

>DescriptionWidth=[<var>n</var> | *]</a> (<em>Apache HTTP Server 2.0.23 and

later</em>)</dt>

<dd>The <code>DescriptionWidth</code> keyword allows you to

specify the width of the description column in

characters.</dd>

<dd><code>-DescriptionWidth</code> (or unset) allows

<module>mod_autoindex</module> to calculate the best width.</dd>

<dd><code>DescriptionWidth=<var>n</var></code> fixes the column width to

<var>n</var> bytes wide.</dd>

<dd><code>DescriptionWidth=*</code> grows the column to the

width necessary to accommodate the longest description

string.</dd>

<dd><strong>See the section on <directive

module="mod_autoindex">AddDescription</directive> for dangers

inherent in truncating descriptions.</strong></dd>

<dt><a name="indexoptions.fancyindexing"

id="indexoptions.fancyindexing">FancyIndexing</a></dt>

<dd>This turns on fancy indexing of directories.</dd>

<dt><a name="indexoptions.foldersfirst"

id="indexoptions.foldersfirst">FoldersFirst</a> (<em>Apache HTTP Server

2.0.23 and later</em>)</dt>

<dd>If this option is enabled, subdirectory listings will

<em>always</em> appear first, followed by normal files in the

directory. The listing is basically broken into two

components, the files and the subdirectories, and each is

sorted separately and then displayed subdirectories-first.

For instance, if the sort order is descending by name, and

<code>FoldersFirst</code> is enabled, subdirectory

<code>Zed</code> will be listed before subdirectory

<code>Beta</code>, which will be listed before normal files

<code>Gamma</code> and <code>Alpha</code>. <strong>This option

only has an effect if <a href="#indexoptions.fancyindexing"

><code>FancyIndexing</code></a> is also enabled.</strong></dd>

<dt><a name="indexoptions.htmltable"

id="indexoptions.htmltable">HTMLTable</a> (<em>Apache

HTTP Server 2.0.23 and later</em>)</dt>

<dd>This option with <code>FancyIndexing</code> constructs

a simple table for the fancy directory listing.

It is necessary for utf-8 enabled platforms or if file

names or description text will alternate between

left-to-right and right-to-left reading order.</dd>

<dt><a name="indexoptions.iconsarelinks"

id="indexoptions.iconsarelinks">IconsAreLinks</a></dt>

<dd>This makes the icons part of the anchor for the filename, for

fancy indexing.</dd>

<dt><a name="indexoptions.iconheight"

id="indexoptions.iconheight">IconHeight[=<var

>pixels</var>]</a></dt>

<dd>Presence of this option, when used with <code>IconWidth</code>,

will cause the server to include <code>height</code> and

<code>width</code> attributes in the <code>img</code> tag for the file

icon. This allows browser to precalculate the page layout without having

to wait until all the images have been loaded. If no value is given for

the option, it defaults to the standard height of the icons supplied

with the Apache httpd software.</dd>

<dt><a name="indexoptions.iconwidth"

id="indexoptions.iconwidth">IconWidth[=<var

>pixels</var>]</a></dt>

<dd>Presence of this option, when used with <code>IconHeight</code>,

will cause the server to include <code>height</code> and

<code>width</code> attributes in the <code>img</code> tag for

the file icon. This allows browser to precalculate the page

layout without having to wait until all the images have been

loaded. If no value is given for the option, it defaults to

the standard width of the icons supplied with the Apache httpd

software.</dd>

<dt><a name="indexoptions.ignorecase"

id="indexoptions.ignorecase">IgnoreCase</a></dt>

<dd>If this option is enabled, names are sorted in a case-insensitive

manner. For instance, if the sort order is ascending by name, and

<code>IgnoreCase</code> is enabled, file Zeta will be listed after

file alfa (Note: file GAMMA will always be listed before file gamma).

</dd>

<dt><a name="indexoptions.ignoreclient"

id="indexoptions.ignoreclient">IgnoreClient</a></dt>

<dd>This option causes <module>mod_autoindex</module> to ignore all

query variables from the client, including sort order (implies

<code><a href="#indexoptions.suppresscolumnsorting"

>SuppressColumnSorting</a></code>.)</dd>

<dt><a name="indexoptions.namewidth"

id="indexoptions.namewidth">NameWidth=[<var>n</var>

| *]</a></dt>

<dd>The <code>NameWidth</code> keyword allows you to specify the width

of the filename column in bytes.</dd>

<dd><code>-NameWidth</code> (or unset) allows <module

>mod_autoindex</module> to calculate the best width, but only up

to 20 bytes wide.</dd>

<dd><code>NameWidth=<var>n</var></code> fixes the column width to

<var>n</var> bytes wide.</dd>

<dd><code>NameWidth=*</code> grows the column to the necessary

width.</dd>

<dt><a name="indexoptions.scanhtmltitles"

id="indexoptions.scanhtmltitles">ScanHTMLTitles</a></dt>

<dd>This enables the extraction of the title from HTML documents

for fancy indexing. If the file does not have a description

given by <directive module="mod_autoindex">AddDescription</directive>

then httpd will read the document for the value of the

<code>title</code> element. This is CPU and disk intensive.</dd>

<dt><a name="indexoptions.showforbidden"

id="indexoptions.showforbidden">ShowForbidden</a></dt>

<dd>If specified, Apache httpd will show files normally hidden because

the subrequest returned <code>HTTP_UNAUTHORIZED</code> or

<code>HTTP_FORBIDDEN</code></dd>

<dt><a name="indexoptions.suppresscolumnsorting"

id="indexoptions.suppresscolumnsorting"

>SuppressColumnSorting</a></dt>

<dd>If specified, Apache httpd will not make the column headings in a

FancyIndexed directory listing into links for sorting. The

default behavior is for them to be links; selecting the

column heading will sort the directory listing by the values

in that column. <strong>Prior to Apache HTTP Server 2.0.23, this also

disabled parsing the Query Arguments for the sort

string.</strong> That behavior is now controlled by <a

href="#indexoptions.ignoreclient"><code>IndexOptions

IgnoreClient</code></a> in Apache HTTP Server 2.0.23.</dd>

<dt><a name="indexoptions.suppressdescription"

id="indexoptions.suppressdescription"

>SuppressDescription</a></dt>

<dd>This will suppress the file description in fancy indexing

listings. By default, no file descriptions are defined, and

so the use of this option will regain 23 characters of screen

space to use for something else. See <directive module="mod_autoindex"

>AddDescription</directive> for information about setting the file

description. See also the <code><a

href="#indexoptions.descriptionwidth">DescriptionWidth</a></code>

index option to limit the size of the description column.</dd>

<dt><a name="indexoptions.suppresshtmlpreamble"

id="indexoptions.suppresshtmlpreamble"

>SuppressHTMLPreamble</a></dt>

<dd>If the directory actually contains a file specified by the

<directive module="mod_autoindex">HeaderName</directive>

directive, the module usually includes the contents of the file

after a standard HTML preamble (<code>&lt;html&gt;</code>,

<code>&lt;head&gt;</code>, <em>et cetera</em>). The

<code>SuppressHTMLPreamble</code> option disables this behaviour,

causing the module to start the display with the header file

contents. The header file must contain appropriate HTML instructions

in this case. If there is no header file, the preamble is generated

as usual. If you also specify a <directive

module="mod_autoindex">ReadmeName</directive>, and if that file

exists, The closing &lt;/body&gt;&lt;/html&gt; tags are also

ommitted from the output, under the assumption that you'll likely

put those closing tags in that file.</dd>

<dt><a name="indexoptions.suppressicon"

id="indexoptions.suppressicon">SuppressIcon</a> (<em>Apache HTTP Server

2.0.23 and later</em>)</dt>

<dd>This will suppress the icon in fancy indexing listings.

Combining both <code>SuppressIcon</code> and

<code>SuppressRules</code> yields proper HTML 3.2 output, which

by the final specification prohibits <code>img</code> and

<code>hr</code> elements from the <code>pre</code> block (used to

format FancyIndexed listings.)</dd>

<dt><a name="indexoptions.suppresslastmodified"

id="indexoptions.suppresslastmodified"

>SuppressLastModified</a></dt>

<dd>This will suppress the display of the last modification date,

in fancy indexing listings.</dd>

<dt><a name="indexoptions.suppressrules"

id="indexoptions.suppressrules">SuppressRules</a>

(<em>Apache HTTP Server 2.0.23 and later</em>)</dt>

<dd>This will suppress the horizontal rule lines (<code>hr</code>

elements) in directory listings. Combining both <code>SuppressIcon</code> and

<code>SuppressRules</code> yields proper HTML 3.2 output, which

by the final specification prohibits <code>img</code> and

<code>hr</code> elements from the <code>pre</code> block (used to

format FancyIndexed listings.)</dd>

<dt><a name="indexoptions.suppresssize"

id="indexoptions.suppresssize">SuppressSize</a></dt>

<dd>This will suppress the file size in fancy indexing listings.</dd>

<dt><a name="indexoptions.trackmodified"

id="indexoptions.trackmodified">TrackModified</a> (<em>Apache HTTP Server

2.0.23 and later</em>)</dt>

<dd>This returns the <code>Last-Modified</code> and <code>ETag</code>

values for the listed directory in the HTTP header. It is only valid

if the operating system and file system return appropriate stat()

results. Some Unix systems do so, as do OS2's JFS and Win32's

NTFS volumes. OS2 and Win32 FAT volumes, for example, do not.

Once this feature is enabled, the client or proxy can track

changes to the list of files when they perform a <code>HEAD</code>

request. Note some operating systems correctly track new and

removed files, but do not track changes for sizes or dates of

the files within the directory. <strong>Changes to the size

or date stamp of an existing file will not update the

<code>Last-Modified</code> header on all Unix platforms.</strong>

If this is a concern, leave this option disabled.</dd>

<dt><a name="indexoptions.type"

id="indexoptions.type"

>Type=<var>MIME content-type</var></a> (<em>Apache HTTP Server 2.0.61 and

later</em>)</dt>

<dd>The <code>Type</code> keyword allows you to

specify the MIME content-type of the generated page. The default

is <var>text/html</var>.

<example><title>Example:</title>

IndexOptions Type=text/plain

</example>

</dd>

<dt><a name="indexoptions.versionsort"

id="indexoptions.versionsort">VersionSort</a>

(<em>Apache HTTP Server 2.0a3 and later</em>)</dt>

<dd>The <code>VersionSort</code> keyword causes files containing

version numbers to sort in a natural way. Strings are sorted as

usual, except that substrings of digits in the name and

description are compared according to their numeric value.

<example><title>Example:</title>

foo-1.7<br />

foo-1.7.2<br />

foo-1.7.12<br />

foo-1.8.2<br />

foo-1.8.2a<br />

foo-1.12

</example>

<p>If the number starts with a zero, then it is considered to

be a fraction:</p>

<example>

foo-1.001<br />

foo-1.002<br />

foo-1.030<br />

foo-1.04

</example>

</dd>

<dt><a name="indexoptions.xhtml"

id="indexoptions.xhtml">XHTML</a>

(<em>Apache HTTP Server 2.0.49 and later</em>)</dt>

<dd>The <code>XHTML</code> keyword forces <module>mod_autoindex</module>

to emit XHTML 1.0 code instead of HTML 3.2.</dd>

</dl>

<!--

<dl><dt>Incremental IndexOptions</dt>

<dd>

<p>Be aware of how multiple <directive>IndexOptions</directive> are

handled.</p>

<ul>

<li>Multiple <directive>IndexOptions</directive> directives for a

single directory are now merged together. The result of:

<example>

&lt;Directory /foo&gt;

<indent>

IndexOptions HTMLTable<br />

IndexOptions SuppressColumnsorting

</indent>

&lt;/Directory&gt;

</example>

<p>will be the equivalent of</p>

<example>

IndexOptions HTMLTable SuppressColumnsorting

</example>

</li>

<li>The addition of the incremental syntax (<em>i.e.</em>, prefixing

keywords with <code>+</code> or <code>-</code>).</li>

</ul>

<p>Whenever a '+' or '-' prefixed keyword is encountered, it

is applied to the current <directive>IndexOptions</directive>

settings (which may have been inherited from an upper-level

directory). However, whenever an unprefixed keyword is processed, it

clears all inherited options and any incremental settings encountered

so far. Consider the following example:</p>

<example>

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing<br />

IndexOptions +SuppressSize

</example>

<p>The net effect is equivalent to <code>IndexOptions FancyIndexing

+SuppressSize</code>, because the unprefixed <code>FancyIndexing</code>

discarded the incremental keywords before it, but allowed them to

start accumulating again afterward.</p>

<p>To unconditionally set the <directive>IndexOptions</directive> for

a particular directory, clearing the inherited settings, specify

keywords without any <code>+</code> or <code>-</code> prefixes.</p>

</dd>

</dl>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexOrderDefault</name>

<description>Sets the default ordering of the directory index</description>

<syntax>IndexOrderDefault Ascending|Descending

Name|Date|Size|Description</syntax>

<default>IndexOrderDefault Ascending Name</default>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>IndexOrderDefault</directive> directive is used

in combination with the <code><a href="#indexoptions.fancyindexing"

>FancyIndexing</a></code> index option. By default, fancyindexed

directory listings are displayed in ascending order by filename; the

<directive>IndexOrderDefault</directive> allows you to change this

initial display order.</p>

<p><directive>IndexOrderDefault</directive> takes two

arguments. The first must be either <code>Ascending</code> or

<code>Descending</code>, indicating the direction of the sort.

The second argument must be one of the keywords <code>Name</code>,

<code>Date</code>, <code>Size</code>, or <code>Description</code>,

and identifies the primary key. The secondary key is

<em>always</em> the ascending filename.</p>

<p>You can, if desired, prevent the client from reordering the list

by also adding the <code><a

href="#indexoptions.suppresscolumnsorting">SuppressColumnSorting</a></code>

index option to remove the sort link from the top of the column,

along with the <code><a

href="#indexoptions.ignoreclient">IgnoreClient</a></code> index

option to prevent them from manually adding sort options to the

query string in order to override your ordering preferences.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexStyleSheet</name>

<description>Adds a CSS stylesheet to the directory index</description>

<syntax>IndexStyleSheet <var>url-path</var></syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>IndexStyleSheet</directive> directive sets the name of

the file that will be used as the CSS for the index listing.

</p>

<example>

<title>Example</title>

IndexStyleSheet "/css/style.css"

</example>

<p>Using this directive in conjunction with <code>IndexOptions

HTMLTable</code> adds a number of CSS classes to the resulting HTML.

The entire table is given a CSS id of <code>indexlist</code> and the

following classes are associated with the various parts of the

listing:</p>

<table border="1" style="zebra">

<tr><th>Class</th><th>Definition</th></tr>

<tr><td>tr.indexhead</td><td>Header row of listing</td></tr>

<tr><td>th.indexcolicon and td.indexcolicon</td> <td>Icon column</td></tr>

<tr><td>th.indexcolname and td.indexcolname</td> <td>File name column</td></tr>

<tr><td>th.indexcollastmod and td.indexcollastmod</td> <td>Last modified column</td></tr>

<tr><td>th.indexcolsize and td.indexcolsize</td> <td>File size column</td></tr>

<tr><td>th.indexcoldesc and td.indexcoldesc</td> <td>Description column</td></tr>

<tr><td>tr.breakrow</td> <td>Horizontal rule at the bottom of the table</td></tr>

<tr><td>tr.odd and tr.even</td> <td>Alternating even and odd rows</td></tr>

</table>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>IndexHeadInsert</name>

<description>Inserts text in the HEAD section of an index page.</description>

<syntax>IndexHeadInsert <var>"markup ..."</var></syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>IndexHeadInsert</directive> directive specifies a

string to insert in the <var>&lt;head&gt;</var> section of the HTML

generated for the index page.</p>

<example>

<title>Example</title>

IndexHeadInsert "&lt;link rel=\"sitemap\" href=\"/sitemap.html\"&gt;"

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ReadmeName</name>

<description>Name of the file that will be inserted at the end

of the index listing</description>

<syntax>ReadmeName <var>filename</var></syntax>

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

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

</contextlist>

<override>Indexes</override>

<usage>

<p>The <directive>ReadmeName</directive> directive sets the name

of the file that will be appended to the end of the index

listing. <var>Filename</var> is the name of the file to include, and

is taken to be relative to the location being indexed. If

<var>Filename</var> begins with a slash, it will be taken to be

relative to the <directive module="core">DocumentRoot</directive>.

</p>

<example><title>Example</title>

ReadmeName FOOTER.html

</example>

<example><title>Example 2</title>

ReadmeName /include/FOOTER.html

</example>

<p>See also <directive module="mod_autoindex"

>HeaderName</directive>, where this behavior is described in greater

detail.</p>

</usage>

</directivesynopsis>

</modulesynopsis>