From 6beeb1b708550be0d4a53b272283e17e5e35fe17 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:01:30 +0200 Subject: Adding upstream version 2.4.57. Signed-off-by: Daniel Baumann --- docs/manual/custom-error.html.en | 237 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 docs/manual/custom-error.html.en (limited to 'docs/manual/custom-error.html.en') diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en new file mode 100644 index 0000000..358a19a --- /dev/null +++ b/docs/manual/custom-error.html.en @@ -0,0 +1,237 @@ + + + + + +Custom Error Responses - Apache HTTP Server Version 2.4 + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+

Custom Error Responses

+
+

Available Languages:  en  | + es  | + fr  | + ja  | + ko  | + tr 

+
+ + +

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

+ +
+ +
top
+
+

Configuration

+ +

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

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

The syntax of the ErrorDocument directive is:

+ + 
ErrorDocument <3-digit-code> <action>
+ + +

where the action will be treated as:

+ +
    +
  1. A local URL to redirect to (if the action begins with a "/").
    2. +
  2. An external URL to redirect to (if the action is a valid URL).
    3. +
  3. Text to be displayed (if none of the above). The text must be + wrapped in quotes (") if it consists of more than one word.
    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.

+ +
top
+
+

Available Variables

+ +

Redirecting to another URL can be useful, but only if some + information can be passed which can then be used to explain or log + the error condition more clearly.

+ +

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 receive, in addition to more usual + environment variables, the following.

+ +

+ 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=client.example.com
+ REDIRECT_SERVER_NAME=www.example.edu
+ REDIRECT_SERVER_PORT=80
+ REDIRECT_SERVER_SOFTWARE=Apache/2.2.15
+ REDIRECT_URL=/cgi-bin/buggy.pl +

+ +

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.

+ +

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

+
top
+
+

Customizing Error Responses

+ +

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 environment variables to customize this + response.

+ +

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.

+ +

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 Custom 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_include and mod_negotiation + must be enabled to use this feature.

+ +
+
+

Available Languages:  en  | + es  | + fr  | + ja  | + ko  | + tr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3