<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

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

<example>

ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br />

ErrorDocument 500 /cgi-bin/crash-recover<br />

ErrorDocument 500 http://error.example.com/server_error.html<br />

ErrorDocument 404 /errors/not_found.html <br />

ErrorDocument 401 /subscription/how_to_subscribe.html

</example>

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

<example>

ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;

</example>

<p>where the action can be one of:</p>

<ol>

<li>Text to be displayed. Wrap the text with quotes (").</li>

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

<li>An external URL to redirect to.</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 recieve, 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 environent 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>

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

<example>

# Multi-language error messages<br />

#Include conf/extra/httpd-multilang-errordoc.conf

</example>

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