How to enable custom error messages on the Zeus web server

How to enable custom error messages on the Zeus web server

This document describes how to configure the Zeus web server so that it will redirect common server errors - like 404 Not Found or 500 Internal Server Error - to a Perl CGI script for processing.

In order to configure Zeus error handling, you must:

1. Edit a ".htaccess" file in the root folder of your web site

Follow these steps to add a custom error page to Zeus:

1. Before you tweak Zeus, first make an initial request to your custom error page using its direct URL. Make sure it displays properly. If your error page is a Perl CGI script, and it is failing, then it will be very difficult to debug what is going on when other errors are redirected to it.

2. Some FTP servers and FTP client software do not allow the viewing or manipulation of files that begin with a dot, like ".htaccess". Some systems will allow you to upload files named ".htaccess", but once the file is on the server, the file won't appear in your file list and you won't be able to delete or rename it - which will be a problem if the .htaccess file makes your site inaccessible.

   So, first, create an empty file named ".foo". Upload it to your site. Will your FTP client software allow it? Will the FTP server accept it? Can you then rename and delete the file? If you have trouble with any of these operations, then you should not proceed to .htaccess. Instead contact your system administrator to see about getting the right software/settings for the job.

3. Before beginning, request a file from your website that doesn't exist, like www.foo.com/no_such_file. Observe the 404 Not Found error handling: do you see a plaintext file like "404 Not Found"? Or do you see a pretty error message that someone else has already customized, perhaps one specific to your web hosting company? Or are you redirected to a special file, like www.foo.com/404.html? You need to know what the baseline behavior is so that you can evaluate the behavior later after you start tweaking things.

4. Edit the file named ".htaccess" in the root folder of your web site. Create the file if necessary. Add the following lines, where the path "/cgi-bin/guardian/ag.pl" has been replaced with your path to your Perl script:

   ErrorDocument 401 /cgi-bin/guardian/ag.pl?401
   ErrorDocument 403 /cgi-bin/guardian/ag.pl?403
   ErrorDocument 404 /cgi-bin/guardian/ag.pl?404
   ErrorDocument 500 /cgi-bin/guardian/ag.pl?500

   Note that this is essentially the same syntax as on the Apache server, except that the error code is repeated in the query string. One consequence of this is that you are not able to see what the query string was on the original error page - if somebody requests "nothing.html?foo" then your error handler script will only record a 404 Not Found event on "nothing.html".

5. Upload the updated .htaccess file. Be sure to upload it in ASCII mode. Be sure to apply read permissions to the file (chmod 744).

6. Immediately after uploading, make a test request for any valid file on your site. If Zeus has been configured such that it doesn't allow overrides of the ErrorDocument directives, or if you are running an older version of Zeus that doesn't understand ErrorDocument, or if there is some error with your file, then all requests to your web site will fail!! You want to check whether there are problems with normal requests.

   If all normal requests fail after you updated the .htaccess file, immediately delete or rename it. If you had an obvious error, like misspelling ErrorDocument, then try to correct it and upload again. Otherwise check with your system administrators about whether your web site allows for custom error handling.

7. So, now the .htaccess file has been updated and uploaded, and normal requests work okay. Make a test request for a file that doesn't exist. One of four things will usually happen:

   1. You will be redirected to your custom error page. Yay!

   2. You will see the standard Zeus error message, or the behavior will be the same as whatever it was before you updated the .htaccess file (which you checked in step 3). If this happens, then you probably don't have the AllowOverride privilege, and you will have to bother your administrator.

   3. You will see something like this: "Not Found; The requested URL /scripts/guardian/test/a was not found on this server; Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request". This means that you need to review the path the follows "ErrorDocument 404" in your .htaccess file.

   4. You will see something similar, like this: "Not Found; The requested URL /scripts/guardian/test/a was not found on this server. Additionally, a 500 Internal Server Error error was encountered while trying to use an ErrorDocument to handle the request". This means that the Perl CGI script you have set up to handle errors has failed. You should go back and debug that script further. If you are using Guardian, use the "System Test" option from the Admin Page to exercise the error-handling code paths.