NCSA HTTPd Directory Indexing

NCSA HTTPd provides a directory indexing format which is similar to that which will be offered by the WWW Common Library. To set up this indexing, follow these steps.

For an example of what these indexes look like, take a look at the demo.

Activating Fancy Indexing

You first need to tell HTTPd to use the advanced indexing instead of the simple version. The simple version should be used if you prefer its simplicity, or if you are serving files off of a remote file server, for which the stat() call would be costly. You tell the server which you want to use with either the IndexOptions directive, or the older FancyIndexing directive. We recommend: 

IndexOptions FancyIndexing

Choosing Icons

NCSA HTTPd comes with a number of icons in the /icons subdirectory which are used for directory indexing. As of 1.5, NCSA HTTPd comes with color versions of all of the icons. The .xbm files are black&white and the .gif files are color. The first thing you should do is make sure your Server Resource Map has the following line in it:

Alias /icons/ /usr/local/etc/httpd/icons/

You should replace /usr/local/etc/httpd/ with whatever you set ServerRoot to be.

Next, you need to tell the server what icons to provide for different types of files. You do this with the AddIcon and AddIconByType directives. We recommend something like the following setup:

AddIconByType (IMG,/icons/image.gif) image/*
AddIconByType (SND,/icons/sound.gif) audio/*
AddIconByType (TXT,/icons/text.gif) text/*
This covers the three main types of files. If you want to add your own icons, simply create the appropriately sized image, place it in /icons, and choose a 3-letter ALT identifier for the type.

HTTPd also requires three special icons, one for directories, one which is a blank icon the same size as the other icons, and one which specifies the parent directory of this index. To use the icons in the distribution, use the following lines in srm.conf:

AddIcon /icons/menu.xbm ^^DIRECTORY^^
AddIcon /icons/blank.xbm ^^BLANKICON^^
AddIcon /icons/back.xbm ..
However, not all files fit one of these types. To provide a general icon for any unknown files, use the DefaultIcon directive:

DefaultIcon /icons/unknown.xbm

Adding Descriptions

If you want to add descriptions to your files, use the AddDescription directive. For instance, to add the description "My pictures" to /www/my/images, use the following line:

AddDescription "My pictures" /www/my/images/*
If you want to have the titles of your HTML documents displayed for their descriptions, use the IndexOptions directive to activate ScanHTMLTitles:

IndexOptions FancyIndexing ScanHTMLTitles
WARNING: You should only use this option if your server has CPU time to spare!!! This is a costly operation!

Ignoring Items

Generally, you don't want HTTPd sending references to certain files when it's creating indexes. Such files are emacs autosave and backup files, HTTPd's .htaccess files, and perhaps any file beginning with . (if you have a gopher or FTP server running in that directory as well). We recommend you ignore the following patterns: 

IndexIgnore */.??* */README* */HEADER*
This tells HTTPd to ignore any file beginning with ., and any file starting with README or HEADER.

Creating READMEs and HEADERs

When HTTPd is indexing a directory, it will look for two things and insert them into the index: A HEADER, and a README. Generally, the HEADER contains an HTML <H1> tag with a title for this index, and a brief description of what's in this directory. The README contains things you may want people to read about the items being served.

HTTPd will look for both plaintext and HTML versions of HEADERs or READMEs. If we add the following lines to srm.conf: 

ReadmeName README
HeaderName HEADER
When HTTPd is indexing a directory, it will first look for HEADER.html. If it doesn't find that file, it will look for HEADER. If it finds neither, it will generate its own. If it finds one, it will insert it at the beginning of the index. Similarly, the server will look for README.html, then README to insert a trailer for the document.

[Back] Return to the tutorial index
NCSA HTTPd Development Team / httpd@ncsa.uiuc.edu / 9-27-95