← Back to branch summary

~ubuntu-branches/ubuntu/feisty/apache2/feisty

« back to all changes in this revision

Viewing changes to docs/manual/custom-error.html.en

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Barth
  • Date: 2006-12-09 21:05:45 UTC
  • mfrom: (0.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20061209210545-h70s0xaqc2v8vqr2
Tags: 2.2.3-3.2
http://bugs.debian.org/396265
* Non-maintainer upload.
* 043_ajp_connection_reuse: Patch from upstream Bugzilla, fixing a critical
  issue with regard to connection reuse in mod_proxy_ajp.
  Closes: #396265

Show diffs side-by-side

added added

removed removed

Lines of Context:
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.2</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.2</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>
 
 
b'\\ No newline at end of file'