custom-error.html revision db81e057b060e365d840d9a1d35a5797192efa81
57221209d11b05aa0373cc3892d5df89ba96ebf9Christian Maeder<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu Prodescu<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
3f69b6948966979163bdfe8331c38833d5d90ecdChristian Maeder BGCOLOR="#FFFFFF"
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder TEXT="#000000"
351145cfe8c03b4d47133c96b209f2bd6cfbf504Christian Maeder LINK="#0000FF"
f3a94a197960e548ecd6520bb768cb0d547457bbChristian Maeder VLINK="#000080"
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski ALINK="#FF0000"
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder<!--#include virtual="header.html" -->
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder<H1 ALIGN="CENTER">Custom error responses</H1>
ad270004874ce1d0697fb30d7309f180553bb315Christian Maeder <DD>Additional functionality. Allows webmasters to configure the response of
5e46b572ed576c0494768998b043d9d340594122Till Mossakowski Apache to some error or problem.
23a00c966f2aa8da525d7a7c51933c99964426c0Christian Maeder <P>Customizable responses can be defined to be activated in the
575a55eadc8dcab8ee350324b417cbd9e52e69c0Christian Maeder event of a server detected error or problem.
8e9c3881fb6e710b1e08bf5ac8ff9d393df2e74eChristian Maeder <P>e.g. if a script crashes and produces a "500 Server Error"
db453fe9625a9dab5d108f7a5e464598814144b8Jian Chun Wang response, then this response can be replaced with either some
8c63cd89ef840cd7a3d3b75f0207dc800388c800Christian Maeder friendlier text or by a redirection to another URL (local or
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski<DT>Old behavior
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <DD>NCSA httpd 1.3 would return some boring old error/problem message
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder which would often be meaningless to the user, and would provide no
90c174bac60a72ffd81bc3bf5ae2dd9a61943b8bChristian Maeder means of logging the symptoms which caused it.<BR>
ca020e82eb3567e7bdbb1cf70729efbd07e9caa4Klaus Luettich<DT>New behavior
a001917177db7ae636853b37c0d0f9f4e90a83ffChristian Maeder <DD>The server can be asked to;
4b6aa93c12e4db86ccc7694a48a73e9cf7262d06Christian Maeder <LI>Display some other text, instead of the NCSA hard coded messages, or
c7e03d0708369f944b6f235057b39142a21599f2Mihai Codescu <LI>redirect to a local URL, or
9ecf13b5fd914bc7272f1fc17348d7f4a8c77061Christian Maeder <LI>redirect to an external URL.
8e80792f474d154ff11762fac081a422e34f1accChristian Maeder <P>Redirecting to another URL can be useful, but only if some information
03136b84a0c70d877e227444f0875e209506b9e4Christian Maeder can be passed which can then be used to explain and/or log the error/problem
03136b84a0c70d877e227444f0875e209506b9e4Christian Maeder more clearly.
9ecf13b5fd914bc7272f1fc17348d7f4a8c77061Christian Maeder <P>To achieve this, Apache will define new CGI-like environment
4c7f058cdd19ce67b2b5d4b7f69703d0f8a21e38Christian MaederREDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>
b2026c46f0e4c6a05931f1bf0ab2e84ce884c814Christian MaederREDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
b2026c46f0e4c6a05931f1bf0ab2e84ce884c814Christian MaederREDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br>
b2026c46f0e4c6a05931f1bf0ab2e84ce884c814Christian MaederREDIRECT_QUERY_STRING= <br>
b2026c46f0e4c6a05931f1bf0ab2e84ce884c814Christian MaederREDIRECT_REMOTE_ADDR=121.345.78.123 <br>
b2026c46f0e4c6a05931f1bf0ab2e84ce884c814Christian MaederREDIRECT_SERVER_PORT=80 <br>
9eb39c7a0e7a1ddad1eec1d23c6d4e3a99c54023Christian Maeder <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder be passed to the new URL (assuming it's a cgi-script or a cgi-include). The
9eb39c7a0e7a1ddad1eec1d23c6d4e3a99c54023Christian Maeder other variables will exist only if they existed prior to the error/problem.
9eb39c7a0e7a1ddad1eec1d23c6d4e3a99c54023Christian Maeder <b>None</b> of these will be set if your ErrorDocument is an
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder <i>external</i> redirect (i.e. anything starting with a protocol name
351145cfe8c03b4d47133c96b209f2bd6cfbf504Christian Maeder like <code>http:</code>, even if it refers to the same host as the
9a6779c8495854bdf36e4a87f98f095e8d0a6e45Christian Maeder<DT>Configuration
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.
351145cfe8c03b4d47133c96b209f2bd6cfbf504Christian Maeder <P>Here are some examples...
81101b83a042f5a1bdeeef93b1b49aff05817e44Christian MaederErrorDocument 500 /cgi-bin/crash-recover <br>
81101b83a042f5a1bdeeef93b1b49aff05817e44Christian MaederErrorDocument 500 "Sorry, our script crashed. Oh dear<br>
351145cfe8c03b4d47133c96b209f2bd6cfbf504Christian MaederErrorDocument 404 /Lame_excuses/not_found.html <br>
d5833d2ee7bafcbf2fdd2bdfd9a728c769b100c7Christian MaederErrorDocument 401 /Subscription/how_to_subscribe.html
9eb39c7a0e7a1ddad1eec1d23c6d4e3a99c54023Christian Maeder <P>The syntax is,
d0c66a832d7b556e20ea4af4852cdc27a5463d51Christian Maeder <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>
d0c66a832d7b556e20ea4af4852cdc27a5463d51Christian Maeder<3-digit-code> action
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder <P>where the action can be,
4b6aa93c12e4db86ccc7694a48a73e9cf7262d06Christian Maeder <LI>Text to be displayed. Prefix the text with a quote ("). Whatever
4b6aa93c12e4db86ccc7694a48a73e9cf7262d06Christian Maeder follows the quote is displayed. <em>Note: the (") prefix isn't
a001917177db7ae636853b37c0d0f9f4e90a83ffChristian Maeder displayed.</em>
03136b84a0c70d877e227444f0875e209506b9e4Christian Maeder <LI>An external URL to redirect to.
9ecf13b5fd914bc7272f1fc17348d7f4a8c77061Christian Maeder <LI>A local URL to redirect to.
4b6aa93c12e4db86ccc7694a48a73e9cf7262d06Christian Maeder<h2>Custom error responses and redirects</H2>
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski <DD>Apache's behavior to redirected URLs has been modified so that additional
a001917177db7ae636853b37c0d0f9f4e90a83ffChristian Maeder environment variables are available to a script/server-include.<p>
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski<DT>Old behavior
4b6aa93c12e4db86ccc7694a48a73e9cf7262d06Christian Maeder <DD>Standard CGI vars were made available to a script which has been
a001917177db7ae636853b37c0d0f9f4e90a83ffChristian Maeder redirected to. No indication of where the redirection came from was provided.
9ecf13b5fd914bc7272f1fc17348d7f4a8c77061Christian Maeder<DT>New behavior
03136b84a0c70d877e227444f0875e209506b9e4Christian MaederA new batch of environment variables will be initialized for use by a
26d11a256b1433604a3dbc69913b520fff7586acChristian Maederscript which has been redirected to. Each new variable will have the
03136b84a0c70d877e227444f0875e209506b9e4Christian Maederprefix <code>REDIRECT_</code>. <code>REDIRECT_</code> environment
03136b84a0c70d877e227444f0875e209506b9e4Christian Maedervariables are created from the CGI environment variables which existed
03136b84a0c70d877e227444f0875e209506b9e4Christian Maederprior to the redirect, they are renamed with a <code>REDIRECT_</code>
9ecf13b5fd914bc7272f1fc17348d7f4a8c77061Christian Maederprefix, i.e. <code>HTTP_USER_AGENT</code> becomes
03136b84a0c70d877e227444f0875e209506b9e4Christian Maeder<code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these new
03136b84a0c70d877e227444f0875e209506b9e4Christian Maedervariables, Apache will define <code>REDIRECT_URL</code> and
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder<code>REDIRECT_STATUS</code> to help the script trace its origin.
aea143fff7a50aceb809845fbc42698b0b3f545aChristian MaederBoth the original URL and the URL being redirected to can be logged in
03136b84a0c70d877e227444f0875e209506b9e4Christian Maederthe access log.
01aafb6a9520f05df5ff467b591ecb5474dcfc86Christian Maeder<!--#include virtual="footer.html" -->