custom_errordocs.html revision 2eaf662cbc81e823e8d9aeb8d54e69e63032493e
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4610465ed9408cbe434dbfb8be8ea53f48969c91Bob Halley "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User <meta name="generator" content="HTML Tidy, see www.w3.org" />
4610465ed9408cbe434dbfb8be8ea53f48969c91Bob Halley <title>International Customized Server Error Messages</title>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <!--#include virtual="header.html" -->
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <h1 align="CENTER">Using XSSI and <samp>ErrorDocument</samp> to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User configure customized international server error responses</h1>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li><a href="#createdir">Creating an ErrorDocument
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li><a href="#docnames">Naming the individual error document
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li><a href="#headfoot">The common header and footer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <li><a href="#createdocs">Creating ErrorDocuments in
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li><a href="#fallback">The fallback language</a></li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li><a href="#listings">HTML listing of the discussed
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <h2><a id="intro" name="intro">Introduction</a></h2>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User This document describes an easy way to provide your apache WWW
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User server with a set of customized error messages which take
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User advantage of <a href="/content-negotiation.html">Content
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Negotiation</a> and <a href="/mod/mod_include.html">eXtended
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Server Side Includes (XSSI)</a> to return error messages
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User generated by the server in the client's native language. <br />
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein href="/mod/core.html#errordocument">customized messages</a>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein can share a homogenous and consistent style and layout, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein maintenance work (changing images, changing links) is kept to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein minimum because all layout information can be kept in a single
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User Error documents can be shared across different servers, or
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User even hosts, because all varying information is inserted at the
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User time the error document is returned on behalf of a failed
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User <p>Content Negotiation then selects the appropriate language
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User version of a particular error message text, honoring the
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User language preferences passed in the client's request. (Users
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein usually select their favorite languages in the preferences
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein options menu of today's browsers). When an error document in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the client's primary language version is unavailable, the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein secondary languages are tried or a default (fallback) version
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is used.</p>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <p>You have full flexibility in designing your error documents
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to your personal taste (or your company's conventions). For
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein demonstration purposes, we present a simple generic error
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein document scheme. For this hypothetic server, we assume that all
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User error messages...</p>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <li>possibly are served by different virtual hosts (different
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User host name, different IP address, or different port) on the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User server machine,</li>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <li>show a predefined company logo in the right top of the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User message (selectable by virtual host),</li>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <li>print the error title first, followed by an explanatory
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User text and (depending on the error context) help on how to
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User resolve the error,</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>have some kind of standardized background image,</li>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <li>display an apache logo and a feedback email address at
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User the bottom of the error message.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p>An example of a "document not found" message for a german
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein client might look like this:<br />
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User alt="[Needs graphics capability to display]" /><br />
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User All links in the document as well as links to the server's
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User administrator mail address, and even the name and port of the
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User serving virtual host are inserted in the error document at
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User "run-time", <em>i.e.</em>, when the error actually occurs.</p>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <h2><a id="createdir" name="createdir">Creating an
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User For this concept to work as easily as possible, we must take
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User advantage of as much server support as we can get:
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User href="/mod/core.html#options">MultiViews option</a>, we
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User enable the language selection of the most appropriate
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User language alternative (content negotiation).</li>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User href="/mod/mod_negotiation.html#languagepriority">LanguagePriority</a>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User directive we define a set of default fallback languages in
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User the situation where the client's browser did not express any
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein preference at all.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>By enabling <a href="/mod/mod_include.html">Server Side
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User Includes</a> (and disallowing execution of cgi scripts for
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User security reasons), we allow the server to include building
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User blocks of the error message, and to substitute the value of
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User certain environment variables into the generated document
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User (dynamic HTML) or even to conditionally include or omit parts
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User of the text.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User href="/mod/mod_mime.html#addhandler">AddHandler</a> and <a
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User href="/mod/mod_mime.html#addtype">AddType</a> directives
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User are useful for automatically XSSI-expanding all files with a
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <samp>.shtml</samp> suffix to <em>text/html</em>.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User href="/mod/mod_alias.html#alias">Alias</a> directive, we
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User keep the error document directory outside of the document
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User tree because it can be regarded more as a server part than
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User part of the document tree.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User href="/mod/core.html#directory"><Directory></a>-Block
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein restricts these "special" settings to the error document
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User directory and avoids an impact on any of the settings for the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User regular document tree.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>For each of the error codes to be handled (see RFC2068
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User for an exact description of each error code, or look at
c247e3f281613fabe1af362e9f3157e35ebbe52cMark Andrews <code>src/main/http_protocol.c</code> if you wish to see
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User apache's standard messages), an <a
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User href="/mod/core.html#errordocument">ErrorDocument</a> in
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User the aliased <samp>/errordocs</samp> directory is defined.
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User Note that we only define the basename of the document here
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User because the MultiViews option will select the best candidate
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User based on the language suffixes and the client's preferences.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User Any error situation with an error code <em>not</em> handled
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User by a custom document will be dealt with by the server in the
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User standard way (<em>i.e.</em>, a plain error message in
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User english).</li>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User href="/mod/core.html#allowoverride">AllowOverride</a>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User directive tells apache that it is not necessary to look for a
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User .htaccess file in the /errordocs directory: a minor speed
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User optimization.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User The resulting <samp>httpd.conf</samp> configuration would then
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User look similar to this: <small>(Note that you can define your own
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein error messages using this method for only part of the document
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User tree, e.g., a /~user/ subtree. In this case, the configuration
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User could as well be put into the .htaccess file at the root of the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User subtree, and the <Directory> and </Directory>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User directives -but not the contained directives- must be
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User omitted.)</small>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User LanguagePriority en fr de
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User AllowOverride none
0ccb0e98c77a9b9636a036f8f64f5679a430aaf4Tinderbox User Options MultiViews IncludesNoExec FollowSymLinks
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <FilesMatch "\.shtml[.$]">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User SetOutputFilter INCLUDES
395c95214142142854509945adf3293c0270e1c5Tinderbox User </FilesMatch>
395c95214142142854509945adf3293c0270e1c5Tinderbox User </Directory>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User # "400 Bad Request",
395c95214142142854509945adf3293c0270e1c5Tinderbox User # "401 Authorization Required",
395c95214142142854509945adf3293c0270e1c5Tinderbox User # "403 Forbidden",
395c95214142142854509945adf3293c0270e1c5Tinderbox User # "404 Not Found",
395c95214142142854509945adf3293c0270e1c5Tinderbox User # "500 Internal Server Error",
395c95214142142854509945adf3293c0270e1c5Tinderbox User The directory for the error messages (here:
395c95214142142854509945adf3293c0270e1c5Tinderbox User <samp>/usr/local/apache/errordocs/</samp>) must then be created
395c95214142142854509945adf3293c0270e1c5Tinderbox User with the appropriate permissions (readable and executable by
395c95214142142854509945adf3293c0270e1c5Tinderbox User the server uid or gid, only writable for the administrator).
395c95214142142854509945adf3293c0270e1c5Tinderbox User <h3><a id="docnames" name="docnames">Naming the individual
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User By defining the <samp>MultiViews</samp> option, the server was
395c95214142142854509945adf3293c0270e1c5Tinderbox User told to automatically scan the directory for matching variants
395c95214142142854509945adf3293c0270e1c5Tinderbox User (looking at language and content type suffixes) when a
395c95214142142854509945adf3293c0270e1c5Tinderbox User requested document was not found. In the configuration, we
395c95214142142854509945adf3293c0270e1c5Tinderbox User defined the names for the error documents to be just their
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User error number (without any suffix).
395c95214142142854509945adf3293c0270e1c5Tinderbox User <p>The names of the individual error documents are now
395c95214142142854509945adf3293c0270e1c5Tinderbox User determined like this (I'm using 403 as an example, think of it
395c95214142142854509945adf3293c0270e1c5Tinderbox User as a placeholder for any of the configured error
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User documents):</p>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>No file errordocs/403 should exist. Otherwise, it would
395c95214142142854509945adf3293c0270e1c5Tinderbox User be found and served (with the DefaultType, usually
395c95214142142854509945adf3293c0270e1c5Tinderbox User text/plain), all negotiation would be bypassed.</li>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>For each language for which we have an internationalized
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User version (note that this need not be the same set of languages
395c95214142142854509945adf3293c0270e1c5Tinderbox User for each error code - you can get by with a single language
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User version until you actually <em>have</em> translated
395c95214142142854509945adf3293c0270e1c5Tinderbox User versions), a document
395c95214142142854509945adf3293c0270e1c5Tinderbox User <samp>errordocs/403.shtml.<em>lang</em></samp> is created and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User filled with the error text in that language (<a
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <li>One fallback document called
6d45011a65dfc43f476ca15c3fd9ee5227eb968fTinderbox User <samp>errordocs/403.shtml</samp> is created, usually by
395c95214142142854509945adf3293c0270e1c5Tinderbox User creating a symlink to the default language variant (<a
395c95214142142854509945adf3293c0270e1c5Tinderbox User <h3><a id="headfoot" name="headfoot">The common header and
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User By putting as much layout information in two special "include
395c95214142142854509945adf3293c0270e1c5Tinderbox User files", the error documents can be reduced to a bare minimum.
395c95214142142854509945adf3293c0270e1c5Tinderbox User <p>One of these layout files defines the HTML document header
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User and a configurable list of paths to the icons to be shown in
395c95214142142854509945adf3293c0270e1c5Tinderbox User the resulting error document. These paths are exported as a set
395c95214142142854509945adf3293c0270e1c5Tinderbox User of XSSI environment variables and are later evaluated by the
395c95214142142854509945adf3293c0270e1c5Tinderbox User "footer" special file. The title of the current error (which is
395c95214142142854509945adf3293c0270e1c5Tinderbox User put into the TITLE tag and an H1 header) is simply passed in
395c95214142142854509945adf3293c0270e1c5Tinderbox User from the main error document in a variable called
395c95214142142854509945adf3293c0270e1c5Tinderbox User <strong>By changing this file, the layout of all generated
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User error messages can be changed in a second.</strong> (By
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User exploiting the features of XSSI, you can easily define
395c95214142142854509945adf3293c0270e1c5Tinderbox User different layouts based on the current virtual host, or even
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User based on the client's domain name).</p>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p>The second layout file describes the footer to be displayed
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User at the bottom of every error message. In this example, it shows
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User an apache logo, the current server time, the server version
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User string and adds a mail reference to the site's webmaster.</p>
1ca759b3f5c0672b2a66bc02288fe010cabbfe37Tinderbox User <p>For simplicity, the header file is simply called
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User <code>head.shtml</code> because it contains server-parsed
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User content but no language specific information. The footer file
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User exists once for each language translation, plus a symlink for
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User the default language.</p>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User <p><strong>Example:</strong> for English, French and German
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User versions (default english)<br />
164ade1482251e1da962b42e5bf0d3aa02a11e03Tinderbox User <p>Both files are included into the error document by using the
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User directives <code><!--#include virtual="head" --></code>
395c95214142142854509945adf3293c0270e1c5Tinderbox User and <code><!--#include virtual="foot" --></code>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User respectively: the rest of the magic occurs in mod_negotiation
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User and in mod_include.</p>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p>See <a href="#listings">the listings below</a> to see an
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User actual HTML implementation of the discussed example.</p>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <h3><a id="createdocs" name="createdocs">Creating
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User ErrorDocuments in different languages</a></h3>
395c95214142142854509945adf3293c0270e1c5Tinderbox User After all this preparation work, little remains to be said
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User about the actual documents. They all share a simple common
395c95214142142854509945adf3293c0270e1c5Tinderbox User<!--#set var="title" value="<em>error description title</em>" -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User<!--#include virtual="head" -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<!--#include virtual="foot" -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User In the <a href="#listings">listings section</a>, you can see an
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User example of a [400 Bad Request] error document. Documents as
395c95214142142854509945adf3293c0270e1c5Tinderbox User simple as that certainly cause no problems to translate or
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <h3><a id="fallback" name="fallback">The fallback
395c95214142142854509945adf3293c0270e1c5Tinderbox User Do we need a special handling for languages other than those we
4f9cb7bd58e2c0a7407fee3758ea265aee329ac6Tinderbox User have translations for? We did set the LanguagePriority, didn't
395c95214142142854509945adf3293c0270e1c5Tinderbox User <p>Well, the LanguagePriority directive is for the case where
395c95214142142854509945adf3293c0270e1c5Tinderbox User the client does not express any language priority at all. But
395c95214142142854509945adf3293c0270e1c5Tinderbox User what happens in the situation where the client wants one of the
395c95214142142854509945adf3293c0270e1c5Tinderbox User languages we do not have, and none of those we do have?</p>
395c95214142142854509945adf3293c0270e1c5Tinderbox User <p>Without doing anything, the Apache server will usually
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User return a [406 no acceptable variant] error, listing the choices
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User from which the client may select. But we're in an error message
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User already, and important error information might get lost when
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User the client had to choose a language representation first.</p>
395c95214142142854509945adf3293c0270e1c5Tinderbox User <p>So, in this situation it appears to be easier to define a
0ccb0e98c77a9b9636a036f8f64f5679a430aaf4Tinderbox User fallback language (by copying or linking, <em>e.g.</em>, the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User english version to a language-less version). Because the
395c95214142142854509945adf3293c0270e1c5Tinderbox User negotiation algorithm prefers "more specialized" variants over
395c95214142142854509945adf3293c0270e1c5Tinderbox User "more generic" variants, these generic alternatives will only
395c95214142142854509945adf3293c0270e1c5Tinderbox User be chosen when the normal negotiation did not succeed.</p>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p>A simple shell script to do it (execute within the
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User errordocs/ dir):</p>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User ln -s $f `basename $f .en`
0ccb0e98c77a9b9636a036f8f64f5679a430aaf4Tinderbox User <h2><a id="proxy" name="proxy">Customizing Proxy Error
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <p>As of Apache-1.3, it is possible to use the
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <code>ErrorDocument</code> mechanism for proxy error messages
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User as well (previous versions always returned fixed predefined
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User error messages).</p>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <p>Most proxy errors return an error code of [500 Internal
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User Server Error]. To find out whether a particular error document
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User was invoked on behalf of a proxy error or because of some other
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User server error, and what the reason for the failure was, you can
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User check the contents of the new <code>ERROR_NOTES</code> CGI
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User environment variable: if invoked for a proxy error, this
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User variable will contain the actual proxy error message text in
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User HTML form.</p>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <p>The following excerpt demonstrates how to exploit the
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <code>ERROR_NOTES</code> variable within an error document:</p>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User The server encountered an unexpected condition
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User which prevented it from fulfilling the request.
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User WebMaster</A>; it includes useful debugging information about
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User the Request which caused the error.
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <pre><!--#printenv --></pre>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <!--#else -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User <!--#echo var="REDIRECT_ERROR_NOTES" -->
0ccb0e98c77a9b9636a036f8f64f5679a430aaf4Tinderbox User <!--#endif -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User <h2><a id="listings" name="listings">HTML listing of the
395c95214142142854509945adf3293c0270e1c5Tinderbox User So, to summarize our example, here's the complete listing of
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User the <samp>400.shtml.en</samp> document. You will notice that it
395c95214142142854509945adf3293c0270e1c5Tinderbox User contains almost nothing but the error text (with conditional
395c95214142142854509945adf3293c0270e1c5Tinderbox User additions). Starting with this example, you will find it easy
395c95214142142854509945adf3293c0270e1c5Tinderbox User to add more error documents, or to translate the error
395c95214142142854509945adf3293c0270e1c5Tinderbox User documents to different languages.
395c95214142142854509945adf3293c0270e1c5Tinderbox User<!--#set var="title" value="Bad Request"
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User--><!--#include virtual="head" --><P>
395c95214142142854509945adf3293c0270e1c5Tinderbox User Your browser sent a request that this server could not understand:
395c95214142142854509945adf3293c0270e1c5Tinderbox User <BLOCKQUOTE>
395c95214142142854509945adf3293c0270e1c5Tinderbox User <STRONG><!--#echo var="REQUEST_URI" --></STRONG>
395c95214142142854509945adf3293c0270e1c5Tinderbox User </BLOCKQUOTE>
395c95214142142854509945adf3293c0270e1c5Tinderbox User The request could not be understood by the server due to malformed
395c95214142142854509945adf3293c0270e1c5Tinderbox User syntax. The client should not repeat the request without
395c95214142142854509945adf3293c0270e1c5Tinderbox User modifications.
395c95214142142854509945adf3293c0270e1c5Tinderbox User <!--#if expr="$HTTP_REFERER != ''" -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Please inform the owner of
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <A HREF="<!--#echo var="HTTP_REFERER" -->">the referring page</A> about
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User the malformed link.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <!--#else -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User Please check your request for typing errors and retry.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <!--#endif -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User<!--#include virtual="foot" -->
395c95214142142854509945adf3293c0270e1c5Tinderbox User Here is the complete <samp>head.shtml</samp> file (the funny
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User line breaks avoid empty lines in the document after XSSI
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User processing). Note the configuration section at top. That's
395c95214142142854509945adf3293c0270e1c5Tinderbox User where you configure the images and logos as well as the apache
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User documentation directory. Look how this file displays two
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User different logos depending on the content of the virtual host
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User name ($SERVER_NAME), and that an animated apache logo is shown
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User if the browser appears to support it (the latter requires
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User server configuration lines of the form <br />
61ab11c0ec845606f85452b2c9f2e223772aae00Tinderbox User <code>BrowserMatch "^Mozilla/[2-4]" anigif</code><br />
61ab11c0ec845606f85452b2c9f2e223772aae00Tinderbox User for browser types which support animated GIFs).
61ab11c0ec845606f85452b2c9f2e223772aae00Tinderbox User<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/"
f5c27ecceb6dcba6ad8b75172fe5f9823d7a6d42Tinderbox User--><!--#set var="IMG_CorpLogo"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="ALT_CorpLogo" value="Powered by Linux!"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#else
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="IMG_CorpLogo"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="ALT_CorpLogo" value="Powered by Linux!"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#endif
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User--><!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#if expr="$anigif"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#else
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User--><!--#endif
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User--><!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <TITLE>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </TITLE>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User </HEAD>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <BODY BGCOLOR="white" BACKGROUND="<!--#echo var="IMG_BgImage" -->"><UL>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <H1 ALIGN="center">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <IMG SRC="<!--#echo var="IMG_CorpLogo" -->"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User ALT="<!--#echo var="ALT_CorpLogo" -->" ALIGN=right>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <HR><!-- ======================================================== -->
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User and this is the <samp>foot.shtml.en</samp> file:
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <DIV ALIGN="right"><SMALL><SUP>Local Server time:
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <!--#echo var="DATE_LOCAL" -->
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User </SUP></SMALL></DIV>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <DIV ALIGN="center">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <A HREF="<!--#echo var="DOC_Apache" -->">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <IMG SRC="<!--#echo var="IMG_Apache" -->" BORDER=0 ALIGN="bottom"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User ALT="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></A><BR>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <SMALL><SUP><!--#set var="var"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User value="Powered by $SERVER_SOFTWARE -- File last modified on $LAST_MODIFIED"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User --><!--#echo var="var" --></SUP></SMALL>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <ADDRESS>If the indicated error looks like a misconfiguration, please inform
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->"
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User SUBJECT="Feedback about Error message [<!--#echo var="REDIRECT_STATUS"
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User -->] <!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->">
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User <!--#echo var="SERVER_NAME" -->'s WebMaster</A>.
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User </ADDRESS>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User </UL></BODY>
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User If you have tips to contribute, send mail to <a
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User href="mailto:martin@apache.org">martin@apache.org</a>
395c95214142142854509945adf3293c0270e1c5Tinderbox User <!--#include virtual="footer.html" -->