granicus.if.org Git - apache/blob - docs/manual/custom-error.html.en

   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" />
  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="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  23 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  24 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  25 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  26 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  27 </div>
  28
  29
  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>
  36
  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
  39     status.</p>
  40
  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>
  47
  48   </div>
  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>
  53 </ul></div>
  54 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  55 <div class="section">
  56 <h2><a name="configuration" id="configuration">Configuration</a></h2>
  57
  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
  62     FileInfo.</p>
  63
  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
  70     </code></p></div>
  71
  72     <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
  73
  74     <div class="example"><p><code>
  75       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
  76     </code></p></div>
  77
  78     <p>where the action will be treated as:</p>
  79
  80     <ol>
  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>
  85     </ol>
  86
  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
  89     external URLs.</p>
  90
  91   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  92 <div class="section">
  93 <h2><a name="variables" id="variables">Available Variables</a></h2>
  94
  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>
  98
  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>
 104
 105       <p>For example, you might recieve, in addition to more usual
 106       environment variables, the following.</p>
 107
 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
 119       </code></p></div>
 120
 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>
 126
 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
 130       error condition.</p>
 131
 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
 136       as the server).</p>
 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>
 140
 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
 145       response.</p>
 146
 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>
 153
 154       <div class="example"><p><code>
 155         ... <br />
 156         print  "Content-type: text/html\n"; <br />
 157         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
 158         ...
 159       </code></p></div>
 160
 161       <p>If the script is dedicated to handling a particular error
 162       condition, such as <code>404&nbsp;Not&nbsp;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&nbsp;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     <div class="example"><p><code>
 184     # Multi-language error messages<br />
 185     #Include conf/extra/httpd-multilang-errordoc.conf
 186     </code></p></div>
 187
 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>
 191
 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
 195     do now.</p>
 196
 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>
 200
 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>
 203
 204  </div></div>
 205 <div class="bottomlang">
 206 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
 207 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 208 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 209 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 210 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 211 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</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>
 215 </body></html>