docs/manual/custom-error.xml - httpd - Git at Google

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
 <!-- $Revision: 1.8 $ -->

 <!--
  Copyright 2002-2004 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->

 <manualpage metafile="custom-error.xml.meta">

   <title>Custom Error Responses</title>

   <summary>
     <p>Additional functionality allows webmasters to configure the response
     of Apache to some error or problem.</p>

     <p>Customizable responses can be defined to be activated in the event of
     a server detected error or problem.</p>

     <p>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>
   </summary>

   <section id="behavior">
     <title>Behavior</title>

     <section>
       <title>Old Behavior</title>

       <p>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.</p>
     </section>

     <section>
       <title>New Behavior</title>

       <p>The server can be asked to:</p>

       <ol>
         <li>Display some other text, instead of the NCSA hard coded
         messages, or</li>

         <li>redirect to a local URL, or</li>

         <li>redirect to an external URL.</li>
       </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>

       <p>To achieve this, Apache will define new CGI-like environment
       variables:</p>

       <example>
         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
       </example>

       <p>Note the <code>REDIRECT_</code> prefix.</p>

       <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 <directive module="core">ErrorDocument</directive> is an
       <em>external</em> redirect (anything starting with a
       scheme name like <code>http:</code>, even if it refers to the same host
       as the server).</p>
     </section>
   </section>

   <section id="configuration">
     <title>Configuration</title>

     <p>Use of <directive module="core">ErrorDocument</directive> is enabled
     for .htaccess files when the
     <directive module="core">AllowOverride</directive> is set accordingly.</p>

     <p>Here are some examples...</p>

     <example>
       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
     </example>

     <p>The syntax is,</p>

     <example>
       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
     </example>

     <p>where the action can be,</p>

     <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>

       <li>An external URL to redirect to.</li>

       <li>A local URL to redirect to.</li>
     </ol>
   </section>

   <section id="custom">
     <title>Custom Error Responses and Redirects</title>

     <p>Apache's behavior to redirected URLs has been modified so
     that additional environment variables are available to a
     script/server-include.</p>

     <section>
       <title>Old behavior</title>

       <p>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>
     </section>

     <section>
       <title>New behavior</title>

       <p>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.</p>

       <p>If the ErrorDocument specifies a local redirect to a CGI
       script, the script should include a "<code>Status:</code>"
       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>

       <example>
         ... <br />
         print  "Content-type: text/html\n"; <br />
         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
         ...
       </example>

       <p>If the script is dedicated to handling a particular error
       condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
       use the specific code and error text instead.</p>

       <p>Note that the script <em>must</em> emit an appropriate
       <code>Status:</code> header (such as <code>302&nbsp;Found</code>), if the
       response contains a <code>Location:</code> header (in order to issue a
       client side redirect). Otherwise the <code>Location:</code> header may
       have no effect.</p>
     </section>
   </section>
 </manualpage>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
	<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
	<!-- $Revision: 1.8 $ -->

	<!--
	Copyright 2002-2004 The Apache Software Foundation

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<manualpage metafile="custom-error.xml.meta">

	<title>Custom Error Responses</title>

	<summary>
	<p>Additional functionality allows webmasters to configure the response
	of Apache to some error or problem.</p>

	<p>Customizable responses can be defined to be activated in the event of
	a server detected error or problem.</p>

	<p>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>
	</summary>

	<section id="behavior">
	<title>Behavior</title>

	<section>
	<title>Old Behavior</title>

	<p>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.</p>
	</section>

	<section>
	<title>New Behavior</title>

	<p>The server can be asked to:</p>

	<ol>
	<li>Display some other text, instead of the NCSA hard coded
	messages, or</li>

	<li>redirect to a local URL, or</li>

	<li>redirect to an external URL.</li>
	</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>

	<p>To achieve this, Apache will define new CGI-like environment
	variables:</p>

	<example>
	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
	</example>

	<p>Note the <code>REDIRECT_</code> prefix.</p>

	<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 <directive module="core">ErrorDocument</directive> is an
	<em>external</em> redirect (anything starting with a
	scheme name like <code>http:</code>, even if it refers to the same host
	as the server).</p>
	</section>
	</section>

	<section id="configuration">
	<title>Configuration</title>

	<p>Use of <directive module="core">ErrorDocument</directive> is enabled
	for .htaccess files when the
	<directive module="core">AllowOverride</directive> is set accordingly.</p>

	<p>Here are some examples...</p>

	<example>
	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
	</example>

	<p>The syntax is,</p>

	<example>
	ErrorDocument <3-digit-code> <action>
	</example>

	<p>where the action can be,</p>

	<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>

	<li>An external URL to redirect to.</li>

	<li>A local URL to redirect to.</li>
	</ol>
	</section>

	<section id="custom">
	<title>Custom Error Responses and Redirects</title>

	<p>Apache's behavior to redirected URLs has been modified so
	that additional environment variables are available to a
	script/server-include.</p>

	<section>
	<title>Old behavior</title>

	<p>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>
	</section>

	<section>
	<title>New behavior</title>

	<p>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.</p>

	<p>If the ErrorDocument specifies a local redirect to a CGI
	script, the script should include a "<code>Status:</code>"
	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>

	<example>
	... <br />
	print "Content-type: text/html\n"; <br />
	printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
	...
	</example>

	<p>If the script is dedicated to handling a particular error
	condition, such as <code>404 Not Found</code>, it can
	use the specific code and error text instead.</p>

	<p>Note that the script <em>must</em> emit an appropriate
	<code>Status:</code> header (such as <code>302 Found</code>), if the
	response contains a <code>Location:</code> header (in order to issue a
	client side redirect). Otherwise the <code>Location:</code> header may
	have no effect.</p>
	</section>
	</section>
	</manualpage>