1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Custom Error Responses - Apache HTTP Server</title>
9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.3</p>
16 <img alt="" src="./images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
21 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English"> en </a> |
22 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español"> es </a> |
23 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
24 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
25 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
26 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
30 <p>Although the Apache HTTP Server provides generic error responses
31 in the event of 4xx or 5xx HTTP status codes, these responses are
32 rather stark, uninformative, and can be intimidating to site users.
33 You may wish to provide custom error responses which are either
34 friendlier, or in some language other than English, or perhaps which
35 are styled more in line with your site layout.</p>
37 <p>Customized error responses can be defined for any HTTP status
38 code designated as an error condition - that is, any 4xx or 5xx
41 <p>Additionally, a set of values are provided, so
42 that the error document can be customized further based on the
43 values of these variables, using <a href="howto/ssi.html">Server
44 Side Includes</a>. Or, you can have error conditions handled by a
45 cgi program, or other dynamic handler (PHP, mod_perl, etc) which
46 makes use of these variables.</p>
49 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#configuration">Configuration</a></li>
50 <li><img alt="" src="./images/down.gif" /> <a href="#variables">Available Variables</a></li>
51 <li><img alt="" src="./images/down.gif" /> <a href="#custom">Customizing Error Responses</a></li>
52 <li><img alt="" src="./images/down.gif" /> <a href="#multi-lang">Multi Language Custom Error Documents</a></li>
54 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
56 <h2><a name="configuration" id="configuration">Configuration</a></h2>
58 <p>Custom error documents are configured using the <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> directive,
59 which may be used in global,
60 virtualhost, or directory context. It may be used in .htaccess files
61 if <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is set to
64 <div class="example"><p><code>
65 ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br />
66 ErrorDocument 500 /cgi-bin/crash-recover<br />
67 ErrorDocument 500 http://error.example.com/server_error.html<br />
68 ErrorDocument 404 /errors/not_found.html <br />
69 ErrorDocument 401 /subscription/how_to_subscribe.html
72 <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
74 <div class="example"><p><code>
75 ErrorDocument <3-digit-code> <action>
78 <p>where the action will be treated as:</p>
81 <li>A local URL to redirect to (if the action begins with a "/").</li>
82 <li>An external URL to redirect to (if the action is a valid URL).</li>
83 <li>Text to be displayed (if none of the above). The text must be
84 wrapped in quotes (") if it consists of more than one word.</li>
87 <p>When redirecting to a local URL, additional environment variables
88 are set so that the response can be further customized. They are not sent to
91 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
93 <h2><a name="variables" id="variables">Available Variables</a></h2>
95 <p>Redirecting to another URL can be useful, but only if some
96 information can be passed which can then be used to explain or log
97 the error condition more clearly.</p>
99 <p>To achieve this, when the error redirect is sent, additional
100 environment variables will be set, which will be generated from
101 the headers provided to the original request by prepending
102 'REDIRECT_' onto the original header name. This provides the error
103 document the context of the original request.</p>
105 <p>For example, you might recieve, in addition to more usual
106 environment variables, the following.</p>
108 <div class="example"><p><code>
109 REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
110 REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
111 REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
112 REDIRECT_QUERY_STRING=<br />
113 REDIRECT_REMOTE_ADDR=121.345.78.123<br />
114 REDIRECT_REMOTE_HOST=client.example.com<br />
115 REDIRECT_SERVER_NAME=www.example.edu<br />
116 REDIRECT_SERVER_PORT=80<br />
117 REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
118 REDIRECT_URL=/cgi-bin/buggy.pl
121 <p><code>REDIRECT_</code> environment variables are created from
122 the environment variables which existed prior to the
123 redirect. They are renamed with a <code>REDIRECT_</code>
124 prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
125 <code>REDIRECT_HTTP_USER_AGENT</code>.</p>
127 <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
128 <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
129 the other headers will be set only if they existed prior to the
132 <p><strong>None</strong> of these will be
133 set if the <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> target is an
134 <em>external</em> redirect (anything starting with a
135 scheme name like <code>http:</code>, even if it refers to the same host
137 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
138 <div class="section">
139 <h2><a name="custom" id="custom">Customizing Error Responses</a></h2>
141 <p>If you point your <code>ErrorDocument</code> to some variety of
142 dynamic handler such as a server-side include document, CGI
143 script, or some variety of other handler, you may wish to use the
144 available custom environent variables to customize this
147 <p>If the ErrorDocument specifies a local redirect to a CGI
148 script, the script should include a "<code>Status:</code>"
149 header field in its output in order to ensure the propagation
150 all the way back to the client of the error condition that
151 caused it to be invoked. For instance, a Perl ErrorDocument
152 script might include the following:</p>
154 <div class="example"><p><code>
156 print "Content-type: text/html\n"; <br />
157 printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
161 <p>If the script is dedicated to handling a particular error
162 condition, such as <code>404 Not Found</code>, it can
163 use the specific code and error text instead.</p>
165 <p>Note that if the response contains <code>Location:</code>
166 header (in order to issue a client-side redirect), the script
167 <em>must</em> emit an appropriate <code>Status:</code> header
168 (such as <code>302 Found</code>). Otherwise the
169 <code>Location:</code> header may have no effect.</p>
171 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
172 <div class="section">
173 <h2><a name="multi-lang" id="multi-lang">Multi Language Custom Error Documents</a></h2>
175 <p>Provided with your installation of the Apache HTTP Server is a
176 directory of custom error documents translated into 16 different
177 languages. There's also a configuration file in the
178 <code>conf/extra</code> configuration directory that can be included
179 to enable this feature.</p>
181 <p>In your server configuration file, you'll see a line such as:</p>
183 <div class="example"><p><code>
184 # Multi-language error messages<br />
185 #Include conf/extra/httpd-multilang-errordoc.conf
188 <p>Uncommenting this <code>Include</code> line will enable this
189 feature, and provide language-negotiated error messages, based on
190 the language preference set in the client browser.</p>
192 <p>Additionally, these documents contain various of the
193 <code>REDIRECT_</code> variables, so that additional information can
194 be provided to the end-user about what happened, and what they can
197 <p>These documents can be customized to whatever degree you wish to
198 provide more useful information to users about your site, and what
199 they can expect to find there.</p>
201 <p><code class="module"><a href="./mod/mod_include.html">mod_include</a></code> and <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>
202 must be enabled to use this feature.</p>
205 <div class="bottomlang">
206 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English"> en </a> |
207 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español"> es </a> |
208 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
209 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
210 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
211 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
212 </div><div id="footer">
213 <p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
214 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>