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