# 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. redirect to a local URL, or
  3. redirect to an external URL.

  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.

Configuration
  file: server configuration

  Here are some examples...

  > `ErrorDocument 500 /cgi-bin/crash-recover
  > ErrorDocument 500 "Sorry, our script crashed because %s. 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. If the error/problem produced any additional information, it can be specified using `%s`. Note: the (") prefix isn't displayed.
  2. An external URL to redirect to.
  3. A local URL to redirect to.

  `ErrorDocument` definitions are sensitive to a `SIGHUP`, so you can change any of the definitions or add new ones prior to sending a `SIGHUP` (kill -1) signal.

## Custom error responses and redirects

Purpose
  Apache's behaviour to redirected URLs has been modified so that additional environment variables are available to a script/server-include.

Old behaviour
  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 behaviour
  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 -> 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.
  Logging: both the original URL and the URL being redirected to, will now be logged correctly in the access log.