custom-error.html revision 091caae3b2ebdb760c98575d0d5e349cd686f913
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek BGCOLOR="#FFFFFF"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek TEXT="#000000"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek LINK="#0000FF"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek VLINK="#000080"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek ALINK="#FF0000"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!--#include virtual="header.html" -->
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <DD>Additional functionality. Allows webmasters to configure the response of
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek Apache to some error or problem.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>Customizable responses can be defined to be activated in the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek event of a server detected error or problem.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>e.g. if a script crashes and produces a "500 Server Error"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek response, then this response can be replaced with either some
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek friendlier text or by a redirection to another URL (local or
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<DT>Old behavior
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <DD>NCSA httpd 1.3 would return some boring old error/problem message
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek which would often be meaningless to the user, and would provide no
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek means of logging the symptoms which caused it.<BR>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek<DT>New behavior
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <DD>The server can be asked to;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>Display some other text, instead of the NCSA hard coded messages, or
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>redirect to a local URL, or
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>redirect to an external URL.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>Redirecting to another URL can be useful, but only if some information
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek can be passed which can then be used to explain and/or log the
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek more clearly.
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <P>To achieve this, Apache will define new CGI-like environment
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekREDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekREDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekREDIRECT_QUERY_STRING= <BR>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekREDIRECT_REMOTE_ADDR=121.345.78.123 <BR>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekREDIRECT_SERVER_PORT=80 <BR>
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek be passed to the new URL (assuming it's a cgi-script or a cgi-include).
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov other variables will exist only if they existed prior to the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <STRONG>None</STRONG> of these will be set if your ErrorDocument is an
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov like <CODE>http:</CODE>, even if it refers to the same host as the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<DT>Configuration
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>Here are some examples...
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekErrorDocument 500 "Sorry, our script crashed. Oh dear<BR>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekErrorDocument 404 /Lame_excuses/not_found.html <BR>
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal ZidekErrorDocument 401 /Subscription/how_to_subscribe.html
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>The syntax is,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<3-digit-code> action
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <P>where the action can be,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>Text to be displayed. Prefix the text with a quote ("). Whatever
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek follows the quote is displayed. <EM>Note: the (") prefix isn't
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek displayed.</EM>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>An external URL to redirect to.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI>A local URL to redirect to.
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek <DD>Apache's behavior to redirected URLs has been modified so that additional
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek environment variables are available to a script/server-include.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<DT>Old behavior
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek <DD>Standard CGI vars were made available to a script which has been
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek redirected to. No indication of where the redirection came from was
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek<DT>New behavior
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekA new batch of environment variables will be initialized for use by a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekscript which has been redirected to. Each new variable will have the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekprefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekvariables are created from the CGI environment variables which existed
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekprior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekprefix, i.e. <CODE>HTTP_USER_AGENT</CODE> becomes
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekvariables, Apache will define <CODE>REDIRECT_URL</CODE> and
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekBoth the original URL and the URL being redirected to can be logged in
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe access log.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekIf the ErrorDocument specifies a local redirect to a CGI script, the script
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekshould include a "<SAMP>Status:</SAMP>" header field in its output
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekin order to ensure the propagation all the way back to the client
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekof the error condition that caused it to be invoked. For instance, a Perl
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekErrorDocument script might include the following:
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekIf the script is dedicated to handling a particular error condition, such as
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<SAMP>404 Not Found</SAMP>, it can use the specific code and
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekerror text instead.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!--#include virtual="footer.html" -->