--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+ <relativepath href=".." />
+ <parentdocument href="./">Miscellaneous Documentation</parentdocument>
+
+ <title>International Customized Server Error Messages</title>
+
+ <summary>
+
+ <note type="warning"><title>Warning:</title>
+ <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>
+ </note>
+
+ <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 <module>mod_include</module> to return
+ error messages generated by the server in the client's native
+ language.</p>
+
+ </summary>
+
+ <section id="intro">
+
+ <title>Introduction</title>
+
+ <p>By using SSI, all <directive
+ module="core">ErrorDocument</directive> 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>
+ </section>
+
+ <section id="createdir">
+
+ <title>Creating an ErrorDocument directory</title>
+
+ <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 <directive
+ module="core">Options</directive>, we
+ enable the language selection of the most appropriate
+ language alternative (content negotiation).</li>
+
+ <li>By setting the <directive
+ module="mod_negotiation.html">LanguagePriority</directive>
+ 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 <module>mod_include</module>
+ (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 <directive
+ module="mod_mime">AddHandler</directive> and <directive
+ module="mod_mime">AddType</directive> 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 <directive
+ module="mod_alias">Alias</directive> 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 <directive type="section"
+ module="core">Directory</directive> 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 <directive
+ module="core">ErrorDocument</directive> 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 <directive
+ module="core">AllowOverride</directive> 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>
+
+ <note><title>Note</title>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.</note>
+
+<example>
+ LanguagePriority en fr de <br />
+ Alias /errordocs /usr/local/apache/errordocs <br />
+ <br />
+ <Directory /usr/local/apache/errordocs> <br />
+ <indent>
+ AllowOverride none <br />
+ Options MultiViews IncludesNoExec FollowSymLinks <br />
+ AddType text/html .shtml <br />
+ <FilesMatch "\.shtml[.$]"> <br />
+ <indent>
+ SetOutputFilter INCLUDES <br />
+ </indent>
+ </FilesMatch> <br />
+ </indent>
+ </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 />
+</example>
+
+ <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>
+
+ <section id="naming">
+
+ <title>Naming the Individual Error Document files</title>
+
+ <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>
+ </section>
+
+ <section id="headfoot">
+
+ <title>The Common Header and Footer Files</title>
+
+ <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>
+
+<example>
+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
+</example>
+
+ <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>
+ </section>
+
+ <section id="createdocs">
+
+ <title>Creating ErrorDocuments in Different Languages</title>
+
+ <p>After all this preparation work, little remains to be said
+ about the actual documents. They all share a simple common
+ structure:</p>
+
+<example>
+<!--#set var="title" value="<em>error description title</em>" --> <br />
+<!--#include virtual="head" --> <br />
+<indent>
+ <em>explanatory error text</em> <br />
+</indent>
+<!--#include virtual="foot" -->
+</example>
+
+ <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>
+ </section>
+
+ <section id="fallback">
+
+ <title>The Fallback Language</title>
+
+ <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>
+
+<example>
+ for f in *.shtml.en <br />
+ do <br />
+ <indent>
+ ln -s $f `basename $f .en` <br />
+ </indent>
+ done
+</example>
+
+ </section>
+ </section>
+
+ <section id="proxy">
+
+ <title>Customizing Proxy Error Messages</title>
+
+ <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>
+
+<example>
+ <!--#if expr="$REDIRECT_ERROR_NOTES = ''" --> <br />
+ <br />
+ <p> <br />
+ <indent>
+ The server encountered an unexpected condition <br />
+ which prevented it from fulfilling the request. <br />
+ </indent>
+ </p> <br />
+<br />
+ <p> <br />
+ <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 />
+ </indent>
+ </p> <br/>
+ <br />
+ <!--#else --> <br />
+ <indent>
+ <!--#echo var="REDIRECT_ERROR_NOTES" --><br />
+ </indent>
+<br />
+ <!--#endif -->
+</example>
+
+ </section>
+
+ <section id="listings">
+
+ <title>HTML Listing of the Discussed Example</title>
+
+ <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>
+
+<example>
+<!--#set var="title" value="Bad Request"--> <br />
+<!--#include virtual="head" --><br />
+<br />
+ <p> <br />
+ <indent>
+ Your browser sent a request that this server could not understand: <br />
+ <blockquote> <br />
+ <indent>
+ <strong><!--#echo var="REQUEST_URI" --></strong><br />
+ </indent>
+ </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 />
+ </indent>
+ </p> <br />
+<br />
+ <p> <br />
+ <indent>
+ <!--#if expr="$HTTP_REFERER != ''" --> <br />
+ <indent>
+ Please inform the owner of <br />
+ <a href="<!--#echo var="HTTP_REFERER" -->">the referring page</a> about <br />
+ the malformed link. <br />
+ </indent>
+ <br />
+ <!--#else --> <br />
+ <indent>
+ Please check your request for typing errors and retry. <br />
+ </indent>
+ <br />
+ <!--#endif --> <br />
+ </indent>
+ </p> <br />
+<br />
+<!--#include virtual="foot" -->
+</example>
+
+ <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>
+
+ <example>BrowserMatch "^Mozilla/[2-4]" anigif</example>
+
+ <p>for browser types which support animated GIFs).</p>
+
+<example>
+<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" --><br />
+<indent>
+<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" --><br />
+<!--#set var="ALT_CorpLogo" value="Powered by Linux!" --><br />
+</indent>
+<br />
+<!--#else --> <br />
+<indent>
+<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" --> <br />
+<!--#set var="ALT_CorpLogo" value="Powered by Linux!" --> <br />
+</indent>
+<!--#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 />
+<indent>
+<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" --> <br />
+</indent>
+<!--#else--><br />
+<indent>
+<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" --><br />
+</indent>
+<!--#endif--><br />
+<br />
+
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <br />
+<html> <br />
+<head> <br />
+ <indent>
+ <title> <br />
+ [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> <br />
+ </title> <br />
+ </indent>
+</head> <br />
+<br />
+<body bgcolor="white" background="<!--#echo var="IMG_BgImage" -->"> <br />
+<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>
+</indent>
+</example>
+
+ <p>and this is the <code>foot.shtml.en</code> file:</p>
+
+<example>
+<indent>
+ </div> <br />
+ <hr /> <br />
+ <br />
+ <div align="right"> <br />
+ <indent>
+ <small>Local Server time:
+ <!--#echo var="DATE_LOCAL" --></small> <br />
+ </indent>
+ </div> <br />
+ <br />
+ <div align="center"><br />
+ <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 />
+ </indent>
+ </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 />
+ </indent>
+<br />
+</body><br />
+</html>
+</example>
+
+ <p>If you have tips to contribute, send mail to <a
+ href="mailto:martin@apache.org">martin@apache.org</a></p>
+ </section>
+
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+ <relativepath href=".." />
+ <parentdocument href="./">Miscellaneous Documentation</parentdocument>
+
+ <title>Descriptors and Apache</title>
+
+ <summary>
+
+ <note type="warning"><title>Warning:</title>
+ <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>
+ </note>
+
+ <p>A <em>descriptor</em>, also commonly called a <em>file
+ handle</em> is an object that a program uses to read or write
+ an open file, or open network socket, or a variety of other
+ devices. It is represented by an integer, and you may be
+ familiar with <code>stdin</code>, <code>stdout</code>, and
+ <code>stderr</code> which are descriptors 0, 1, and 2
+ respectively. Apache needs a descriptor for each log file, plus
+ one for each network socket that it listens on, plus a handful
+ of others. Libraries that Apache uses may also require
+ descriptors. Normal programs don't open up many descriptors at
+ all, and so there are some latent problems that you may
+ experience should you start running Apache with many
+ descriptors (<em>i.e.</em>, with many virtual hosts).</p>
+
+ <p>The operating system enforces a limit on the number of
+ descriptors that a program can have open at a time. There are
+ typically three limits involved here. One is a kernel
+ limitation, depending on your operating system you will either
+ be able to tune the number of descriptors available to higher
+ numbers (this is frequently called <em>FD_SETSIZE</em>). Or you
+ may be stuck with a (relatively) low amount. The second limit
+ is called the <em>hard resource</em> limit, and it is sometimes
+ set by root in an obscure operating system file, but frequently
+ is the same as the kernel limit. The third limit is called the
+ <em>soft resource</em> limit. The soft limit is always less
+ than or equal to the hard limit. For example, the hard limit
+ may be 1024, but the soft limit only 64. Any user can raise
+ their soft limit up to the hard limit. Root can raise the hard
+ limit up to the system maximum limit. The soft limit is the
+ actual limit that is used when enforcing the maximum number of
+ files a process can have open.</p>
+
+ <p>To summarize:</p>
+
+<example>
+ #open files <= soft limit <= hard limit <= kernel limit
+</example>
+
+
+ <p>You control the hard and soft limits using the
+ <code>limit</code> (csh) or <code>ulimit</code> (sh)
+ directives. See the respective man pages for more information.
+ For example you can probably use <code>ulimit -n
+ unlimited</code> to raise your soft limit up to the hard limit.
+ You should include this command in a shell script which starts
+ your webserver.</p>
+
+ <p>Unfortunately, it's not always this simple. As mentioned
+ above, you will probably run into some system limitations that
+ will need to be worked around somehow. Work was done in version
+ 1.2.1 to improve the situation somewhat. Here is a partial list
+ of systems and workarounds (assuming you are using 1.2.1 or
+ later).</p>
+
+ </summary>
+
+ <section id="bsdi"><title>BSDI 2.0</title>
+
+ <p>Under BSDI 2.0 you can build Apache to support more
+ descriptors by adding <code>-DFD_SETSIZE=nnn</code> to
+ <code>EXTRA_CFLAGS</code> (where nnn is the number of
+ descriptors you wish to support, keep it less than the hard
+ limit). But it will run into trouble if more than
+ approximately 240 Listen directives are used. This may be
+ cured by rebuilding your kernel with a higher
+ FD_SETSIZE.</p>
+
+ </section>
+
+ <section id="freebsd"><title>FreeBSD 2.2, BSDI 2.1+</title>
+
+ <p>Similar to the BSDI 2.0 case, you should define
+ <code>FD_SETSIZE</code> and rebuild. But the extra Listen
+ limitation doesn't exist.</p>
+
+ </section>
+
+ <section id="linux"><title>Linux</title>
+
+ <p>By default Linux has a kernel maximum of 256 open
+ descriptors per process. There are several patches available
+ for the 2.0.x series which raise this to 1024 and beyond, and
+ you can find them in the "unofficial patches" section of <a
+ href="http://www.linuxhq.com/">the Linux Information HQ</a>.
+ None of these patches are perfect, and an entirely different
+ approach is likely to be taken during the 2.1.x development.
+ Applying these patches will raise the FD_SETSIZE used to
+ compile all programs, and unless you rebuild all your
+ libraries you should avoid running any other program with a
+ soft descriptor limit above 256. As of this writing the
+ patches available for increasing the number of descriptors do
+ not take this into account. On a dedicated webserver you
+ probably won't run into trouble.</p>
+
+ </section>
+
+ <section id="solaris"><title>Solaris through 2.5.1</title>
+
+ <p>Solaris has a kernel hard limit of 1024 (may be lower in
+ earlier versions). But it has a limitation that files using
+ the stdio library cannot have a descriptor above 255. Apache
+ uses the stdio library for the ErrorLog directive. When you
+ have more than approximately 110 virtual hosts (with an error
+ log and an access log each) you will need to build Apache
+ with <code>-DHIGH_SLACK_LINE=256</code> added to
+ <code>EXTRA_CFLAGS</code>. You will be limited to
+ approximately 240 error logs if you do this.</p>
+
+ </section>
+
+ <section id="AIX"><title>AIX</title>
+
+ <p>AIX version 3.2?? appears to have a hard limit of 128
+ descriptors. End of story. Version 4.1.5 has a hard limit of
+ 2000.</p>
+
+ </section>
+
+ <section id="sco"><title>SCO OpenServer</title>
+
+ <p>Edit the <code>/etc/conf/cf.d/stune</code> file or use
+ <code>/etc/conf/cf.d/configure</code> choice 7 (User and
+ Group configuration) and modify the <code>NOFILES</code>
+ kernel parameter to a suitably higher value. SCO recommends a
+ number between 60 and 11000, the default is 110. Relink and
+ reboot, and the new number of descriptors will be
+ available.</p>
+
+ </section>
+
+ <section id="tru64"><title>Compaq Tru64 UNIX/Digital UNIX/OSF</title>
+
+ <ol>
+ <li>Raise <code>open_max_soft</code> and
+ <code>open_max_hard</code> to 4096 in the proc subsystem.
+ Do a man on sysconfig, sysconfigdb, and
+ sysconfigtab.</li>
+
+ <li>Raise <code>max-vnodes</code> to a large number which
+ is greater than the number of apache processes * 4096
+ (Setting it to 250,000 should be good for most people).
+ Do a man on sysconfig, sysconfigdb, and
+ sysconfigtab.</li>
+
+ <li>If you are using Tru64 5.0, 5.0A, or 5.1, define
+ <code>NO_SLACK</code> to work around a bug in the OS.
+ <code>CFLAGS="-DNO_SLACK" ./configure</code></li>
+ </ol>
+
+ </section>
+
+ <section id="others"><title>Others</title>
+
+ <p>If you have details on another operating system, please
+ submit it through our <a
+ href="http://httpd.apache.org/bug_report.html">Bug Report
+ Page</a>.</p>
+
+ <p>In addition to the problems described above there are
+ problems with many libraries that Apache uses. The most common
+ example is the bind DNS resolver library that is used by pretty
+ much every unix, which fails if it ends up with a descriptor
+ above 256. We suspect there are other libraries that similar
+ limitations. So the code as of 1.2.1 takes a defensive stance
+ and tries to save descriptors less than 16 for use while
+ processing each request. This is called the <em>low slack
+ line</em>.</p>
+
+ <p>Note that this shouldn't waste descriptors. If you really
+ are pushing the limits and Apache can't get a descriptor above
+ 16 when it wants it, it will settle for one below 16.</p>
+
+ <p>In extreme situations you may want to lower the low slack
+ line, but you shouldn't ever need to. For example, lowering it
+ can increase the limits 240 described above under Solaris and
+ BSDI 2.0. But you'll play a delicate balancing game with the
+ descriptors needed to serve a request. Should you want to play
+ this game, the compile time parameter is
+ <code>LOW_SLACK_LINE</code> and there's a tiny bit of
+ documentation in the header file <code>httpd.h</code>.</p>
+
+ <p>Finally, if you suspect that all this slack stuff is causing
+ you problems, you can disable it. Add <code>-DNO_SLACK</code>
+ to <code>EXTRA_CFLAGS</code> and rebuild. But please report it
+ to our <a href="http://httpd.apache.org/bug_report.html">Bug
+ Report Page</a> so that we can investigate. </p>
+
+ </section>
+
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+ <relativepath href=".." />
+ <parentdocument href="./">Miscellaneous Documentation</parentdocument>
+
+ <title>Connections in the FIN_WAIT_2 state and Apache</title>
+
+ <summary>
+
+ <note type="warning"><title>Warning:</title>
+ <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>
+ </note>
+
+ <p>Starting with the Apache 1.2 betas, people are reporting
+ many more connections in the FIN_WAIT_2 state (as reported
+ by <code>netstat</code>) than they saw using older
+ versions. When the server closes a TCP connection, it sends
+ a packet with the FIN bit set to the client, which then
+ responds with a packet with the ACK bit set. The client
+ then sends a packet with the FIN bit set to the server,
+ which responds with an ACK and the connection is closed.
+ The state that the connection is in during the period
+ between when the server gets the ACK from the client and
+ the server gets the FIN from the client is known as
+ FIN_WAIT_2. See the <a
+ href="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</a> for
+ the technical details of the state transitions.</p>
+
+ <p>The FIN_WAIT_2 state is somewhat unusual in that there
+ is no timeout defined in the standard for it. This means
+ that on many operating systems, a connection in the
+ FIN_WAIT_2 state will stay around until the system is
+ rebooted. If the system does not have a timeout and too
+ many FIN_WAIT_2 connections build up, it can fill up the
+ space allocated for storing information about the
+ connections and crash the kernel. The connections in
+ FIN_WAIT_2 do not tie up an httpd process.</p>
+
+ </summary>
+
+ <section id="why"><title>Why Does It Happen?</title>
+
+ <p>There are numerous reasons for it happening, some of them
+ may not yet be fully clear. What is known follows.</p>
+
+ <section id="buggy"><title>Buggy Clients and Persistent
+ Connections</title>
+
+ <p>Several clients have a bug which pops up when dealing with
+ persistent connections (aka
+ keepalives). When the connection is idle and the server
+ closes the connection (based on the <directive
+ module="core">KeepAliveTimeout</directive>),
+ the client is programmed so that the client does not send
+ back a FIN and ACK to the server. This means that the
+ connection stays in the FIN_WAIT_2 state until one of the
+ following happens:</p>
+
+ <ul>
+ <li>The client opens a new connection to the same or a
+ different site, which causes it to fully close the older
+ connection on that socket.</li>
+
+ <li>The user exits the client, which on some (most?)
+ clients causes the OS to fully shutdown the
+ connection.</li>
+
+ <li>The FIN_WAIT_2 times out, on servers that have a
+ timeout for this state.</li>
+ </ul>
+
+ <p>If you are lucky, this means that the buggy client will
+ fully close the connection and release the resources on
+ your server. However, there are some cases where the socket
+ is never fully closed, such as a dialup client
+ disconnecting from their provider before closing the
+ client. In addition, a client might sit idle for days
+ without making another connection, and thus may hold its
+ end of the socket open for days even though it has no
+ further use for it. <strong>This is a bug in the browser or
+ in its operating system's TCP implementation.</strong></p>
+
+ <p>The clients on which this problem has been verified to
+ exist:</p>
+
+ <ul>
+ <li>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE
+ i386)</li>
+
+ <li>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE
+ i386)</li>
+
+ <li>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)</li>
+
+ <li>MSIE 3.01 on the Macintosh</li>
+
+ <li>MSIE 3.01 on Windows 95</li>
+ </ul>
+
+ <p>This does not appear to be a problem on:</p>
+
+ <ul>
+ <li>Mozilla/3.01 (Win95; I)</li>
+ </ul>
+
+ <p>It is expected that many other clients have the same
+ problem. What a client <strong>should do</strong> is
+ periodically check its open socket(s) to see if they have
+ been closed by the server, and close their side of the
+ connection if the server has closed. This check need only
+ occur once every few seconds, and may even be detected by a
+ OS signal on some systems (<em>e.g.</em>, Win95 and NT
+ clients have this capability, but they seem to be ignoring
+ it).</p>
+
+ <p>Apache <strong>cannot</strong> avoid these FIN_WAIT_2
+ states unless it disables persistent connections for the
+ buggy clients, just like we recommend doing for Navigator
+ 2.x clients due to other bugs. However, non-persistent
+ connections increase the total number of connections needed
+ per client and slow retrieval of an image-laden web page.
+ Since non-persistent connections have their own resource
+ consumptions and a short waiting period after each closure,
+ a busy server may need persistence in order to best serve
+ its clients.</p>
+
+ <p>As far as we know, the client-caused FIN_WAIT_2 problem
+ is present for all servers that support persistent
+ connections, including Apache 1.1.x and 1.2.</p>
+
+ </section>
+
+ <section id="code"><title>A necessary bit of code
+ introduced in 1.2</title>
+
+ <p>While the above bug is a problem, it is not the whole
+ problem. Some users have observed no FIN_WAIT_2 problems
+ with Apache 1.1.x, but with 1.2b enough connections build
+ up in the FIN_WAIT_2 state to crash their server. The most
+ likely source for additional FIN_WAIT_2 states is a
+ function called <code>lingering_close()</code> which was
+ added between 1.1 and 1.2. This function is necessary for
+ the proper handling of persistent connections and any
+ request which includes content in the message body
+ (<em>e.g.</em>, PUTs and POSTs). What it does is read any
+ data sent by the client for a certain time after the server
+ closes the connection. The exact reasons for doing this are
+ somewhat complicated, but involve what happens if the
+ client is making a request at the same time the server
+ sends a response and closes the connection. Without
+ lingering, the client might be forced to reset its TCP
+ input buffer before it has a chance to read the server's
+ response, and thus understand why the connection has
+ closed. See the <a href="#appendix">appendix</a> for more
+ details.</p>
+
+ <p>The code in <code>lingering_close()</code> appears to
+ cause problems for a number of factors, including the
+ change in traffic patterns that it causes. The code has
+ been thoroughly reviewed and we are not aware of any bugs
+ in it. It is possible that there is some problem in the BSD
+ TCP stack, aside from the lack of a timeout for the
+ FIN_WAIT_2 state, exposed by the
+ <code>lingering_close</code> code that causes the observed
+ problems.</p>
+
+ </section>
+ </section>
+
+ <section id="what"><title>What Can I Do About it?</title>
+
+ <p>There are several possible workarounds to the problem, some
+ of which work better than others.</p>
+
+ <section id="add_timeout"><title>Add a timeout for FIN_WAIT_2</title>
+
+ <p>The obvious workaround is to simply have a timeout for the
+ FIN_WAIT_2 state. This is not specified by the RFC, and
+ could be claimed to be a violation of the RFC, but it is
+ widely recognized as being necessary. The following systems
+ are known to have a timeout:</p>
+
+ <ul>
+ <li><a href="http://www.freebsd.org/">FreeBSD</a>
+ versions starting at 2.0 or possibly earlier.</li>
+
+ <li><a href="http://www.netbsd.org/">NetBSD</a> version
+ 1.2(?)</li>
+
+ <li><a href="http://www.openbsd.org/">OpenBSD</a> all
+ versions(?)</li>
+
+ <li><a href="http://www.bsdi.com/">BSD/OS</a> 2.1, with
+ the <a
+ href="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027">
+ K210-027</a> patch installed.</li>
+
+ <li><a href="http://www.sun.com/">Solaris</a> as of
+ around version 2.2. The timeout can be tuned by using
+ <code>ndd</code> to modify
+ <code>tcp_fin_wait_2_flush_interval</code>, but the
+ default should be appropriate for most servers and
+ improper tuning can have negative impacts.</li>
+
+ <li><a href="http://www.linux.org/">Linux</a> 2.0.x and
+ earlier(?)</li>
+
+ <li><a href="http://www.hp.com/">HP-UX</a> 10.x defaults
+ to terminating connections in the FIN_WAIT_2 state after
+ the normal keepalive timeouts. This does not refer to the
+ persistent connection or HTTP keepalive timeouts, but the
+ <code>SO_LINGER</code> socket option which is enabled by
+ Apache. This parameter can be adjusted by using
+ <code>nettune</code> to modify parameters such as
+ <code>tcp_keepstart</code> and <code>tcp_keepstop</code>.
+ In later revisions, there is an explicit timer for
+ connections in FIN_WAIT_2 that can be modified; contact
+ HP support for details.</li>
+
+ <li><a href="http://www.sgi.com/">SGI IRIX</a> can be
+ patched to support a timeout. For IRIX 5.3, 6.2, and 6.3,
+ use patches 1654, 1703 and 1778 respectively. If you have
+ trouble locating these patches, please contact your SGI
+ support channel for help.</li>
+
+ <li><a href="http://www.ncr.com/">NCR's MP RAS Unix</a>
+ 2.xx and 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it
+ is non-tunable at 600 seconds, while in 3.xx it defaults
+ to 600 seconds and is calculated based on the tunable
+ "max keep alive probes" (default of 8) multiplied by the
+ "keep alive interval" (default 75 seconds).</li>
+
+ <li><a href="http://www.sequent.com">Sequent's ptx/TCP/IP
+ for DYNIX/ptx</a> has had a FIN_WAIT_2 timeout since
+ around release 4.1 in mid-1994.</li>
+ </ul>
+
+ <p>The following systems are known to not have a
+ timeout:</p>
+
+ <ul>
+ <li><a href="http://www.sun.com/">SunOS 4.x</a> does not
+ and almost certainly never will have one because it as at
+ the very end of its development cycle for Sun. If you
+ have kernel source should be easy to patch.</li>
+ </ul>
+
+ <p>There is a <a
+ href="http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch">
+ patch available</a> for adding a timeout to the FIN_WAIT_2
+ state; it was originally intended for BSD/OS, but should be
+ adaptable to most systems using BSD networking code. You
+ need kernel source code to be able to use it.</p>
+
+ </section>
+
+ <section id="no_lingering"><title>Compile without using
+ <code>lingering_close()</code></title>
+
+ <p>It is possible to compile Apache 1.2 without using the
+ <code>lingering_close()</code> function. This will result
+ in that section of code being similar to that which was in
+ 1.1. If you do this, be aware that it can cause problems
+ with PUTs, POSTs and persistent connections, especially if
+ the client uses pipelining. That said, it is no worse than
+ on 1.1, and we understand that keeping your server running
+ is quite important.</p>
+
+ <p>To compile without the <code>lingering_close()</code>
+ function, add <code>-DNO_LINGCLOSE</code> to the end of the
+ <code>EXTRA_CFLAGS</code> line in your
+ <code>Configuration</code> file, rerun
+ <code>Configure</code> and rebuild the server.</p>
+
+ </section>
+
+ <section id="so_linger"><title>Use <code>SO_LINGER</code> as
+ an alternative to <code>lingering_close()</code></title>
+
+ <p>On most systems, there is an option called
+ <code>SO_LINGER</code> that can be set with
+ <code>setsockopt(2)</code>. It does something very similar
+ to <code>lingering_close()</code>, except that it is broken
+ on many systems so that it causes far more problems than
+ <code>lingering_close</code>. On some systems, it could
+ possibly work better so it may be worth a try if you have
+ no other alternatives.</p>
+
+ <p>To try it, add <code>-DUSE_SO_LINGER
+ -DNO_LINGCLOSE</code> to the end of the
+ <code>EXTRA_CFLAGS</code> line in your
+ <code>Configuration</code> file, rerun
+ <code>Configure</code> and rebuild the server.</p>
+
+ <note><title>NOTE</title>Attempting to use
+ <code>SO_LINGER</code> and <code>lingering_close()</code>
+ at the same time is very likely to do very bad things, so
+ don't.</note>
+
+ </section>
+
+ <section id="increase_mem"><title>Increase the amount of memory
+ used for storing connection state</title>
+
+ <dl>
+ <dt>BSD based networking code:</dt>
+
+ <dd>
+ BSD stores network data, such as connection states, in
+ something called an mbuf. When you get so many
+ connections that the kernel does not have enough mbufs
+ to put them all in, your kernel will likely crash. You
+ can reduce the effects of the problem by increasing the
+ number of mbufs that are available; this will not
+ prevent the problem, it will just make the server go
+ longer before crashing.
+
+ <p>The exact way to increase them may depend on your
+ OS; look for some reference to the number of "mbufs" or
+ "mbuf clusters". On many systems, this can be done by
+ adding the line <code>NMBCLUSTERS="n"</code>, where
+ <code>n</code> is the number of mbuf clusters you want
+ to your kernel config file and rebuilding your
+ kernel.</p>
+ </dd>
+ </dl>
+
+ </section>
+
+ <section id="disable"><title>Disable KeepAlive</title>
+
+ <p>If you are unable to do any of the above then you
+ should, as a last resort, disable KeepAlive. Edit your
+ httpd.conf and change "KeepAlive On" to "KeepAlive
+ Off".</p>
+
+ </section>
+ </section>
+
+ <section id="appendix"><title>Appendix</title>
+
+ <p>Below is a message from Roy Fielding, one of the authors
+ of HTTP/1.1.</p>
+
+ <section id="message"><title>Why the lingering close
+ functionality is necessary with HTTP</title>
+
+ <p>The need for a server to linger on a socket after a close
+ is noted a couple times in the HTTP specs, but not
+ explained. This explanation is based on discussions between
+ myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and
+ John C. Mallery in the hallways of MIT while I was at W3C.</p>
+
+ <p>If a server closes the input side of the connection
+ while the client is sending data (or is planning to send
+ data), then the server's TCP stack will signal an RST
+ (reset) back to the client. Upon receipt of the RST, the
+ client will flush its own incoming TCP buffer back to the
+ un-ACKed packet indicated by the RST packet argument. If
+ the server has sent a message, usually an error response,
+ to the client just before the close, and the client
+ receives the RST packet before its application code has
+ read the error message from its incoming TCP buffer and
+ before the server has received the ACK sent by the client
+ upon receipt of that buffer, then the RST will flush the
+ error message before the client application has a chance to
+ see it. The result is that the client is left thinking that
+ the connection failed for no apparent reason.</p>
+
+ <p>There are two conditions under which this is likely to
+ occur:</p>
+
+ <ol>
+ <li>sending POST or PUT data without proper
+ authorization</li>
+
+ <li>sending multiple requests before each response
+ (pipelining) and one of the middle requests resulting in
+ an error or other break-the-connection result.</li>
+ </ol>
+
+ <p>The solution in all cases is to send the response, close
+ only the write half of the connection (what shutdown is
+ supposed to do), and continue reading on the socket until
+ it is either closed by the client (signifying it has
+ finally read the response) or a timeout occurs. That is
+ what the kernel is supposed to do if SO_LINGER is set.
+ Unfortunately, SO_LINGER has no effect on some systems; on
+ some other systems, it does not have its own timeout and
+ thus the TCP memory segments just pile-up until the next
+ reboot (planned or not).</p>
+
+ <p>Please note that simply removing the linger code will
+ not solve the problem -- it only moves it to a different
+ and much harder one to detect.</p>
+ </section>
+ </section>
+</manualpage>
<p>Below is a list of additional documentation pages that apply
to the Apache web server development project.</p>
+ <div class="warning"><h3>Warning</h3>
+ <p>Some of the documents below have 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>
+
<dl>
<dt><a href="custom_errordocs.html">How to use XSSI and
Negotiation for custom ErrorDocuments</a></dt>
Apache for highest performance. Notes explaining why Apache
does some things, and why it doesn't do other things (which
make it slower/faster).</p>
-
- <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>
-
</dd>
<dt><a href="security_tips.html">Security Tips</a></dt>
to solve typical URL-based problems webmasters are usually confronted
with in practice.</p>
</dd>
- </dl>
+ <dt><a href="tutorials.html">Apache Tutorials</a></dt>
+
+ <dd>
+ <p>A list of external resources which help to accomplish common
+ tasks with the Apache HTTP server.</p>
+ </dd>
+ </dl>
</div>
</div>
<div id="footer">
<p>Below is a list of additional documentation pages that apply
to the Apache web server development project.</p>
+ <note type="warning"><title>Warning</title>
+ <p>Some of the documents below have 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>
+ </note>
+
<dl>
<dt><a href="custom_errordocs.html">How to use XSSI and
Negotiation for custom ErrorDocuments</a></dt>
Apache for highest performance. Notes explaining why Apache
does some things, and why it doesn't do other things (which
make it slower/faster).</p>
-
- <note type="warning"><title>Warning</title>
- <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>
- </note>
-
</dd>
<dt><a href="security_tips.html">Security Tips</a></dt>
to solve typical URL-based problems webmasters are usually confronted
with in practice.</p>
</dd>
- </dl>
+ <dt><a href="tutorials.html">Apache Tutorials</a></dt>
+
+ <dd>
+ <p>A list of external resources which help to accomplish common
+ tasks with the Apache HTTP server.</p>
+ </dd>
+ </dl>
</summary>
</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+ <relativepath href=".." />
+ <parentdocument href="./">Miscellaneous Documentation</parentdocument>
+
+ <title>Known Problems in Clients</title>
+
+ <summary>
+
+ <note type="warning"><title>Warning:</title>
+ <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>
+ </note>
+
+ <p>Over time the Apache Group has discovered or been notified
+ of problems with various clients which we have had to work
+ around, or explain. This document describes these problems and
+ the workarounds available. It's not arranged in any particular
+ order. Some familiarity with the standards is assumed, but not
+ necessary.</p>
+
+ <p>For brevity, <em>Navigator</em> will refer to Netscape's
+ Navigator product (which in later versions was renamed
+ "Communicator" and various other names), and <em>MSIE</em> will
+ refer to Microsoft's Internet Explorer product. All trademarks
+ and copyrights belong to their respective companies. We welcome
+ input from the various client authors to correct
+ inconsistencies in this paper, or to provide us with exact
+ version numbers where things are broken/fixed.</p>
+
+ <p>For reference, <a
+ href="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</a>
+ defines HTTP/1.0, and <a
+ href="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</a>
+ defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1
+ server (with an optional HTTP/1.0 proxy).</p>
+
+ <p>Various of these workarounds are triggered by environment
+ variables. The admin typically controls which are set, and for
+ which clients, by using <code>mod_browser</code>. Unless
+ otherwise noted all of these workarounds exist in versions 1.2
+ and later.</p>
+
+ </summary>
+
+ <section id="trailing-crlf"><title>Trailing CRLF on POSTs</title>
+
+ <p>This is a legacy issue. The CERN webserver required
+ <code>POST</code> data to have an extra <code>CRLF</code>
+ following it. Thus many clients send an extra <code>CRLF</code>
+ that is not included in the <code>Content-Length</code> of the
+ request. Apache works around this problem by eating any empty
+ lines which appear before a request.</p>
+
+ </section>
+
+ <section id="broken-keepalive"><title>Broken KeepAlive</title>
+
+ <p>Various clients have had broken implementations of
+ <em>keepalive</em> (persistent connections). In particular the
+ Windows versions of Navigator 2.0 get very confused when the
+ server times out an idle connection. The workaround is present
+ in the default config files:</p>
+
+ <example>
+ BrowserMatch Mozilla/2 nokeepalive
+ </example>
+
+ <p>Note that this matches some earlier versions of MSIE, which
+ began the practice of calling themselves <em>Mozilla</em> in
+ their user-agent strings just like Navigator.</p>
+
+ <p>MSIE 4.0b2, which claims to support HTTP/1.1, does not
+ properly support keepalive when it is used on 301 or 302
+ (redirect) responses. Unfortunately Apache's
+ <code>nokeepalive</code> code prior to 1.2.2 would not work
+ with HTTP/1.1 clients. You must apply <a
+ href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
+ this patch</a> to version 1.2.1. Then add this to your
+ config:</p>
+
+ <example>
+ BrowserMatch "MSIE 4\.0b2;" nokeepalive
+ </example>
+
+ </section>
+
+ <section id="force-response-1.0"><title>Incorrect interpretation of
+ <code>HTTP/1.1</code> in response</title>
+
+ <p>To quote from section 3.1 of RFC1945:</p>
+
+ <note>
+ HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to
+ indicate versions of the protocol. The protocol versioning
+ policy is intended to allow the sender to indicate the format
+ of a message and its capacity for understanding further HTTP
+ communication, rather than the features obtained via that
+ communication.
+ </note>
+
+ <p>Since Apache is an HTTP/1.1 server, it indicates so as part of
+ its response. Many client authors mistakenly treat this part of
+ the response as an indication of the protocol that the response
+ is in, and then refuse to accept the response.</p>
+
+ <p>The first major indication of this problem was with AOL's
+ proxy servers. When Apache 1.2 went into beta it was the first
+ wide-spread HTTP/1.1 server. After some discussion, AOL fixed
+ their proxies. In anticipation of similar problems, the
+ <code>force-response-1.0</code> environment variable was added
+ to Apache. When present Apache will indicate "HTTP/1.0" in
+ response to an HTTP/1.0 client, but will not in any other way
+ change the response.</p>
+
+ <p>The pre-1.1 Java Development Kit (JDK) that is used in many
+ clients (including Navigator 3.x and MSIE 3.x) exhibits this
+ problem. As do some of the early pre-releases of the 1.1 JDK.
+ We think it is fixed in the 1.1 JDK release. In any event the
+ workaround:</p>
+
+ <example>
+ BrowserMatch Java/1.0 force-response-1.0<br />
+ BrowserMatch JDK/1.0 force-response-1.0
+ </example>
+
+ <p>RealPlayer 4.0 from Progressive Networks also exhibits this
+ problem. However they have fixed it in version 4.01 of the
+ player, but version 4.01 uses the same <code>User-Agent</code>
+ as version 4.0. The workaround is still:</p>
+
+ <example>
+ BrowserMatch "RealPlayer 4.0" force-response-1.0
+ </example>
+
+ </section>
+
+ <section id="msie4.0b2"><title>Requests use HTTP/1.1 but
+ responses must be in HTTP/1.0</title>
+
+ <p>MSIE 4.0b2 has this problem. Its Java VM makes requests in
+ HTTP/1.1 format but the responses must be in HTTP/1.0 format
+ (in particular, it does not understand <em>chunked</em>
+ responses). The workaround is to fool Apache into believing the
+ request came in HTTP/1.0 format.</p>
+
+ <example>
+ BrowserMatch "MSIE 4\.0b2;" downgrade-1.0
+ force-response-1.0
+ </example>
+
+ <p>This workaround is available in 1.2.2, and in a <a
+ href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
+ patch</a> against 1.2.1.</p>
+
+ </section>
+
+ <section id="byte-257"><title>Boundary problems with
+ header parsing</title>
+
+ <p>All versions of Navigator from 2.0 through 4.0b2 (and
+ possibly later) have a problem if the trailing CRLF of the
+ response header starts at offset 256, 257 or 258 of the
+ response. A BrowserMatch for this would match on nearly every
+ hit, so the workaround is enabled automatically on all
+ responses. The workaround implemented detects when this
+ condition would occur in a response and adds extra padding to
+ the header to push the trailing CRLF past offset 258 of the
+ response.</p>
+
+ </section>
+
+ <section id="boundary-string"><title>Multipart responses and
+ Quoted Boundary Strings</title>
+
+ <p>On multipart responses some clients will not accept quotes
+ (") around the boundary string. The MIME standard recommends
+ that such quotes be used. But the clients were probably written
+ based on one of the examples in RFC2068, which does not include
+ quotes. Apache does not include quotes on its boundary strings
+ to workaround this problem.</p>
+
+ </section>
+
+ <section id="byterange-requests"><title>Byterange Requests</title>
+
+ <p>A byterange request is used when the client wishes to
+ retrieve a portion of an object, not necessarily the entire
+ object. There was a very old draft which included these
+ byteranges in the URL. Old clients such as Navigator 2.0b1 and
+ MSIE 3.0 for the MAC exhibit this behaviour, and it will appear
+ in the servers' access logs as (failed) attempts to retrieve a
+ URL with a trailing ";xxx-yyy". Apache does not attempt to
+ implement this at all.</p>
+
+ <p>A subsequent draft of this standard defines a header
+ <code>Request-Range</code>, and a response type
+ <code>multipart/x-byteranges</code>. The HTTP/1.1 standard
+ includes this draft with a few fixes, and it defines the header
+ <code>Range</code> and type
+ <code>multipart/byteranges</code>.</p>
+
+ <p>Navigator (versions 2 and 3) sends both <code>Range</code>
+ and <code>Request-Range</code> headers (with the same value),
+ but does not accept a <code>multipart/byteranges</code>
+ response. The response must be
+ <code>multipart/x-byteranges</code>. As a workaround, if Apache
+ receives a <code>Request-Range</code> header it considers it
+ "higher priority" than a <code>Range</code> header and in
+ response uses <code>multipart/x-byteranges</code>.</p>
+
+ <p>The Adobe Acrobat Reader plugin makes extensive use of
+ byteranges and prior to version 3.01 supports only the
+ <code>multipart/x-byterange</code> response. Unfortunately
+ there is no clue that it is the plugin making the request. If
+ the plugin is used with Navigator, the above workaround works
+ fine. But if the plugin is used with MSIE 3 (on Windows) the
+ workaround won't work because MSIE 3 doesn't give the
+ <code>Range-Request</code> clue that Navigator does. To
+ workaround this, Apache special cases "MSIE 3" in the
+ <code>User-Agent</code> and serves
+ <code>multipart/x-byteranges</code>. Note that the necessity
+ for this with MSIE 3 is actually due to the Acrobat plugin, not
+ due to the browser.</p>
+
+ <p>Netscape Communicator appears to not issue the non-standard
+ <code>Request-Range</code> header. When an Acrobat plugin prior
+ to version 3.01 is used with it, it will not properly
+ understand byteranges. The user must upgrade their Acrobat
+ reader to 3.01.</p>
+
+ </section>
+
+ <section id="cookie-merge"><title><code>Set-Cookie</code> header is
+ unmergeable</title>
+
+ <p>The HTTP specifications say that it is legal to merge
+ headers with duplicate names into one (separated by commas).
+ Some browsers that support Cookies don't like merged headers
+ and prefer that each <code>Set-Cookie</code> header is sent
+ separately. When parsing the headers returned by a CGI, Apache
+ will explicitly avoid merging any <code>Set-Cookie</code>
+ headers.</p>
+
+ </section>
+
+ <section id="gif89-expires"><title><code>Expires</code> headers
+ and GIF89A animations</title>
+
+ <p>Navigator versions 2 through 4 will erroneously re-request
+ GIF89A animations on each loop of the animation if the first
+ response included an <code>Expires</code> header. This happens
+ regardless of how far in the future the expiry time is set.
+ There is no workaround supplied with Apache, however there are
+ hacks for <a
+ href="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">
+ 1.2</a> and for <a
+ href="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">
+ 1.3</a>.</p>
+
+ </section>
+
+ <section id="no-content-length"><title><code>POST</code> without
+ <code>Content-Length</code></title>
+
+ <p>In certain situations Navigator 3.01 through 3.03 appear to
+ incorrectly issue a POST without the request body. There is no
+ known workaround. It has been fixed in Navigator 3.04,
+ Netscapes provides some <a
+ href="http://help.netscape.com/kb/client/971014-42.html">information</a>.
+ There's also <a
+ href="http://www.arctic.org/~dgaudet/apache/no-content-length/">
+ some information</a> about the actual problem.</p>
+
+ </section>
+
+ <section id="jdk-12-bugs"><title>JDK 1.2 betas lose
+ parts of responses.</title>
+
+ <p>The http client in the JDK1.2beta2 and beta3 will throw away
+ the first part of the response body when both the headers and
+ the first part of the body are sent in the same network packet
+ AND keep-alive's are being used. If either condition is not met
+ then it works fine.</p>
+
+ <p>See also Bug-ID's 4124329 and 4125538 at the java developer
+ connection.</p>
+
+ <p>If you are seeing this bug yourself, you can add the
+ following BrowserMatch directive to work around it:</p>
+
+ <example>
+ BrowserMatch "Java1\.2beta[23]" nokeepalive
+ </example>
+
+ <p>We don't advocate this though since bending over backwards
+ for beta software is usually not a good idea; ideally it gets
+ fixed, new betas or a final release comes out, and no one uses
+ the broken old software anymore. In theory.</p>
+
+ </section>
+
+ <section id="content-type-persistent"><title><code>Content-Type</code>
+ change is not noticed after reload</title>
+
+ <p>Navigator (all versions?) will cache the
+ <code>content-type</code> for an object "forever". Using reload
+ or shift-reload will not cause Navigator to notice a
+ <code>content-type</code> change. The only work-around is for
+ the user to flush their caches (memory and disk). By way of an
+ example, some folks may be using an old <code>mime.types</code>
+ file which does not map <code>.htm</code> to
+ <code>text/html</code>, in this case Apache will default to
+ sending <code>text/plain</code>. If the user requests the page
+ and it is served as <code>text/plain</code>. After the admin
+ fixes the server, the user will have to flush their caches
+ before the object will be shown with the correct
+ <code>text/html</code> type.</p>
+
+ </section>
+
+ <section id="msie-cookie-y2k"><title>MSIE Cookie
+ problem with expiry date in the year 2000</title>
+
+ <p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not
+ handle cookie expiry dates in the year 2000 properly. Years
+ after 2000 and before 2000 work fine. This is fixed in IE4.01
+ service pack 1, and in the Y2K patch for IE3.02. Users should
+ avoid using expiry dates in the year 2000.</p>
+
+ </section>
+
+ <section id="lynx-negotiate-trans"><title>Lynx incorrectly asking for
+ transparent content negotiation</title>
+
+ <p>The Lynx browser versions 2.7 and 2.8 send a "negotiate:
+ trans" header in their requests, which is an indication the
+ browser supports transparent content negotiation (TCN). However
+ the browser does not support TCN. As of version 1.3.4, Apache
+ supports TCN, and this causes problems with these versions of
+ Lynx. As a workaround future versions of Apache will ignore
+ this header when sent by the Lynx client.</p>
+
+ </section>
+
+ <section id="ie40-vary"><title>MSIE 4.0 mishandles Vary
+ response header</title>
+
+ <p>MSIE 4.0 does not handle a Vary header properly. The Vary
+ header is generated by mod_rewrite in apache 1.3. The result is
+ an error from MSIE saying it cannot download the requested
+ file. There are more details in <a
+ href="http://bugs.apache.org/index/full/4118">PR#4118</a>.</p>
+
+ <p>A workaround is to add the following to your server's
+ configuration files:</p>
+
+ <example>
+ BrowserMatch "MSIE 4\.0" force-no-vary
+ </example>
+
+ <p>(This workaround is only available with releases
+ <strong>after</strong> 1.3.6 of the Apache Web server.)</p>
+
+ </section>
+</manualpage>
--- /dev/null
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+ <relativepath href=".."/>
+ <parentdocument href="./">Miscellaneous Documentation</parentdocument>
+ <title>Apache Tutorials</title>
+
+ <summary>
+
+ <note type="warning"><title>Warning:</title>
+ <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>
+ </note>
+
+ <p>The following documents give you step-by-step instructions
+ on how to accomplish common tasks with the Apache HTTP server.
+ Many of these documents are located at external sites and are
+ not the work of the Apache Software Foundation. Copyright to
+ documents on external sites is owned by the authors or their
+ assignees. Please consult the <a href="../">official Apache
+ Server documentation</a> to verify what you read on external
+ sites.</p>
+
+ </summary>
+
+ <section id="starting">
+
+ <title>Installation & Getting Started</title>
+
+ <ul>
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF">
+ Getting Started with Apache 1.3</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW">
+ Configuring Your Apache Server Installation</a>
+ (ApacheToday)</li>
+
+ <li><a
+ href="http://www.onlamp.com/pub/a/apache/2000/02/24/installing_apache.html">
+ Getting, Installing, and Running Apache (on Unix)</a>
+ (O'Reilly Network Apache DevCenter)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/Apache/ss01.html">Maximum
+ Apache: Getting Started</a> (CNET Builder.com)</li>
+
+ <li><a
+ href="http://www.devshed.com/Server_Side/Administration/APACHE/">
+ How to Build the Apache of Your Dreams</a> (Developer
+ Shed)</li>
+ </ul>
+ </section>
+
+ <section id="basics">
+
+ <title>Basic Configuration</title>
+
+ <ul>
+ <li><a
+ href="http://www.onlamp.com/pub/a/apache/2000/03/02/configuring_apache.html">
+ An Amble Through Apache Configuration</a> (O'Reilly Network
+ Apache DevCenter)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-19-002-01-NW-LF-SW">
+ Using .htaccess Files with Apache</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS">
+ Setting Up Virtual Hosts</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/Apache/ss02.html">Maximum
+ Apache: Configure Apache</a> (CNET Builder.com)</li>
+
+ <li><a
+ href="http://www.devshed.com/Server_Side/Administration/MoreApache/">
+ Getting More Out of Apache</a> (Developer Shed)</li>
+ </ul>
+ </section>
+
+ <section id="security">
+
+ <title>Security</title>
+
+ <ul>
+ <li><a
+ href="http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/">
+ Security and Apache: An Essential Primer</a>
+ (LinuxPlanet)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/userauth">Using User
+ Authentication</a> (Apacheweek)</li>
+
+ <li><a href="http://www.apacheweek.com/features/dbmauth">DBM
+ User Authentication</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://linux.com/security/newsitem.phtml?sid=12&aid=3549">
+ An Introduction to Securing Apache</a> (Linux.com)</li>
+
+ <li><a
+ href="http://linux.com/security/newsitem.phtml?sid=12&aid=3667">
+ Securing Apache - Access Control</a> (Linux.com)</li>
+
+ <li>Apache Authentication <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-24-002-01-NW-LF-SW">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF">
+ Part 2</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-07-001-01-NW-LF-SW">
+ Part 3</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-14-001-01-NW-LF-SW">
+ Part 4</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW">
+ mod_access: Restricting Access by Host</a> (ApacheToday)</li>
+ </ul>
+ </section>
+
+ <section id="logging">
+
+ <title>Logging</title>
+
+ <ul>
+ <li><a
+ href="http://www.onlamp.com/pub/a/apache/2000/03/10/log_rhythms.html">
+ Log Rhythms</a> (O'Reilly Network Apache DevCenter)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/logfiles">Gathering
+ Visitor Information: Customising Your Logfiles</a>
+ (Apacheweek)</li>
+
+ <li>Apache Guide: Logging <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-21-003-01-NW-LF-SW">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-28-001-01-NW-LF-SW">
+ Part 2</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-05-001-01-NW-LF-SW">
+ Part 3</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-18-003-01-NW-LF-SW">
+ Part 4</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-25-001-01-NW-LF-SW">
+ Part 5</a> (ApacheToday)</li>
+ </ul>
+ </section>
+
+ <section id="cgi_ssi">
+
+ <title>CGI and SSI</title>
+
+ <ul>
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-05-001-10-NW-LF-SW">
+ Dynamic Content with CGI</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.cpan.org/doc/FAQs/cgi/idiots-guide.html">
+ The Idiot's Guide to Solving Perl CGI Problems</a>
+ (CPAN)</li>
+
+ <li><a
+ href="http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/">
+ Executing CGI Scripts as Other Users</a> (LinuxPlanet)</li>
+
+ <li><a href="http://www.htmlhelp.org/faq/cgifaq.html">CGI
+ Programming FAQ</a> (Web Design Group)</li>
+
+ <li>Introduction to Server Side Includes <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-12-001-01-PS">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-19-002-01-NW-LF-SW">
+ Part 2</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-26-001-01-NW-LF-SW">
+ Advanced SSI Techniques</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/ApacheFiles/082400/">Setting
+ up CGI and SSI with Apache</a> (CNET Builder.com)</li>
+ </ul>
+ </section>
+
+ <section id="other">
+
+ <title>Other Features</title>
+
+ <ul>
+ <li><a
+ href="http://www.apacheweek.com/features/negotiation">Content
+ Negotiation Explained</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/imagemaps">Using
+ Apache Imagemaps</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
+ Keeping Your Images from Adorning Other Sites</a>
+ (ApacheToday)</li>
+
+ <li><a
+ href="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html">Language
+ Negotiation Notes</a> (Alan J. Flavell)</li>
+ </ul>
+
+ <p>If you have a pointer to an accurate and well-written
+ tutorial not included here, please let us know by submitting it
+ to the <a href="http://bugs.apache.org/">Apache Bug
+ Database</a>.</p>
+ </section>
+
+</manualpage>
+
projects / thirdparty / apache / httpd.git / commitdiff
