Apache might be a great web server, but there is no doubt it can be a bit persnickety sometimes.

On one machine where I'm running Debian Stable (i.e. Sarge at the time of writing) and Apache 1.3.33 I wanted to install a Perl handler that would trap requests to a virtual host.

That's easy enough. If for example, your Perl handler package is MY::Handler, you just add:

       SetHandler perl-script
       PerlHandler MY::Handler

That's something that every Apache hacker knows. However, Apache just wouldn't invoke the handler. Bizarrely, the handler was invoked for any location except the root location, that is '/'. At the root location, I was getting a directory listing as specified by DocumentRoot.

Of course, I hit Google to try to find out if anyone has had the same problem. One person suggested that it only work if the root directory didn't exist. I tried this, but that just brought up a '404 Not Found' error.

I then tried Apache::ShowRequest. This shows the handlers used during each Apache request phase. Run against my installation it showed that, for some reason, Apache wasn't respecting the SetHandler directive. It was overriding it and setting the handler as a httpd/unix-directory. In accordance with this, Apache wasn't invoking my PerlHandler, but the mod_dir handler.

The solution was a little two-line fix-up handler. To invoke one you add this in the appropriate place in your httpd.conf:

PerlFixupHandler MY::FixupHandler

The fix-up handler itself is a tiny perl package that you is like this:

package MY::FixupHandler;

use Apache::Constants 'OK';

sub handler {
    my $r = shift;
    $r->set_handlers(PerlHandler => ['MY::Handler']);
    $r->content_type('perl-script');

    return OK;
}
1;

So that solved the problem. But why the problem is occurring in the first place I don't know. Anyone else know?