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