O'Reilly Hacks
oreilly.comO'Reilly NetworkSafari BookshelfConferences Sign In/My Account | View Cart   
Book List Learning Lab PDFs O'Reilly Gear Newsletters Press Room Jobs  


APACHE HACK

Quick File Cataloging with mod_autoindex
You have a need to catalog thousands of documents (mp3s, text files, jpgs, etc), but you don't have the time or inclination to create a decent PHP/MySQL indexing system. Nor do you want to get into complicated cookie authentication systems that would allow you to restrict users by file types ("only special people can download mp3s", etc.). Finally, creating the catalog indexes by hand is not a happy thought.

Contributed by:
Morbus Iff
[03/14/03 | Discuss (1) | Link to this hack]

Prerequisites

  • A default installation of Apache and the ability to modify httpd.conf.
  • Access to create or modify an .htaccess file (optional).
  • Ability to create .htpasswd files for authentication (optional)

mod_autoindex controls the automatic indexes Apache will generate if you don't have an index.html, index.htm or similar self-loading HTML file (determined by DirectoryIndex) in the directory being browsed. There's a lot more power behind this module than the default display - you can control the initial sorting order, the descriptions of the files shown, and even include headers or footers (in either HTML or plain text).

Take the following example, for instance. This will add a descriptive blurb to all JPEG images and a different description for all PHP files. When Apache generates the index, it'll display our blurbage for each matching file.

 {{{
   <Directory "/usr/local/httpd/htdocs/files">
       Options Includes Indexes Multiviews
       AllowOverride All

       IndexOptions FancyIndexing
       AddDescription "This is a short description" *.jpg
       AddDescription "This is a description of questionable quality." *.php
   </Directory>
}}}

Of course, you don't have to use wildcards. You could just as easily describe each file individually:

 {{{
   AddDescription "Rufus is my hound, y0." hound.jpg
   AddDescription "My hound on a mound." mound.png
}}}

There's one problem, however, and that's description length. With the look and feel of Apache's auto index, the description could be cut off arbitrarily, or else the browser would scroll the description off screen, creating horizontal scrollbars.

One way to control this is with HeaderName and ReadmeName. These directives tell Apache what files to use as the header (controlled by HeaderName) and footer (controlled by ReadmeName) of a directory listing. By default, these files are HEADER.txt (or .html) and README.txt (or .html).

With that in mind, create HEADER.html:

 {{{
   <html>
   <head>
      <style type="text/css"><!--
         pre { font-size: 14px; font-family: times, serif; }
      --></style>
   </head>
   <body>
   <h1>Uberrific Directory Listings</h1>
}}}

The above example comes with a CSS tag that will make the generated listing a bit smaller and more compact. We can't completely change the generated HTML ourselves, but we can certainly use CSS to tweak it's appearance.

I'll also nudge our configuration a little:

 {{{
   <Directory "usr/local/httpd/htdocs/files">
      Options Includes Indexes Multiviews
      AllowOverride All

      IndexOptions FancyIndexing SuppressHTMLPreamble DescriptionWidth=*
      AddDescription "This is a <u>short</u> description" *.jpg
      AddDescription "This is a description of questionable quality." *.php
      AddDescription "Rufus is my hound, y0." hound.jpg
      AddDescription "My hound on a mound." mound.png
   </Directory>
}}}

Besides the fact that we've now added our own HTML header which makes the font smaller (via HEADER.html), we've also told Apache not to spit out it's normal header code (with SuppressHTMLPreamble). Our descriptions will no longer be truncated, since we've given ourselves unlimited length via DescriptionWidth (although we still have to worry about horizontal browser scroll bars).

You may also notice that we added an underline to one of our descriptions - including HTML within the AddDescription comes with no restrictions, but you do want to be careful about truncating. If you're not careful, the HTML code could be cut in half, distorting the rest of your page. In the above example, there's nothing to worry about since we've turned off truncating with DescriptionWidth. If you're worried about horizontal scrollbars, you could throw a <br /> tag or two to further control the length, or even use <br /> as the first thing in the AddDescription to make it appear on a new line, beneath the relevant file.

The downside is the sheer amount of files that could be shown in one listing. A thousand files in one directory can create a thumb-twirling load time as you wait for it to render. In that regard, you could break your files up into subfolders ("a", "b") - not only would organization improve but the load time on the individual indexes would decrease as well.

Adding user authentication based on file types is also easy:

 {{{
    AuthType basic
    AuthName "Morbus Only"
    AuthUserFile /usr/local/httpd/.htpasswd

    <Files *.mp3>
       Require user morbus
    </Files>
}}} 

Assuming we've added the "morbus" user to the AuthUserFile (by invoking the htpasswd shell utility), only that user will be able to download mp3s from the current directory, and any subdirectories beneath it. This makes a quick and easy authentication system, and it wouldn't be too hard to create a Perl script that worked with the Apache logfile to create trails of activity.

See also:


O'Reilly Home | Privacy Policy

© 2007 O'Reilly Media, Inc.
Website: | Customer Service: | Book issues:

All trademarks and registered trademarks appearing on oreilly.com are the property of their respective owners.