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