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

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Custom error responses</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16 <H1 ALIGN="CENTER">Custom error responses</H1>
  17
  18 <DL>
  19
  20 <DT>Purpose
  21
  22   <DD>Additional functionality. Allows webmasters to configure the response of
  23       Apache to some error or problem.
  24
  25       <P>Customizable responses can be defined to be activated in the
  26       event of a server detected error or problem.
  27
  28       <P>e.g. if a script crashes and produces a "500 Server Error"
  29       response, then this response can be replaced with either some
  30       friendlier text or by a redirection to another URL (local or
  31       external).
  32
  33       <P>
  34
  35 <DT>Old behavior
  36
  37   <DD>NCSA httpd 1.3 would return some boring old error/problem message
  38       which would often be meaningless to the user, and would provide no
  39       means of logging the symptoms which caused it.<BR>
  40
  41       <P>
  42
  43 <DT>New behavior
  44
  45   <DD>The server can be asked to;
  46   <OL>
  47     <LI>Display some other text, instead of the NCSA hard coded messages, or
  48     <LI>redirect to a local URL, or
  49     <LI>redirect to an external URL.
  50   </OL>
  51
  52   <P>Redirecting to another URL can be useful, but only if some information
  53      can be passed which can then be used to explain and/or log the error/problem
  54      more clearly.
  55
  56   <P>To achieve this, Apache will define new CGI-like environment
  57      variables, e.g.
  58
  59   <blockquote><code>
  60 REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>
  61 REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
  62 REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br>
  63 REDIRECT_QUERY_STRING= <br>
  64 REDIRECT_REMOTE_ADDR=121.345.78.123 <br>
  65 REDIRECT_REMOTE_HOST=ooh.ahhh.com <br>
  66 REDIRECT_SERVER_NAME=crash.bang.edu <br>
  67 REDIRECT_SERVER_PORT=80 <br>
  68 REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br>
  69 REDIRECT_URL=/cgi-bin/buggy.pl <br>
  70   </code></blockquote>
  71
  72   <P>note the <code>REDIRECT_</code> prefix.
  73
  74   <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will
  75      be passed to the new URL (assuming it's a cgi-script or a cgi-include). The
  76      other variables will exist only if they existed prior to the error/problem.
  77      <b>None</b> of these will be set if your ErrorDocument is an
  78      <i>external</i> redirect (i.e. anything starting with a protocol name
  79      like <code>http:</code>, even if it refers to the same host as the
  80      server).<p>
  81
  82 <DT>Configuration
  83
  84   <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
  85        <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.
  86
  87   <P>Here are some examples...
  88
  89   <blockquote><code>
  90 ErrorDocument 500 /cgi-bin/crash-recover <br>
  91 ErrorDocument 500 "Sorry, our script crashed. Oh dear<br>
  92 ErrorDocument 500 http://xxx/ <br>
  93 ErrorDocument 404 /Lame_excuses/not_found.html  <br>
  94 ErrorDocument 401 /Subscription/how_to_subscribe.html
  95   </code></blockquote>
  96
  97   <P>The syntax is,
  98
  99   <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>
 100 &lt;3-digit-code&gt; action
 101
 102   <P>where the action can be,
 103
 104   <OL>
 105     <LI>Text to be displayed.  Prefix the text with a quote (&quot;). Whatever
 106         follows the quote is displayed. <em>Note: the (&quot;) prefix isn't
 107         displayed.</em>
 108
 109     <LI>An external URL to redirect to.
 110
 111     <LI>A local URL to redirect to.
 112
 113   </OL>
 114 </DL>
 115
 116 <P><HR><P>
 117
 118 <h2>Custom error responses and redirects</H2>
 119
 120 <DL>
 121
 122 <DT>Purpose
 123
 124   <DD>Apache's behavior to redirected URLs has been modified so that additional
 125       environment variables are available to a script/server-include.<p>
 126
 127 <DT>Old behavior
 128
 129   <DD>Standard CGI vars were made available to a script which has been
 130       redirected to. No indication of where the redirection came from was provided.
 131
 132   <p>
 133
 134 <DT>New behavior
 135   <DD>
 136
 137 A new batch of environment variables will be initialized for use by a
 138 script which has been redirected to.  Each new variable will have the
 139 prefix <code>REDIRECT_</code>.  <code>REDIRECT_</code> environment
 140 variables are created from the CGI environment variables which existed
 141 prior to the redirect, they are renamed with a <code>REDIRECT_</code>
 142 prefix, i.e. <code>HTTP_USER_AGENT</code> becomes
 143 <code>REDIRECT_HTTP_USER_AGENT</code>.  In addition to these new
 144 variables, Apache will define <code>REDIRECT_URL</code> and
 145 <code>REDIRECT_STATUS</code> to help the script trace its origin.
 146 Both the original URL and the URL being redirected to can be logged in
 147 the access log.
 148
 149 </DL>
 150
 151 <!--#include virtual="footer.html" -->
 152 </BODY>
 153 </HTML>