custom-error.html revision 3c4b33ebec75a9564c03067d22c0ea4481aff1e2
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<!--#include virtual="header.html" -->
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<DD>Additional functionality. Allows webmasters to configure the response of
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowenApache to some error or problem.<BR>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<P>Customizable responses can be defined to be activated in the event of a
a78048ccbdb6256da15e6b0e7e95355e480c2301ndserver detected error or problem.<BR>
a78048ccbdb6256da15e6b0e7e95355e480c2301nde.g. if a script crashes and produces a "500 Server Error" response, then
a78048ccbdb6256da15e6b0e7e95355e480c2301ndthis response can be replaced with either some friendlier text or by a
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowenredirection to another URL (local or external).
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<DT>Old behavior
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DD>NCSA httpd 1.3 would return some boring old error/problem message which
a78048ccbdb6256da15e6b0e7e95355e480c2301ndwould often be meaningless to the user, and would provide no means of logging
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<DT>New behavior
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DD>The server can be asked to;
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<LI>Display some other text, instead of the NCSA hard coded messages, or
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<LI>redirect to a local URL, or
11495c9f0bd33e51a25b4d532beadfbcf9b944a3nilgun<LI>redirect to an external URL.
f3ec420152ca921e4c1ce77782f51b53f659018dnd<P>Redirecting to another URL can be useful, but only if some information
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjungcan be passed which can then be used to explain and/or log the error/problem
a78048ccbdb6256da15e6b0e7e95355e480c2301ndmore clearly.<BR>To achieve this, Apache will define new CGI-like environment
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_QUERY_STRING= <br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_REMOTE_ADDR=121.345.78.123 <br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_SERVER_PORT=80 <br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndAt least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will
a78048ccbdb6256da15e6b0e7e95355e480c2301ndbe passed to the new URL (assuming it's a cgi-script or a cgi-include). The
a78048ccbdb6256da15e6b0e7e95355e480c2301ndother variables will exist only if they existed prior to the error/problem.<p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DT>Configuration
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<P>Here are some examples...
a78048ccbdb6256da15e6b0e7e95355e480c2301ndErrorDocument 500 "Sorry, our script crashed because %s. Oh dear<br>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndThe syntax is, <p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<code><A HREF="core.html#errordocument">ErrorDocument</A></code>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<3-digit-code> action <p>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndwhere the action can be,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever
a78048ccbdb6256da15e6b0e7e95355e480c2301ndfollows the quote is displayed. If the error/problem produced any additional
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<LI>An external URL to redirect to.
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<LI>A local URL to redirect to.
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<P><code>ErrorDocument</code> definitions are sensitive to a
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<code>SIGHUP</code>, so you can change any of the definitions or add new ones
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DT>Purpose
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DD>Apache's behaviour to redirected URLs has been modified so that additional
a78048ccbdb6256da15e6b0e7e95355e480c2301ndenvironment variables are available to a script/server-include.<p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DT>Old behaviour
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DD>Standard CGI vars were made available to a script which has been
a78048ccbdb6256da15e6b0e7e95355e480c2301ndredirected to. No indication of where the redirection came from was provided.
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DT>New behaviour
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<DD>A new batch of environment variables will be initialized for use by a
a78048ccbdb6256da15e6b0e7e95355e480c2301ndscript which has been redirected to.<BR>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndEach new variable will have the prefix <code>REDIRECT_</code>.<BR>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_ environment variables are created from the CGI environment
a78048ccbdb6256da15e6b0e7e95355e480c2301ndvariables which existed prior to the redirect, they are renamed with a
a78048ccbdb6256da15e6b0e7e95355e480c2301ndREDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndIn addition to these new variables, Apache will define
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<code>REDIRECT_URL</code> and <code>REDIRECT_STATUS</code> to help the script
a78048ccbdb6256da15e6b0e7e95355e480c2301ndtrace its origin.<BR>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndLogging: both the original URL and the URL being redirected to, will
a78048ccbdb6256da15e6b0e7e95355e480c2301ndnow be logged correctly in the access log.<p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<!--#include virtual="footer.html" -->