Making Our Own Indexes (Apache: The Definitive Guide, 3rd Edition)

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).

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

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.

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

local-url is the 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 IndexOptions is set, the server will generate its own listing of the directory. For example, if this is the specification:

DirectoryIndex index.html

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

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

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

A common technique for getting a CGI script to run immediately when a site is accessed is to declare it as the DirectoryIndex:

DirectoryIndex /cgi-bin/my_start_script

If this is to work, redirection to cgi-bin must have been arranged using ScriptAlias or ScriptAliasMatch higher up in the Config file.

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

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

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

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

<Directory /usr/www/APACHE3/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 contains:

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

The HTML document index.html contains:

<!DOCTYPE HTML PUBLIC "//-W3C//DTD HTML 4.0//EN"
<html>
<head>
<title>Index to Butterthlies Catalogues</title>
</head>
<body>
<h1>Index to Butterthlies Catalogues</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,000 111 222 3333
</br>
</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 used, 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/APACHE3/cgi-bin/mycgi to ... /htdocs/d*/hullo.cgi.

If you are using Unix and hullo.cgi isn't executable, remember to make it executable in its new home with the following:

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_ADDR=192.168.123.1 
QUERY_STRING= 
REMOTE_PORT=1080 
HTTP_USER_AGENT=Mozilla/4.0 (compatible; MSIE 5.0; Windows 98; DigExt) 
DOCUMENT_ROOT=/usr/www/APACHE3/site.ownindex/htdocs 
SERVER_SIGNATURE= 
HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-
excel, application/msword, application/vnd.ms-powerpoint, */* 
SCRIPT_FILENAME=/usr/www/APACHE3/site.ownindex/htdocs/d1/hullo.cgi 
HTTP_HOST=www.butterthlies.com 
REQUEST_URI=/d1/ 
SERVER_SOFTWARE=Apache/1.3.14 (Unix) 
HTTP_CONNECTION=Keep-Alive 
REDIRECT_URL=/d1/ 
PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/games:/usr/local/sbin:/usr/local/bin:/usr/
X11R6/bin:/root/bin:/usr/src/java/jdk1.1.8/bin 
HTTP_ACCEPT_LANGUAGE=en-gb 
HTTP_REFERER=http://www.butterthlies.com/ SERVER_PROTOCOL=HTTP/1.1 
HTTP_ACCEPT_ENCODING=gzip, deflate REDIRECT_STATUS=200 
REQUEST_METHOD=GET 
SERVER_ADMIN=[no address given] 
SERVER_ADDR=192.168.123.2 
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), 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 this:

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

If we select d4, we get this:

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 goodbye

This gives us the same three possibilities as before. It's worth remembering that using entries in .htaccess is much slower than using entries in the Config file. This is 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