dmy

mod_autoindex

written by admin 320 days ago. Last update at 2010-04-07 09:02:31. Categories admin, apache httpd. Tags .

mod_autoindex is a plugin for the the Apache web server. The plugin is responsible for presenting the contents of a folder if folder browsing has been enabled and if a default file, traditionally index.html, is not available.

So far so good except that the default presentation generated by mod_autoindex is rather boring. We want to have it a bit more spicy. Therefore mod_autoindex has a lot of applicable options which are crying to be used.

Apache’s webserver has got a reputation of being difficult to configure and mod_autoindex is actually a perfect example for this claim. I don’t judge the software here as such, in my opinion, it’s rather about the documentation. As a teaser, you might wonder what mod_autoindex generates by default? This is what get generated for a folder containg just a file and just a subfolder:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
 <head><title>Index of /js</title></head>
 <body>
<h1>Index of /js</h1>
<ul><li><a href="/"> Parent Directory</a></li>
<li><a href="file"> file</a></li>
<li><a href="folder"> folder</a></li>
</ul>
</body>
</html>

Let’s go one step further and take how to apply index options as an example. Index options can be used on a server config level or within a directory tag. In other words, you may have an httpd.conf file looking partially like

IndexOptions XHTML
IndexOptions HTMLTable
<directory />
 IndexOptions HTMLTable
</directory>

The overall question is: what do we get by this?. Obviously we try to enable XHTML and we try to enable the generation of a table instead of the unordered list (<ul>). But that’s not what we get. What we get is the html table rendered in plain HTML 3.2. How does this come?

It appears, and the documentation really needs to be more explicit on this, that index options are handled quite differently if they are encountered within a directory tag (<directory />) or on the top level. When processing the configuration, Apache first calculates the value on the server config level. This is simply done by accumulating all index options into a list. For example, if there is IndexOptions X and somewhere later a IndexOptions Y, then we end up in a list like {X, Y}.. This is probably what you expect.

The server config value calculated is then applied to the root directory (/). If no directory tags are present, this is then the value applied.

If a directory tag for path /foo/bar is present, the value is calculated in two steps. In step one, the value is inherited from directory /foo which in turn will get its value from /. In step two, index options found within the directory tag are applied in an incremental fashion.

Incremental index options are applied like this: if the options starts with a plus sign, the option’s value gets added to the list value. If it starts with a dash, the option’s value will be removed from the list. If neither plus not dash, the current list value is erased and the new list value will be the value of index option under investigation.

So, let’s have again a look at our configuration:

IndexOptions XHTML
IndexOptions HTMLTable
<directory />
 IndexOptions HTMLTable
</directory>

The calculated index option valaue after having processed the server config level before digging into the directory tag is {XHTML, HTMLTable}. Then directory / is processed by inheriting {XHTML, HTMLTable} followed by applying incremental rules. Therefore the final value is cleared and replaced by {HTMLTable}.

Notice on the other hand that incremental options on top level do not work at all:

IndexOptions +XHTML
IndexOptions +HTMLTable

This has just no effect. Incremental options on top level are silently ignored.

In summary it’s mainly Apache’s documentation doing a bad job here:

  • The documentation does not state what we have to expect if no options are applied
  • It is not clear at all how options are processed. Lots of other weired behaviours could have been implemented.
  • It is rather bad to use the same identifier (IndexOptions) for a different behaviour. If so this should be clearly documented

I like to dwell in a bit on the last point. From a legacy point of view, older version of Apache supported non-incremental index options. Starting with Apache 1.3, incremental index options were added. So suddenly we can have index options that start with a plus character, or a dash or with extra character. Then someone decided that the absence of a character means erase. That conflicts of course with the legacy meaning where the absence of a character means actually +.

It would have been much better to define the absence of a character as use the default character and to use a third character for replacing. Such a character could have been =. Then we would end up in those rules, regardless whether on a server config level or within a directory:

  • If an index options starts with + then it’s value is added.
  • If an index options starts with - then it’s value is removed.
  • If an index options starts with = then it’s value replaces the calculated value so far
  • Otherwise: treat the option as if the value starts with +.