[Chapter 24] 24.6 Directory Indexing
Author: Stephen Spainhour and Valerie Quercia
Date: Fri Aug 29 18:23:59 1997

#

| Chapter 24 CERN Server Configuration |

## 24.6 Directory Indexing

This section discusses the directives used to determine exactly how the server will respond when a user makes a directory request.

###

#### AddBlankIcon

`AddBlankIcon` icon_path

Specifies an icon that is the same size as the other directory index icons, but is entirely transparent, i.e., a blank icon. This is used to properly align the column headings with the columns of information in the file listing.

#### AddDirIcon

`AddDirIcon` icon_path alt_text

Specifies an icon to be used for subdirectories in a file listing. The second argument specifies alternate text for the icon. For example:

    AddDirIcon /icons/directory.xbm   DIR

#### AddIcon

`AddIcon` icon_path alt_text mime_type

Specifies an icon and alternate text to be associated with a given MIME type or encoding of a file in a directory listing. For example, to use the icon /icons/compass.gif and the alt text "MAP" for Netcarta webmaps (MIME type application/webmap), use the following setting:

    AddIcon /icons/compass.gif MAP application
    /webmap

The CERN server does have some default icon mappings (and includes the icons with the server distribution), but these are all wiped out if you use `AddIcon` directives to add mappings of your own.

#### AddIconToStd

`AddIconToStd` icon_path alt_text mime_type

The `AddIconToStd` directive acts just like `AddIcon`, except that your icons augment the mapping list rather than replace it.

#### AddParentIcon

`AddParentIcon` icon_path alt_text

The `AddParentIcon` directive specifies an icon and alt text for the parent directory ("..") in a directory listing. For example:

    AddParentIcon /icons/back.xbm UP

#### AddUnknownIcon

`AddUnknownIcon` icon_path

The `AddUnknownIcon` directive specifies an icon to be used for files of unknown type or encoding.

#### AlwaysWelcome

`AlwaysWelcome` On|Off

Specifies whether requesting a directory without its trailing slash returns a directory listing or a "welcome" document (see the `Welcome` directive). The default is `On`, in which case the "welcome" document is returned whether or not the trailing slash is included.

#### DirAccess

`DirAccess` On|Off|Selective

Specifies whether, and under what conditions, the server should generate its own directory indices. Options are:

`On`

  The server may build an index for any requested directory. (Default)

`Off`

  The server may never build a directory index.

`Selective`

  Allows you to pick and choose which directory the server may index and which it will not. The server will first look in the directory for a file named www_browsable. If this file exists, regardless of size or contents, the server is allowed to generate an index for the directory. If the file is not present, the server generates a `403` (`Access Denied`) error. There is no provision for changing the name of this file.

#### DirAddHref

`DirAddHref` filename suffix

Links a resource to the icon of specified file types in a file listing. For example, you could have an icon reference a CGI script on your server that could unpack the contents of a listed tar file and return a listing of the archive:

    DirAddHref /cgi-bin/untar .tar

#### DirReadme

`DirReadme` Top|Bottom|None

When a directory index is generated, the server looks in the directory being indexed for a file named README. If this file exists, its contents are included in the directory index as an explanation of the contents of the directory. The `DirReadMe` directive specifies if and where this file should be included. Values are:

`top`

  Include the file before the file listing

`Bottom`

  Include the file after the file listing

`None`

  Don't include the file at all

#### DirShowBrackets

`DirShowBrackets` On|Off

Specifies whether alternate text of MIME type descriptions will have square brackets around them. The default setting is:

    DirShowBrackets On

which means the descriptions will be placed within brackets. If icons are not included, this directive has no effect.

#### DirShowBytes

`DirShowBytes` On|Off

Specifies whether file size should be shown in a file listing when sizes are turned on with `DirShowSize`.

#### DirShowCase

`DirShowCase` On|Off

Determines whether the server notices case when ordering the files for the listing. If case is noticed, then all files with uppercase names will be listed before their lowercase neighbors (i.e., normal ls order). If case is not noticed, upper- and lowercase names will be interleaved. The default setting is `Off`.

#### DirShowDate

`DirShowDate` On|Off

Specifies whether the last-modified time should be included for each file.

#### DirShowDescription

`DirShowDescription` should

Specifies whether a description of the file should be shown in a directory listing. The server looks for a file named .www_descript in the directory to act as a description database. The format of this database is one entry per line, where an entry consists of the word "DESCRIBE," the filename or template, and the description, with whitespace acting as the delimiter. Here are some example entries:

    DESCRIBE    techspecs.html technical docs
    DESCRIBE    adcopy.html    advertising copy

#### DirShowGroup

`DirShowGroup` On|Off

Specifies whether the group of the file should be included. The group name is used if it is available; otherwise, the group id is used. The default is `Off`.

#### DirShowHidden

`DirShowHidden` On|Off

Specifies whether hidden files (i.e., those whose names begin with ".") should be included in the file listing. The default is `Off`.

#### DirShowIcons

`DirShowIcons` On|Off

Specifies whether icons indicating the MIME types of the files should be included on each line. The default is `On`.

#### DirShowMaxDes...

`DirShowMaxDescrLength` length

If descriptions of the files in a listing are shown, the length of the description is determined by the number of characters specified with the `DirShowMaxDescrLength` directive. The default is 25.

#### DirShowMaxLength

`DirShowMaxLength` length

Specifies the maximum number of characters used for filenames in a listing. The file listing will always use at least the minimum number of characters (from `DirShowMinLength`), but will never show more than the maximum, truncating filenames that are too long. The default is 25.

#### DirShowMinLength

length The

Specifies the minimum number of characters used for filenames in a listing. The default is 15.

#### DirShowMode

`DirShowMode` On|Off

Specifies whether permissions of the file should be included. The mode is written in mnemonic form, such as "`rw-rw-rw-`", rather than numeric form, such as "`666`". The default is `Off`.

#### DirShowOwner

`DirShowOwner` On|Off

Specifies whether the owner of the file should be included in the directory listing. The user name is used if it is available; otherwise, the user id is used. The default is `Off`.

#### DirShowSize

`DirShowSize` On|Off

Specifies whether the size should be included for each file in a listing. The default is `On`.

#### IconPath

`IconPath` prefix

Specifies a server path prefix to be attached to all icon paths. For example, for the `Add*Icon` directives, the /icons/ part of the filenames could have been left off the icon path by adding the following line before them in the configuration file:

    IconPath /icons/

Remember that this will be prefixed to every path, so only use it if you are sure that you will put all of your icons within a single directory or tree.

#### Welcome

`Welcome` filename

Specifies the name of the file in a directory to use when a directory is requested rather than a specific document. If multiple `Welcome` directives are specified, they are searched for in order, and the first one located is returned. By default, the files are Welcome.html, welcome.html, and index.html.

Script Configuration |  | Access Control Configuration