Making Our Own Indexes (Apache: The Definitive Guide)

In the last section, we looked at Apache's indexing facilities. So far we have not been very adventurous with our own indexing of the document root directory. We replaced Apache's adequate directory listing with a custom-made .html file: index.html (see Chapter 3, "Toward a Real Web Site").

We can improve on index.html with the DirectoryIndex command. This command specifies a list of possible index files to be used in order.

7.2.1. DirectoryIndex

DirectoryIndex local-url local-url ...
Default: index.html
Server config, virtual host, directory, .htaccess

The DirectoryIndex directive sets the list of resources to look for when the client requests an index of the directory by specifying a "/" at the end of the directory name. local-url is the (%-encoded) URL of a document on the server relative to the requested directory; it is usually the name of a file in the directory. Several URLs may be given, in which case the server will return the first one that it finds. If none of the resources exists and Options Indexes is set, the server will generate its own listing of the directory. For example, if the specification is:

DirectoryIndex index.html

then a request for http://myserver/docs/ would return http://myserver/docs/index.html if it exists, or would list the directory if it did not. Note that the documents do not need to be relative to the directory:

DirectoryIndex index.html index.txt /cgi-bin/index.pl

would cause the CGI script /cgi-bin/index.pl to be executed if neither index.html or index.txt existed in a directory.

The Config file from ... /site.ownindex is as follows:

User webuser
Group webgroup
ServerName www.butterthlies.com
DocumentRoot /usr/www/site.ownindex/htdocs
AddHandler cgi-script cgi
Options ExecCGI indexes

<Directory /usr/www/site.ownindex/htdocs/d1>
DirectoryIndex hullo.cgi index.html goodbye
</Directory>

<Directory /usr/www/site.ownindex/htdocs/d2>
DirectoryIndex index.html goodbye
</Directory>

<Directory /usr/www/site.ownindex/htdocs/d3>
DirectoryIndex goodbye
</Directory>

In ... /htdocs we have five subdirectories, each containing what you would expect to find in ... /htdocs itself, plus the following files:

hullo.cgi
index.html
goodbye

The CGI script hullo.cgi is:

#!/bin/sh
echo "Content-type: text/html"
echo
env
echo Hi there

The HTML script index.html is:

<html>
<body>
<h1>Index to Butterthlies Catalogs</h1>
<ul>
<li><A href="catalog_summer.html">Summer catalog </A>
<li><A href="catalog_autumn.html">Autumn catalog </A>
</ul>
<hr>
<br>
Butterthlies Inc, Hopeful City, Nevada 99999
</body>
</html>

The text file goodbye is:

Sorry, we can't help you. Have a nice day!

The Config file sets up different DirectoryIndex options for each subdirectory with a decreasing list of DirectoryIndex (es). If hullo.cgi fails for any reason, then index.html is run, and if that fails, we have a polite message in goodbye.

In real life, hullo.cgi might be a very energetic script that really got to work on the clients -- registering their account numbers, encouraging the free spenders, chiding the close-fisted, and generally promoting healthy commerce. Actually, we won't go to all that trouble just now. We will just copy the file /usr/www/mycgi to ... /htdocs/d*/hullo.cgi. If it isn't executable, we have to remember to make it executable in its new home with:

chmod +x hullo.cgi

Start Apache with ./go and access www.butterthlies.com. You see the following:

Index of /

. Parent Directory
. d1
. d2
. d3
. d4
. d5

If we select d1, we get:

GATEWAY_INTERFACE=CGI/1.1
REMOTE_HOST=192.168.123.1
REMOTE_ADDR=192.168.123.1
QUERY_STRING=
DOCUMENT_ROOT=/usr/www/site.ownindex/htdocs
HTTP_USER_AGENT=Mozilla/3.0b7 (Win95; I)
HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
SCRIPT_FILENAME=/usr/www/site.ownindex/htdocs/d1/hullo.cgi
HTTP_HOST=www.butterthlies.com
SERVER_SOFTWARE=Apache/1.1.1
HTTP_CONNECTION=Keep-Alive
HTTP_COOKIE=Apache=192287840536604921
REDIRECT_URL=/d1/
PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
HTTP_REFERER=http://192.168.123.2/
SERVER_PROTOCOL=HTTP/1.0
REDIRECT_STATUS=200
REQUEST_METHOD=GET
SERVER_ADMIN=[no address given]
SERVER_PORT=80
SCRIPT_NAME=/d1/hullo.cgi
SERVER_NAME=www.butterthlies.com
have a nice day

If we select d2 (or disable ... /d1/hullo.cgi somehow), we should see the output of ... /htdocs/d1/index.html:

D2: Index to Butterthlies Catalogs

* catalog_summer.html
* catalog_autumn.html

Butterthlies Inc, Hopeful City, Nevada 99999

If we select d3, we get:

Sorry, we can't help you. Have a nice day!

If we select d4, we get:

Index of /d4 
. Parent Directory 
. bath.jpg 
. bench.jpg 
. catalog_autumn.html 
. catalog_summer.html 
. hen.jpg 
. tree.jpg

In directory d5, we have the contents of d1, plus a .htaccess file that contains:

DirectoryIndex hullo.cgi index.html.ok goodbye

This gives us the same three possibilities as before. It may be worth remembering that using entries in .htaccess is much slower than using entries in the Config file, because the directives in the ... /conf files are loaded when Apache starts, whereas .htaccess is consulted each time a client accesses the site.

Generally, the DirectoryIndex method leaves the ball in your court. You have to write the index.html scripts to do whatever needs to be done, but of course, you have the opportunity to produce something amazing.

7.2. Making Our Own Indexes

7.2.1. DirectoryIndex