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
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="<-" alt="<-" src="./images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
21 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English"> en </a> |
22 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español"> es </a> |
23 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
24 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
25 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
26 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
29 <p>Additional functionality allows webmasters to configure the response
30 of Apache to some error or problem.</p>
32 <p>Customizable responses can be defined to be activated in the event of
33 a server detected error or problem.</p>
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>
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>
43 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
45 <h2><a name="behavior" id="behavior">Behavior</a></h2>
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>
59 <p>The server can be asked to:</p>
62 <li>Display some other text, instead of the NCSA hard coded
65 <li>redirect to a local URL, or</li>
67 <li>redirect to an external URL.</li>
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>
74 <p>To achieve this, Apache will define new CGI-like environment
77 <div class="example"><p><code>
78 REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
80 REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
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
92 <p>Note the <code>REDIRECT_</code> prefix.</p>
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
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>
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>
113 <p>Here are some examples...</p>
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
123 <p>The syntax is,</p>
125 <div class="example"><p><code>
126 ErrorDocument <3-digit-code> <action>
129 <p>where the action can be,</p>
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>
136 <li>An external URL to redirect to.</li>
138 <li>A local URL to redirect to.</li>
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>
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>
149 <h3>Old behavior</h3>
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>
157 <h3>New behavior</h3>
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>
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>
180 <div class="example"><p><code>
182 print "Content-type: text/html\n"; <br />
183 printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
187 <p>If the script is dedicated to handling a particular error
188 condition, such as <code>404 Not Found</code>, it can
189 use the specific code and error text instead.</p>
191 <p>Note that the script <em>must</em> emit an appropriate
192 <code>Status:</code> header (such as <code>302 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
198 <div class="bottomlang">
199 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English"> en </a> |
200 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español"> es </a> |
201 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
202 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
203 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
204 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </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>