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 Customer 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 can be one of:</p>
  79
  80     <ol>
  81       <li>Text to be displayed. Wrap the text with quotes (").</li>
  82       <li>A local URL to redirect to.</li>
  83       <li>An external URL to redirect to.</li>
  84     </ol>
  85
  86     <p>When redirecting to a local URL, additional environment variables
  87     are set so that the response can be further customized. They are not sent to
  88     external URLs.</p>
  89
  90   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  91 <div class="section">
  92 <h2><a name="variables" id="variables">Available Variables</a></h2>
  93
  94       <p>Redirecting to another URL can be useful, but only if some
  95       information can be passed which can then be used to explain or log
  96       the error condition more clearly.</p>
  97
  98       <p>To achieve this, when the error redirect is sent, additional
  99       environment variables will be set, which will be generated from
 100       the headers provided to the original request by prepending
 101       'REDIRECT_' onto the original header name. This provides the error
 102       document the context of the original request.</p>
 103
 104       <p>For example, you might recieve, in addition to more usual
 105       environment variables, the following.</p>
 106
 107       <div class="example"><p><code>
 108         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
 109         REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
 110         REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
 111         REDIRECT_QUERY_STRING=<br />
 112         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
 113         REDIRECT_REMOTE_HOST=client.example.com<br />
 114         REDIRECT_SERVER_NAME=www.example.edu<br />
 115         REDIRECT_SERVER_PORT=80<br />
 116         REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
 117         REDIRECT_URL=/cgi-bin/buggy.pl
 118       </code></p></div>
 119
 120       <p><code>REDIRECT_</code> environment variables are created from
 121       the environment variables which existed prior to the
 122       redirect. They are renamed with a <code>REDIRECT_</code>
 123       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
 124       <code>REDIRECT_HTTP_USER_AGENT</code>.</p>
 125
 126       <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
 127       <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
 128       the other headers will be set only if they existed prior to the
 129       error condition.</p>
 130
 131       <p><strong>None</strong> of these will be
 132       set if the <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> target is an
 133       <em>external</em> redirect (anything starting with a
 134       scheme name like <code>http:</code>, even if it refers to the same host
 135       as the server).</p>
 136   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 137 <div class="section">
 138 <h2><a name="custom" id="custom">Customizing Error Responses</a></h2>
 139
 140       <p>If you point your <code>ErrorDocument</code> to some variety of
 141       dynamic handler such as a server-side include document, CGI
 142       script, or some variety of other handler, you may wish to use the
 143       available custom environent variables to customize this
 144       response.</p>
 145
 146       <p>If the ErrorDocument specifies a local redirect to a CGI
 147       script, the script should include a "<code>Status:</code>"
 148       header field in its output in order to ensure the propagation
 149       all the way back to the client of the error condition that
 150       caused it to be invoked. For instance, a Perl ErrorDocument
 151       script might include the following:</p>
 152
 153       <div class="example"><p><code>
 154         ... <br />
 155         print  "Content-type: text/html\n"; <br />
 156         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
 157         ...
 158       </code></p></div>
 159
 160       <p>If the script is dedicated to handling a particular error
 161       condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
 162       use the specific code and error text instead.</p>
 163
 164       <p>Note that if the response contains <code>Location:</code>
 165       header (in order to issue a client-side redirect), the script
 166       <em>must</em> emit an appropriate <code>Status:</code> header
 167       (such as <code>302&nbsp;Found</code>). Otherwise the
 168       <code>Location:</code> header may have no effect.</p>
 169
 170   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 171 <div class="section">
 172 <h2><a name="multi-lang" id="multi-lang">Multi Language Customer Error Documents</a></h2>
 173
 174     <p>Provided with your installation of the Apache HTTP Server is a
 175     directory of custom error documents translated into 16 different
 176     languages. There's also a configuration file in the
 177     <code>conf/extra</code> configuration directory that can be included
 178     to enable this feature.</p>
 179
 180     <p>In your server configuration file, you'll see a line such as:</p>
 181
 182     <div class="example"><p><code>
 183     # Multi-language error messages<br />
 184     #Include conf/extra/httpd-multilang-errordoc.conf
 185     </code></p></div>
 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">&nbsp;en&nbsp;</a> |
 206 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 207 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 208 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 209 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 210 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 211 </div><div id="footer">
 212 <p class="apache">Copyright 2010 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>
 213 <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>
 214 </body></html>