+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- This file is generated from xml source: DO NOT EDIT
- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- -->
-<title>International Customized Server Error Messages - Apache HTTP Server</title>
-<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
-<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
-<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
-<link href="../images/favicon.ico" rel="shortcut icon" /></head>
-<body id="manual-page"><div id="page-header">
-<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
-<p class="apache">Apache HTTP Server Version 2.0</p>
-<img alt="" src="../images/feather.gif" /></div>
-<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
-<div id="path">
-<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Miscellaneous Documentation</a></div><div id="page-content"><div id="preamble"><h1>International Customized Server Error Messages</h1>
-<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/misc/custom_errordocs.html" title="English"> en </a></p>
-</div>
-
-
- <div class="warning"><h3>Warning:</h3>
- <p>This document has not been fully updated
- to take into account changes made in the 2.0 version of the
- Apache HTTP Server. Some of the information may still be
- relevant, but please use it with care.</p>
- </div>
-
- <p>This document describes an easy way to provide your Apache
- HTTP Server with a set of customized error messages which take
- advantage of <a href="../content-negotiation.html">Content
- Negotiation</a> and <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> to return
- error messages generated by the server in the client's native
- language.</p>
-
- </div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#intro">Introduction</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#createdir">Creating an ErrorDocument directory</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxy">Customizing Proxy Error Messages</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#listings">HTML Listing of the Discussed Example</a></li>
-</ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="intro" id="intro">Introduction</a></h2>
-
-
-
- <p>By using SSI, all <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> messages
- can share a homogenous and consistent style and layout, and
- maintenance work (changing images, changing links) is kept to a
- minimum because all layout information can be kept in a single
- file.</p>
-
- <p>Error documents can be shared across different servers, or
- even hosts, because all varying information is inserted at the
- time the error document is returned on behalf of a failed
- request.</p>
-
- <p>Content Negotiation then selects the appropriate language
- version of a particular error message text, honoring the
- language preferences passed in the client's request. (Users
- usually select their favorite languages in the preferences
- options menu of today's browsers). When an error document in
- the client's primary language version is unavailable, the
- secondary languages are tried or a default (fallback) version
- is used.</p>
-
- <p>You have full flexibility in designing your error documents
- to your personal taste (or your company's conventions). For
- demonstration purposes, we present a simple generic error
- document scheme. For this hypothetic server, we assume that all
- error messages...</p>
-
- <ul>
- <li>possibly are served by different virtual hosts (different
- host name, different IP address, or different port) on the
- server machine,</li>
-
- <li>show a predefined company logo in the right top of the
- message (selectable by virtual host),</li>
-
- <li>print the error title first, followed by an explanatory
- text and (depending on the error context) help on how to
- resolve the error,</li>
-
- <li>have some kind of standardized background image,</li>
-
- <li>display an apache logo and a feedback email address at
- the bottom of the error message.</li>
- </ul>
-
- <p>An example of a "document not found" message for a german
- client might look like this:</p>
-
- <p><img src="../images/custom_errordocs.gif" alt="[Needs graphics capability to display]" /></p>
-
- <p>All links in the document as well as links to the server's
- administrator mail address, and even the name and port of the
- serving virtual host are inserted in the error document at
- "run-time", i.e., when the error actually occurs.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="createdir" id="createdir">Creating an ErrorDocument directory</a></h2>
-
-
-
- <p>For this concept to work as easily as possible, we must take
- advantage of as much server support as we can get:</p>
-
- <ol>
- <li>By defining the MultiViews <code class="directive"><a href="../mod/core.html#options">Options</a></code>, we
- enable the language selection of the most appropriate
- language alternative (content negotiation).</li>
-
- <li>By setting the <code class="directive"><a href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>
- directive we define a set of default fallback languages in
- the situation where the client's browser did not express any
- preference at all.</li>
-
- <li>By enabling <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- (and disallowing execution of cgi scripts for
- security reasons), we allow the server to include building
- blocks of the error message, and to substitute the value of
- certain environment variables into the generated document
- (dynamic HTML) or even to conditionally include or omit parts
- of the text.</li>
-
- <li>The <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> and <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directives
- are useful for automatically SSI-expanding all files with a
- <code>.shtml</code> suffix to <em>text/html</em>.</li>
-
- <li>By using the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive, we
- keep the error document directory outside of the document
- tree because it can be regarded more as a server part than
- part of the document tree.</li>
-
- <li>The <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> block
- restricts these "special" settings to the error document
- directory and avoids an impact on any of the settings for the
- regular document tree.</li>
-
- <li>For each of the error codes to be handled (see RFC2068
- for an exact description of each error code, or look at
- <code>src/main/http_protocol.c</code> if you wish to see
- apache's standard messages), an <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> in
- the aliased <code>/errordocs</code> directory is defined.
- Note that we only define the basename of the document here
- because the MultiViews option will select the best candidate
- based on the language suffixes and the client's preferences.
- Any error situation with an error code <em>not</em> handled
- by a custom document will be dealt with by the server in the
- standard way (<em>i.e.</em>, a plain error message in
- english).</li>
-
- <li>Finally, the <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> directive tells
- apache that it is not necessary to look for a .htaccess file
- in the /errordocs directory: a minor speed optimization.</li>
- </ol>
-
- <p>The resulting <code>httpd.conf</code> configuration would then
- look similar to this:</p>
-
- <div class="note"><h3>Note</h3>Note that you can define your own
- error messages using this method for only part of the document
- tree, e.g., a /~user/ subtree. In this case, the configuration
- could as well be put into the .htaccess file at the root of the
- subtree, and the <Directory> and </Directory>
- directives -but not the contained directives- must be
- omitted.</div>
-
-<div class="example"><p><code>
- LanguagePriority en fr de <br />
- Alias /errordocs /usr/local/apache/errordocs <br />
- <br />
- <Directory /usr/local/apache/errordocs> <br />
- <span class="indent">
- AllowOverride none <br />
- Options MultiViews IncludesNoExec FollowSymLinks <br />
- AddType text/html .shtml <br />
- <FilesMatch "\.shtml[.$]"> <br />
- <span class="indent">
- SetOutputFilter INCLUDES <br />
- </span>
- </FilesMatch> <br />
- </span>
- </Directory> <br />
- <br />
- # "400 Bad Request", <br />
- ErrorDocument 400 /errordocs/400 <br />
- # "401 Authorization Required", <br />
- ErrorDocument 401 /errordocs/401 <br />
- # "403 Forbidden", <br />
- ErrorDocument 403 /errordocs/403 <br />
- # "404 Not Found", <br />
- ErrorDocument 404 /errordocs/404 <br />
- # "500 Internal Server Error", <br />
- ErrorDocument 500 /errordocs/500 <br />
-</code></p></div>
-
- <p>The directory for the error messages (here:
- <code>/usr/local/apache/errordocs/</code>) must then be created
- with the appropriate permissions (readable and executable by
- the server uid or gid, only writable for the administrator).</p>
-
- <h3><a name="naming" id="naming">Naming the Individual Error Document files</a></h3>
-
-
-
- <p>By defining the <code>MultiViews</code> option, the server was
- told to automatically scan the directory for matching variants
- (looking at language and content type suffixes) when a
- requested document was not found. In the configuration, we
- defined the names for the error documents to be just their
- error number (without any suffix).</p>
-
- <p>The names of the individual error documents are now
- determined like this (I'm using 403 as an example, think of it
- as a placeholder for any of the configured error
- documents):</p>
-
- <ul>
- <li>No file errordocs/403 should exist. Otherwise, it would
- be found and served (with the DefaultType, usually
- text/plain), all negotiation would be bypassed.</li>
-
- <li>For each language for which we have an internationalized
- version (note that this need not be the same set of languages
- for each error code - you can get by with a single language
- version until you actually <em>have</em> translated
- versions), a document
- <code>errordocs/403.shtml.<em>lang</em></code> is created and
- filled with the error text in that language (<a href="#createdocs">see below</a>).</li>
-
- <li>One fallback document called
- <code>errordocs/403.shtml</code> is created, usually by
- creating a symlink to the default language variant (<a href="#fallback">see below</a>).</li>
- </ul>
-
-
- <h3><a name="headfoot" id="headfoot">The Common Header and Footer Files</a></h3>
-
-
-
- <p>By putting as much layout information in two special "include
- files", the error documents can be reduced to a bare minimum.</p>
-
- <p>One of these layout files defines the HTML document header
- and a configurable list of paths to the icons to be shown in
- the resulting error document. These paths are exported as a set
- of SSI environment variables and are later evaluated by the
- "footer" special file. The title of the current error (which is
- put into the TITLE tag and an H1 header) is simply passed in
- from the main error document in a variable called
- <code>title</code>.</p>
-
- <p><strong>By changing this file, the layout of all generated
- error messages can be changed in a second.</strong> (By
- exploiting the features of SSI, you can easily define
- different layouts based on the current virtual host, or even
- based on the client's domain name).</p>
-
- <p>The second layout file describes the footer to be displayed
- at the bottom of every error message. In this example, it shows
- an apache logo, the current server time, the server version
- string and adds a mail reference to the site's webmaster.</p>
-
- <p>For simplicity, the header file is simply called
- <code>head.shtml</code> because it contains server-parsed
- content but no language specific information. The footer file
- exists once for each language translation, plus a symlink for
- the default language.</p>
-
-<div class="example"><p><code>
-for English, French and German versions (default english) <br />
-<br />
-foot.shtml.en, <br />
-foot.shtml.fr, <br />
-foot.shtml.de, <br />
-foot.shtml symlink to <br />
-foot.shtml.en
-</code></p></div>
-
- <p>Both files are included into the error document by using the
- directives <code><!--#include virtual="head" --></code>
- and <code><!--#include virtual="foot" --></code>
- respectively: the rest of the magic occurs in mod_negotiation
- and in mod_include.</p>
-
- <p>See <a href="#listings">the listings below</a> to see an
- actual HTML implementation of the discussed example.</p>
-
-
- <h3><a name="createdocs" id="createdocs">Creating ErrorDocuments in Different Languages</a></h3>
-
-
-
- <p>After all this preparation work, little remains to be said
- about the actual documents. They all share a simple common
- structure:</p>
-
-<div class="example"><p><code>
-<!--#set var="title" value="<em>error description title</em>" --> <br />
-<!--#include virtual="head" --> <br />
-<span class="indent">
- <em>explanatory error text</em> <br />
-</span>
-<!--#include virtual="foot" -->
-</code></p></div>
-
- <p>In the <a href="#listings">listings section</a>, you can see an
- example of a [400 Bad Request] error document. Documents as
- simple as that certainly cause no problems to translate or
- expand.</p>
-
-
- <h3><a name="fallback" id="fallback">The Fallback Language</a></h3>
-
-
-
- <p>Do we need a special handling for languages other than those we
- have translations for? We did set the LanguagePriority, didn't
- we?!</p>
-
- <p>Well, the LanguagePriority directive is for the case where
- the client does not express any language priority at all. But
- what happens in the situation where the client wants one of the
- languages we do not have, and none of those we do have?</p>
-
- <p>Without doing anything, the Apache server will usually
- return a [406 no acceptable variant] error, listing the choices
- from which the client may select. But we're in an error message
- already, and important error information might get lost when
- the client had to choose a language representation first.</p>
-
- <p>So, in this situation it appears to be easier to define a
- fallback language (by copying or linking, <em>e.g.</em>, the
- english version to a language-less version). Because the
- negotiation algorithm prefers "more specialized" variants over
- "more generic" variants, these generic alternatives will only
- be chosen when the normal negotiation did not succeed.</p>
-
- <p>A simple shell script to do it (execute within the
- errordocs/ dir):</p>
-
-<div class="example"><p><code>
- for f in *.shtml.en <br />
- do <br />
- <span class="indent">
- ln -s $f `basename $f .en` <br />
- </span>
- done
-</code></p></div>
-
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="proxy" id="proxy">Customizing Proxy Error Messages</a></h2>
-
-
-
- <p>As of Apache-1.3, it is possible to use the
- <code>ErrorDocument</code> mechanism for proxy error messages
- as well (previous versions always returned fixed predefined
- error messages).</p>
-
- <p>Most proxy errors return an error code of [500 Internal
- Server Error]. To find out whether a particular error document
- was invoked on behalf of a proxy error or because of some other
- server error, and what the reason for the failure was, you can
- check the contents of the new <code>ERROR_NOTES</code> CGI
- environment variable: if invoked for a proxy error, this
- variable will contain the actual proxy error message text in
- HTML form.</p>
-
- <p>The following excerpt demonstrates how to exploit the
- <code>ERROR_NOTES</code> variable within an error document:</p>
-
-<div class="example"><p><code>
- <!--#if expr="$REDIRECT_ERROR_NOTES = ''" --> <br />
- <br />
- <p> <br />
- <span class="indent">
- The server encountered an unexpected condition <br />
- which prevented it from fulfilling the request. <br />
- </span>
- </p> <br />
-<br />
- <p> <br />
- <span class="indent">
- <a href="mailto:<!--#echo var="SERVER_ADMIN" -->" <br />
- SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->"> <br />
- Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s <br />
- WebMaster</a>; it includes useful debugging information about <br />
- the Request which caused the error. <br />
-<br />
- <pre><!--#printenv --></pre> <br />
- </span>
- </p> <br />
- <br />
- <!--#else --> <br />
- <span class="indent">
- <!--#echo var="REDIRECT_ERROR_NOTES" --><br />
- </span>
-<br />
- <!--#endif -->
-</code></p></div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="listings" id="listings">HTML Listing of the Discussed Example</a></h2>
-
-
-
- <p>So, to summarize our example, here's the complete listing of
- the <code>400.shtml.en</code> document. You will notice that it
- contains almost nothing but the error text (with conditional
- additions). Starting with this example, you will find it easy
- to add more error documents, or to translate the error
- documents to different languages.</p>
-
-<div class="example"><p><code>
-<!--#set var="title" value="Bad Request"--> <br />
-<!--#include virtual="head" --><br />
-<br />
- <p> <br />
- <span class="indent">
- Your browser sent a request that this server could not understand: <br />
- <blockquote> <br />
- <span class="indent">
- <strong><!--#echo var="REQUEST_URI" --></strong><br />
- </span>
- </blockquote> <br />
- <br />
- The request could not be understood by the server due to malformed <br />
- syntax. The client should not repeat the request without <br />
- modifications. <br />
- </span>
- </p> <br />
-<br />
- <p> <br />
- <span class="indent">
- <!--#if expr="$HTTP_REFERER != ''" --> <br />
- <span class="indent">
- Please inform the owner of <br />
- <a href="<!--#echo var="HTTP_REFERER" -->">the referring page</a> about <br />
- the malformed link. <br />
- </span>
- <br />
- <!--#else --> <br />
- <span class="indent">
- Please check your request for typing errors and retry. <br />
- </span>
- <br />
- <!--#endif --> <br />
- </span>
- </p> <br />
-<br />
-<!--#include virtual="foot" -->
-</code></p></div>
-
- <p>Here is the complete <code>head.shtml.en</code> file (the funny
- line breaks avoid empty lines in the document after SSI
- processing). Note the configuration section at top. That's
- where you configure the images and logos as well as the apache
- documentation directory. Look how this file displays two
- different logos depending on the content of the virtual host
- name ($SERVER_NAME), and that an animated apache logo is shown
- if the browser appears to support it (the latter requires
- server configuration lines of the form </p>
-
- <div class="example"><p><code>BrowserMatch "^Mozilla/[2-4]" anigif</code></p></div>
-
- <p>for browser types which support animated GIFs).</p>
-
-<div class="example"><p><code>
-<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" --><br />
-<span class="indent">
-<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" --><br />
-<!--#set var="ALT_CorpLogo" value="Powered by Linux!" --><br />
-</span>
-<br />
-<!--#else --> <br />
-<span class="indent">
-<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" --> <br />
-<!--#set var="ALT_CorpLogo" value="Powered by Linux!" --> <br />
-</span>
-<!--#endif--> <br />
-<br />
-<!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" --> <br />
-<!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" --> <br />
-<br />
-<!--#if expr="$anigif" --> <br />
-<span class="indent">
-<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" --> <br />
-</span>
-<!--#else--><br />
-<span class="indent">
-<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" --><br />
-</span>
-<!--#endif--><br />
-<br />
-
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <br />
-<html> <br />
-<head> <br />
- <span class="indent">
- <title> <br />
- [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> <br />
- </title> <br />
- </span>
-</head> <br />
-<br />
-<body bgcolor="white" background="<!--#echo var="IMG_BgImage" -->"> <br />
-<span class="indent">
- <h1 align="center"> <br />
- [<!--#echo var="REDIRECT_STATUS" -->]
- <!--#echo var="title" --> <br />
- <img src="<!--#echo var="IMG_CorpLogo" -->" <br />
- alt="<!--#echo var="ALT_CorpLogo" -->" align="right"> <br />
- </h1> <br />
-<br />
- <hr />
- <!-- ======================================================== --> <br />
- <div>
-</span>
-</code></p></div>
-
- <p>and this is the <code>foot.shtml.en</code> file:</p>
-
-<div class="example"><p><code>
-<span class="indent">
- </div> <br />
- <hr /> <br />
- <br />
- <div align="right"> <br />
- <span class="indent">
- <small>Local Server time:
- <!--#echo var="DATE_LOCAL" --></small> <br />
- </span>
- </div> <br />
- <br />
- <div align="center"><br />
- <span class="indent">
- <a href="<!--#echo var="DOC_Apache" -->"> <br />
- <img src="<!--#echo var="IMG_Apache" -->" border="0" align="bottom" <br />
- alt="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></a> <br />
- <br /><br />
-
- <small><!--#set var="var" value="Powered by $SERVER_SOFTWARE -- <br />
- File last modified on $LAST_MODIFIED" --> <br />
- <!--#echo var="var" --></small> <br />
- </span>
- </div> <br />
- <br />
- <p>If the indicated error looks like a misconfiguration, please inform <br />
- <a href="mailto:<!--#echo var="SERVER_ADMIN" -->" <br />
- subject="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" -->] <br />
- <!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->"> <br />
- <!--#echo var="SERVER_NAME" -->'s WebMaster</a>.<br />
- </p><br />
- </span>
-<br />
-</body><br />
-</html>
-</code></p></div>
-
- <p>If you have tips to contribute, send mail to <a href="mailto:martin@apache.org">martin@apache.org</a></p>
- </div></div>
-<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/misc/custom_errordocs.html" title="English"> en </a></p>
-</div><div id="footer">
-<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
-<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
-</body></html>
\ No newline at end of file
Code Review / bottlenecks.git / blobdiff