📄 custom_errordocs.html.en
字号:
<?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⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -