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, 0 insertions, 577 deletions
diff --git a/rubbos/app/apache2/manual/misc/custom_errordocs.html.en b/rubbos/app/apache2/manual/misc/custom_errordocs.html.en deleted file mode 100644 index fc2ccd8e..00000000 --- a/rubbos/app/apache2/manual/misc/custom_errordocs.html.en +++ /dev/null @@ -1,577 +0,0 @@ -<?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 |