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