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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>Custom Error Responses - Apache HTTP Server Version 2.5</title>
  11 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <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" />
  14 <script src="./style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  18 <body id="manual-page"><div id="page-header">
  19 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.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>
  20 <p class="apache">Apache HTTP Server Version 2.5</p>
  21 <img alt="" src="./images/feather.png" /></div>
  22 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  23 <div id="path">
  24 <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.5</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  28 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  29 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  30 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  31 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  32 </div>
  33
  34
  35     <p>Although the Apache HTTP Server provides generic error responses
  36     in the event of 4xx or 5xx HTTP status codes, these responses are
  37     rather stark, uninformative, and can be intimidating to site users.
  38     You may wish to provide custom error responses which are either
  39     friendlier, or in some language other than English, or perhaps which
  40     are styled more in line with your site layout.</p>
  41
  42     <p>Customized error responses can be defined for any HTTP status
  43     code designated as an error condition - that is, any 4xx or 5xx
  44     status.</p>
  45
  46     <p>Additionally, a set of values are provided, so
  47     that the error document can be customized further based on the
  48     values of these variables, using <a href="howto/ssi.html">Server
  49     Side Includes</a>. Or, you can have error conditions handled by a
  50     cgi program, or other dynamic handler (PHP, mod_perl, etc) which
  51     makes use of these variables.</p>
  52
  53   </div>
  54 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#configuration">Configuration</a></li>
  55 <li><img alt="" src="./images/down.gif" /> <a href="#variables">Available Variables</a></li>
  56 <li><img alt="" src="./images/down.gif" /> <a href="#custom">Customizing Error Responses</a></li>
  57 <li><img alt="" src="./images/down.gif" /> <a href="#multi-lang">Multi Language Custom Error Documents</a></li>
  58 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  59 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  60 <div class="section">
  61 <h2><a name="configuration" id="configuration">Configuration</a><a title="Permanent link" href="#configuration" class="permalink">&para;</a></h2>
  62
  63     <p>Custom error documents are configured using the <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> directive,
  64     which may be used in global,
  65     virtualhost, or directory context. It may be used in .htaccess files
  66     if <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is set to
  67     FileInfo.</p>
  68
  69     <pre class="prettyprint lang-config">ErrorDocument 500 "Sorry, our script crashed. Oh dear"
  70 ErrorDocument 500 /cgi-bin/crash-recover
  71 ErrorDocument 500 http://error.example.com/server_error.html
  72 ErrorDocument 404 /errors/not_found.html
  73 ErrorDocument 401 /subscription/how_to_subscribe.html</pre>
  74
  75
  76     <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
  77
  78     <pre class="prettyprint lang-config">ErrorDocument &lt;3-digit-code&gt; &lt;action&gt;</pre>
  79
  80
  81     <p>where the action will be treated as:</p>
  82
  83     <ol>
  84       <li>A local URL to redirect to (if the action begins with a "/").</li>
  85       <li>An external URL to redirect to (if the action is a valid URL).</li>
  86       <li>Text to be displayed (if none of the above). The text must be
  87           wrapped in quotes (") if it consists of more than one word.</li>
  88     </ol>
  89
  90     <p>When redirecting to a local URL, additional environment variables
  91     are set so that the response can be further customized. They are not sent to
  92     external URLs.</p>
  93
  94   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  95 <div class="section">
  96 <h2><a name="variables" id="variables">Available Variables</a><a title="Permanent link" href="#variables" class="permalink">&para;</a></h2>
  97
  98       <p>Redirecting to another URL can be useful, but only if some
  99       information can be passed which can then be used to explain or log
 100       the error condition more clearly.</p>
 101
 102       <p>To achieve this, when the error redirect is sent, additional
 103       environment variables will be set, which will be generated from
 104       the headers provided to the original request by prepending
 105       'REDIRECT_' onto the original header name. This provides the error
 106       document the context of the original request.</p>
 107
 108       <p>For example, you might receive, in addition to more usual
 109       environment variables, the following.</p>
 110
 111       <div class="example"><p><code>
 112         REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
 113         REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
 114         REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
 115         REDIRECT_QUERY_STRING=<br />
 116         REDIRECT_REMOTE_ADDR=121.345.78.123<br />
 117         REDIRECT_REMOTE_HOST=client.example.com<br />
 118         REDIRECT_SERVER_NAME=www.example.edu<br />
 119         REDIRECT_SERVER_PORT=80<br />
 120         REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
 121         REDIRECT_URL=/cgi-bin/buggy.pl
 122       </code></p></div>
 123
 124       <p><code>REDIRECT_</code> environment variables are created from
 125       the environment variables which existed prior to the
 126       redirect. They are renamed with a <code>REDIRECT_</code>
 127       prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
 128       <code>REDIRECT_HTTP_USER_AGENT</code>.</p>
 129
 130       <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
 131       <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
 132       the other headers will be set only if they existed prior to the
 133       error condition.</p>
 134
 135       <p><strong>None</strong> of these will be
 136       set if the <code class="directive"><a href="./mod/core.html#errordocument">ErrorDocument</a></code> target is an
 137       <em>external</em> redirect (anything starting with a
 138       scheme name like <code>http:</code>, even if it refers to the same host
 139       as the server).</p>
 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">Customizing Error Responses</a><a title="Permanent link" href="#custom" class="permalink">&para;</a></h2>
 143
 144       <p>If you point your <code>ErrorDocument</code> to some variety of
 145       dynamic handler such as a server-side include document, CGI
 146       script, or some variety of other handler, you may wish to use the
 147       available custom environment variables to customize this
 148       response.</p>
 149
 150       <p>If the ErrorDocument specifies a local redirect to a CGI
 151       script, the script should include a "<code>Status:</code>"
 152       header field in its output in order to ensure the propagation
 153       all the way back to the client of the error condition that
 154       caused it to be invoked. For instance, a Perl ErrorDocument
 155       script might include the following:</p>
 156
 157        <pre class="prettyprint lang-perl">...
 158 print  "Content-type: text/html\n";
 159 printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
 160 ...</pre>
 161
 162
 163       <p>If the script is dedicated to handling a particular error
 164       condition, such as <code>404&nbsp;Not&nbsp;Found</code>, it can
 165       use the specific code and error text instead.</p>
 166
 167       <p>Note that if the response contains <code>Location:</code>
 168       header (in order to issue a client-side redirect), the script
 169       <em>must</em> emit an appropriate <code>Status:</code> header
 170       (such as <code>302&nbsp;Found</code>). Otherwise the
 171       <code>Location:</code> header may have no effect.</p>
 172
 173   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 174 <div class="section">
 175 <h2><a name="multi-lang" id="multi-lang">Multi Language Custom Error Documents</a><a title="Permanent link" href="#multi-lang" class="permalink">&para;</a></h2>
 176
 177     <p>Provided with your installation of the Apache HTTP Server is a
 178     directory of custom error documents translated into 16 different
 179     languages. There's also a configuration file in the
 180     <code>conf/extra</code> configuration directory that can be included
 181     to enable this feature.</p>
 182
 183     <p>In your server configuration file, you'll see a line such as:</p>
 184
 185     <pre class="prettyprint lang-config"># Multi-language error messages
 186 #Include conf/extra/httpd-multilang-errordoc.conf</pre>
 187
 188
 189     <p>Uncommenting this <code>Include</code> line will enable this
 190     feature, and provide language-negotiated error messages, based on
 191     the language preference set in the client browser.</p>
 192
 193     <p>Additionally, these documents contain various of the
 194     <code>REDIRECT_</code> variables, so that additional information can
 195     be provided to the end-user about what happened, and what they can
 196     do now.</p>
 197
 198     <p>These documents can be customized to whatever degree you wish to
 199     provide more useful information to users about your site, and what
 200     they can expect to find there.</p>
 201
 202     <p><code class="module"><a href="./mod/mod_include.html">mod_include</a></code> and <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>
 203     must be enabled to use this feature.</p>
 204
 205  </div></div>
 206 <div class="bottomlang">
 207 <p><span>Available Languages: </span><a href="./en/custom-error.html" title="English">&nbsp;en&nbsp;</a> |
 208 <a href="./es/custom-error.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 209 <a href="./fr/custom-error.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 210 <a href="./ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 211 <a href="./ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 212 <a href="./tr/custom-error.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 213 </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>
 214 <script type="text/javascript"><!--//--><![CDATA[//><!--
 215 var comments_shortname = 'httpd';
 216 var comments_identifier = 'http://httpd.apache.org/docs/trunk/custom-error.html';
 217 (function(w, d) {
 218     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 219         d.write('<div id="comments_thread"><\/div>');
 220         var s = d.createElement('script');
 221         s.type = 'text/javascript';
 222         s.async = true;
 223         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 224         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 225     }
 226     else {
 227         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 228     }
 229 })(window, document);
 230 //--><!]]></script></div><div id="footer">
 231 <p class="apache">Copyright 2018 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>
 232 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.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[//><!--
 233 if (typeof(prettyPrint) !== 'undefined') {
 234     prettyPrint();
 235 }
 236 //--><!]]></script>
 237 </body></html>