diff options
Diffstat (limited to 'rubbos/app/apache2/manual/misc/custom_errordocs.html.en')
| -rw-r--r-- | rubbos/app/apache2/manual/misc/custom_errordocs.html.en | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/rubbos/app/apache2/manual/misc/custom_errordocs.html.en b/rubbos/app/apache2/manual/misc/custom_errordocs.html.en new file mode 100644 index 00000000..fc2ccd8e --- /dev/null +++ b/rubbos/app/apache2/manual/misc/custom_errordocs.html.en @@ -0,0 +1,577 @@ +<?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 |