Module mod_autoindex
Module mod_autoindex contains directives for the IBM® HTTP Server for i Web server.
Summary
The module mod_autoindex provides for automatic directory indexing. The index of a directory can come from one of two sources:
- A file written by the user, typically called index.html. The DirectoryIndex directive sets the name of this file. This is controlled by mod_dir.
- A listing generated by the server. The other directives control the format of this listing. The AddIcon, AddIconByEncoding and AddIconByType are used to set a list of icons to display for various file types; for each file listed, the first icon listed that matches the file is displayed. These are controlled by mod_autoindex.
If the FancyIndexing keyword is present on the IndexOptions directive, the column headers are links that control the order of the display. If you select a header link, the listing will be regenerated, sorted by the values in that column. Selecting the same header repeatedly toggles between ascending and descending order.
For all mod_autoindex directives that specify a file name (AddDescription, AddIcon, and so on), case sensitivity is handled based on the file system. If the object is in the QOpenSys file system, the name is handled in a case sensitive manner. If the object is a file system other than QOpenSys, the name is handled in a case insensitive manner.
Directives
AddAlt
Module: mod_autoindex | |
Syntax: AddAlt string file [file...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddAlt "IMG" jpg gif |
The AddAlt directive sets the alternate text to display for automatic directory indexing.
- Parameter One: string
- The string parameter is enclosed in double quotes ("..."). This alternate text is displayed if the client is image-incapable or has image loading disabled.
- Parameter Two: file
- The file parameter is either ^^DIRECTORY^^ for child directories,
^^PARENT^^ for parent directories, ^^BLANKICON^^ for blank lines (to
format the list correctly), a file extension, a wildcard expression,
a partial file, or a complete filename. It could also be a QSYS.LIB
member type if this directive is being used to set alternate text
for QSYS.LIB members. For example:
AddAlt "IMG" .jpg .gif AddAlt " " ^^BLANKICON^^ AddAlt "BAK" *~
- The file parameter is either ^^DIRECTORY^^ for child directories,
^^PARENT^^ for parent directories, ^^BLANKICON^^ for blank lines (to
format the list correctly), a file extension, a wildcard expression,
a partial file, or a complete filename. It could also be a QSYS.LIB
member type if this directive is being used to set alternate text
for QSYS.LIB members. For example:
AddAltByEncoding
Module: mod_autoindex | |
Syntax: AddAltByEncoding string MIME-encoding [MIME-encoding...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddAltByEncoding "CMP" x-compress |
The AddAltByEncoding directive sets the alternate text to display for a file, instead of an icon, for automatic directory indexing.
- Parameter One: string
- The string parameter is enclosed in double quotes ("..."). This alternate text is displayed if the client is image-incapable or has image loading disabled.
- Parameter Two: MIME-encoding
- The MIME-encoding parameter is a valid content-encoding, such as x-compress.
AddAltByType
Module: mod_autoindex | |
Syntax: AddAltByType string MIME-type [MIME-type ...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddAltByType "HTM" text/html |
The AddAltByType directive sets the alternate text to display for a file, instead of an icon, for automatic directory indexing.
- Parameter One: string
- The string parameter is enclosed in double quotes ("..."). This alternate text is displayed if the client is image-incapable or has image loading disabled.
- Parameter Two: MIME-type
- The MIME-type parameter is a valid content-type, such as text/html.
AddDescription
Module: mod_autoindex | |
Syntax: AddDescription string file [file...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddDescription "Famous People" /web/pics/famous* | |
Example: AddDescription "My pictures" /QSYS.LIB/MYLIB/MYFILE.FILE/pic* |
The AddDescription directive sets the description to display for a file, for automatic directory indexing. File is a file extension, partial filename, QSYS.LIB member type, wildcard expression or full filename for files to describe. String is enclosed in double quotes ("). For example:
AddDescription "The planet Mars" /web/pics/mars.gif
By default, the description field is 23 bytes wide. Seven more bytes may be added if the directory is covered by an IndexOptions SuppressSize, and 19 bytes may be added if IndexOptions SuppressLastModified is in effect. The widest this column can be is therefore 49 bytes, unless configured differently using IndexOptions DescriptionMaxWidth.
The DescriptionWidth IndexOptions keyword allows you to adjust this width to any arbitrary size.
The following order of precedence will be used to search for a directory listing file description. The first mechanism from this list that applies will be used to generate the file description:
- The file matches one of those specified on an AddDescription directive. The string from the directive is displayed. This option is the least CPU intensive.
- The file system contains a description for the file. The file system description information is displayed. Note that if the file is a QSYS.LIB member, the member text is displayed.
- If IndexOptions ScanHTMLTitles is configured, the title is extracted from HTML documents for fancy indexing. This is CPU and disk intensive.
AddIcon
Module: mod_autoindex | |
Syntax: AddIcon icon name [name ...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddIcon (IMG,icons/image) .gif .jpg |
The AddIcon directive sets the icon to display next to a file ending in name for automatic directory indexing.
- Parameter One: icon
- The icon parameter is either a (%-escape) relative URL to the icon or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
- Parameter Two: name
- The name parameter is either ^^DIRECTORY^^ for
child directories, ^^PARENT^^ for parent directories, ^^BLANKICON^^ for
blank lines (to format the list correctly), a file extension, a wildcard
expression, a partial file or a complete filename. For example
AddIcon (IMG,icons/image) .gif .jpg AddIcon (PAR, icons/parent .gif) ^^PARENT^^ AddIcon /dir.gif ^^DIRECTORY^^ AddIcon backup.gif *~
- The name parameter is either ^^DIRECTORY^^ for
child directories, ^^PARENT^^ for parent directories, ^^BLANKICON^^ for
blank lines (to format the list correctly), a file extension, a wildcard
expression, a partial file or a complete filename. For example
AddIconByType should be used in preference to AddIcon, when possible.
AddIconByEncoding
Module: mod_autoindex | |
Syntax: AddIconByEncoding icon MIME-encoding [MIME-encoding ...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddIconByEncoding /compress.xbm x-compress |
The AddIConByEncoding directive sets the icon to display next to files with MIME-encoding for automatic directory indexing.
- Parameter One: icon
- The icon parameter is either a (%-escaped) relative URL to the icon or of the format (alttext,url) where alttext is the text tag five for an icon for non-graphical browsers.
- Parameter Two: MIME-encoding
- The MIME-encoding parameter is a wildcard expression matching required content-encoding.
AddIconByType
Module: mod_autoindex | |
Syntax: AddIconByType icon MIME-type [MIME-type ...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: AddIconByType (IMG,image.gif) image/* |
The AddIconByType directive sets the icon to display next to files of type MIME-type for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
- Parameter One: icon
- The icon parameter is either a (%-escaped) relative URL to the icon or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
- Parameter Two: MIME-type
- The MIME-type parameter is a wildcard expression matching the required MIME types.
DefaultIcon
Module: mod_autoindex | |
Syntax: DefaultIcon url | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Modified | |
Example: DefaultIcon /icon/unknown.gif |
The DefaultIcon directive sets the icon to display for files when no specific icon is known, for automatic directory indexing.
- Parameter: url
- The url parameter is either a (%-escaped) relative URL to the
icon or of the format (alttext,url) where alttext is the text tag
given for an icon for non-graphical browsers. For example:
DefaultIcon (UNK,unknown.gif)
- The url parameter is either a (%-escaped) relative URL to the
icon or of the format (alttext,url) where alttext is the text tag
given for an icon for non-graphical browsers. For example:
HeaderName
Module: mod_autoindex | |
Syntax: HeaderName filename | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: HeaderName headerfile | |
Example: HeaderName PREAMBLE.MBR |
The HeaderName directive sets the name of the file that will be inserted at the top of the index listing.
- Parameter: filename
- The filename parameter is the name of the file to include.
Filename is treated as a URI path relative to the one used to access the directory being indexed, and must resolve to a document with a major content type of "text" (for example, text/html, text/plain). This means that filename may refer to a CGI script if the script's actual file type (as opposed to its output) is marked as text/html such as with a directive like:
AddType text/html .cgi
Content negotiation will be performed if the MultiViews option is enabled. See Content negotiation for HTTP Server for more information.
If filename resolves to a static text/html document (not a CGI script) and the Includes Option is enabled, the file will be processed for server-side includes. See mod_include for more information.
See also ReadmeName.
IndexHeadInsert
Module: mod_autoindex | |
Syntax: IndexHeadInsert markup | |
Default: none | |
Context: server config, virtual host, directory, .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example:
|
The IndexHeadInsert directive specifies a string to insert in the <head> section of the HTML generated for the index page.
- Parameter: markup
- The markup parameter is a string to be inserted in the <head> section of the HTML generated for the index page. The markup parameter must be enclosed in double quotes ("...").
IndexIgnore
Module: mod_autoindex | |
Syntax: IndexIgnore file [file ...] | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: IndexIgnore README .htaccess | |
Example: IndexIgnore README.MBR |
The IndexIgnore directive adds to the list of files to hide when listing a directory. Multiple IndexIgnore directives add to the list, rather than the replacing the list of ignored files. By default, the dot directory (.) is ignored.
- Parameter: file
- The file parameter is a file extension, QSYS.LIB member type, partial filename, wildcard expression or full filename for files to ignore.
IndexIgnoreReset
Module: mod_autoindex | |
Syntax: IndexIgnoreReset ON|OFF | |
Default: IndexIgnoreReset OFF | |
Context: server config, virtual host, directory, .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: IndexIgnoreReset ON |
The IndexIgnoreReset directive removes any files ignored by IndexIgnore otherwise inherited from other configuration sections.
- Parameter: on | off
- When on is specified, any files ignored by IndexIgnore will be reset.
- When off is specified, it inherites from other configuration sections by default.
For example:
<Directory /var/www>
IndexIgnore *.bak .??* *~ *# HEADER* README* RCS CVS *,v *,t
</Directory>
<Directory /var/www/backups>
IndexIgnoreReset ON
IndexIgnore .??* *# HEADER* README* RCS CVS *,v *,t
</Directory>
IndexOptions
Module: mod_autoindex | |
Syntax: IndexOptions [+|-]option [+|-]option ... | |
Default: none | |
Context: server config, virtual host, directory, .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: IndexOptions FancyIndexing ShowOwner FoldersFirst |
- AddAltClass
- Adds an additional CSS class declaration to each row of the directory listing table when IndexOptions HTMLTable is in effect and an IndexStyleSheet is defined. Rather than the standard even and odd classes that would otherwise be applied to each row of the table, a class of even-ALT or odd-ALT where ALT is either the standard alt text associated with the file style (eg. snd, txt, img, etc) or the alt text defined by one of the various AddAlt* directives.
- DescriptionWidth= [n | *]
- The DescriptionWidth keyword allows you to specify the width of the description column in characters. -DescriptionWidth (or unset) allows mod_autoindex to calculate the best width. DescriptionWidth=n fixes the column width to n characters wide. DescriptionWidth=* grows the column to the width necessary to accommodate the longest description string. See the section on AddDescription for dangers inherent in truncating descriptions.
- FancyIndexing
- This option turns on fancy indexing of directories. With FancyIndexing, the column headers are links that control the order of the display. If you select a header link, the listing will be regenerated, sorted by the values in that column. Selecting the same header repeatedly toggles between ascending and descending order.
- FoldersFirst
- If this option is enabled, subdirectories in a FancyIndexed listing will always appear first, followed by normal files in the directory. The listing is 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 FoldersFirst is enabled, subdirectory Zed will be listed before subdirectory Beta, which will be listed before normal files Gamma and Alpha. This option only has an effect if FancyIndexing is also enabled
- IconsAreLinks
- This makes the icons part of the anchor for the filename, for fancy indexing.
- IconHeight=[pixels]
- Presence of this option, when used with IconWidth, will cause the server to include HEIGHT and WIDTH attributes in the IMG 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 the HTTP Server software. This option only has an effect if FancyIndexing is also enabled.
- IconWidth=[pixels]
- Presence of this option, when used with IconHeight, will cause the server to include HEIGHT and WIDTH attributes in the IMG 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 HTTP Server software.
- IgnoreCase
- If this option is enabled, names are sorted in a case-insensitive manner. For instance, if the sort order is ascending by name, and IgnoreCase is enabled, file zeta will be listed after file Alpha. Likewise, if IgnoreCase is disabled, file zeta will be listed before file Alpha. By default IgnoreCase is disabled. This option only has an effect if FancyIndexing is also enabled. The new IgnoreCase value replaces the IndexOrderDefault CaseSense|NoCaseSense parameter.
- IgnoreClient
- This option causes mod_autoindex to ignore all query variables from the client, including sort order (implies SuppressColumnSorting.)
- NameWidth=[n | *]
- The NameWidth keyword allows you to specify the width of the filename column in characters. If the keyword value is '*', then the column is automatically sized to the length of the longest filename in the display. -NameWidth (or unset) allows mod_autoindex to calculate the best width. NameWidth=n fixes the column width to n characters wide. The minimum value allowed is 5.
- NameMinWidth=[n]
- The NameMinWidth keyword allows you to specify the minimum width that will always be reserved for the filename column in characters. The default setting is 15. The minimum value allowed is 5. If NameMinWidth is greater than NameWidth, then the filename column will have a length=NameMinWidth.
- ScanHTMLTitles
- This enables the extraction of the title from HTML documents for fancy indexing. If the file does not have a description given by AddDescription then the HTTP Server will read the document for the value of the TITLE tag. This is CPU and disk intensive.
- SelectiveDirAccess
- This option will cause the server to return directory listings only for directories that contain a wwwbrws file. The contents of wwwbrws file are not important. The server only checks for its existence. The object is a member name of an IBM i physical file or a type of object in an integrated file system directory. For case-sensitive file systems such as /QOpenSys, the wwwbrws name is lowercase. **SelectiveDirAccess is an AS400 specific option. This specific option works on a "per directory" basis, in other words you must specify the +/-SelectiveDirAccess on a Directory container.
- ShowForbidden
This option is new for Apache 2.2. If you use this option, Apache will show files normally hidden because the subrequest returned HTTP_UNAUTHORIZED or HTTP_FORBIDDEN.
- ShowOwner.
- This directive determines whether directory listings should include the owner ID for each file.
- SuppressColumnSorting
- If specified, the HTTP Server 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.
- SuppressDescription
- 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 AddDescription for information about setting the file description. See also the DescriptionWidth index option to limit the size of the description column. This option only has an effect if FancyIndexing is also enabled.
- SuppressHTMLPreamble
- If the directory actually contains a file specified by the HeaderName directive, the module usually includes the contents of the file after a standard HTML preamble (<HTML> <HEAD>). The SuppressHTMLPreamble option disables this behavior, 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.
- SuppressIcon
- This directive suppresses the display of icons on directory listings. The default is that no options are enabled.
- SuppressLastModified
- This directive will suppress the display of the last modification date, in fancy indexing listings. This option only has an effect if FancyIndexing is also enabled.
- SuppressRules
- This directive will suppress the horizontal rule lines (HR tags) in directory listings. Combining both SuppressIcon and SuppressRules yields proper HTML 3.2 output, which by the final specification prohibits IMG and HR tags from the PRE block (used to format FancyIndexed listings). This option only has an effect if FancyIndexing is also enabled.
- SuppressSize
- This directive will suppress the file size in fancy indexing listings. This option only has an effect if FancyIndexing is also enabled.
- TrackModified
- This returns the Last-Modified and ETag values for the listed directory in the HTTP header. It is only valid if the operating system and file system return appropriate stat() results. Once this feature is enabled, the client or proxy can track changes to the list of files when they perform a HEAD request. Changes to the size or date stamp of an existing file will not update the Last-Modified header on all Unix platforms. If this is a concern, leave this option disabled.
- Type=MIME content-type
- The Type keyword allows you to specify the MIME content-type of the generated page. The default
is text/html.
IndexOptions Type=text/plain
- UseOldDateFormat
- The date format used for the Last Modified field was inadvertently changed to "%Y-%m-%d %H:%M" from "%d-%b-%Y %H:%M" in Apache 2.4. Setting this option restores the date format from Apache 2.2 and earlier.
- VersionSort
- The VersionSort 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. For example:
- foo-1.73
- foo-1.7.2
- foo-1.7.12
- foo-1.8.2
- foo-1.8.2a
- foo-1.12
- foo-1.001
- foo-1.002
- foo-1.030
- foo-1.04
- XHTML
- The XHTML keyword forces mod_autoindex to emit XHTML 1.0 code instead of HTML 3.2. This option only has an effect if FancyIndexing is also enabled.
IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize
The net effect is equivalent
to IndexOptions FancyIndexing +SuppressSize, because the non-prefixed
FancyIndexing discarded the incremental keywords before it, but allowed
them to start accumulating again afterward. To unconditionally set
the IndexOptions for a particular directory, clearing the inherited
settings, specify keywords without either '+' or '-' prefixes.IndexOrderDefault
Module: mod_autoindex | |
Syntax: IndexOrderDefault [ ascending | descending ] [ name | date | size | owner | description ] [ CaseSense | NoCaseSense ] | |
Default: IndexOrderDefault Ascending Name CaseSense | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Modified | |
Example: IndexOrderDefault descending size |
The IndexOrderDefault directive is used in combination with the FancyIndexing index option. By default, FancyIndexed directory listings are displayed in ascending order by filename; the IndexOrderDefault allows you to change this initial display order.
IndexOrderDefault takes two required arguments and a third optional argument.
- Parameter One: ascending | descending
- The ascending and descending parameter indicates the direction of the sort.
- Parameter Two: name | date | size | owner | description
- The name, date, size, owner, and description parameter arguments must be used and identifies the primary key. The secondary key is always ascending filename.
- Parameter Three: CaseSense | NoCaseSense
- The CaseSense and NoCaseSense parameters are optional third keywords that allow you to choose if the column sort is case sensitive. This keyword is valid if the second keyword is name, owner or description only. If the second keyword is date or size, then this parameter is ignored. The default for keyword is CaseSense.
You can force a directory listing to only be displayed in a particular order by combining this directive with the SuppressColumnSorting index option; this will prevent the client from requesting the directory listing in a different order.
IndexStyleSheet
Module: mod_autoindex | |
Syntax: IndexStyleSheet url-path | |
Default: none | |
Context: Server, Virtual Host, Directory, .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: IndexStyleSheet "/css/style.css" |
The IndexStyleSheet directive sets the name of the file that will be used as the CSS for the index listing.
ReadmeName
Module: mod_autoindex | |
Syntax: ReadmeName filename | |
Default: none | |
Context: server config, virtual host, directory (but not location), .htaccess | |
Override: Indexes | |
Origin: Apache | |
Example: ReadMeName readme | |
Example: ReadMeName README.MBR |
The ReadmeName directive sets the name of the file that will be appended to the end of the index listing.
- Parameter: filename
- The filename parameter is the name of the file to include and is taken to be relative to the location being indexed. Details of how its handled may be found under the description of the HeaderName directive, which uses the same mechanism as ReadmeName.