From 4b50c27ec5ec786ab4022e61f94c0e58e969c883 Mon Sep 17 00:00:00 2001 From: Jason McIntyre Date: Fri, 29 Jul 2005 23:55:41 +0000 Subject: from tamas tevesz: ==> de-multiviewification complete. (rename *.html.html -> *.html) --- usr.sbin/httpd/htdocs/manual/custom-error.html | 196 +++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 usr.sbin/httpd/htdocs/manual/custom-error.html (limited to 'usr.sbin/httpd/htdocs/manual/custom-error.html') diff --git a/usr.sbin/httpd/htdocs/manual/custom-error.html b/usr.sbin/httpd/htdocs/manual/custom-error.html new file mode 100644 index 00000000000..bccb11a9a20 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/custom-error.html @@ -0,0 +1,196 @@ + + + + + + + + Custom error responses + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Custom error responses

+ +
+
Purpose
+ +
+ Additional functionality. Allows webmasters to configure + the response of Apache to some error or problem. + +

Customizable responses can be defined to be activated in + the event of a server detected error or problem.

+ +

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).

+
+ +
Old behavior
+ +
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.
+
+ +
New behavior
+ +
+ The server can be asked to; + +
    +
  1. Display some other text, instead of the NCSA hard + coded messages, or
    2. + +
  2. redirect to a local URL, or
    3. + +
  3. redirect to an external URL.
    4. +
+ +

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.

+ +

To achieve this, Apache will define new CGI-like + environment variables, e.g.

+ +
+ REDIRECT_HTTP_ACCEPT=*/*, image/gif, + image/x-xbitmap, image/jpeg
+ REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX + A.09.05 9000/712)
+ REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
+ REDIRECT_QUERY_STRING=
+ REDIRECT_REMOTE_ADDR=121.345.78.123
+ REDIRECT_REMOTE_HOST=ooh.ahhh.com
+ REDIRECT_SERVER_NAME=crash.bang.edu
+ REDIRECT_SERVER_PORT=80
+ REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
+ REDIRECT_URL=/cgi-bin/buggy.pl
+ +
+ +

note the REDIRECT_ prefix.

+ +

At least REDIRECT_URL and + REDIRECT_QUERY_STRING 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. None of these will be + set if your ErrorDocument is an external redirect + (i.e., anything starting with a scheme name like + http:, even if it refers to the same host as + the server).

+
+ +
Configuration
+ +
+ Use of "ErrorDocument" is enabled for .htaccess files when + the "FileInfo" + override is allowed. + +

Here are some examples...

+ +
+ ErrorDocument 500 /cgi-bin/crash-recover
+ ErrorDocument 500 "Sorry, our script crashed. Oh + dear
+ ErrorDocument 500 http://xxx/
+ ErrorDocument 404 /Lame_excuses/not_found.html
+ ErrorDocument 401 + /Subscription/how_to_subscribe.html +
+ +

The syntax is,

+ +

ErrorDocument + <3-digit-code> action

+ +

where the action can be,

+ +
    +
  1. Text to be displayed. Prefix the text with a quote + ("). Whatever follows the quote is displayed. Note: + the (") prefix isn't displayed.
    2. + +
  2. An external URL to redirect to.
    3. + +
  3. A local URL to redirect to.
    4. +
+
+
+
+ +

Custom error responses and redirects

+ +
+
Purpose
+ +
Apache's behavior to redirected URLs has been modified so + that additional environment variables are available to a + script/server-include.
+ +
Old behavior
+ +
Standard CGI vars were made available to a script which + has been redirected to. No indication of where the + redirection came from was provided.
+ +
New behavior
+ +
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 REDIRECT_. + 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 becomes + REDIRECT_HTTP_USER_AGENT. In addition to these + new variables, Apache will define REDIRECT_URL + and REDIRECT_STATUS to help the script trace its + origin. Both the original URL and the URL being redirected to + can be logged in the access log.
+
+ +

If the ErrorDocument specifies a local redirect to a CGI + script, the script should include a "Status:" + 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:

+
+      :
+    print  "Content-type: text/html\n";
+    printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
+      :
+
+ +

If the script is dedicated to handling a particular error + condition, such as 404 Not Found, it can + use the specific code and error text instead.

+
+ +

Apache HTTP Server

+ Index + + + + + + -- cgit v1.2.3