+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>International Customized Server Error Messages</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Using XSSI and <samp>ErrorDocument</samp> to
- configure customized international server error responses</h1>
-
- <h2>Index</h2>
-
- <ul>
- <li><a href="#intro">Introduction</a></li>
-
- <li><a href="#createdir">Creating an ErrorDocument
- directory</a></li>
-
- <li><a href="#docnames">Naming the individual error document
- files</a></li>
-
- <li><a href="#headfoot">The common header and footer
- files</a></li>
-
- <li><a href="#createdocs">Creating ErrorDocuments in
- different languages</a></li>
-
- <li><a href="#fallback">The fallback language</a></li>
-
- <li><a href="#proxy">Customizing Proxy Error
- Messages</a></li>
-
- <li><a href="#listings">HTML listing of the discussed
- example</a></li>
- </ul>
- <hr />
-
- <h2><a id="intro" name="intro">Introduction</a></h2>
- This document describes an easy way to provide your apache WWW
- server with a set of customized error messages which take
- advantage of <a href="../content-negotiation.html">Content
- Negotiation</a> and <a href="../mod/mod_include.html">eXtended
- Server Side Includes (XSSI)</a> to return error messages
- generated by the server in the client's native language. <br />
- <br />
-
-
- <p>By using XSSI, all <a
- href="../mod/core.html#errordocument">customized messages</a>
- 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.<br />
- 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>
- <br />
- <br />
-
-
- <p>An example of a "document not found" message for a german
- client might look like this:<br />
- <img src="../images/custom_errordocs.gif"
- alt="[Needs graphics capability to display]" /><br />
- 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", <em>i.e.</em>, when the error actually occurs.</p>
-
- <h2><a id="createdir" name="createdir">Creating an
- ErrorDocument directory</a></h2>
- For this concept to work as easily as possible, we must take
- advantage of as much server support as we can get:
-
- <ol>
- <li>By defining the <a
- href="../mod/core.html#options">MultiViews option</a>, we
- enable the language selection of the most appropriate
- language alternative (content negotiation).</li>
-
- <li>By setting the <a
- href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a>
- 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 <a href="../mod/mod_include.html">Server Side
- Includes</a> (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 <a
- href="../mod/mod_mime.html#addhandler">AddHandler</a> and <a
- href="../mod/mod_mime.html#addtype">AddType</a> directives
- are useful for automatically XSSI-expanding all files with a
- <samp>.shtml</samp> suffix to <em>text/html</em>.</li>
-
- <li>By using the <a
- href="../mod/mod_alias.html#alias">Alias</a> 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 <a
- href="../mod/core.html#directory"><Directory></a>-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 <a
- href="../mod/core.html#errordocument">ErrorDocument</a> in
- the aliased <samp>/errordocs</samp> 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 <a
- href="../mod/core.html#allowoverride">AllowOverride</a>
- directive tells apache that it is not necessary to look for a
- .htaccess file in the /errordocs directory: a minor speed
- optimization.</li>
- </ol>
- The resulting <samp>httpd.conf</samp> configuration would then
- look similar to this: <small>(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.)</small>
-<pre>
- LanguagePriority en fr de
- Alias /errordocs /usr/local/apache/errordocs
- <Directory /usr/local/apache/errordocs>
- AllowOverride none
- Options MultiViews IncludesNoExec FollowSymLinks
- AddType text/html .shtml
- <FilesMatch "\.shtml[.$]">
- SetOutputFilter INCLUDES
- </FilesMatch>
- </Directory>
- # "400 Bad Request",
- ErrorDocument 400 /errordocs/400
- # "401 Authorization Required",
- ErrorDocument 401 /errordocs/401
- # "403 Forbidden",
- ErrorDocument 403 /errordocs/403
- # "404 Not Found",
- ErrorDocument 404 /errordocs/404
- # "500 Internal Server Error",
- ErrorDocument 500 /errordocs/500
-</pre>
- The directory for the error messages (here:
- <samp>/usr/local/apache/errordocs/</samp>) must then be created
- with the appropriate permissions (readable and executable by
- the server uid or gid, only writable for the administrator).
-
- <h3><a id="docnames" name="docnames">Naming the individual
- error document files</a></h3>
- By defining the <samp>MultiViews</samp> 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>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
- <samp>errordocs/403.shtml.<em>lang</em></samp> is created and
- filled with the error text in that language (<a
- href="#createdocs">see below</a>).</li>
-
- <li>One fallback document called
- <samp>errordocs/403.shtml</samp> is created, usually by
- creating a symlink to the default language variant (<a
- href="#fallback">see below</a>).</li>
- </ul>
-
- <h3><a id="headfoot" name="headfoot">The common header and
- footer files</a></h3>
- By putting as much layout information in two special "include
- files", the error documents can be reduced to a bare minimum.
-
- <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 XSSI 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>.<br />
- <strong>By changing this file, the layout of all generated
- error messages can be changed in a second.</strong> (By
- exploiting the features of XSSI, 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>
-
- <p><strong>Example:</strong> for English, French and German
- versions (default english)<br />
- <code>foot.shtml.en</code>,<br />
- <code>foot.shtml.fr</code>,<br />
- <code>foot.shtml.de</code>,<br />
- <code>foot.shtml</code> symlink to
- <code>foot.shtml.en</code></p>
-
- <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 id="createdocs" name="createdocs">Creating
- ErrorDocuments in different languages</a></h3>
- After all this preparation work, little remains to be said
- about the actual documents. They all share a simple common
- structure:
-<pre>
-<!--#set var="title" value="<em>error description title</em>" -->
-<!--#include virtual="head" -->
- <em>explanatory error text</em>
-<!--#include virtual="foot" -->
-</pre>
- 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.
-
- <h3><a id="fallback" name="fallback">The fallback
- language</a></h3>
- Do we need a special handling for languages other than those we
- have translations for? We did set the LanguagePriority, didn't
- we?!
-
- <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>
-<pre>
- for f in *.shtml.en
- do
- ln -s $f `basename $f .en`
- done
-</pre>
-
- <h2><a id="proxy" name="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>
-<pre>
- <!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->
- <p>
- The server encountered an unexpected condition
- which prevented it from fulfilling the request.
- </p>
- <p>
- <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->"
- SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->">
- Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s
- WebMaster</A>; it includes useful debugging information about
- the Request which caused the error.
- <pre><!--#printenv --></pre>
- </p>
- <!--#else -->
- <!--#echo var="REDIRECT_ERROR_NOTES" -->
- <!--#endif -->
-</pre>
-
- <h2><a id="listings" name="listings">HTML listing of the
- discussed example</a></h2>
- So, to summarize our example, here's the complete listing of
- the <samp>400.shtml.en</samp> 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.
- <hr />
-<pre>
-<!--#set var="title" value="Bad Request"
---><!--#include virtual="head" --><P>
- Your browser sent a request that this server could not understand:
- <BLOCKQUOTE>
- <STRONG><!--#echo var="REQUEST_URI" --></STRONG>
- </BLOCKQUOTE>
- The request could not be understood by the server due to malformed
- syntax. The client should not repeat the request without
- modifications.
- </P>
- <P>
- <!--#if expr="$HTTP_REFERER != ''" -->
- Please inform the owner of
- <A HREF="<!--#echo var="HTTP_REFERER" -->">the referring page</A> about
- the malformed link.
- <!--#else -->
- Please check your request for typing errors and retry.
- <!--#endif -->
- </P>
-<!--#include virtual="foot" -->
-</pre>
- <hr />
- Here is the complete <samp>head.shtml</samp> file (the funny
- line breaks avoid empty lines in the document after XSSI
- 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 <br />
- <code>BrowserMatch "^Mozilla/[2-4]" anigif</code><br />
- for browser types which support animated GIFs).
- <hr />
-<pre>
-<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/"
---><!--#set var="IMG_CorpLogo"
- value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif"
---><!--#set var="ALT_CorpLogo" value="Powered by Linux!"
---><!--#else
---><!--#set var="IMG_CorpLogo"
- value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif"
---><!--#set var="ALT_CorpLogo" value="Powered by Linux!"
---><!--#endif
---><!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif"
---><!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/"
---><!--#if expr="$anigif"
---><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif"
---><!--#else
---><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif"
---><!--#endif
---><!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<HTML>
- <HEAD>
- <TITLE>
- [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
- </TITLE>
- </HEAD>
- <BODY BGCOLOR="white" BACKGROUND="<!--#echo var="IMG_BgImage" -->"><UL>
- <H1 ALIGN="center">
- [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
- <IMG SRC="<!--#echo var="IMG_CorpLogo" -->"
- ALT="<!--#echo var="ALT_CorpLogo" -->" ALIGN=right>
- </H1>
- <HR><!-- ======================================================== -->
- <DIV>
-</pre>
- <hr />
- and this is the <samp>foot.shtml.en</samp> file:
- <hr />
-<pre>
- </DIV>
- <HR>
- <DIV ALIGN="right"><SMALL><SUP>Local Server time:
- <!--#echo var="DATE_LOCAL" -->
- </SUP></SMALL></DIV>
- <DIV ALIGN="center">
- <A HREF="<!--#echo var="DOC_Apache" -->">
- <IMG SRC="<!--#echo var="IMG_Apache" -->" BORDER=0 ALIGN="bottom"
- ALT="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></A><BR>
- <SMALL><SUP><!--#set var="var"
- value="Powered by $SERVER_SOFTWARE -- File last modified on $LAST_MODIFIED"
- --><!--#echo var="var" --></SUP></SMALL>
- </DIV>
- <ADDRESS>If the indicated error looks like a misconfiguration, please inform
- <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->"
- SUBJECT="Feedback about Error message [<!--#echo var="REDIRECT_STATUS"
- -->] <!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->">
- <!--#echo var="SERVER_NAME" -->'s WebMaster</A>.
- </ADDRESS>
- </UL></BODY>
-</HTML>
-</pre>
- <hr />
-
- <h3>More welcome!</h3>
- If you have tips to contribute, send mail to <a
- href="mailto:martin@apache.org">martin@apache.org</a>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>Descriptors and Apache</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Descriptors and Apache</h1>
-
- <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>
-
- <center>
-<pre>
- #open files <= soft limit <= hard limit <= kernel limit
-</pre>
- </center>
-
- <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>
-
- <dl>
- <dt><strong>BSDI 2.0</strong></dt>
-
- <dd>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.</dd>
-
- <dt><strong>FreeBSD 2.2, BSDI 2.1+</strong></dt>
-
- <dd>Similar to the BSDI 2.0 case, you should define
- <code>FD_SETSIZE</code> and rebuild. But the extra Listen
- limitation doesn't exist.</dd>
-
- <dt><strong>Linux</strong></dt>
-
- <dd>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.</dd>
-
- <dt><strong>Solaris through 2.5.1</strong></dt>
-
- <dd>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.</dd>
-
- <dt><strong>AIX</strong></dt>
-
- <dd>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.</dd>
-
- <dt><strong>SCO OpenServer</strong></dt>
-
- <dd>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.</dd>
-
- <dt><strong>Compaq Tru64 UNIX/Digital UNIX/OSF</strong></dt>
-
- <dd>
- <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>
- </dd>
-
- <dt><strong>Others</strong></dt>
-
- <dd>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>.</dd>
- </dl>
-
- <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>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>Connections in FIN_WAIT_2 and Apache</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Connections in the FIN_WAIT_2 state and
- Apache</h1>
-
- <ol>
- <li>
- <h2>What is the FIN_WAIT_2 state?</h2>
- 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>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>
- </li>
-
- <li>
- <h2>But why does it happen?</h2>
- There are numerous reasons for it happening, some of them
- may not yet be fully clear. What is known follows.
-
- <h3>Buggy clients and persistent connections</h3>
- 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 <a
- href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a>),
- 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:
-
- <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>
-
- <h3>A necessary bit of code introduced in 1.2</h3>
- 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>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>
- </li>
-
- <li>
- What can I do about it? There are several possible
- workarounds to the problem, some of which work better than
- others.
-
- <h3>Add a timeout for FIN_WAIT_2</h3>
- 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:
-
- <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>
-
- <h3>Compile without using
- <code>lingering_close()</code></h3>
- 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>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>
-
- <h3>Use <code>SO_LINGER</code> as an alternative to
- <code>lingering_close()</code></h3>
- 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>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>
-
- <p><strong>NOTE:</strong> 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.</p>
-
- <h3>Increase the amount of memory used for storing
- connection state</h3>
-
- <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>
-
- <h3>Disable KeepAlive</h3>
-
- <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>
- </li>
-
- <li>
- <h2><a id="appendix" name="appendix">Appendix</a></h2>
-
- <p>Below is a message from Roy Fielding, one of the authors
- of HTTP/1.1.</p>
-
- <h3>Why the lingering close functionality is necessary with
- HTTP</h3>
- 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>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>
- </li>
- </ol>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
- <hr />
-
- <h3 align="center">Apache HTTP Server Version 2.1</h3>
- <a href="./"><img src="../images/index.gif" alt="Index" /></a>
- <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+++ /dev/null
- <div align="center">
- <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
-
- <h3>Apache HTTP Server Version 2.1</h3>
- </div>
-
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>Apache HTTP Server Project</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Known Problems in Clients</h1>
-
- <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>
-
- <h3><a id="trailing-crlf" name="trailing-crlf">Trailing CRLF on
- POSTs</a></h3>
-
- <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>
-
- <h3><a id="broken-keepalive" name="broken-keepalive">Broken
- keepalive</a></h3>
-
- <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>
-
- <blockquote>
- <code>BrowserMatch Mozilla/2 nokeepalive</code>
- </blockquote>
- 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>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>
-
- <blockquote>
- <code>BrowserMatch "MSIE 4\.0b2;" nokeepalive</code>
- </blockquote>
-
- <h3><a id="force-response-1.0"
- name="force-response-1.0">Incorrect interpretation of
- <code>HTTP/1.1</code> in response</a></h3>
-
- <p>To quote from section 3.1 of RFC1945:</p>
-
- <blockquote>
- 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.
- </blockquote>
- 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>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>
-
- <blockquote>
- <code>BrowserMatch Java/1.0 force-response-1.0<br />
- BrowserMatch JDK/1.0 force-response-1.0</code>
- </blockquote>
-
- <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>
-
- <blockquote>
- <code>BrowserMatch "RealPlayer 4.0" force-response-1.0</code>
- </blockquote>
-
- <h3><a id="msie4.0b2" name="msie4.0b2">Requests use HTTP/1.1
- but responses must be in HTTP/1.0</a></h3>
-
- <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>
-
- <blockquote>
- <code>BrowserMatch "MSIE 4\.0b2;" downgrade-1.0
- force-response-1.0</code>
- </blockquote>
- 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.
-
- <h3><a id="byte-257" name="byte-257">Boundary problems with
- header parsing</a></h3>
-
- <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>
-
- <h3><a id="boundary-string" name="boundary-string">Multipart
- responses and Quoted Boundary Strings</a></h3>
-
- <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>
-
- <h3><a id="byterange-requests"
- name="byterange-requests">Byterange requests</a></h3>
-
- <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>
-
- <h3><a id="cookie-merge"
- name="cookie-merge"><code>Set-Cookie</code> header is
- unmergeable</a></h3>
-
- <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>
-
- <h3><a id="gif89-expires"
- name="gif89-expires"><code>Expires</code> headers and GIF89A
- animations</a></h3>
-
- <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>
-
- <h3><a id="no-content-length"
- name="no-content-length"><code>POST</code> without
- <code>Content-Length</code></a></h3>
-
- <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>
-
- <h3><a id="jdk-12-bugs" name="jdk-12-bugs">JDK 1.2 betas lose
- parts of responses.</a></h3>
-
- <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>
-
- <blockquote>
- <code>BrowserMatch "Java1\.2beta[23]" nokeepalive</code>
- </blockquote>
-
- <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>
-
- <h3><a id="content-type-persistence"
- name="content-type-persistence"><code>Content-Type</code>
- change is not noticed after reload</a></h3>
-
- <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>
-
- <h3><a id="msie-cookie-y2k" name="msie-cookie-y2k">MSIE Cookie
- problem with expiry date in the year 2000</a></h3>
-
- <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>
-
- <h3><a id="lynx-negotiate-trans"
- name="lynx-negotiate-trans">Lynx incorrectly asking for
- transparent content negotiation</a></h3>
-
- <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>
-
- <h3><a id="ie40-vary" name="ie40-vary">MSIE 4.0 mishandles Vary
- response header</a></h3>
-
- <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>
-<pre>
- BrowserMatch "MSIE 4\.0" force-no-vary
-</pre>
-
- <p>(This workaround is only available with releases
- <strong>after</strong> 1.3.6 of the Apache Web server.)</p>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>Apache Tutorials</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Apache Tutorials</h1>
-
- <blockquote>
- <strong>Warning:</strong> This document has not been 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.
- </blockquote>
-
- <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>
-
- <h2>Installation & Getting Started</h2>
-
- <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>
-
- <h2>Basic Configuration</h2>
-
- <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>
-
- <h2>Security</h2>
-
- <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>
-
- <h2>Logging</h2>
-
- <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>
-
- <h2>CGI and SSI</h2>
-
- <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>
-
- <h2>Other Features</h2>
-
- <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>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
projects / apache / commitdiff
