home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277655_customerror.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  7KB  |  192 lines
  1. <?xml version="1.0" encoding="UTF-8" ?>
  2. <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
  3. <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
  4. <!-- $Revision: 1.1.2.7 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <manualpage metafile="custom-error.xml.meta">
  23.  
  24.   <title>Custom Error Responses</title>
  25.  
  26.   <summary>
  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.   </summary>
  37.  
  38.   <section id="behavior">
  39.     <title>Behavior</title>
  40.  
  41.     <section>
  42.       <title>Old Behavior</title>
  43.  
  44.       <p>NCSA httpd 1.3 would return some boring old error/problem message 
  45.       which would often be meaningless to the user, and would provide no 
  46.       means of logging the symptoms which caused it.</p>
  47.     </section>
  48.  
  49.     <section>
  50.       <title>New Behavior</title>
  51.  
  52.       <p>The server can be asked to:</p>
  53.  
  54.       <ol>
  55.         <li>Display some other text, instead of the NCSA hard coded 
  56.         messages, or</li>
  57.  
  58.         <li>redirect to a local URL, or</li>
  59.  
  60.         <li>redirect to an external URL.</li>
  61.       </ol>
  62.  
  63.       <p>Redirecting to another URL can be useful, but only if some 
  64.       information can be passed which can then be used to explain and/or log 
  65.       the error/problem more clearly.</p>
  66.  
  67.       <p>To achieve this, Apache will define new CGI-like environment 
  68.       variables:</p>
  69.  
  70.       <example>
  71.         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, 
  72.             image/jpeg<br />
  73.         REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 
  74.             9000/712)<br />
  75.         REDIRECT_PATH=.:/bin:/usr/local/bin:/etc<br />
  76.         REDIRECT_QUERY_STRING=<br />
  77.         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
  78.         REDIRECT_REMOTE_HOST=ooh.ahhh.com<br />
  79.         REDIRECT_SERVER_NAME=crash.bang.edu<br />
  80.         REDIRECT_SERVER_PORT=80<br />
  81.         REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
  82.         REDIRECT_URL=/cgi-bin/buggy.pl
  83.       </example>
  84.  
  85.       <p>Note the <code>REDIRECT_</code> prefix.</p>
  86.  
  87.       <p>At least <code>REDIRECT_URL</code> and
  88.       <code>REDIRECT_QUERY_STRING</code> will be passed to the
  89.       new URL (assuming it's a cgi-script or a cgi-include). The
  90.       other variables will exist only if they existed prior to
  91.       the error/problem. <strong>None</strong> of these will be
  92.       set if your <directive module="core">ErrorDocument</directive> is an 
  93.       <em>external</em> redirect (anything starting with a 
  94.       scheme name like <code>http:</code>, even if it refers to the same host 
  95.       as the server).</p>
  96.     </section>
  97.   </section>
  98.  
  99.   <section id="configuration">
  100.     <title>Configuration</title>
  101.  
  102.     <p>Use of <directive module="core">ErrorDocument</directive> is enabled 
  103.     for .htaccess files when the 
  104.     <directive module="core">AllowOverride</directive> is set accordingly.</p>
  105.  
  106.     <p>Here are some examples...</p>
  107.  
  108.     <example>
  109.       ErrorDocument 500 /cgi-bin/crash-recover <br />
  110.       ErrorDocument 500 "Sorry, our script crashed. Oh dear" <br />
  111.       ErrorDocument 500 http://xxx/ <br />
  112.       ErrorDocument 404 /Lame_excuses/not_found.html <br />
  113.       ErrorDocument 401 /Subscription/how_to_subscribe.html
  114.     </example>
  115.  
  116.     <p>The syntax is,</p>
  117.  
  118.     <example>
  119.       ErrorDocument <3-digit-code> <action>
  120.     </example>
  121.  
  122.     <p>where the action can be,</p>
  123.  
  124.     <ol>
  125.       <li>Text to be displayed. Prefix the text with a quote
  126.       ("). Whatever follows the quote is displayed. <em>Note:
  127.       the (") prefix isn't displayed.</em></li>
  128.  
  129.       <li>An external URL to redirect to.</li>
  130.  
  131.       <li>A local URL to redirect to.</li>
  132.     </ol>
  133.   </section>
  134.  
  135.   <section id="custom">
  136.     <title>Custom Error Responses and Redirects</title>
  137.  
  138.     <p>Apache's behavior to redirected URLs has been modified so
  139.     that additional environment variables are available to a
  140.     script/server-include.</p>
  141.  
  142.     <section>
  143.       <title>Old behavior</title>
  144.  
  145.       <p>Standard CGI vars were made available to a script which
  146.       has been redirected to. No indication of where the
  147.       redirection came from was provided.</p>
  148.     </section>
  149.  
  150.     <section>
  151.       <title>New behavior</title>
  152.  
  153.       <p>A new batch of environment variables will be initialized
  154.       for use by a script which has been redirected to. Each new
  155.       variable will have the prefix <code>REDIRECT_</code>.
  156.       <code>REDIRECT_</code> environment variables are created from
  157.       the CGI environment variables which existed prior to the
  158.       redirect, they are renamed with a <code>REDIRECT_</code>
  159.       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
  160.       <code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these
  161.       new variables, Apache will define <code>REDIRECT_URL</code>
  162.       and <code>REDIRECT_STATUS</code> to help the script trace its
  163.       origin. Both the original URL and the URL being redirected to
  164.       can be logged in the access log.</p>
  165.  
  166.       <p>If the ErrorDocument specifies a local redirect to a CGI
  167.       script, the script should include a "<code>Status:</code>"
  168.       header field in its output in order to ensure the propagation
  169.       all the way back to the client of the error condition that
  170.       caused it to be invoked. For instance, a Perl ErrorDocument
  171.       script might include the following:</p>
  172.  
  173.       <example>
  174.         ... <br />
  175.         print  "Content-type: text/html\n"; <br />
  176.         printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
  177.         ...
  178.       </example>
  179.  
  180.       <p>If the script is dedicated to handling a particular error
  181.       condition, such as <code>404 Not Found</code>, it can
  182.       use the specific code and error text instead.</p>
  183.  
  184.       <p>Note that the script <em>must</em> emit an appropriate
  185.       <code>Status:</code> header (such as <code>302 Found</code>), if the
  186.       response contains a <code>Location:</code> header (in order to issue a
  187.       client side redirect). Otherwise the <code>Location:</code> header may
  188.       have no effect.</p>
  189.     </section>
  190.   </section>
  191. </manualpage>
  192.