Sometimes you want to give users a wider selection of files to load. If you want to spiff up the default file listings that Apache returns when an index file is unavailable, you can generate fancy directory listings. Rich Bowen explains how.
When a user requests a directory without specifying a particular
file name, Apache attempts to serve up a default document. The
document served is determined by the directive
and is usually called
index.html. However, if that document is
not present, it is sometimes desirable to instead give a complete
directory listing, permitting the user to select a file.
Directory listings are generated by the module
which is compiled into Apache by default. Left to itself, it
generates an uninteresting file listing, but with the techniques
I'll show you in this article, you'll be able to make these
listings as fancy as you like.
If your directory does not have a
index.html in it, they you
will get a directory listing, ordered by date, in which each
filename is linked to that file for download. For each file,
you are also given the last modified date of the file, and
the size of the file.
There are a variety of default icons defined, so that different
file types have different icons associated with them. And there's
a link to the parent directory.
It's actually pretty nice, but there are some annoying things about
it. The directories are interspersed amoung the files, rather than
appearing at the top like most of us are used to. There's a
Description column, but there's nothing actually in that
column. And although files are alphabetically listed, the a's come
after the Z's, rather than with the A's.
Some of the problems can be solved with the directives available
For the full scoop on what you can do with
should see the documentation at
http://www.apache.org/docs/mod/mod_autoindex.html I'm working on
that while I work on this, so it should be a little more current
by the time you read this.
To the left of each file name in a file listing, there's a little
icon which presumably represents the type of file you're looking at.
There's a pretty good selection of image files to choose from, but
there are some file types missing, and occasionally you might
want to have your own images, rather than the ones that ship with
There are three directives with which you can rectify this
situation. These are the
AddIconByEncoding. They let you specify a particular icon
to be displayed, by file name, file type, or file encoding,
AddIcon lets you specify particular file names that should
be displayed with a particular icon. The syntax of this directive
AddIcon (ALT,/url/of/image.gif) filename
ALT is the alternate text to be displayed if the image does
filename can be a while file name, a wildcard, or some
portion of a file name, such as a file extension. Examples might be:
AddIcon (Image,/icons/image3.gif) .gif .jpg .png
AddIcon /images/tmp.jpg *~
AddIconByType is the preferred directive, as it lets you
specify an icon by mime type, rather than by file name. This
allows for matching entire categories of files, rather than having
to try to guess at file names.
AddIconByType (Image,/icons/image1.gif) image/*
AddIconByEncoding lets you specify the icon by the mime
encoding of the file. The syntax is the same as the other
directives, and the argument is a mime-encoding:
AddIconByEncoding /icons/compressed.gif x-compress
IndexOptions directive provides a list of options to set
various features of the index listing. These options don't
warrant their own directive, and so are lumped together here.
The syntax of the
IndexOptions directive is:
IndexOptions +option1 -option2 ...
Options marked with + will be included in the set of options, and
those marked with - will be ommitted. Note that if you forget the
+ or - in that list, the last item on the list is all that you
get. That is,
IndexOptions SuppressDescription ScanHTMLTitles
is exactly the same directive as
And, furthermore, it overrides all previous
that are already active. Don't forget the + and -!
I'm not going to go over all of the available options - see the
docs - but here are a few that I like.
Those of you that are used to a graphical representation of your
directories -- something like the Windows file explorer, for example --
are used to seeing the directories at the top of the listing,
and the files below that. The default Apache view is to have the
directories listed in the same alphabetic ordering as the files.
To override this behavior, use the
IndexOptions +FancyIndexing +FoldersFirst
Note that the
FancyIndexing option is necessary for several of the
options to work, including this one.
ScanHTMLTitles option, you can get a
description of each HTML file in a listing by looking in the
<TITLE> tag of each file. If you have written good HTML, this
will give a very good idea of what each file is, before the user downloads.
Note that in order to do this, Apache will need to open each file and
parse it looking for a title tag. This can take a long time, and
use up a lot of system resources.
An exceptionally useful feature of
mod_autoindex is the ability
to provide descriptions for your files, and have these descriptions
appear in the directory listing. This is accomplished with the
AddDescription directive. As with several of these directive,
you can specify exact file names, or you can give wild-cards to
indicate a group of files.
AddDescription "My dog" /images/fido.jpg
AddDescription "PNG images" *.png
If you are in the habit of using really long file descriptions,
or if you are using the
ScanHTMLTitles option above, you
might find that the space allocated to you for displaying a
description is insufficient. You can correct oft this with the
DescriptionWidth option. This is an option for the
IndexOptions directive. You can specify a particular
width, or you can specify ''*'', indicating that the field should
be wide enough to accomodate the largest description you
OK, one more. It may be desirable to display some informative
text at the top of a directory list. This may be information about
the files in the directory, or it might be administrative information
about the server. Or whatever. The
directives allow you to indicate a file that will be put
at the top or bottom (respectively) of the directory listing.
The argument for this directive is a filename stub. That means
that if you have:
and you have a file in that directory called
that file will be displayed as the readme file for that directory.
Another neat trick here is that you can use
IndexOptions +SuppressHTMLPreamble, putting
HTML in the header file to specify background, fonts, style
sheets, or whatever you use on the rest of your site, so that
the directory listing does not have to look like it does not
belong to the rest of your site.
In the cases where you have directory listings rather than
actual HTML pages,
mod_autoindex can make these listings look
exactly as you want them to, without having to generate custom
directory listing pages for each directory.
Thanks for your feedback on my articles, and thanks for reading.
Please drop me a note at ApacheToday@rcbowen.com if you
have questions, or suggestions of topics you'd like for me to
cover in future columns.