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"?>
 <!-- $LastChangedRevision$ -->

 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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>Although the Apache HTTP Server provides generic error responses
     in the event of 4xx or 5xx HTTP status codes, these responses are
     rather stark, uninformative, and can be intimidating to site users.
     You may wish to provide custom error responses which are either
     friendlier, or in some language other than English, or perhaps which
     are styled more in line with your site layout.</p>

     <p>Customized error responses can be defined for any HTTP status
     code designated as an error condition - that is, any 4xx or 5xx
     status.</p>

     <p>Additionally, a set of values are provided, so
     that the error document can be customized further based on the
     values of these variables, using <a href="howto/ssi.html">Server
     Side Includes</a>. Or, you can have error conditions handled by a
     cgi program, or other dynamic handler (PHP, mod_perl, etc) which
     makes use of these variables.</p>

   </summary>

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

     <p>Custom error documents are configured using the <directive
     module="core">ErrorDocument</directive> directive,
     which may be used in global,
     virtualhost, or directory context. It may be used in .htaccess files
     if <directive module="core">AllowOverride</directive> is set to
     FileInfo.</p>

     <highlight language="config">
 ErrorDocument 500 "Sorry, our script crashed. Oh dear"
 ErrorDocument 500 /cgi-bin/crash-recover
 ErrorDocument 500 http://error.example.com/server_error.html
 ErrorDocument 404 /errors/not_found.html
 ErrorDocument 401 /subscription/how_to_subscribe.html
     </highlight>

     <p>The syntax of the <code>ErrorDocument</code> directive is:</p>

     <highlight language="config">
       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
     </highlight>

     <p>where the action will be treated as:</p>

     <ol>
       <li>A local URL to redirect to (if the action begins with a "/").</li>
       <li>An external URL to redirect to (if the action is a valid URL).</li>
       <li>Text to be displayed (if none of the above). The text must be
           wrapped in quotes (") if it consists of more than one word.</li>
     </ol>

     <p>When redirecting to a local URL, additional environment variables
     are set so that the response can be further customized. They are not sent to
     external URLs.</p>

   </section>

   <section id="variables"><title>Available Variables</title>

       <p>Redirecting to another URL can be useful, but only if some
       information can be passed which can then be used to explain or log
       the error condition more clearly.</p>

       <p>To achieve this, when the error redirect is sent, additional
       environment variables will be set, which will be generated from
       the headers provided to the original request by prepending
       'REDIRECT_' onto the original header name. This provides the error
       document the context of the original request.</p>

       <p>For example, you might receive, in addition to more usual
       environment variables, the following.</p>

       <example>
         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
         REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
         REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
         REDIRECT_QUERY_STRING=<br />
         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
         REDIRECT_REMOTE_HOST=client.example.com<br />
         REDIRECT_SERVER_NAME=www.example.edu<br />
         REDIRECT_SERVER_PORT=80<br />
         REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
         REDIRECT_URL=/cgi-bin/buggy.pl
       </example>

       <p><code>REDIRECT_</code> environment variables are created from
       the 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>.</p>

       <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
       <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
       the other headers will be set only if they existed prior to the
       error condition.</p>

       <p><strong>None</strong> of these will be
       set if the <directive module="core">ErrorDocument</directive> target 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 id="custom"><title>Customizing Error Responses</title>

       <p>If you point your <code>ErrorDocument</code> to some variety of
       dynamic handler such as a server-side include document, CGI
       script, or some variety of other handler, you may wish to use the
       available custom environment variables to customize this
       response.</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>

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

       <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 if the response contains <code>Location:</code>
       header (in order to issue a client-side redirect), the script
       <em>must</em> emit an appropriate <code>Status:</code> header
       (such as <code>302&nbsp;Found</code>). Otherwise the
       <code>Location:</code> header may have no effect.</p>

   </section>

   <section id="multi-lang"><title>Multi Language Custom Error Documents</title>

     <p>Provided with your installation of the Apache HTTP Server is a
     directory of custom error documents translated into 16 different
     languages. There's also a configuration file in the
     <code>conf/extra</code> configuration directory that can be included
     to enable this feature.</p>

     <p>In your server configuration file, you'll see a line such as:</p>

     <highlight language="config">
 # Multi-language error messages
 #Include conf/extra/httpd-multilang-errordoc.conf
     </highlight>

     <p>Uncommenting this <code>Include</code> line will enable this
     feature, and provide language-negotiated error messages, based on
     the language preference set in the client browser.</p>

     <p>Additionally, these documents contain various of the
     <code>REDIRECT_</code> variables, so that additional information can
     be provided to the end-user about what happened, and what they can
     do now.</p>

     <p>These documents can be customized to whatever degree you wish to
     provide more useful information to users about your site, and what
     they can expect to find there.</p>

     <p><module>mod_include</module> and <module>mod_negotiation</module>
     must be enabled to use this feature.</p>

  </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"?>
	<!-- $LastChangedRevision$ -->

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You 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>Although the Apache HTTP Server provides generic error responses
	in the event of 4xx or 5xx HTTP status codes, these responses are
	rather stark, uninformative, and can be intimidating to site users.
	You may wish to provide custom error responses which are either
	friendlier, or in some language other than English, or perhaps which
	are styled more in line with your site layout.</p>

	<p>Customized error responses can be defined for any HTTP status
	code designated as an error condition - that is, any 4xx or 5xx
	status.</p>

	<p>Additionally, a set of values are provided, so
	that the error document can be customized further based on the
	values of these variables, using <a href="howto/ssi.html">Server
	Side Includes</a>. Or, you can have error conditions handled by a
	cgi program, or other dynamic handler (PHP, mod_perl, etc) which
	makes use of these variables.</p>

	</summary>

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

	<p>Custom error documents are configured using the <directive
	module="core">ErrorDocument</directive> directive,
	which may be used in global,
	virtualhost, or directory context. It may be used in .htaccess files
	if <directive module="core">AllowOverride</directive> is set to
	FileInfo.</p>

	<highlight language="config">
	ErrorDocument 500 "Sorry, our script crashed. Oh dear"
	ErrorDocument 500 /cgi-bin/crash-recover
	ErrorDocument 500 http://error.example.com/server_error.html
	ErrorDocument 404 /errors/not_found.html
	ErrorDocument 401 /subscription/how_to_subscribe.html
	</highlight>

	<p>The syntax of the <code>ErrorDocument</code> directive is:</p>

	<highlight language="config">
	ErrorDocument <3-digit-code> <action>
	</highlight>

	<p>where the action will be treated as:</p>

	<ol>
	<li>A local URL to redirect to (if the action begins with a "/").</li>
	<li>An external URL to redirect to (if the action is a valid URL).</li>
	<li>Text to be displayed (if none of the above). The text must be
	wrapped in quotes (") if it consists of more than one word.</li>
	</ol>

	<p>When redirecting to a local URL, additional environment variables
	are set so that the response can be further customized. They are not sent to
	external URLs.</p>

	</section>

	<section id="variables"><title>Available Variables</title>

	<p>Redirecting to another URL can be useful, but only if some
	information can be passed which can then be used to explain or log
	the error condition more clearly.</p>

	<p>To achieve this, when the error redirect is sent, additional
	environment variables will be set, which will be generated from
	the headers provided to the original request by prepending
	'REDIRECT_' onto the original header name. This provides the error
	document the context of the original request.</p>

	<p>For example, you might receive, in addition to more usual
	environment variables, the following.</p>

	<example>
	REDIRECT_HTTP_ACCEPT=/, image/gif, image/jpeg, image/png<br />
	REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
	REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
	REDIRECT_QUERY_STRING=<br />
	REDIRECT_REMOTE_ADDR=121.345.78.123<br />
	REDIRECT_REMOTE_HOST=client.example.com<br />
	REDIRECT_SERVER_NAME=www.example.edu<br />
	REDIRECT_SERVER_PORT=80<br />
	REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
	REDIRECT_URL=/cgi-bin/buggy.pl
	</example>

	<p><code>REDIRECT_</code> environment variables are created from
	the 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>.</p>

	<p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
	<code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
	the other headers will be set only if they existed prior to the
	error condition.</p>

	<p><strong>None</strong> of these will be
	set if the <directive module="core">ErrorDocument</directive> target 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 id="custom"><title>Customizing Error Responses</title>

	<p>If you point your <code>ErrorDocument</code> to some variety of
	dynamic handler such as a server-side include document, CGI
	script, or some variety of other handler, you may wish to use the
	available custom environment variables to customize this
	response.</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>

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

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

	</section>

	<section id="multi-lang"><title>Multi Language Custom Error Documents</title>

	<p>Provided with your installation of the Apache HTTP Server is a
	directory of custom error documents translated into 16 different
	languages. There's also a configuration file in the
	<code>conf/extra</code> configuration directory that can be included
	to enable this feature.</p>

	<p>In your server configuration file, you'll see a line such as:</p>

	<highlight language="config">
	# Multi-language error messages
	#Include conf/extra/httpd-multilang-errordoc.conf
	</highlight>

	<p>Uncommenting this <code>Include</code> line will enable this
	feature, and provide language-negotiated error messages, based on
	the language preference set in the client browser.</p>

	<p>Additionally, these documents contain various of the
	<code>REDIRECT_</code> variables, so that additional information can
	be provided to the end-user about what happened, and what they can
	do now.</p>

	<p>These documents can be customized to whatever degree you wish to
	provide more useful information to users about your site, and what
	they can expect to find there.</p>

	<p><module>mod_include</module> and <module>mod_negotiation</module>
	must be enabled to use this feature.</p>

	</section>

	</manualpage>