From: Rich Bowen Date: Fri, 12 Mar 2010 14:19:08 +0000 (+0000) Subject: I'm not completely satisfied with this, but I need to stop and come back X-Git-Tag: 2.3.6~354 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ddf45eb4adabce178c609ee205212870b06026dd;p=apache I'm not completely satisfied with this, but I need to stop and come back to it later. This is a complete rewrite, because the original document was, in fact, the original document - that is, it described how NCSA did things. Wow. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@922267 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en index c637552e88..cfb0263730 100644 --- a/docs/manual/custom-error.html.en +++ b/docs/manual/custom-error.html.en @@ -26,147 +26,122 @@  tr 

-

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.

+

Although the Apache HTTP Server provides generic error responses + in the event of 4xx or 5xx HTTP status codes, these responses are + rather stark, uninformative, and can be indimidating to site users. + You may wish to provide custom error responses which are either + friendlier, or in some language other than English, or perhaps which + are styled more in line with your site layout.

+ +

Customized error responses can be defined for any HTTP status + code designated as an error condition - that is, any 4xx or 5xx + status.

+ +

Additionally, a set of values are provided, so + that the error document can be customized further based on the + values of these variables, using Server + Side Includes. Or, you can have error conditions handled by a + cgi program, or other dynamic handler (PHP, mod_perl, etc) which + makes use of these variables.

-

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

-
+

Note that if the response contains Location: + header (in order to issue a client-side redirect), the script + must emit an appropriate Status: header + (such as 302 Found). Otherwise the + Location: header may have no effect.

+ +
top
+
+

Multi Language Customer Error Documents

+ +

Provided with your installation of the Apache HTTP Server is a + directory of custom error documents translated into 16 different + languages. There's also a configuration file in the + conf/extra configuration directory that can be included + to enable this feature.

+ +

In your server configuration file, you'll see a line such as:

+ +

+ # Multi-language error messages
+ #Include conf/extra/httpd-multilang-errordoc.conf +

+ +

Uncommenting this Include line will enable this + feature, and provide language-negotiated error messages, based on + the language preference set in the client browser.

+ +

Additionally, these documents contain various of the + REDIRECT_ variables, so that additional information can + be provided to the end-user about what happened, and what they can + do now.

+ +

These documents can be customized to whatever degree you wish to + provide more useful information to users about your site, and what + they can expect to find there.

+ +

mod_includes and mod_negotiation + must be enabled to use this feature.

+ +

Available Languages:  en  |  es  | diff --git a/docs/manual/custom-error.xml b/docs/manual/custom-error.xml index 3475337087..19ed890eee 100644 --- a/docs/manual/custom-error.xml +++ b/docs/manual/custom-error.xml @@ -25,142 +25,117 @@ 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.

+

Although the Apache HTTP Server provides generic error responses + in the event of 4xx or 5xx HTTP status codes, these responses are + rather stark, uninformative, and can be indimidating to site users. + You may wish to provide custom error responses which are either + friendlier, or in some language other than English, or perhaps which + are styled more in line with your site layout.

+ +

Customized error responses can be defined for any HTTP status + code designated as an error condition - that is, any 4xx or 5xx + status.

+ +

Additionally, a set of values are provided, so + that the error document can be customized further based on the + values of these variables, using Server + Side Includes. Or, you can have error conditions handled by a + cgi program, or other dynamic handler (PHP, mod_perl, etc) which + makes use of these variables.

-

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 +
Configuration -
- Old Behavior +

Custom error documents are configured using the ErrorDocument directive. + ErrorDocument, which may be used in global, + virtualhost, or directory context. It may be used in .htaccess files + if AllowOverride is set to + FileInfo.

-

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.

-
+ + ErrorDocument 500 "Sorry, our script crashed. Oh dear"
+ ErrorDocument 500 /cgi-bin/crash-recover
+ ErrorDocument 500 http://error.example.com/server_error.html
+ ErrorDocument 404 /errors/not_found.html
+ ErrorDocument 401 /subscription/how_to_subscribe.html + -
- New Behavior +

The syntax of the ErrorDocuemnt directrive is:

-

The server can be asked to:

+ + ErrorDocument <3-digit-code> <action> + -
    -
  1. Display some other text, instead of the NCSA hard coded - messages, or
    2. +

    where the action can be one of:

    -
  2. redirect to a local URL, or
    3. +
      +
    1. Text to be displayed. Wrap the text with quotes (").
      2. +
    2. A local URL to redirect to.
      3. +
    3. An external URL to redirect to.
      4. +
    + +

    When redirecting to a local URL, additional environment variables + are set so that the response can be further customized. They are not sent to + external URLs.

    + +
-
  • redirect to an external URL.
    • - +
    Available Variables

    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.

    + information can be passed which can then be used to explain or log + the error condition more clearly.

    -

    To achieve this, Apache will define new CGI-like environment - variables:

    +

    To achieve this, when the error redirect is sent, additional + environment variables will be set, which will be generated from + the headers provided to the original request by prepending + 'REDIRECT_' onto the original header name. This provides the error + document the context of the original request.

    + +

    For example, you might recieve, in addition to more usual + environment variables, the following.

    - 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_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png
    + REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8
    + REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin
    REDIRECT_QUERY_STRING=
    REDIRECT_REMOTE_ADDR=121.345.78.123
    - REDIRECT_REMOTE_HOST=ooh.ahhh.com
    - REDIRECT_SERVER_NAME=crash.bang.edu
    + REDIRECT_REMOTE_HOST=client.example.com
    + REDIRECT_SERVER_NAME=www.example.edu
    REDIRECT_SERVER_PORT=80
    - REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
    + REDIRECT_SERVER_SOFTWARE=Apache/2.2.15
    REDIRECT_URL=/cgi-bin/buggy.pl     -

    Note the REDIRECT_ prefix.

    +

    REDIRECT_ environment variables are created from + the 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.

    + +

    REDIRECT_URL, REDIRECT_STATUS, and + REDIRECT_QUERY_STRING are guaranteed to be set, and + the other headers will be set only if they existed prior to the + error condition.

    -

    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 +

    None of these will be + set if the ErrorDocument target 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 to FileInfo.

    - -

    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,

    +
    Customizing Error Responses - - ErrorDocument <3-digit-code> <action> - - -

    where the action can be,

    - -
      -
    1. Text to be displayed. Wrap the text with quotes (").
      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 you point your ErrorDocument to some variety of + dynamic handler such as a server-side include document, CGI + script, or some variety of other handler, you may wish to use the + available custom environent variables to customize this + response.

    If the ErrorDocument specifies a local redirect to a CGI script, the script should include a "Status:" @@ -180,11 +155,45 @@ condition, such as 404 Not Found, it can use the specific code and error text instead.

    -

    Note that the script must emit an appropriate - Status: header (such as 302 Found), if the - response contains a Location: header (in order to issue a - client side redirect). Otherwise the Location: header may - have no effect.

    -
    +

    Note that if the response contains Location: + header (in order to issue a client-side redirect), the script + must emit an appropriate Status: header + (such as 302 Found). Otherwise the + Location: header may have no effect.

    +
    + +
    Multi Language Customer Error Documents + +

    Provided with your installation of the Apache HTTP Server is a + directory of custom error documents translated into 16 different + languages. There's also a configuration file in the + conf/extra configuration directory that can be included + to enable this feature.

    + +

    In your server configuration file, you'll see a line such as:

    + + + # Multi-language error messages
    + #Include conf/extra/httpd-multilang-errordoc.conf +     + +

    Uncommenting this Include line will enable this + feature, and provide language-negotiated error messages, based on + the language preference set in the client browser.

    + +

    Additionally, these documents contain various of the + REDIRECT_ variables, so that additional information can + be provided to the end-user about what happened, and what they can + do now.

    + +

    These documents can be customized to whatever degree you wish to + provide more useful information to users about your site, and what + they can expect to find there.

    + +

    mod_includes and mod_negotiation + must be enabled to use this feature.

    + +
    +