From 1f222f58351aa46238fff261b29e3d57a064484c Mon Sep 17 00:00:00 2001 From: David Shane Holden Date: Sun, 8 Sep 2002 22:45:05 +0000 Subject: [PATCH] New XML. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96717 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/custom-error.html.en | 319 ++++++++++++++----------------- docs/manual/custom-error.xml | 169 ++++++++++++++++ 2 files changed, 317 insertions(+), 171 deletions(-) create mode 100644 docs/manual/custom-error.xml diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en index 2a4741d321..3051b296ba 100644 --- a/docs/manual/custom-error.html.en +++ b/docs/manual/custom-error.html.en @@ -1,152 +1,131 @@ - - - - - - - Custom error responses - - - - - - -

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 + + +Custom Error Responses - Apache HTTP Server

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.0

<-

Custom Error Responses

+

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.

+ +

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

+
top

Behavior

+ + +

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:

+ +

+ 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 (anything starting with a + scheme name like http:, even if it refers to the same host + as the server).

+ +
top

Configuration

+ + +

Use of ErrorDocument is enabled + for .htaccess files when the + AllowOverride is set accordingly.

+ +

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. +
+
top

Custom Error Responses and Redirects

+ + +

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 + 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 @@ -157,26 +136,24 @@ 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.

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

+ + \ No newline at end of file diff --git a/docs/manual/custom-error.xml b/docs/manual/custom-error.xml new file mode 100644 index 0000000000..c480a6c617 --- /dev/null +++ b/docs/manual/custom-error.xml @@ -0,0 +1,169 @@ + + + + + + + + Custom Error Responses + + +

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.

+ +

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

+ + +
+ Behavior + +
+ 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:

+ + + 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 (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 + AllowOverride is set accordingly.

+ +

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 + +

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.

+
+
+ \ No newline at end of file -- 2.50.1