custom-error.html revision 25503838e438bb909e3ff880125732c7ed5e64ad
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher BGCOLOR="#FFFFFF"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher TEXT="#000000"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher LINK="#0000FF"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher VLINK="#000080"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher ALINK="#FF0000"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<!--#include virtual="header.html" -->
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<H1 ALIGN="CENTER">Custom error responses</H1>
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <DD>Additional functionality. Allows webmasters to configure the response of
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher Apache to some error or problem.
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <P>Customizable responses can be defined to be activated in the
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher event of a server detected error or problem.
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <P>e.g. if a script crashes and produces a "500 Server Error"
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher response, then this response can be replaced with either some
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher friendlier text or by a redirection to another URL (local or
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<DT>Old behavior
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <DD>NCSA httpd 1.3 would return some boring old error/problem message
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher which would often be meaningless to the user, and would provide no
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher means of logging the symptoms which caused it.<BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose<DT>New behavior
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <DD>The server can be asked to;
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <LI>Display some other text, instead of the NCSA hard coded messages, or
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <LI>redirect to a local URL, or
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <LI>redirect to an external URL.
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <P>Redirecting to another URL can be useful, but only if some information
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose can be passed which can then be used to explain and/or log the error/problem
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose more clearly.
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <P>To achieve this, Apache will define new CGI-like environment
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseREDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseREDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseREDIRECT_QUERY_STRING= <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseREDIRECT_REMOTE_ADDR=121.345.78.123 <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseREDIRECT_SERVER_PORT=80 <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> will
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose be passed to the new URL (assuming it's a cgi-script or a cgi-include). The
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose other variables will exist only if they existed prior to the error/problem.
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <STRONG>None</STRONG> of these will be set if your ErrorDocument is an
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <EM>external</EM> redirect (i.e. anything starting with a protocol name
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose like <CODE>http:</CODE>, even if it refers to the same host as the
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose<DT>Configuration
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <P>Here are some examples...
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseErrorDocument 500 "Sorry, our script crashed. Oh dear<BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseErrorDocument 404 /Lame_excuses/not_found.html <BR>
949fbc93defad394648b2651b43a7bbfa5bff42bSumit BoseErrorDocument 401 /Subscription/how_to_subscribe.html
949fbc93defad394648b2651b43a7bbfa5bff42bSumit Bose <P>The syntax is,
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE>
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose<3-digit-code> action
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose <P>where the action can be,
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose <LI>Text to be displayed. Prefix the text with a quote ("). Whatever
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose follows the quote is displayed. <EM>Note: the (") prefix isn't
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose displayed.</EM>
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose <LI>An external URL to redirect to.
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit Bose <LI>A local URL to redirect to.
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<H2>Custom error responses and redirects</H2>
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <DD>Apache's behavior to redirected URLs has been modified so that additional
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher environment variables are available to a script/server-include.<P>
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<DT>Old behavior
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher <DD>Standard CGI vars were made available to a script which has been
46222e5191473f9a46aec581273eb2eef22e23beMichal Zidek redirected to. No indication of where the redirection came from was provided.
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<DT>New behavior
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen GallagherA new batch of environment variables will be initialized for use by a
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagherscript which has been redirected to. Each new variable will have the
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagherprefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallaghervariables are created from the CGI environment variables which existed
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagherprior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE>
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagherprefix, i.e. <CODE>HTTP_USER_AGENT</CODE> becomes
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallaghervariables, Apache will define <CODE>REDIRECT_URL</CODE> and
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagher<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin.
bfb40893be20b45279a40188cf16ef0eec1f9423Sumit BoseBoth the original URL and the URL being redirected to can be logged in
505e75ba28b42bb3de7a6d55de825091b70cc2b2Stephen Gallagherthe access log.
46222e5191473f9a46aec581273eb2eef22e23beMichal Zidek<!--#include virtual="footer.html" -->