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

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="custom-error.xml.meta">
  24
  25   <title>Custom Error Responses</title>
  26
  27   <summary>
  28
  29     <p>Although the Apache HTTP Server provides generic error responses
  30     in the event of 4xx or 5xx HTTP status codes, these responses are
  31     rather stark, uninformative, and can be intimidating to site users.
  32     You may wish to provide custom error responses which are either
  33     friendlier, or in some language other than English, or perhaps which
  34     are styled more in line with your site layout.</p>
  35
  36     <p>Customized error responses can be defined for any HTTP status
  37     code designated as an error condition - that is, any 4xx or 5xx
  38     status.</p>
  39
  40     <p>Additionally, a set of values are provided, so
  41     that the error document can be customized further based on the
  42     values of these variables, using <a href="howto/ssi.html">Server
  43     Side Includes</a>. Or, you can have error conditions handled by a
  44     cgi program, or other dynamic handler (PHP, mod_perl, etc) which
  45     makes use of these variables.</p>
  46
  47   </summary>
  48
  49   <section id="configuration"><title>Configuration</title>
  50
  51     <p>Custom error documents are configured using the <directive
  52     module="core">ErrorDocument</directive> directive,
  53     which may be used in global,
  54     virtualhost, or directory context. It may be used in .htaccess files
  55     if <directive module="core">AllowOverride</directive> is set to
  56     FileInfo.</p>
  57
  58     <highlight language="config">
  59 ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br />
  60 ErrorDocument 500 /cgi-bin/crash-recover<br />
  61 ErrorDocument 500 http://error.example.com/server_error.html<br />
  62 ErrorDocument 404 /errors/not_found.html <br />
  63 ErrorDocument 401 /subscription/how_to_subscribe.html
  64     </highlight>
  65
  66     <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
  67
  68     <highlight language="config">
  69       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
  70     </highlight>
  71
  72     <p>where the action will be treated as:</p>
  73
  74     <ol>
  75       <li>A local URL to redirect to (if the action begins with a "/").</li>
  76       <li>An external URL to redirect to (if the action is a valid URL).</li>
  77       <li>Text to be displayed (if none of the above). The text must be
  78           wrapped in quotes (") if it consists of more than one word.</li>
  79     </ol>
  80
  81     <p>When redirecting to a local URL, additional environment variables
  82     are set so that the response can be further customized. They are not sent to
  83     external URLs.</p>
  84
  85   </section>
  86
  87   <section id="variables"><title>Available Variables</title>
  88
  89       <p>Redirecting to another URL can be useful, but only if some
  90       information can be passed which can then be used to explain or log
  91       the error condition more clearly.</p>
  92
  93       <p>To achieve this, when the error redirect is sent, additional
  94       environment variables will be set, which will be generated from
  95       the headers provided to the original request by prepending
  96       'REDIRECT_' onto the original header name. This provides the error
  97       document the context of the original request.</p>
  98
  99       <p>For example, you might receive, in addition to more usual
 100       environment variables, the following.</p>
 101
 102       <example>
 103         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
 104         REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
 105         REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
 106         REDIRECT_QUERY_STRING=<br />
 107         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
 108         REDIRECT_REMOTE_HOST=client.example.com<br />
 109         REDIRECT_SERVER_NAME=www.example.edu<br />
 110         REDIRECT_SERVER_PORT=80<br />
 111         REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
 112         REDIRECT_URL=/cgi-bin/buggy.pl
 113       </example>
 114
 115       <p><code>REDIRECT_</code> environment variables are created from
 116       the environment variables which existed prior to the
 117       redirect. They are renamed with a <code>REDIRECT_</code>
 118       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
 119       <code>REDIRECT_HTTP_USER_AGENT</code>.</p>
 120
 121       <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
 122       <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
 123       the other headers will be set only if they existed prior to the
 124       error condition.</p>
 125
 126       <p><strong>None</strong> of these will be
 127       set if the <directive module="core">ErrorDocument</directive> target is an
 128       <em>external</em> redirect (anything starting with a
 129       scheme name like <code>http:</code>, even if it refers to the same host
 130       as the server).</p>
 131   </section>
 132
 133   <section id="custom"><title>Customizing Error Responses</title>
 134
 135       <p>If you point your <code>ErrorDocument</code> to some variety of
 136       dynamic handler such as a server-side include document, CGI
 137       script, or some variety of other handler, you may wish to use the
 138       available custom environment variables to customize this
 139       response.</p>
 140
 141       <p>If the ErrorDocument specifies a local redirect to a CGI
 142       script, the script should include a "<code>Status:</code>"
 143       header field in its output in order to ensure the propagation
 144       all the way back to the client of the error condition that
 145       caused it to be invoked. For instance, a Perl ErrorDocument
 146       script might include the following:</p>
 147
 148        <highlight language="perl">
 149 ...
 150 print  "Content-type: text/html\n"; <br />
 151 printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
 152 ...
 153       </highlight>
 154
 155       <p>If the script is dedicated to handling a particular error
 156       condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
 157       use the specific code and error text instead.</p>
 158
 159       <p>Note that if the response contains <code>Location:</code>
 160       header (in order to issue a client-side redirect), the script
 161       <em>must</em> emit an appropriate <code>Status:</code> header
 162       (such as <code>302&nbsp;Found</code>). Otherwise the
 163       <code>Location:</code> header may have no effect.</p>
 164
 165   </section>
 166
 167   <section id="multi-lang"><title>Multi Language Custom Error Documents</title>
 168
 169     <p>Provided with your installation of the Apache HTTP Server is a
 170     directory of custom error documents translated into 16 different
 171     languages. There's also a configuration file in the
 172     <code>conf/extra</code> configuration directory that can be included
 173     to enable this feature.</p>
 174
 175     <p>In your server configuration file, you'll see a line such as:</p>
 176
 177     <highlight language="config">
 178     # Multi-language error messages<br />
 179     #Include conf/extra/httpd-multilang-errordoc.conf
 180     </highlight>
 181
 182     <p>Uncommenting this <code>Include</code> line will enable this
 183     feature, and provide language-negotiated error messages, based on
 184     the language preference set in the client browser.</p>
 185
 186     <p>Additionally, these documents contain various of the
 187     <code>REDIRECT_</code> variables, so that additional information can
 188     be provided to the end-user about what happened, and what they can
 189     do now.</p>
 190
 191     <p>These documents can be customized to whatever degree you wish to
 192     provide more useful information to users about your site, and what
 193     they can expect to find there.</p>
 194
 195     <p><module>mod_include</module> and <module>mod_negotiation</module>
 196     must be enabled to use this feature.</p>
 197
 198  </section>
 199
 200 </manualpage>