Apache HTTP Server Version 2.2
Apache HTTP Server Version 2.2
This document refers to a legacy release (2.2) of Apache httpd. The active release (2.4) is documented here. If you have not already upgraded, please follow this link for more information.
You may follow this link to go to the current version of this document.
Additional functionality allows webmasters to configure the response of Apache to some error or problem.
Customizable responses can be defined to be activated in the event of a server detected error or problem.
If a script crashes and produces a "500 Server Error" response, then this response can be replaced with either some friendlier text or by a redirection to another URL (local or external).
NCSA httpd 1.3 would return some boring old error/problem message which would often be meaningless to the user, and would provide no means of logging the symptoms which caused it.
The server can be asked to:
Redirecting to another URL can be useful, but only if some information can be passed which can then be used to explain and/or log the error/problem more clearly.
To achieve this, Apache will define new CGI-like environment variables:
REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
image/jpeg
REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
9000/712)
REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=ooh.ahhh.com
REDIRECT_SERVER_NAME=crash.bang.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
REDIRECT_URL=/cgi-bin/buggy.pl
Note the REDIRECT_ prefix.
At least REDIRECT_URL and
REDIRECT_QUERY_STRING will be passed to the
new URL (assuming it's a cgi-script or a cgi-include). The
other variables will exist only if they existed prior to
the error/problem. None of these will be
set if your ErrorDocument is an
external redirect (anything starting with a
scheme name like http:, even if it refers to the same host
as the server).
Use of ErrorDocument is enabled
for .htaccess files when the
AllowOverride is set accordingly.
Here are some examples...
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 http://xxx/
ErrorDocument 404 /Lame_excuses/not_found.html
ErrorDocument 401 /Subscription/how_to_subscribe.html
The syntax is,
ErrorDocument <3-digit-code> <action>
where the action can be,
Apache's behavior to redirected URLs has been modified so that additional environment variables are available to a script/server-include.
Standard CGI vars were made available to a script which has been redirected to. No indication of where the redirection came from was provided.
A new batch of environment variables will be initialized
for use by a script which has been redirected to. Each new
variable will have the prefix REDIRECT_.
REDIRECT_ environment variables are created from
the CGI environment variables which existed prior to the
redirect, they are renamed with a REDIRECT_
prefix, i.e., HTTP_USER_AGENT becomes
REDIRECT_HTTP_USER_AGENT. In addition to these
new variables, Apache will define REDIRECT_URL
and REDIRECT_STATUS to help the script trace its
origin. Both the original URL and the URL being redirected to
can be logged in the access log.
If the ErrorDocument specifies a local redirect to a CGI
script, the script should include a "Status:"
header field in its output in order to ensure the propagation
all the way back to the client of the error condition that
caused it to be invoked. For instance, a Perl ErrorDocument
script might include the following:
...
print "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...
If the script is dedicated to handling a particular error
condition, such as 404 Not Found, it can
use the specific code and error text instead.
Note that the script must emit an appropriate
Status: header (such as 302 Found), if the
response contains a Location: header (in order to issue a
client side redirect). Otherwise the Location: header may
have no effect.
