custom-error.html revision 57d0156f7bbd9ea3a72342cf9912aba61d118702
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <meta name="generator" content="HTML Tidy, see www.w3.org" />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <!--#include virtual="header.html" -->
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <h1 align="CENTER">Custom error responses</h1>
233c9bf946d6f3689b7901dfab3255300c873187Christian Maeder Additional functionality. Allows webmasters to configure
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder the response of Apache to some error or problem.
7fcb2e9d349608760b0c2c16a864c6f39d455383Christian Maeder <p>Customizable responses can be defined to be activated in
233c9bf946d6f3689b7901dfab3255300c873187Christian Maeder the event of a server detected error or problem.</p>
233c9bf946d6f3689b7901dfab3255300c873187Christian Maeder <p>e.g. if a script crashes and produces a "500 Server
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder Error" response, then this response can be replaced with
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder either some friendlier text or by a redirection to another
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder URL (local or external).</p>
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <dd>NCSA httpd 1.3 would return some boring old error/problem
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder message which would often be meaningless to the user, and
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder would provide no means of logging the symptoms which caused
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder The server can be asked to;
1ea4b86ab3f5a34824945e099176785070496d2dChristian Maeder <li>Display some other text, instead of the NCSA hard
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder coded messages, or</li>
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <p>Redirecting to another URL can be useful, but only if
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder some information can be passed which can then be used to
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder explain and/or log the error/problem more clearly.</p>
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <p>To achieve this, Apache will define new CGI-like
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_PATH=.:/bin:/usr/local/bin:/etc<br />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_QUERY_STRING=<br />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_REMOTE_ADDR=121.345.78.123<br />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_SERVER_PORT=80<br />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder </blockquote>
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <p>note the <code>REDIRECT_</code> prefix.</p>
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <code>REDIRECT_QUERY_STRING</code> will be passed to the
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder new URL (assuming it's a cgi-script or a cgi-include). The
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder other variables will exist only if they existed prior to
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder the error/problem. <strong>None</strong> of these will be
a51483c406bf549f85bc64e3c4ad37c3d994b691Christian Maeder set if your ErrorDocument is an <em>external</em> redirect
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder (<em>i.e.</em>, anything starting with a scheme name like
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder <code>http:</code>, even if it refers to the same host as
aa7cc6042ab7f01edc6a66d4f80951ed40562a27Christian Maeder the server).</p>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder Use of "ErrorDocument" is enabled for .htaccess files when
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder the <a href="mod/core.html#allowoverride">"FileInfo"
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder override</a> is allowed.
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder <code>ErrorDocument 500 /cgi-bin/crash-recover<br />
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder ErrorDocument 500 "Sorry, our script crashed. Oh
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder ErrorDocument 404 /Lame_excuses/not_found.html<br />
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder ErrorDocument 401
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder </blockquote>
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder href="mod/core.html#errordocument">ErrorDocument</a></code>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <3-digit-code> action</p>
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder <li>Text to be displayed. Prefix the text with a quote
cb1375e6805fbe42b931c54dcc37674193443267Christian Maeder ("). Whatever follows the quote is displayed. <em>Note:
80875f917d741946a39d0ec0b5721e46ba609823Till Mossakowski <h2>Custom error responses and redirects</h2>
6cebb023849767a177210a61b6d6a429cd82db61Christian Maeder <dd>Apache's behavior to redirected URLs has been modified so
6cebb023849767a177210a61b6d6a429cd82db61Christian Maeder that additional environment variables are available to a
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <dd>Standard CGI vars were made available to a script which
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder has been redirected to. No indication of where the
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder redirection came from was provided.</dd>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <dd>A new batch of environment variables will be initialized
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder for use by a script which has been redirected to. Each new
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder variable will have the prefix <code>REDIRECT_</code>.
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <code>REDIRECT_</code> environment variables are created from
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder the CGI environment variables which existed prior to the
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder redirect, they are renamed with a <code>REDIRECT_</code>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder new variables, Apache will define <code>REDIRECT_URL</code>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder and <code>REDIRECT_STATUS</code> to help the script trace its
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder origin. Both the original URL and the URL being redirected to
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder can be logged in the access log.</dd>
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder <p>If the ErrorDocument specifies a local redirect to a CGI
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder script, the script should include a "<samp>Status:</samp>"
6cebb023849767a177210a61b6d6a429cd82db61Christian Maeder header field in its output in order to ensure the propagation
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder all the way back to the client of the error condition that
4e14c1bc2b97679b84c6ad996fa11c273b74ea02Christian Maeder caused it to be invoked. For instance, a Perl ErrorDocument
233c9bf946d6f3689b7901dfab3255300c873187Christian Maeder script might include the following:</p>
845ccfe51a09dd310631b04ebeaf049c76afbf7eChristian Maeder printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
845ccfe51a09dd310631b04ebeaf049c76afbf7eChristian Maeder <p>If the script is dedicated to handling a particular error
776cda2886b69d564d3445422a31b099cb559e6cChristian Maeder condition, such as <samp>404 Not Found</samp>, it can
4f03aaa386ce5c7711269711c6d8e74024f7a5dfChristian Maeder use the specific code and error text instead.</p>
4f03aaa386ce5c7711269711c6d8e74024f7a5dfChristian Maeder <!--#include virtual="footer.html" -->