<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
<manualpage metafile="custom-error.xml.meta">
-
+
<title>Custom Error Responses</title>
-
+
<summary>
<p>Additional functionality allows webmasters to configure the response
of Apache to some error or problem.</p>
-
+
<p>Customizable responses can be defined to be activated in the event of
a server detected error or problem.</p>
-
+
<p>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).</p>
</summary>
-
+
<section id="behavior">
<title>Behavior</title>
-
+
<section>
<title>Old Behavior</title>
-
+
<p>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.</p>
</section>
-
+
<section>
<title>New Behavior</title>
-
+
<p>The server can be asked to:</p>
-
+
<ol>
<li>Display some other text, instead of the NCSA hard coded
messages, or</li>
-
+
<li>redirect to a local URL, or</li>
-
+
<li>redirect to an external URL.</li>
</ol>
-
+
<p>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.</p>
-
+
<p>To achieve this, Apache will define new CGI-like environment
variables:</p>
-
+
<example>
REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
image/jpeg<br />
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15<br />
REDIRECT_URL=/cgi-bin/buggy.pl
</example>
-
+
<p>Note the <code>REDIRECT_</code> prefix.</p>
-
+
<p>At least <code>REDIRECT_URL</code> and
<code>REDIRECT_QUERY_STRING</code> will be passed to the
new URL (assuming it's a cgi-script or a cgi-include). The
as the server).</p>
</section>
</section>
-
+
<section id="configuration">
<title>Configuration</title>
-
+
<p>Use of <directive module="core">ErrorDocument</directive> is enabled
for .htaccess files when the
<directive module="core">AllowOverride</directive> is set accordingly.</p>
-
+
<p>Here are some examples...</p>
-
+
<example>
ErrorDocument 500 /cgi-bin/crash-recover <br />
ErrorDocument 500 "Sorry, our script crashed. Oh dear" <br />
ErrorDocument 404 /Lame_excuses/not_found.html <br />
ErrorDocument 401 /Subscription/how_to_subscribe.html
</example>
-
+
<p>The syntax is,</p>
-
+
<example>
ErrorDocument <3-digit-code> <action>
</example>
-
+
<p>where the action can be,</p>
-
+
<ol>
<li>Text to be displayed. Prefix the text with a quote
("). Whatever follows the quote is displayed. <em>Note:
the (") prefix isn't displayed.</em></li>
-
+
<li>An external URL to redirect to.</li>
-
+
<li>A local URL to redirect to.</li>
</ol>
</section>
-
+
<section id="custom">
<title>Custom Error Responses and Redirects</title>
-
+
<p>Apache's behavior to redirected URLs has been modified so
that additional environment variables are available to a
script/server-include.</p>
-
+
<section>
<title>Old behavior</title>
-
+
<p>Standard CGI vars were made available to a script which
has been redirected to. No indication of where the
redirection came from was provided.</p>
</section>
-
+
<section>
<title>New behavior</title>
-
+
<p>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 <code>REDIRECT_</code>.
and <code>REDIRECT_STATUS</code> to help the script trace its
origin. Both the original URL and the URL being redirected to
can be logged in the access log.</p>
-
+
<p>If the ErrorDocument specifies a local redirect to a CGI
script, the script should include a "<code>Status:</code>"
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:</p>
-
+
<example>
... <br />
print "Content-type: text/html\n"; <br />
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
...
</example>
-
+
<p>If the script is dedicated to handling a particular error
condition, such as <code>404 Not Found</code>, it can
use the specific code and error text instead.</p>
also used as a mechanism to communicate with external programs
such as CGI scripts. This document discusses different ways to
manipulate and use these variables.</p>
-
+
<p>Although these variables are referred to as <em>environment
variables</em>, they are not the same as the environment
variables controlled by the underlying operating system.
<directive module="mod_env">UnsetEnv</directive>
</directivelist>
</related>
-
+
<section id="basic-manipulation">
<title>Basic Environment Manipulation</title>
-
+
<p>The most basic way to set an environment variable in Apache
is using the unconditional <directive module="mod_env"
>SetEnv</directive> directive. Variables may also be passed from
the environment of the shell which started the server using the
<directive module="mod_env">PassEnv</directive> directive.</p>
-
+
</section>
<section id="conditional">
<title>Conditional Per-Request Settings</title>
-
+
<p>For additional flexibility, the directives provided by
mod_setenvif allow environment variables to be set on a
per-request basis, conditional on characteristics of particular
is available through the mod_rewrite's <directive
module="mod_rewrite">RewriteRule</directive> which uses the
<code>[E=...]</code> option to set environment variables.</p>
-
+
</section>
<section id="unique-identifiers">
<title>Unique Identifiers</title>
-
+
<p>Finally, mod_unique_id sets the environment variable
<code>UNIQUE_ID</code> for each request to a value which is
guaranteed to be unique across "all" requests under very
specific conditions.</p>
-
+
</section>
<section id="standard-cgi">
<title>Standard CGI Variables</title>
-
+
<p>In addition to all environment variables set within the
Apache configuration and passed from the shell, CGI scripts and
SSI pages are provided with a set of environment variables
containing meta-information about the request as required by
the <a href="http://cgi-spec.golux.com/">CGI
specification</a>.</p>
-
+
</section>
<section id="caveats">
<title>Some Caveats</title>
-
+
<ul>
<li>It is not possible to override or change the standard CGI
variables using the environment manipulation directives.</li>
-
+
<li>When <a href="suexec.html">suexec</a> is used to launch
CGI scripts, the environment will be cleaned down to a set of
<em>safe</em> variables before CGI scripts are launched. The
list of <em>safe</em> variables is defined at compile-time in
<code>suexec.c</code>.</li>
-
+
<li>For portability reasons, the names of environment
variables may contain only letters, numbers, and the
underscore character. In addition, the first character may
</section>
<section id="using">
<title>Using Environment Variables</title>
-
+
<related>
<modulelist>
<module>mod_authz_host</module>
<section id="cgi-scripts">
<title>CGI Scripts</title>
-
+
<p>One of the primary uses of environment variables is to
communicate information to CGI scripts. As discussed above, the
environment passed to CGI scripts includes standard
meta-information about the request in addition to any variables
set within the Apache configuration. For more details, see the
<a href="howto/cgi.html">CGI tutorial</a>.</p>
-
+
</section>
<section id="ssi-pages">
<title>SSI Pages</title>
-
+
<p>Server-parsed (SSI) documents processed by mod_include's
<code>INCLUDES</code> filter can print environment variables
using the <code>echo</code> element, and can use environment
provides SSI pages with the standard CGI environment variables
as discussed above. For more details, see the <a
href="howto/ssi.html">SSI tutorial</a>.</p>
-
+
</section>
<section id="access-control">
<title>Access Control</title>
-
+
<p>Access to the server can be controlled based on the value of
environment variables using the <code>allow from env=</code>
and <code>deny from env=</code> directives. In combination with
characteristics of the client. For example, you can use these
directives to deny access to a particular browser (User-Agent).
</p>
-
+
</section>
<section id="logging">
<title>Conditional Logging</title>
-
+
<p>Environment variables can be logged in the access log using
the <directive module="mod_log_config">LogFormat</directive>
option <code>%e</code>. In addition, the decision on whether
requests for filenames ending in <code>gif</code>, or you can
choose to only log requests from clients which are outside your
subnet.</p>
-
+
</section>
<section id="response-headers">
<title>Conditional Response Headers</title>
-
+
<p>The <directive module="mod_headers">Header</directive>
directive can use the presence or
absence of an environment variable to determine whether or not
client. This allows, for example, a certain response header to
be sent only if a corresponding header is received in the
request from the client.</p>
-
+
</section>
<section id="external-filter">
<section id="url-rewriting">
<title>URL Rewriting</title>
-
+
<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
the <directive module="mod_rewrite">RewriteCond</directive>
allows mod_rewrite's rewrite
which cannot be accessed from other modules.</p>
</section>
</section>
-
+
<section id="special">
<title>Special Purpose Environment Variables</title>
-
+
<p>Interoperability problems have led to the introduction of
mechanisms to modify the way Apache behaves when talking to
particular clients. To make these mechanisms as flexible as
>BrowserMatch</directive>, though <directive module="mod_env"
>SetEnv</directive> and <directive module="mod_env"
>PassEnv</directive> could also be used, for example.</p>
-
+
<section id="downgrade">
<title>downgrade-1.0</title>
-
+
<p>This forces the request to be treated as a HTTP/1.0 request
even if it was in a later dialect.</p>
-
+
</section>
<section id="force-no-vary">
<title>force-no-vary</title>
-
+
<p>This causes any <code>Vary</code> fields to be removed from
the response header before it is sent back to the client. Some
clients don't interpret this field correctly; setting this
</section>
<section id="force-response">
<title>force-response-1.0</title>
-
+
<p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
request. It was originally
implemented as a result of a problem with AOL's proxies. Some
<section id="nokeepalive">
<title>nokeepalive</title>
-
+
<p>This disables <directive module="core">KeepAlive</directive>
when set.</p>
-
+
</section>
<section id="prefer-language"><title>prefer-language</title>
-
+
<p>This influences <module>mod_negotiation</module>'s behaviour. If
it contains a language tag (such as <code>en</code>, <code>ja</code>
or <code>x-klingon</code>), <module>mod_negotiation</module> tries
to deliver a variant with that language. If there's no such variant,
the normal <a href="content-negotiation.html">negotiation</a> process
applies.</p>
-
+
</section>
<section id="redirect-carefully">
<title>redirect-carefully</title>
-
+
<p>This forces the server to be more careful when sending a redirect
to the client. This is typically used when a client has a known
problem handling redirects. This was originally implemented as a
result of a problem with Microsoft's WebFolders software which has
a problem handling redirects on directory resources via DAV
methods.</p>
-
+
</section>
<section id="suppress-error-charset">
<section id="examples">
<title>Examples</title>
-
+
<section id="misbehaving">
<title>Changing protocol behavior with misbehaving clients</title>
-
+
<p>We recommend that the following lines be included in
httpd.conf to deal with known client problems.</p>
<example><pre>
</section>
<section id="no-img-log">
<title>Do not log requests for images in the access log</title>
-
+
<p>This example keeps requests for images from appearing in the
access log. It can be easily modified to prevent logging of
particular directories, or to prevent logging of requests
SetEnvIf Request_URI \.jpg image-request
SetEnvIf Request_URI \.png image-request
CustomLog logs/access_log common env=!image-request</pre></example>
-
+
</section>
<section id="image-theft">
<title>Prevent "Image Theft"</title>
-
+
<p>This example shows how to keep people not on your server
from using images on your server as inline-images on their
pages. This is not a recommended configuration, but it can work
Deny from all
Allow from env=local_referal
</Directory></pre></example>
-
+
<p>For more information about this technique, see the
ApacheToday tutorial " <a
href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
projects / apache / commitdiff