PageRenderTime 49ms CodeModel.GetById 27ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/manual/custom-error.html.en

https://github.com/xscc/httpd
Unknown | 228 lines | 183 code | 45 blank | 0 comment | 0 complexity | 2bbf117302e0f82d933ee345d1167176 MD5 | raw file
Possible License(s): LGPL-2.0, Apache-2.0, BSD-3-Clause
  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" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" />
  12. <script src="./style/scripts/prettify.min.js" type="text/javascript">
  13. </script>
  14. <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  15. <body id="manual-page"><div id="page-header">
  16. <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  17. <p class="apache">Apache HTTP Server Version 2.2</p>
  18. <img alt="" src="./images/feather.gif" /></div>
  19. <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  20. <div id="path">
  21. <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>
  22. <div class="toplang">
  23. <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
  24. <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  25. <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  26. <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  27. <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  28. </div>
  29. <p>Additional functionality allows webmasters to configure the response
  30. of Apache to some error or problem.</p>
  31. <p>Customizable responses can be defined to be activated in the event of
  32. a server detected error or problem.</p>
  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><ul class="seealso"><li><a href="#comments_section">Comments</a></li></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. <h3>Old Behavior</h3>
  45. <p>NCSA httpd 1.3 would return some boring old error/problem message
  46. which would often be meaningless to the user, and would provide no
  47. means of logging the symptoms which caused it.</p>
  48. <h3>New Behavior</h3>
  49. <p>The server can be asked to:</p>
  50. <ol>
  51. <li>Display some other text, instead of the NCSA hard coded
  52. messages, or</li>
  53. <li>redirect to a local URL, or</li>
  54. <li>redirect to an external URL.</li>
  55. </ol>
  56. <p>Redirecting to another URL can be useful, but only if some
  57. information can be passed which can then be used to explain and/or log
  58. the error/problem more clearly.</p>
  59. <p>To achieve this, Apache will define new CGI-like environment
  60. variables:</p>
  61. <div class="example"><p><code>
  62. REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
  63. image/jpeg<br />
  64. REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
  65. 9000/712)<br />
  66. REDIRECT_PATH=.:/bin:/usr/local/bin:/etc<br />
  67. REDIRECT_QUERY_STRING=<br />
  68. REDIRECT_REMOTE_ADDR=121.345.78.123<br />
  69. REDIRECT_REMOTE_HOST=ooh.ahhh.com<br />
  70. REDIRECT_SERVER_NAME=crash.bang.edu<br />
  71. REDIRECT_SERVER_PORT=80<br />
  72. REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
  73. REDIRECT_URL=/cgi-bin/buggy.pl
  74. </code></p></div>
  75. <p>Note the <code>REDIRECT_</code> prefix.</p>
  76. <p>At least <code>REDIRECT_URL</code> and
  77. <code>REDIRECT_QUERY_STRING</code> will be passed to the
  78. new URL (assuming it's a cgi-script or a cgi-include). The
  79. other variables will exist only if they existed prior to
  80. the error/problem. <strong>None</strong> of these will be
  81. set if your <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> is an
  82. <em>external</em> redirect (anything starting with a
  83. scheme name like <code>http:</code>, even if it refers to the same host
  84. as the server).</p>
  85. </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  86. <div class="section">
  87. <h2><a name="configuration" id="configuration">Configuration</a></h2>
  88. <p>Use of <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> is enabled
  89. for .htaccess files when the
  90. <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is set accordingly.</p>
  91. <p>Here are some examples...</p>
  92. <div class="example"><p><code>
  93. ErrorDocument 500 /cgi-bin/crash-recover <br />
  94. ErrorDocument 500 "Sorry, our script crashed. Oh dear" <br />
  95. ErrorDocument 500 http://xxx/ <br />
  96. ErrorDocument 404 /Lame_excuses/not_found.html <br />
  97. ErrorDocument 401 /Subscription/how_to_subscribe.html
  98. </code></p></div>
  99. <p>The syntax is,</p>
  100. <div class="example"><p><code>
  101. ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;
  102. </code></p></div>
  103. <p>where the action can be,</p>
  104. <ol>
  105. <li>Text to be displayed. Wrap the text with quotes (").</li>
  106. <li>An external URL to redirect to.</li>
  107. <li>A local URL to redirect to.</li>
  108. </ol>
  109. </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  110. <div class="section">
  111. <h2><a name="custom" id="custom">Custom Error Responses and Redirects</a></h2>
  112. <p>Apache's behavior to redirected URLs has been modified so
  113. that additional environment variables are available to a
  114. script/server-include.</p>
  115. <h3>Old behavior</h3>
  116. <p>Standard CGI vars were made available to a script which
  117. has been redirected to. No indication of where the
  118. redirection came from was provided.</p>
  119. <h3>New behavior</h3>
  120. <p>A new batch of environment variables will be initialized
  121. for use by a script which has been redirected to. Each new
  122. variable will have the prefix <code>REDIRECT_</code>.
  123. <code>REDIRECT_</code> environment variables are created from
  124. the CGI environment variables which existed prior to the
  125. redirect, they are renamed with a <code>REDIRECT_</code>
  126. prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
  127. <code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these
  128. new variables, Apache will define <code>REDIRECT_URL</code>
  129. and <code>REDIRECT_STATUS</code> to help the script trace its
  130. origin. Both the original URL and the URL being redirected to
  131. can be logged in the access log.</p>
  132. <p>If the ErrorDocument specifies a local redirect to a CGI
  133. script, the script should include a "<code>Status:</code>"
  134. header field in its output in order to ensure the propagation
  135. all the way back to the client of the error condition that
  136. caused it to be invoked. For instance, a Perl ErrorDocument
  137. script might include the following:</p>
  138. <div class="example"><p><code>
  139. ... <br />
  140. print "Content-type: text/html\n"; <br />
  141. printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
  142. ...
  143. </code></p></div>
  144. <p>If the script is dedicated to handling a particular error
  145. condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
  146. use the specific code and error text instead.</p>
  147. <p>Note that the script <em>must</em> emit an appropriate
  148. <code>Status:</code> header (such as <code>302&nbsp;Found</code>), if the
  149. response contains a <code>Location:</code> header (in order to issue a
  150. client side redirect). Otherwise the <code>Location:</code> header may
  151. have no effect.</p>
  152. </div></div>
  153. <div class="bottomlang">
  154. <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
  155. <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  156. <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  157. <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  158. <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  159. </div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
  160. <script type="text/javascript"><!--//--><![CDATA[//><!--
  161. var comments_shortname = 'httpd';
  162. var comments_identifier = 'http://httpd.apache.org/docs/2.2/custom-error.html';
  163. (function(w, d) {
  164. if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
  165. d.write('<div id="comments_thread"><\/div>');
  166. var s = d.createElement('script');
  167. s.type = 'text/javascript';
  168. s.async = true;
  169. s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
  170. (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
  171. }
  172. else {
  173. d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
  174. }
  175. })(window, document);
  176. //--><!]]></script></div><div id="footer">
  177. <p class="apache">Copyright 2014 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>
  178. <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
  179. if (typeof(prettyPrint) !== 'undefined') {
  180. prettyPrint();
  181. }
  182. //--><!]]></script>
  183. </body></html>