Commit e7fe0563 authored by brian's avatar brian
Browse files

Reviewed by: Brian Behlendorf 

Submitted by:	John Line, WWW server manager <webadm@info.cam.ac.uk>

Fixed oversight in documentation of error_document.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@77306 13f79535-47bb-0310-9956-ffa450edef68
parent 3fb15bc7

docs/manual/custom-error.html

+70 −37
Changes for docs/manual/custom-error.html: 70 added lines, 37 removed lines.
Original line number Diff line number Diff line
@@ -8,29 +8,46 @@ 
<H1>Custom error responses</H1>



<DL>



<DT>Purpose

<DD>Additional functionality. Allows web-masters to configure the response of

Apache to some error or problem.<BR>

<P>Customizable responses can be defined to be activated in the event of a

server detected error or problem.<BR>

e.g. if a script crashes and produces a "500 Server Error" response, then

this response can be replaced with either some friendlier text or by a

redirection to another URL (local or external).



  <DD>Additional functionality. Allows webmasters to configure the response of

      Apache to some error or problem.



      <P>Customizable responses can be defined to be activated in the

      event of a server detected error or problem.



      <P>e.g. if a script crashes and produces a "500 Server Error"

      response, then this response can be replaced with either some

      friendlier text or by a redirection to another URL (local or

      external).

	

      <P>

	

<DT>Old behavior

<DD>NCSA httpd 1.3 would return some boring old error/problem message which

would often be meaningless to the user, and would provide no means of logging

the symptoms which caused it.<BR><BR>



  <DD>NCSA httpd 1.3 would return some boring old error/problem message 

      which would often be meaningless to the user, and would provide no 

      means of logging the symptoms which caused it.<BR>



      <P>



<DT>New behavior



  <DD>The server can be asked to;

  <OL>

    <LI>Display some other text, instead of the NCSA hard coded messages, or

    <LI>redirect to a local URL, or

    <LI>redirect to an external URL.

  </OL>



  <P>Redirecting to another URL can be useful, but only if some information

     can be passed which can then be used to explain and/or log the error/problem

more clearly.<BR>To achieve this, Apache will define new CGI-like environment

     more clearly.



  <P>To achieve this, Apache will define new CGI-like environment

     variables, e.g.



  <blockquote><code>

REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>

REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
@@ -44,63 +61,79 @@ REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> 
REDIRECT_URL=/cgi-bin/buggy.pl <br>

  </code></blockquote>



note the <code>REDIRECT_</code> prefix. <p>

  <P>note the <code>REDIRECT_</code> prefix. 



At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will

  <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will

     be passed to the new URL (assuming it's a cgi-script or a cgi-include). The

     other variables will exist only if they existed prior to the error/problem.<p>



<DT>Configuration

<DD><em>file: </em>server configuration<BR>



  <DD> Use of "ErrorDocument" is enabled for .htaccess files when the

       <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.



  <P>Here are some examples...



  <blockquote><code>

ErrorDocument 500 /cgi-bin/crash-recover <br>

ErrorDocument 500 "Sorry, our script crashed because %s. Oh dear<br>

ErrorDocument 500 "Sorry, our script crashed. Oh dear<br>

ErrorDocument 500 http://xxx/ <br>

ErrorDocument 404 /Lame_excuses/not_found.html  <br>

ErrorDocument 401 /Subscription/how_to_subscribe.html

  </code></blockquote>

The syntax is, <p>

<code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>

&lt;3-digit-code&gt; action <p>



where the action can be,

  <P>The syntax is, 



  <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>

&lt;3-digit-code&gt; action 



  <P>where the action can be,



  <OL>

<LI>Text to be displayed.<BR>Prefix the text with a quote (&quot;). Whatever

follows the quote is displayed. If the error/problem produced any additional

information, it can be specified using <code>%s</code>.

<em>Note: the (&quot;) prefix isn't displayed.</em>

    <LI>Text to be displayed.  Prefix the text with a quote (&quot;). Whatever

        follows the quote is displayed. <em>Note: the (&quot;) prefix isn't 

        displayed.</em>



    <LI>An external URL to redirect to.



    <LI>A local URL to redirect to.



  </OL>

<P><code>ErrorDocument</code> definitions are sensitive to a

<code>SIGHUP</code>, so you can change any of the definitions or add new ones

prior to sending a <code>SIGHUP</code> (kill -1) signal.

</DL>



<P><HR><P>



<h2>Custom error responses and redirects</H2>



<DL>



<DT>Purpose



  <DD>Apache's behavior to redirected URLs has been modified so that additional

      environment variables are available to a script/server-include.<p>



<DT>Old behavior



  <DD>Standard CGI vars were made available to a script which has been

      redirected to. No indication of where the redirection came from was provided.



  <p>



<DT>New behavior

<DD>A new batch of environment variables will be initialized for use by a

script which has been redirected to.<BR>

Each new variable will have the prefix <code>REDIRECT_</code>.<BR>

REDIRECT_ environment variables are created from the CGI environment

variables which existed prior to the redirect, they are renamed with a

REDIRECT_ prefix, i.e. HTTP_USER_AGENT -&gt; REDIRECT_HTTP_USER_AGENT.<BR>

In addition to these new variables, Apache will define

<code>REDIRECT_URL</code> and <code>REDIRECT_STATUS</code> to help the script

trace its origin.<BR>

Logging: both the original URL and the URL being redirected to, will

now be logged correctly in the access log.<p>

  <DD>



A new batch of environment variables will be initialized for use by a

script which has been redirected to.  Each new variable will have the

prefix <code>REDIRECT_</code>.  <code>REDIRECT_</code> environment

variables are created from the CGI environment variables which existed

prior to the redirect, they are renamed with a <code>REDIRECT_</code>

prefix, i.e. <code>HTTP_USER_AGENT</code> becomes

<code>REDIRECT_HTTP_USER_AGENT</code>.  In addition to these new

variables, Apache will define <code>REDIRECT_URL</code> and

<code>REDIRECT_STATUS</code> to help the script trace its origin.

Both the original URL and the URL being redirected to can be logged in

the access log.



</DL>



<!--#include virtual="footer.html" -->

docs/manual/custom-error.html.en

+70 −37
Changes for docs/manual/custom-error.html.en: 70 added lines, 37 removed lines.
Original line number Diff line number Diff line
@@ -8,29 +8,46 @@ 
<H1>Custom error responses</H1>



<DL>



<DT>Purpose

<DD>Additional functionality. Allows web-masters to configure the response of

Apache to some error or problem.<BR>

<P>Customizable responses can be defined to be activated in the event of a

server detected error or problem.<BR>

e.g. if a script crashes and produces a "500 Server Error" response, then

this response can be replaced with either some friendlier text or by a

redirection to another URL (local or external).



  <DD>Additional functionality. Allows webmasters to configure the response of

      Apache to some error or problem.



      <P>Customizable responses can be defined to be activated in the

      event of a server detected error or problem.



      <P>e.g. if a script crashes and produces a "500 Server Error"

      response, then this response can be replaced with either some

      friendlier text or by a redirection to another URL (local or

      external).

	

      <P>

	

<DT>Old behavior

<DD>NCSA httpd 1.3 would return some boring old error/problem message which

would often be meaningless to the user, and would provide no means of logging

the symptoms which caused it.<BR><BR>



  <DD>NCSA httpd 1.3 would return some boring old error/problem message 

      which would often be meaningless to the user, and would provide no 

      means of logging the symptoms which caused it.<BR>



      <P>



<DT>New behavior



  <DD>The server can be asked to;

  <OL>

    <LI>Display some other text, instead of the NCSA hard coded messages, or

    <LI>redirect to a local URL, or

    <LI>redirect to an external URL.

  </OL>



  <P>Redirecting to another URL can be useful, but only if some information

     can be passed which can then be used to explain and/or log the error/problem

more clearly.<BR>To achieve this, Apache will define new CGI-like environment

     more clearly.



  <P>To achieve this, Apache will define new CGI-like environment

     variables, e.g.



  <blockquote><code>

REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>

REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
@@ -44,63 +61,79 @@ REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> 
REDIRECT_URL=/cgi-bin/buggy.pl <br>

  </code></blockquote>



note the <code>REDIRECT_</code> prefix. <p>

  <P>note the <code>REDIRECT_</code> prefix. 



At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will

  <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will

     be passed to the new URL (assuming it's a cgi-script or a cgi-include). The

     other variables will exist only if they existed prior to the error/problem.<p>



<DT>Configuration

<DD><em>file: </em>server configuration<BR>



  <DD> Use of "ErrorDocument" is enabled for .htaccess files when the

       <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.



  <P>Here are some examples...



  <blockquote><code>

ErrorDocument 500 /cgi-bin/crash-recover <br>

ErrorDocument 500 "Sorry, our script crashed because %s. Oh dear<br>

ErrorDocument 500 "Sorry, our script crashed. Oh dear<br>

ErrorDocument 500 http://xxx/ <br>

ErrorDocument 404 /Lame_excuses/not_found.html  <br>

ErrorDocument 401 /Subscription/how_to_subscribe.html

  </code></blockquote>

The syntax is, <p>

<code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>

&lt;3-digit-code&gt; action <p>



where the action can be,

  <P>The syntax is, 



  <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>

&lt;3-digit-code&gt; action 



  <P>where the action can be,



  <OL>

<LI>Text to be displayed.<BR>Prefix the text with a quote (&quot;). Whatever

follows the quote is displayed. If the error/problem produced any additional

information, it can be specified using <code>%s</code>.

<em>Note: the (&quot;) prefix isn't displayed.</em>

    <LI>Text to be displayed.  Prefix the text with a quote (&quot;). Whatever

        follows the quote is displayed. <em>Note: the (&quot;) prefix isn't 

        displayed.</em>



    <LI>An external URL to redirect to.



    <LI>A local URL to redirect to.



  </OL>

<P><code>ErrorDocument</code> definitions are sensitive to a

<code>SIGHUP</code>, so you can change any of the definitions or add new ones

prior to sending a <code>SIGHUP</code> (kill -1) signal.

</DL>



<P><HR><P>



<h2>Custom error responses and redirects</H2>



<DL>



<DT>Purpose



  <DD>Apache's behavior to redirected URLs has been modified so that additional

      environment variables are available to a script/server-include.<p>



<DT>Old behavior



  <DD>Standard CGI vars were made available to a script which has been

      redirected to. No indication of where the redirection came from was provided.



  <p>



<DT>New behavior

<DD>A new batch of environment variables will be initialized for use by a

script which has been redirected to.<BR>

Each new variable will have the prefix <code>REDIRECT_</code>.<BR>

REDIRECT_ environment variables are created from the CGI environment

variables which existed prior to the redirect, they are renamed with a

REDIRECT_ prefix, i.e. HTTP_USER_AGENT -&gt; REDIRECT_HTTP_USER_AGENT.<BR>

In addition to these new variables, Apache will define

<code>REDIRECT_URL</code> and <code>REDIRECT_STATUS</code> to help the script

trace its origin.<BR>

Logging: both the original URL and the URL being redirected to, will

now be logged correctly in the access log.<p>

  <DD>



A new batch of environment variables will be initialized for use by a

script which has been redirected to.  Each new variable will have the

prefix <code>REDIRECT_</code>.  <code>REDIRECT_</code> environment

variables are created from the CGI environment variables which existed

prior to the redirect, they are renamed with a <code>REDIRECT_</code>

prefix, i.e. <code>HTTP_USER_AGENT</code> becomes

<code>REDIRECT_HTTP_USER_AGENT</code>.  In addition to these new

variables, Apache will define <code>REDIRECT_URL</code> and

<code>REDIRECT_STATUS</code> to help the script trace its origin.

Both the original URL and the URL being redirected to can be logged in

the access log.



</DL>



<!--#include virtual="footer.html" -->

docs/manual/mod/core.html

+8 −6
Changes for docs/manual/mod/core.html: 8 added lines, 6 removed lines.
Original line number Diff line number Diff line
@@ -137,8 +137,8 @@ Allow use of the authorization directives 
<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>,

<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>,

<A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>,

<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and

<A HREF="#require">require</A>).

<A HREF="mod_auth.html#authuserfile">AuthUserFile</A>,

<A HREF="#require">require</A>, etc.).

<dt>FileInfo

<dd>

<!--%plaintext &lt;?INDEX {\tt FileInfo} override&gt; -->
@@ -146,8 +146,9 @@ Allow use of the directives controlling document types 
(<A HREF="mod_mime.html#addencoding">AddEncoding</A>,

<A HREF="mod_mime.html#addlanguage">AddLanguage</A>,

<A HREF="mod_mime.html#addtype">AddType</A>,

<A HREF="#defaulttype">DefaultType</A> and

<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>).

<A HREF="#defaulttype">DefaultType</A>,

<A HREF="#errordocment">ErrorDocument</A>,

<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>, etc.).

<dt>Indexes

<dd>

<!--%plaintext &lt;?INDEX {\tt Indexes} override&gt; -->
@@ -161,8 +162,8 @@ Allow use of the directives controlling directory indexing 
<A HREF="mod_dir.html#fancyindexing">FancyIndexing</A>,

<A HREF="mod_dir.html#headername">HeaderName</A>,

<A HREF="mod_dir.html#indexignore">IndexIgnore</A>,

<A HREF="mod_dir.html#indexoptions">IndexOptions</A> and

<A HREF="mod_dir.html#readmename">ReadmeName</A>).

<A HREF="mod_dir.html#indexoptions">IndexOptions</A>,

<A HREF="mod_dir.html#readmename">ReadmeName</A>, etc.).

<dt>Limit

<dd>

<!--%plaintext &lt;?INDEX {\tt Limit} override&gt; -->
@@ -342,6 +343,7 @@ please avoid that. 
<strong>Syntax:</strong> ErrorDocument <em>error-code document</em><br>

<strong>Context</strong> server config, virtual host, directory, .htaccess<br>

<strong>Status:</strong> core<br>

<strong>Override:</strong> FileInfo<br>

<strong>Compatibility:</strong> The directory and .htaccess contexts

are only available in Apache 1.1 and later.<p>