The Guardian is a CGI script which works closely with the Apache 1.1 and later webservers. When a visitor to your site attempts to view a document which does not exist, tries to access a restricted area and fails, or initiates a script error, the Apache Guardian awakes. He will provide the wayward visitor with helpful tips to get him back on track and, more importantly, will fire off a priority email to the site administrator alerting him of the error.

See a Demonstration on Restricted Access
See a Demonstration for Non-Existent Files
See a Demonstration for a Failed Script

View the Code (text file)
Download the Code and Instructions (zip file)

.
Help File for Apache Guardian

• Why Would I Want to Use the Guardian?
• System Requirements
• Installation and Configuration
• Trouble-shooting
• Copyright Information and Notification of Updated Versions
• Credits and Other Stuff

^
Why Would I Want to Use the Guardian?

Though there are excellent tools for tracking the details of legitimate visitors, these often require that the visitor view a real document. What about sites that link to files you've moved? Are you losing hundreds of hits every day because you renamed a file? Apache Guardian alerts you of the "backdoor" visitors who would otherwise go unnoticed.

On the security side, it's nice to know when the Internet community is trying to hack your .htaccess-protected directories, or subvert your CGI scripts with unhealthy input. And by letting them know that you know, you keep your site safe for everyone.

^
System Requirements

To run Apache Guardian, you'll need a web page that allows custom CGI, a webserver that is compatible with Apache version 1.1 (most are), and the ability to write custom .htaccess files.

If you don't have such a web page, they are available for a few dollars per month from hundreds of different companies. You can get an excellent full-service account from Illumanti Online for $10 per month. They are one of the best. If you need your own domain name and lots of storage space, Pair Networks works great. This account (xav.com) is hosted by Pair.

^
Installation and Configuration

This script is fairly easy to install. Download the guardian.cgi script and open it in a text editor. Enter your email address and the URL of your web page in spaces required. If you web page has an internal search engine, enter the full URL to that document. Note that if you do not have one, you can acquire an excellent, easy-to-set-up search engine from Matt Wright's Script Archive.

Once customized, transfer this script in ASCII format to your web server. Give the file read and execute permissions by typing "chmod 755 guardian.cgi" from the telnet prompt.

Next, test the script by pointing your web browser to it's URL. You should see the "Mysterious Reason" error message. Then go the URL with a "?401", "?404", and "?500" appended to the end of the URL. You should see the custom messages associated with those errors. Check your mail to make sure you're getting the error reports.

Finally, only after you've verified that the script works, download the .htaccess file and open it in a text editor. The file looks like this:

ErrorDocument 401 /guardian.cgi?401
ErrorDocument 404 /guardian.cgi?404
ErrorDocument 500 /guardian.cgi?500

If your Apache Guardian script is not the in the top-level directory for your domain, you'll have to customize this file. For example, if you've placed the Guardian at http://xav.com/~zoltan/cgi-bin/guardian.cgi, then your .htaccess file will look like:

ErrorDocument 401 /~zoltan/cgi-bin/guardian.cgi?401
ErrorDocument 404 /~zoltan/cgi-bin/guardian.cgi?404
ErrorDocument 500 /~zoltan/cgi-bin/guardian.cgi?500

Once customized, transfer the .htaccess file in ASCII format to your main web directory. If you already have an .htaccess file, you can add these three lines to the top of it. Your web site is now protected by the Apache Guardian. Woo-hoo!

^
Trouble-shooting

Because the .htaccess file calls the guardian.cgi script whenever there is a script error, there is the risk of infinite looping when the Guardian itself fails. We run the risk of the error-plagued script calling itself over and over again. For this reason, make sure that the script works before installing the .htaccess file. If the script later stops working, remove the .htaccess file (or at least the three relevant lines) before working on the code.

If you get a "malformed header" or "premature end of script headers" message, it may be because the script was transferred as a binary file at some point (which scrables the hidden end-of-line characters and confuses the server - always transfer scripts in ASCII format). If you open the file with Pico, create and delete a line, and then save it, the problem usually goes away.

The most common problem is to not have permissions set correctly. Make sure the script and .htaccess file are readable and executable by everyone (type "chmod 755 guardian.cgi" and "chmod 755 .htaccess").

In addition, when you open the file in a text editor to set the configurable options, the editor might wrap long lines, which will prevent the script from working. We've tried to make all the lines 70 characters or less but some long commands went over that limit. Scroll through the script and make sure that no commands have been interrupted in mid-line.

On the other hand, if the script works fine but errors are not being redirected to it, find out from your administrator whether you have an Apache 1.1 compliant webserver and, if so, whether you are allowed to create custom .htaccess files. Both answers must be yes for this to work.

Fluid Dynamics will provide free, limited support via email for this script. Send requests for assistance to noc@xav.com. Please include the relevant URLs in your message, and cut & paste the telnet response to the "perl -w guardian.cgi" command if possible. Note that we will not support nor respond to those operating sites whose material offends (adult sites & the like).

Custom installation is available at a reasonable rate; custom coding currently runs $40/hour and we have a it-works-or-its-free guarantee. Installing this script would take less than an hour.

^
Copyright Information and Notification of Updated Versions

Apache Guardian is freeware. There are no restrictions on its use (save for the U.S. export restrictions below), nor are any warranties made or implied about its durability or fitness for a particular purpose.

While use is unrestricted, distribution requires the consent of the copyright holder, Fluid Dynamics. For purposes here, installing Apache Guardian for your customers isn't considered distribution, but including it in an archive of freeware CGI scripts is. Just write to us and ask permission, we'll probably say yes.

To receive notification via email when an updated version is released, send an email message to noc@xav.com to that effect. To help drive new updates, please send any suggestions and bug reports to the same address.

^
Credits and Stuff

Please be advised: you must apply for a U.S. export license if you know this product will be used in the design, development, production, or use of chemical, biological or ballistic weapons, or in a facility engaged in such activities. Thank you for your assistance in keeping the world free of such weaponry.

For more information on customized error messages on the Apache web server, visit The Apache Server Project: Custom Error Messages.

Those who point out glaring errors in the code will receive mention in this section.