Custom Error Responses

Available Languages: en | - es | - fr | - ja | - ko | - tr

- -

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).

Behavior
Configuration
Custom Error Responses and Redirects

Behavior

- - -

Old Behavior

- - -

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.

- - -

New Behavior

- - -

The server can be asked to:

- -

Display some other text, instead of the NCSA hard coded - messages, or
redirect to a local URL, or
redirect to an external URL.

- -

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).

- -

Configuration

- - -

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,

- -

Text to be displayed. Prefix the text with a quote - ("). Whatever follows the quote is displayed. Note: - the (") prefix isn't displayed.
An external URL to redirect to.
A local URL to redirect to.

Custom Error Responses and Redirects

- - -

Apache's behavior to redirected URLs has been modified so - that additional environment variables are available to a - script/server-include.

- -

Old behavior

- - -

Standard CGI vars were made available to a script which - has been redirected to. No indication of where the - redirection came from was provided.

- - -

New behavior

- - -

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.

- -