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 7 --> 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.4</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<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.4</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/custom-error.html" title="English"> en </a> | 25<a href="/es/custom-error.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> | 26<a href="/fr/custom-error.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 27<a href="/ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 28<a href="/ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 29<a href="/tr/custom-error.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 30</div> 31 32 33 <p>Although the Apache HTTP Server provides generic error responses 34 in the event of 4xx or 5xx HTTP status codes, these responses are 35 rather stark, uninformative, and can be intimidating to site users. 36 You may wish to provide custom error responses which are either 37 friendlier, or in some language other than English, or perhaps which 38 are styled more in line with your site layout.</p> 39 40 <p>Customized error responses can be defined for any HTTP status 41 code designated as an error condition - that is, any 4xx or 5xx 42 status.</p> 43 44 <p>Additionally, a set of values are provided, so 45 that the error document can be customized further based on the 46 values of these variables, using <a href="howto/ssi.html">Server 47 Side Includes</a>. Or, you can have error conditions handled by a 48 cgi program, or other dynamic handler (PHP, mod_perl, etc) which 49 makes use of these variables.</p> 50 51 </div> 52<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#configuration">Configuration</a></li> 53<li><img alt="" src="/images/down.gif" /> <a href="#variables">Available Variables</a></li> 54<li><img alt="" src="/images/down.gif" /> <a href="#custom">Customizing Error Responses</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#multi-lang">Multi Language Custom Error Documents</a></li> 56</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 57<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 58<div class="section"> 59<h2><a name="configuration" id="configuration">Configuration</a></h2> 60 61 <p>Custom error documents are configured using the <code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code> directive, 62 which may be used in global, 63 virtualhost, or directory context. It may be used in .htaccess files 64 if <code class="directive"><a href="/mod/core.html#allowoverride">AllowOverride</a></code> is set to 65 FileInfo.</p> 66 67 <pre class="prettyprint lang-config">ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br /> 68ErrorDocument 500 /cgi-bin/crash-recover<br /> 69ErrorDocument 500 http://error.example.com/server_error.html<br /> 70ErrorDocument 404 /errors/not_found.html <br /> 71ErrorDocument 401 /subscription/how_to_subscribe.html</pre> 72 73 74 <p>The syntax of the <code>ErrorDocument</code> directive is:</p> 75 76 <pre class="prettyprint lang-config">ErrorDocument <3-digit-code> <action></pre> 77 78 79 <p>where the action will be treated as:</p> 80 81 <ol> 82 <li>A local URL to redirect to (if the action begins with a "/").</li> 83 <li>An external URL to redirect to (if the action is a valid URL).</li> 84 <li>Text to be displayed (if none of the above). The text must be 85 wrapped in quotes (") if it consists of more than one word.</li> 86 </ol> 87 88 <p>When redirecting to a local URL, additional environment variables 89 are set so that the response can be further customized. They are not sent to 90 external URLs.</p> 91 92 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 93<div class="section"> 94<h2><a name="variables" id="variables">Available Variables</a></h2> 95 96 <p>Redirecting to another URL can be useful, but only if some 97 information can be passed which can then be used to explain or log 98 the error condition more clearly.</p> 99 100 <p>To achieve this, when the error redirect is sent, additional 101 environment variables will be set, which will be generated from 102 the headers provided to the original request by prepending 103 'REDIRECT_' onto the original header name. This provides the error 104 document the context of the original request.</p> 105 106 <p>For example, you might receive, in addition to more usual 107 environment variables, the following.</p> 108 109 <div class="example"><p><code> 110 REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br /> 111 REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br /> 112 REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br /> 113 REDIRECT_QUERY_STRING=<br /> 114 REDIRECT_REMOTE_ADDR=121.345.78.123<br /> 115 REDIRECT_REMOTE_HOST=client.example.com<br /> 116 REDIRECT_SERVER_NAME=www.example.edu<br /> 117 REDIRECT_SERVER_PORT=80<br /> 118 REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br /> 119 REDIRECT_URL=/cgi-bin/buggy.pl 120 </code></p></div> 121 122 <p><code>REDIRECT_</code> environment variables are created from 123 the environment variables which existed prior to the 124 redirect. They are renamed with a <code>REDIRECT_</code> 125 prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes 126 <code>REDIRECT_HTTP_USER_AGENT</code>.</p> 127 128 <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and 129 <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and 130 the other headers will be set only if they existed prior to the 131 error condition.</p> 132 133 <p><strong>None</strong> of these will be 134 set if the <code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code> target is an 135 <em>external</em> redirect (anything starting with a 136 scheme name like <code>http:</code>, even if it refers to the same host 137 as the server).</p> 138 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 139<div class="section"> 140<h2><a name="custom" id="custom">Customizing Error Responses</a></h2> 141 142 <p>If you point your <code>ErrorDocument</code> to some variety of 143 dynamic handler such as a server-side include document, CGI 144 script, or some variety of other handler, you may wish to use the 145 available custom environment variables to customize this 146 response.</p> 147 148 <p>If the ErrorDocument specifies a local redirect to a CGI 149 script, the script should include a "<code>Status:</code>" 150 header field in its output in order to ensure the propagation 151 all the way back to the client of the error condition that 152 caused it to be invoked. For instance, a Perl ErrorDocument 153 script might include the following:</p> 154 155 <pre class="prettyprint lang-perl">... 156print "Content-type: text/html\n"; <br /> 157printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br /> 158...</pre> 159 160 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> 164 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> 170 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> 174 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> 180 181 <p>In your server configuration file, you'll see a line such as:</p> 182 183 <pre class="prettyprint lang-config"> # Multi-language error messages<br /> 184 #Include conf/extra/httpd-multilang-errordoc.conf</pre> 185 186 187 <p>Uncommenting this <code>Include</code> line will enable this 188 feature, and provide language-negotiated error messages, based on 189 the language preference set in the client browser.</p> 190 191 <p>Additionally, these documents contain various of the 192 <code>REDIRECT_</code> variables, so that additional information can 193 be provided to the end-user about what happened, and what they can 194 do now.</p> 195 196 <p>These documents can be customized to whatever degree you wish to 197 provide more useful information to users about your site, and what 198 they can expect to find there.</p> 199 200 <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> 201 must be enabled to use this feature.</p> 202 203 </div></div> 204<div class="bottomlang"> 205<p><span>Available Languages: </span><a href="/en/custom-error.html" title="English"> en </a> | 206<a href="/es/custom-error.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> | 207<a href="/fr/custom-error.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 208<a href="/ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 209<a href="/ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 210<a href="/tr/custom-error.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 211</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 212<script type="text/javascript"><!--//--><![CDATA[//><!-- 213var comments_shortname = 'httpd'; 214var comments_identifier = 'http://httpd.apache.org/docs/2.4/custom-error.html'; 215(function(w, d) { 216 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 217 d.write('<div id="comments_thread"><\/div>'); 218 var s = d.createElement('script'); 219 s.type = 'text/javascript'; 220 s.async = true; 221 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 222 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 223 } 224 else { 225 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 226 } 227})(window, document); 228//--><!]]></script></div><div id="footer"> 229<p class="apache">Copyright 2014 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> 230<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 231if (typeof(prettyPrint) !== 'undefined') { 232 prettyPrint(); 233} 234//--><!]]></script> 235</body></html>
