BIRDTRAP.CGI An error handler for the APACHE Server Version 1.0 released January 3, 1999 ################################################################## # (C)1999 Bignosebird.com # http://bignosebird.com/ # This software is FREEWARE! Do with it as you wish. It is yours # to share and enjoy. Modify it, improve it, and have fun with it! # It is distributed strictly as a learning aid and bignosebird.com # disclaims all warranties- including but not limited to: # fitness for a particular purpose, merchantability, loss of # business, harm to your system, etc... ALWAYS BACK UP YOUR # SYSTEM BEFORE INSTALLING ANY SCRIPT OR PROGRAM FROM ANY # SOURCE! ################################################################## OVERVIEW BIRDTRAP.CGI is a very simple script to use in conjunction with your APACHE server to both redirect readers that encounter errors such as script problems and missing pages, and to notify you that the error occurred by means of a log file or e-mail or both. This can make maintaining your site a much more pleasant task. In fact, if you make your error pages entertaining enough, people will enjoy running into problems. Along with this script you will also find a collection of GIF image files, one for each error code. The script is written for PERL 5, and is designed for unix servers. It will also run on Apache for Windows, except the e-mail notification feature will not work. CONTENTS In addition to this README.TXT file, you will also find with this archive: birdtrap.cgi: The actual script htaccess.txt: An example .htaccess file error000.gif: Unknown error graphic error400.gif: Bad Request graphic error401.gif: Authorization Required error403.gif: Forbidden Graphic error404.gif: Missing URL Graphic error500.gif: Server Configuration Error Graphic INSTALLATION This script is STEP 1: Installing the graphics (optional) ------------------------------------------ BIRDTRAP comes complete with a set of six 300H X 119W GIF images. One for each handled error code. You can copy these files into a directory such as "eimages" under your main HTML document directory. The script by default will look in "/eimages" for the graphic files. These images will not only make your readers forget they ran into a message, but also why they came to your site in the first place! STEP 2: Installing the script ----------------------------- Script installation is simple. If you are transfering the file from your PC to a unix server, FTP the birdtrap.cgi file as ASCII, all other files are to be sent using BINARY. All script configuration options are set in the subroutine set_params. To make the script operational you need only provide a few values: The $errorlog is the FULL unix path starting with / to the file to contain your error message log. This is NOT to be the same as your web server ERROR LOG! $errorlog="/usr/local/apache/share/cgi-bin/birdtrap.dat"; If you want e-mail messages sent to you, be sure to put your E-mail address in the $notify variable. Also, be certain you have a \ backslash before the @ (at) sign. $notify="your\@yourdomain.com"; $sitename is a descriptive name of your site, not a URL. $sitename="YourSite.Com"; After a user get's an error message, you can provide them with a link back to a valid page on your site using $returnlink. $returnlink="http://yoursite.com/"; If you are using images, give the full URL directory path to where the image files are stored using $imageurl. $imageurl="http://yoursite.com/eimages"; The two most common locations for sendmail are: $mailprog="/usr/sbin/sendmail -t"; $mailprog="/usr/lib/sendmail -t"; To pick one, remove the # sign from the start of the line for the proper one for your server. Place a # sign at the start of the line for the incorrect one. You will now see a section of code as follows. This is how we control which error codes result in e-mail being sent to you. By default, no e-mail is sent. If you are using APACHE on Windows- DO NOT ENABLE E-MAIL!!!!! As an example, if you want e-mail notification on Server Configuration Error (500), change the 'N' on the same line as 500 to 'Y'. That is all there is too it. %email=('000','N', '400','N', '401','N', '403','N', '404','N', '500','N'); This section of code works exactly like the email notification except by default, all errors are logged. To turn off logging of any item, just change the 'Y' to 'N' on the line(s) of your choice. %logem=('000','Y', '400','Y', '401','Y', '403','Y', '404','Y', '500','Y'); The rest of the editing deals with the HTML code that is presented to your reader when an error occurs. The text is stored between tags such as: $msg{'401'} =<<__401__; __401__ Do NOT disturb these lines or the script will fail. You may put any HTML text you wish between these tags. The only rule is that if you hardcode in an e-mail address, be sure to place a \ backslash before the @ sign. STEP 3: Editing or creating your .htaccess file or Editing your srm.conf file --------------------------------------------------- ***IMPORTANT*** If you add the lines below to either your srm.conf or .htaccess file and the script either does not work, or no pages appear, the system administrator must make certain that the AllowOveride option called FileInfo is set. You should try to obtain AllowOveride All on your directories. *************** The final step in setting up BIRDTRAP is to configure ErrorDocument on your server. You can place these entries in a .htaccess file of your main HTML directory, or if you have access to the master configuration files, srm.conf The exact entries are as follows. You may have to change the way you call a CGI script depending on your server setup, such as /cgi-local/fred/birdtrap.cgi?400, but DO NOT USE THE FULL URL SUCH AS http://yourdomain.com/cgi-bin/birdtrap.cgi?400 Doing so will cause the script to be unable to figure out the cause of the problem! ErrorDocument 400 /cgi-bin/birdtrap.cgi?400 ErrorDocument 401 /cgi-bin/birdtrap.cgi?401 ErrorDocument 403 /cgi-bin/birdtrap.cgi?403 ErrorDocument 404 /cgi-bin/birdtrap.cgi?404 ErrorDocument 500 /cgi-bin/birdtrap.cgi?500 IN CLOSING Happy New Year to all! Enjoy the script.