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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Custom Error Responses - Apache HTTP Server</title>
   9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.1</p>
  16 <img alt="" src="./images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="./">Version 2.1</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
  20     <p>Additional functionality allows webmasters to configure the response
  21     of Apache to some error or problem.</p>
  22
  23     <p>Customizable responses can be defined to be activated in the event of
  24     a server detected error or problem.</p>
  25
  26     <p>If a script crashes and produces a "500 Server Error" response,
  27     then this response can be replaced with either some friendlier text or by
  28     a redirection to another URL (local or external).</p>
  29   </div>
  30 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#behavior">Behavior</a></li>
  31 <li><img alt="" src="./images/down.gif" /> <a href="#configuration">Configuration</a></li>
  32 <li><img alt="" src="./images/down.gif" /> <a href="#custom">Custom Error Responses and Redirects</a></li>
  33 </ul></div>
  34 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  35 <div class="section">
  36 <h2><a name="behavior" id="behavior">Behavior</a></h2>
  37
  38
  39     <h3>Old Behavior</h3>
  40
  41
  42       <p>NCSA httpd 1.3 would return some boring old error/problem message
  43       which would often be meaningless to the user, and would provide no
  44       means of logging the symptoms which caused it.</p>
  45
  46
  47     <h3>New Behavior</h3>
  48
  49
  50       <p>The server can be asked to:</p>
  51
  52       <ol>
  53         <li>Display some other text, instead of the NCSA hard coded
  54         messages, or</li>
  55
  56         <li>redirect to a local URL, or</li>
  57
  58         <li>redirect to an external URL.</li>
  59       </ol>
  60
  61       <p>Redirecting to another URL can be useful, but only if some
  62       information can be passed which can then be used to explain and/or log
  63       the error/problem more clearly.</p>
  64
  65       <p>To achieve this, Apache will define new CGI-like environment
  66       variables:</p>
  67
  68       <div class="example"><p><code>
  69         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
  70             image/jpeg<br />
  71         REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
  72             9000/712)<br />
  73         REDIRECT_PATH=.:/bin:/usr/local/bin:/etc<br />
  74         REDIRECT_QUERY_STRING=<br />
  75         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
  76         REDIRECT_REMOTE_HOST=ooh.ahhh.com<br />
  77         REDIRECT_SERVER_NAME=crash.bang.edu<br />
  78         REDIRECT_SERVER_PORT=80<br />
  79         REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
  80         REDIRECT_URL=/cgi-bin/buggy.pl
  81       </code></p></div>
  82
  83       <p>Note the <code>REDIRECT_</code> prefix.</p>
  84
  85       <p>At least <code>REDIRECT_URL</code> and
  86       <code>REDIRECT_QUERY_STRING</code> will be passed to the
  87       new URL (assuming it's a cgi-script or a cgi-include). The
  88       other variables will exist only if they existed prior to
  89       the error/problem. <strong>None</strong> of these will be
  90       set if your <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> is an
  91       <em>external</em> redirect (anything starting with a
  92       scheme name like <code>http:</code>, even if it refers to the same host
  93       as the server).</p>
  94
  95   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  96 <div class="section">
  97 <h2><a name="configuration" id="configuration">Configuration</a></h2>
  98
  99
 100     <p>Use of <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> is enabled
 101     for .htaccess files when the
 102     <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is set accordingly.</p>
 103
 104     <p>Here are some examples...</p>
 105
 106     <div class="example"><p><code>
 107       ErrorDocument 500 /cgi-bin/crash-recover <br />
 108       ErrorDocument 500 "Sorry, our script crashed. Oh dear" <br />
 109       ErrorDocument 500 http://xxx/ <br />
 110       ErrorDocument 404 /Lame_excuses/not_found.html <br />
 111       ErrorDocument 401 /Subscription/how_to_subscribe.html
 112     </code></p></div>
 113
 114     <p>The syntax is,</p>
 115
 116     <div class="example"><p><code>
 117       ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
 118     </code></p></div>
 119
 120     <p>where the action can be,</p>
 121
 122     <ol>
 123       <li>Text to be displayed. Prefix the text with a quote
 124       ("). Whatever follows the quote is displayed. <em>Note:
 125       the (") prefix isn't displayed.</em></li>
 126
 127       <li>An external URL to redirect to.</li>
 128
 129       <li>A local URL to redirect to.</li>
 130     </ol>
 131   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 132 <div class="section">
 133 <h2><a name="custom" id="custom">Custom Error Responses and Redirects</a></h2>
 134
 135
 136     <p>Apache's behavior to redirected URLs has been modified so
 137     that additional environment variables are available to a
 138     script/server-include.</p>
 139
 140     <h3>Old behavior</h3>
 141
 142
 143       <p>Standard CGI vars were made available to a script which
 144       has been redirected to. No indication of where the
 145       redirection came from was provided.</p>
 146
 147
 148     <h3>New behavior</h3>
 149
 150
 151       <p>A new batch of environment variables will be initialized
 152       for use by a script which has been redirected to. Each new
 153       variable will have the prefix <code>REDIRECT_</code>.
 154       <code>REDIRECT_</code> environment variables are created from
 155       the CGI environment variables which existed prior to the
 156       redirect, they are renamed with a <code>REDIRECT_</code>
 157       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
 158       <code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these
 159       new variables, Apache will define <code>REDIRECT_URL</code>
 160       and <code>REDIRECT_STATUS</code> to help the script trace its
 161       origin. Both the original URL and the URL being redirected to
 162       can be logged in the access log.</p>
 163
 164       <p>If the ErrorDocument specifies a local redirect to a CGI
 165       script, the script should include a "<code>Status:</code>"
 166       header field in its output in order to ensure the propagation
 167       all the way back to the client of the error condition that
 168       caused it to be invoked. For instance, a Perl ErrorDocument
 169       script might include the following:</p>
 170
 171       <div class="example"><p><code>
 172         ... <br />
 173         print  "Content-type: text/html\n"; <br />
 174         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
 175         ...
 176       </code></p></div>
 177
 178       <p>If the script is dedicated to handling a particular error
 179       condition, such as <code>404 Not Found</code>, it can
 180       use the specific code and error text instead.</p>
 181
 182       <p>Note that the script <em>must</em> emit an appropriate
 183       <code>Status:</code> header (such as <code>302 Found</code>), if the
 184       response contains a <code>Location:</code> header (in order to issue a
 185       client side redirect). Otherwise the <code>Location:</code> header may
 186       have no effect.</p>
 187
 188   </div></div>
 189 <div id="footer">
 190 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
 191 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
 192 </body></html>