apache/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     <p>Additional functionality allows webmasters to configure the response
  29     of Apache to some error or problem.</p>
  30
  31     <p>Customizable responses can be defined to be activated in the event of
  32     a server detected error or problem.</p>
  33
  34     <p>If a script crashes and produces a "500 Server Error" response,
  35     then this response can be replaced with either some friendlier text or by
  36     a redirection to another URL (local or external).</p>
  37   </summary>
  38
  39   <section id="behavior">
  40     <title>Behavior</title>
  41
  42     <section>
  43       <title>Old Behavior</title>
  44
  45       <p>NCSA httpd 1.3 would return some boring old error/problem message
  46       which would often be meaningless to the user, and would provide no
  47       means of logging the symptoms which caused it.</p>
  48     </section>
  49
  50     <section>
  51       <title>New Behavior</title>
  52
  53       <p>The server can be asked to:</p>
  54
  55       <ol>
  56         <li>Display some other text, instead of the NCSA hard coded
  57         messages, or</li>
  58
  59         <li>redirect to a local URL, or</li>
  60
  61         <li>redirect to an external URL.</li>
  62       </ol>
  63
  64       <p>Redirecting to another URL can be useful, but only if some
  65       information can be passed which can then be used to explain and/or log
  66       the error/problem more clearly.</p>
  67
  68       <p>To achieve this, Apache will define new CGI-like environment
  69       variables:</p>
  70
  71       <example>
  72         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
  73             image/jpeg<br />
  74         REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
  75             9000/712)<br />
  76         REDIRECT_PATH=.:/bin:/usr/local/bin:/etc<br />
  77         REDIRECT_QUERY_STRING=<br />
  78         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
  79         REDIRECT_REMOTE_HOST=ooh.ahhh.com<br />
  80         REDIRECT_SERVER_NAME=crash.bang.edu<br />
  81         REDIRECT_SERVER_PORT=80<br />
  82         REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
  83         REDIRECT_URL=/cgi-bin/buggy.pl
  84       </example>
  85
  86       <p>Note the <code>REDIRECT_</code> prefix.</p>
  87
  88       <p>At least <code>REDIRECT_URL</code> and
  89       <code>REDIRECT_QUERY_STRING</code> will be passed to the
  90       new URL (assuming it's a cgi-script or a cgi-include). The
  91       other variables will exist only if they existed prior to
  92       the error/problem. <strong>None</strong> of these will be
  93       set if your <directive module="core">ErrorDocument</directive> is an
  94       <em>external</em> redirect (anything starting with a
  95       scheme name like <code>http:</code>, even if it refers to the same host
  96       as the server).</p>
  97     </section>
  98   </section>
  99
 100   <section id="configuration">
 101     <title>Configuration</title>
 102
 103     <p>Use of <directive module="core">ErrorDocument</directive> is enabled
 104     for .htaccess files when the
 105     <directive module="core">AllowOverride</directive> is set accordingly.</p>
 106
 107     <p>Here are some examples...</p>
 108
 109     <example>
 110       ErrorDocument 500 /cgi-bin/crash-recover <br />
 111       ErrorDocument 500 "Sorry, our script crashed. Oh dear" <br />
 112       ErrorDocument 500 http://xxx/ <br />
 113       ErrorDocument 404 /Lame_excuses/not_found.html <br />
 114       ErrorDocument 401 /Subscription/how_to_subscribe.html
 115     </example>
 116
 117     <p>The syntax is,</p>
 118
 119     <example>
 120       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
 121     </example>
 122
 123     <p>where the action can be,</p>
 124
 125     <ol>
 126       <li>Text to be displayed. Wrap the text with quotes (").</li>
 127
 128       <li>An external URL to redirect to.</li>
 129
 130       <li>A local URL to redirect to.</li>
 131     </ol>
 132   </section>
 133
 134   <section id="custom">
 135     <title>Custom Error Responses and Redirects</title>
 136
 137     <p>Apache's behavior to redirected URLs has been modified so
 138     that additional environment variables are available to a
 139     script/server-include.</p>
 140
 141     <section>
 142       <title>Old behavior</title>
 143
 144       <p>Standard CGI vars were made available to a script which
 145       has been redirected to. No indication of where the
 146       redirection came from was provided.</p>
 147     </section>
 148
 149     <section>
 150       <title>New behavior</title>
 151
 152       <p>A new batch of environment variables will be initialized
 153       for use by a script which has been redirected to. Each new
 154       variable will have the prefix <code>REDIRECT_</code>.
 155       <code>REDIRECT_</code> environment variables are created from
 156       the CGI environment variables which existed prior to the
 157       redirect, they are renamed with a <code>REDIRECT_</code>
 158       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
 159       <code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these
 160       new variables, Apache will define <code>REDIRECT_URL</code>
 161       and <code>REDIRECT_STATUS</code> to help the script trace its
 162       origin. Both the original URL and the URL being redirected to
 163       can be logged in the access log.</p>
 164
 165       <p>If the ErrorDocument specifies a local redirect to a CGI
 166       script, the script should include a "<code>Status:</code>"
 167       header field in its output in order to ensure the propagation
 168       all the way back to the client of the error condition that
 169       caused it to be invoked. For instance, a Perl ErrorDocument
 170       script might include the following:</p>
 171
 172       <example>
 173         ... <br />
 174         print  "Content-type: text/html\n"; <br />
 175         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
 176         ...
 177       </example>
 178
 179       <p>If the script is dedicated to handling a particular error
 180       condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
 181       use the specific code and error text instead.</p>
 182
 183       <p>Note that the script <em>must</em> emit an appropriate
 184       <code>Status:</code> header (such as <code>302&nbsp;Found</code>), if the
 185       response contains a <code>Location:</code> header (in order to issue a
 186       client side redirect). Otherwise the <code>Location:</code> header may
 187       have no effect.</p>
 188     </section>
 189   </section>
 190 </manualpage>