diff options
Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/custom-error.html')
| -rw-r--r-- | usr.sbin/httpd/htdocs/manual/custom-error.html | 134 |
1 files changed, 79 insertions, 55 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/custom-error.html b/usr.sbin/httpd/htdocs/manual/custom-error.html index d4ec34ebbb6..ba0602efb5c 100644 --- a/usr.sbin/httpd/htdocs/manual/custom-error.html +++ b/usr.sbin/httpd/htdocs/manual/custom-error.html @@ -15,7 +15,7 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server </H3> </DIV> @@ -35,13 +35,12 @@ 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 + <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> @@ -56,61 +55,67 @@ </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 + can be passed which can then be used to explain and/or log the + error/problem 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> -REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br> -REDIRECT_QUERY_STRING= <br> -REDIRECT_REMOTE_ADDR=121.345.78.123 <br> -REDIRECT_REMOTE_HOST=ooh.ahhh.com <br> -REDIRECT_SERVER_NAME=crash.bang.edu <br> -REDIRECT_SERVER_PORT=80 <br> -REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> -REDIRECT_URL=/cgi-bin/buggy.pl <br> - </code></blockquote> - - <P>note the <code>REDIRECT_</code> prefix. - - <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. - <b>None</b> of these will be set if your ErrorDocument is an - <i>external</i> redirect (i.e. anything starting with a protocol name - like <code>http:</code>, even if it refers to the same host as the - server).<p> + variables, <EM>e.g.</EM> + + <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> +REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR> +REDIRECT_QUERY_STRING= <BR> +REDIRECT_REMOTE_ADDR=121.345.78.123 <BR> +REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR> +REDIRECT_SERVER_NAME=crash.bang.edu <BR> +REDIRECT_SERVER_PORT=80 <BR> +REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR> +REDIRECT_URL=/cgi-bin/buggy.pl <BR> + </CODE></BLOCKQUOTE> + + <P>note the <CODE>REDIRECT_</CODE> prefix. + + <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. + <STRONG>None</STRONG> of these will be set if your ErrorDocument is an + <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a + scheme name + like <CODE>http:</CODE>, even if it refers to the same host as the + server).<P> <DT>Configuration <DD> Use of "ErrorDocument" is enabled for .htaccess files when the - <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed. + <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. Oh dear<br> -ErrorDocument 500 http://xxx/ <br> -ErrorDocument 404 /Lame_excuses/not_found.html <br> + <BLOCKQUOTE><CODE> +ErrorDocument 500 /cgi-bin/crash-recover <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> + </CODE></BLOCKQUOTE> - <P>The syntax is, + <P>The syntax is, - <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code> -<3-digit-code> action + <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE> +<3-digit-code> action <P>where the action can be, <OL> <LI>Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. <em>Note: the (") prefix isn't - displayed.</em> + follows the quote is displayed. <EM>Note: the (") prefix isn't + displayed.</EM> <LI>An external URL to redirect to. @@ -121,43 +126,62 @@ ErrorDocument 401 /Subscription/how_to_subscribe.html <P><HR><P> -<h2>Custom error responses and redirects</H2> +<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> + 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. + redirected to. No indication of where the redirection came from was + provided. - <p> + <P> <DT>New behavior <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 +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. +prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE> +prefix, <EM>i.e.</EM>, <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> +<P> +If the ErrorDocument specifies a local redirect to a CGI script, the script +should include a "<SAMP>Status:</SAMP>" header field in its output +in order to ensure the propagation all the way back to the client +of the error condition that caused it to be invoked. For instance, a Perl +ErrorDocument script might include the following: +</P> +<PRE> + : + print "Content-type: text/html\n"; + printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; + : +</PRE> +<P> +If the script is dedicated to handling a particular error condition, such as +<SAMP>404 Not Found</SAMP>, it can use the specific code and +error text instead. +</P> <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> |