| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Custom error responses</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Custom error responses</H1> |
| |
| <DL> |
| |
| <DT>Purpose |
| |
| <DD>Additional functionality. Allows webmasters to configure the response of |
| Apache to some error or problem. |
| |
| <P>Customizable responses can be defined to be activated in the |
| event of a server detected error or problem. |
| |
| <P>e.g. if a script crashes and produces a "500 Server Error" |
| response, then this response can be replaced with either some |
| friendlier text or by a redirection to another URL (local or |
| external). |
| <P> |
| |
| <DT>Old behavior |
| |
| <DD>NCSA httpd 1.3 would return some boring old error/problem message |
| which would often be meaningless to the user, and would provide no |
| means of logging the symptoms which caused it.<BR> |
| |
| <P> |
| |
| <DT>New behavior |
| |
| <DD>The server can be asked to; |
| <OL> |
| <LI>Display some other text, instead of the NCSA hard coded messages, or |
| <LI>redirect to a local URL, or |
| <LI>redirect to an external URL. |
| </OL> |
| |
| <P>Redirecting to another URL can be useful, but only if some information |
| can be passed which can then be used to explain and/or log the |
| error/problem |
| more clearly. |
| |
| <P>To achieve this, Apache will define new CGI-like environment |
| variables, <EM>e.g.</EM> |
| |
| <BLOCKQUOTE><CODE> |
| REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR> |
| REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR> |
| REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR> |
| REDIRECT_QUERY_STRING= <BR> |
| REDIRECT_REMOTE_ADDR=121.345.78.123 <BR> |
| REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR> |
| REDIRECT_SERVER_NAME=crash.bang.edu <BR> |
| REDIRECT_SERVER_PORT=80 <BR> |
| REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR> |
| REDIRECT_URL=/cgi-bin/buggy.pl <BR> |
| </CODE></BLOCKQUOTE> |
| |
| <P>note the <CODE>REDIRECT_</CODE> prefix. |
| |
| <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> |
| will |
| be passed to the new URL (assuming it's a cgi-script or a cgi-include). |
| The |
| other variables will exist only if they existed prior to the |
| error/problem. |
| <STRONG>None</STRONG> of these will be set if your ErrorDocument is an |
| <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a |
| scheme name |
| like <CODE>http:</CODE>, even if it refers to the same host as the |
| server).<P> |
| |
| <DT>Configuration |
| |
| <DD> Use of "ErrorDocument" is enabled for .htaccess files when the |
| <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is |
| allowed. |
| |
| <P>Here are some examples... |
| |
| <BLOCKQUOTE><CODE> |
| ErrorDocument 500 /cgi-bin/crash-recover <BR> |
| ErrorDocument 500 "Sorry, our script crashed. Oh dear<BR> |
| ErrorDocument 500 http://xxx/ <BR> |
| ErrorDocument 404 /Lame_excuses/not_found.html <BR> |
| ErrorDocument 401 /Subscription/how_to_subscribe.html |
| </CODE></BLOCKQUOTE> |
| |
| <P>The syntax is, |
| |
| <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE> |
| <3-digit-code> action |
| |
| <P>where the action can be, |
| |
| <OL> |
| <LI>Text to be displayed. Prefix the text with a quote ("). Whatever |
| follows the quote is displayed. <EM>Note: the (") prefix isn't |
| displayed.</EM> |
| |
| <LI>An external URL to redirect to. |
| |
| <LI>A local URL to redirect to. |
| |
| </OL> |
| </DL> |
| |
| <P><HR><P> |
| |
| <H2>Custom error responses and redirects</H2> |
| |
| <DL> |
| |
| <DT>Purpose |
| |
| <DD>Apache's behavior to redirected URLs has been modified so that additional |
| environment variables are available to a script/server-include.<P> |
| |
| <DT>Old behavior |
| |
| <DD>Standard CGI vars were made available to a script which has been |
| redirected to. No indication of where the redirection came from was |
| provided. |
| |
| <P> |
| |
| <DT>New behavior |
| <DD> |
| |
| A new batch of environment variables will be initialized for use by a |
| script which has been redirected to. Each new variable will have the |
| prefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment |
| variables are created from the CGI environment variables which existed |
| prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE> |
| prefix, <EM>i.e.</EM>, <CODE>HTTP_USER_AGENT</CODE> becomes |
| <CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new |
| variables, Apache will define <CODE>REDIRECT_URL</CODE> and |
| <CODE>REDIRECT_STATUS</CODE> to help the script trace its origin. |
| Both the original URL and the URL being redirected to can be logged in |
| the access log. |
| |
| </DL> |
| <P> |
| If the ErrorDocument specifies a local redirect to a CGI script, the script |
| should include a "<SAMP>Status:</SAMP>" header field in its output |
| in order to ensure the propagation all the way back to the client |
| of the error condition that caused it to be invoked. For instance, a Perl |
| ErrorDocument script might include the following: |
| </P> |
| <PRE> |
| : |
| print "Content-type: text/html\n"; |
| printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; |
| : |
| </PRE> |
| <P> |
| If the script is dedicated to handling a particular error condition, such as |
| <SAMP>404 Not Found</SAMP>, it can use the specific code and |
| error text instead. |
| </P> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |