custom-error.html revision 44afbb2bc1622ddf021058e2a157cfd31fb67fd0
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<!--#include virtual="header.html" -->
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DD>Additional functionality. Allows web-masters to configure the response of
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenApache to some error or problem.<BR>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<P>Customizable responses can be defined to be activated in the event of a
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenserver detected error or problem.<BR>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainene.g. if a script crashes and produces a "500 Server Error" response, then
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenthis response can be replaced with either some friendlier text or by a
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenredirection to another URL (local or external).
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DT>Old behavior
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DD>NCSA httpd 1.3 would return some boring old error/problem message which
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenwould often be meaningless to the user, and would provide no means of logging
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DT>New behavior
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DD>The server can be asked to;
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<LI>Display some other text, instead of the NCSA hard coded messages, or
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<LI>redirect to a local URL, or
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<LI>redirect to an external URL.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<P>Redirecting to another URL can be useful, but only if some information
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainencan be passed which can then be used to explain and/or log the error/problem
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenmore clearly.<BR>To achieve this, Apache will define new CGI-like environment
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenREDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenREDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenREDIRECT_QUERY_STRING= <br>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenREDIRECT_REMOTE_ADDR=121.345.78.123 <br>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenREDIRECT_SERVER_PORT=80 <br>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenAt least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenbe passed to the new URL (assuming it's a cgi-script or a cgi-include). The
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenother variables will exist only if they existed prior to the error/problem.<p>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<DT>Configuration
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen<P>Here are some examples...
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenErrorDocument 500 "Sorry, our script crashed because %s. Oh dear<br>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo SirainenErrorDocument 404 /Lame_excuses/not_found.html <br>
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo SirainenErrorDocument 401 /Subscription/how_to_subscribe.html
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenThe syntax is, <p>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<3-digit-code> action <p>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenwhere the action can be,
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever
d17a90f5ae38edc8c0e6bf42c2162c9c18edb891Timo Sirainenfollows the quote is displayed. If the error/problem produced any additional
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Siraineninformation, it can be specified using <code>%s</code>.
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<em>Note: the (") prefix isn't displayed.</em>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<LI>An external URL to redirect to.
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<LI>A local URL to redirect to.
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<P><code>ErrorDocument</code> definitions are sensitive to a
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<code>SIGHUP</code>, so you can change any of the definitions or add new ones
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenprior to sending a <code>SIGHUP</code> (kill -1) signal.
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<DD>Apache's behavior to redirected URLs has been modified so that additional
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenenvironment variables are available to a script/server-include.<p>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<DT>Old behavior
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<DD>Standard CGI vars were made available to a script which has been
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenredirected to. No indication of where the redirection came from was provided.
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<DT>New behavior
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<DD>A new batch of environment variables will be initialized for use by a
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenscript which has been redirected to.<BR>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenEach new variable will have the prefix <code>REDIRECT_</code>.<BR>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenREDIRECT_ environment variables are created from the CGI environment
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainenvariables which existed prior to the redirect, they are renamed with a
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenREDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenIn addition to these new variables, Apache will define
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<code>REDIRECT_URL</code> and <code>REDIRECT_STATUS</code> to help the script
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainentrace its origin.<BR>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo SirainenLogging: both the original URL and the URL being redirected to, will
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainennow be logged correctly in the access log.<p>
abe8230dd1dd37d7ccf0163100e934bb5e658c20Timo Sirainen<!--#include virtual="footer.html" -->