WHAT:  web-errors - a web server error-handler package.
WHICH: 2.8
WHO:   Miles O'Neal  <miles.oneal@gmail.com>  http://www.rru.com/~meo/
WHEN:  13 Oct 2017

The errors script is a non-parsed headers CGI 1.1 script for
handling errors in servers derived from NCSA httpd 1.4
or which incorporate its ErrorDocument feature (as does the
Apache server since release 1.1).  This script tries to stick
with standards as much as possible, so it *may* work with other
standard-compliant web servers as well, but there are no
guarantees.

To use this, you need something like the following entries
in your srm.conf (server resource management configuration)
file:

    ErrorDocument 302 /cgi-bin/errors
    ErrorDocument 303 /cgi-bin/errors
    ErrorDocument 400 /cgi-bin/errors
    ErrorDocument 401 /cgi-bin/errors
    ErrorDocument 403 /cgi-bin/errors
    ErrorDocument 404 /cgi-bin/errors
    ErrorDocument 408 /cgi-bin/errors
    ErrorDocument 410 /cgi-bin/errors
    ErrorDocument 413 /cgi-bin/errors
    ErrorDocument 500 /cgi-bin/errors
    ErrorDocument 501 /cgi-bin/errors
    ErrorDocument 503 /cgi-bin/errors

WARNING ABOUT 302:  If you are using imagemaps, you may not be able to
use 302.

--------------------------------------------------------------------------

ERROR CODES

Error codes continue to proliferate with standards.  Not all error
codes are returned by all servers, and some may never be seen outside
the standards documents.  This package currently supports the most
common codes.   We don't mess with 20X codes, since these return the
requested document! The following codes were valid as of 22 Oct 1999.

Supported error codes (coverage varies by EML):

    302: temporary redirect ("found" under HTTPD 1.1 draft 3) [See Note!]
    303: See Other
    307: Temporary Redirect
    400: bad request
    401: unauthorized (requires authentication)
    403: forbidden (unspecified reason)
    404: not found
    406: Not Acceptable
    408: Request Timeout
    410: Gone
    413: Request Entity Too Large
    417: Expectation Failed
    500: internal server error
    501: not implemented
    502: bad gateway
    503: service temporarily unavailable
    504: Gateway Timeout
    505: HTTP Version Not Supported
    505: Variant Also Varies

Other error codes:

    300: Multiple Choices
    301: Permanent Redirect
    304: Not Modified
    305: Use Proxy
    402: Payment Required
    405: Method Not Allowed
    407: Proxy Authentication Required
    409: Conflict
    411: Length Required
    412: Precondition Failed
    414: Request-URI Too Long
    415: Unsupported Media Type
    416: Requested Range Not Satisfiable

Note: Prior to HTTP 1.1, redirects were handled only by 301 (permanent)
or 302 (temporary) codes.  But since 302 was overloaded, HTTP 1.1 changed
302 to be a FOUND code that always redirects with no user intervention.
The old 302 behavior is now handled by 303 (See Other) or 307 (Temporary
Redirect).  The 303 is not cacheable; the 307 is. [See HTTP 1.1 docs for
details.]

--------------------------------------------------------------------------

Error Message Libraries

EMLs provide routines to handle error codes.  For
codes that generate HTTP directives, a routine
called "http()" must be provided.  http() takes one
argument - the list hash for its error code.  The
actual HTML for each error code is handled through
a routine called "Html()", which takes the same
argument as http().

The default routines simply reference hashed lists
for the codes.  To change a message, change the
value for the appropriate code; for instance to change
the message for code "401 Unauthorized", look for the
following entries

   $http{401} = "...";
   $html{401} = "...";

and change them.  NOTE - not all requests will have an
"http" entry.

The haiku EML allows for the random picking between multiple
responses; in this case you are dealing with entities like:

   $h404[0] = "...";
   $h404[1] = "...";
   $h404[1] = "...";
   $h404[1] = "...";
   $html{404} = $h404[(rand() * 4) % 4];

To add a new entry, you must also add it to the %has_dir
array in the "errors" script.

The default EML, err-basic.pl, should be usable
for most sites, but feel free to customize it as your
own default.

For comparison, the Roadkills-R-Us errors file with
smart-aleck responses is also included, in err-www.rru.com.pl .

The easiest way to create a new EML is to copy an
existing one and modify it to your heart's content.

A server-specific EML *must* be in the correct directory (as specified
in $err_lib in the main errors script), and *must* be named
"err-SERVER_NAME.pl", where SERVER_NAME is the server name specified
in your httpd.conf (httpd daemon configuration) file.  If you have
multiple, virtual servers, specify the ServerName for the server you
want this EML to work with.

If the errors script cannot find an error file for a given server, it
will use the default file.  If it cannot find the default file, it will
fail catastrophically.

Each EML needs to include a variable "$unknown_msg" containing the
message to output when an unknown CODE is encountered.

--------------------------------------------------------------------------


Site Maps (Logos, etc)

Site logo & url mapping - If you want a logo displayed on the error
pages and/or a custom "home" page URL, create entries in the "site_map"
file.  See the example "site_map" file for instructions.

--------------------------------------------------------------------------


Page & Link Colors

The errors script includes a routine named common_html which
spits out all the common HTML (duh!) to start the page,
including the BODY tag.  Each EML includes a default BODY
tag which can be modified to suit your color preferences.

If you need more customization than this, you need to remove
common_html from "errors" and duplicate it in each EML, making
changes as necessary.

The current tag is defined in the EML variable $body_tag
such as:

    $body_tag = '<BODY BGCOLOR="#cc0000" TEXT="#ffffff"\n    LINK="#00ff00" ALINK="#ffff00" VLINK="#00ffcc">';


Check the output by setting variables and running the script
from the shell, or by requesting a URL which will generate the
desired message.
