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.
      <b>None</b> of these will be set if your ErrorDocument is an
      <i>external</i> redirect (i.e. anything starting with a protocol 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>

 <!--#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.
	<b>None</b> of these will be set if your ErrorDocument is an
	<i>external</i> redirect (i.e. anything starting with a protocol 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>

	<!--#include virtual="footer.html" -->
	</BODY>
	</HTML>