How to handle all requests with a fallback script in Apache 2.3

Sometimes websites need a standby webserver that tell visitors that a site is down for maintenance. In such times, it's often easiest not to depend on your favorite scripting language being available on the that standby server and use Apache's builtin capabilities to whip up some dynamic response.

Archief jeroenJeroen Pulles 18 oktober 2010

Here's a recipe that will sent all requests to a simple script. The Apache configuration sample below shows how to catch requests to some random URI and send a response with a simple CGI script. I use this to sent a 503 Service Unavailable response to all requests when a real website is down for maintenance and a stand-in website takes over.

ScriptAlias /down.cgi /var/www/
Action down-handler /down.cgi virtual

<LocationMatch "^/(?!down.cgi|favicon.ico).*$">
    SetHandler down-handler

Here's how Apache handles this configuration:

Now, the down.cgi script can be really simple. Here's the simple shell script that sets the special HTTP Status response code and the Retry-After header that usually goes with it. The error message is in a simple HTML file, where 'cat' is used to send that file to the user agent. Oh, and don't forget to mark the file as executable, i.e. “$ chmod a+x down.cgi”.


echo "Status: 503 Service Unavailable"
echo "Retry-After: 2400"
echo "Content-Type: text/html; charset=utf-8"

cat htdocs/technical-difficulties.html

Note that I'm not using mod_rewrite, I'm using just a few stock Apache modules. The Action directive is available in mod_actions, that was introduced long ago with Apache 2 but hasn't seen much take up;

If you're more inclined to use PHP, you could also have dropped a PHP file at for example /down.php and have the Action handler point to that. No need to use the ScriptAlias then. And there's a performance advantage since Apache won't have to fork a shell script, it can use the PHP interpreter it already has built-in.

You probably spotted the favicon.ico exception in the regular expression. I like to keep sending the favicon in any case, since that has become one of the strongest, well, icons, or flagpoles in a webpage. If that favicon is gone, things really start to feel as if something's wrong on the website. But perhaps I'm just being silly.

Learn more about this Apache feature at Apache Module mod_actions.

More advanced examples of shell scripting can be found in Mendel Cooper’s Advanced Bash-Scripting Guide .

How to handle all requests with a fallback script in Apache 2.3