docs/manual/custom-error.html.en - httpd - Git at Google

 <!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, e.g.

   <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>
 &lt;3-digit-code&gt; action

   <P>where the action can be,

   <OL>
     <LI>Text to be displayed.  Prefix the text with a quote (&quot;). Whatever
         follows the quote is displayed. <EM>Note: the (&quot;) 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, i.e. <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&nbsp;Not&nbsp;Found</SAMP>, it can use the specific code and
 error text instead.
 </P>

 <!--#include virtual="footer.html" -->
 </BODY>
 </HTML>
	<!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, e.g.

	<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, i.e. <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>