From: Erik Abele Date: Sun, 2 Mar 2003 01:21:57 +0000 (+0000) Subject: Bust 'em :) X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=583daac7a5664c97587e01a7c94d75b1ca9a6553;p=apache Bust 'em :) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@98875 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/images/custom_errordocs.gif b/docs/manual/images/custom_errordocs.gif deleted file mode 100644 index d566c5d891..0000000000 Binary files a/docs/manual/images/custom_errordocs.gif and /dev/null differ diff --git a/docs/manual/misc/custom_errordocs.html b/docs/manual/misc/custom_errordocs.html deleted file mode 100644 index 6a426a76f2..0000000000 --- a/docs/manual/misc/custom_errordocs.html +++ /dev/null @@ -1,489 +0,0 @@ - - - - - - - International Customized Server Error Messages - - - - - - -

Using XSSI and `ErrorDocument` to - configure customized international server error responses

- -

Index

- -

Introduction
Creating an ErrorDocument - directory
Naming the individual error document - files
The common header and footer - files
Creating ErrorDocuments in - different languages
The fallback language
Customizing Proxy Error - Messages
HTML listing of the discussed - example

- -

Introduction

- This document describes an easy way to provide your apache WWW - server with a set of customized error messages which take - advantage of Content - Negotiation and eXtended - Server Side Includes (XSSI) to return error messages - generated by the server in the client's native language.
-
- - -

By using XSSI, all customized 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.
- 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.

- -

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.

- -

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...

- -

possibly are served by different virtual hosts (different - host name, different IP address, or different port) on the - server machine,
show a predefined company logo in the right top of the - message (selectable by virtual host),
print the error title first, followed by an explanatory - text and (depending on the error context) help on how to - resolve the error,
have some kind of standardized background image,
display an apache logo and a feedback email address at - the bottom of the error message.

-
-
- - -

An example of a "document not found" message for a german - client might look like this:
- [Needs graphics capability to display]
- 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.

- -

Creating an - ErrorDocument directory

- For this concept to work as easily as possible, we must take - advantage of as much server support as we can get: - -

By defining the MultiViews option, we - enable the language selection of the most appropriate - language alternative (content negotiation).
By setting the LanguagePriority - directive we define a set of default fallback languages in - the situation where the client's browser did not express any - preference at all.
By enabling Server Side - Includes (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.
The AddHandler and AddType directives - are useful for automatically XSSI-expanding all files with a - .shtml suffix to text/html.
By using the Alias 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.
The <Directory>-Block - restricts these "special" settings to the error document - directory and avoids an impact on any of the settings for the - regular document tree.
For each of the error codes to be handled (see RFC2068 - for an exact description of each error code, or look at - src/main/http_protocol.c if you wish to see - apache's standard messages), an ErrorDocument in - the aliased /errordocs 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 not handled - by a custom document will be dealt with by the server in the - standard way (i.e., a plain error message in - english).
Finally, the AllowOverride - directive tells apache that it is not necessary to look for a - .htaccess file in the /errordocs directory: a minor speed - optimization.

- The resulting httpd.conf configuration would then - look similar to this: (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.) -

-  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
-

- The directory for the error messages (here: - /usr/local/apache/errordocs/) must then be created - with the appropriate permissions (readable and executable by - the server uid or gid, only writable for the administrator). - -

Naming the individual - error document files

- By defining the MultiViews 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). - -

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):

- -

No file errordocs/403 should exist. Otherwise, it would - be found and served (with the DefaultType, usually - text/plain), all negotiation would be bypassed.
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 have translated - versions), a document - errordocs/403.shtml.lang is created and - filled with the error text in that language (see below).
One fallback document called - errordocs/403.shtml is created, usually by - creating a symlink to the default language variant (see below).

- -

The common header and - footer files

- By putting as much layout information in two special "include - files", the error documents can be reduced to a bare minimum. - -

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 - title.
- By changing this file, the layout of all generated - error messages can be changed in a second. (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).

- -

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.

- -

For simplicity, the header file is simply called - head.shtml 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.

- -

Example: for English, French and German - versions (default english)
- foot.shtml.en,
- foot.shtml.fr,
- foot.shtml.de,
- foot.shtml symlink to - foot.shtml.en

- -

Both files are included into the error document by using the - directives  - and  - respectively: the rest of the magic occurs in mod_negotiation - and in mod_include.

- -

See the listings below to see an - actual HTML implementation of the discussed example.

- -

Creating - ErrorDocuments in different languages

- After all this preparation work, little remains to be said - about the actual documents. They all share a simple common - structure: -

-<!--#set var="title" value="error description title" -->
-<!--#include virtual="head" -->
-   explanatory error text
-<!--#include virtual="foot" -->
-

- In the listings section, 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. - -

The fallback - language

- Do we need a special handling for languages other than those we - have translations for? We did set the LanguagePriority, didn't - we?! - -

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?

- -

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.

- -

So, in this situation it appears to be easier to define a - fallback language (by copying or linking, e.g., 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.

- -

A simple shell script to do it (execute within the - errordocs/ dir):

-  for f in *.shtml.en
-  do
-     ln -s $f `basename $f .en`
-  done
-

- -

Customizing Proxy Error - Messages

- -

As of Apache-1.3, it is possible to use the - ErrorDocument mechanism for proxy error messages - as well (previous versions always returned fixed predefined - error messages).

- -

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 ERROR_NOTES CGI - environment variable: if invoked for a proxy error, this - variable will contain the actual proxy error message text in - HTML form.

- -

The following excerpt demonstrates how to exploit the - ERROR_NOTES variable within an error document:

- <!--#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 -->
-

- -

HTML listing of the - discussed example

- So, to summarize our example, here's the complete listing of - the 400.shtml.en 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. -

-<!--#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" -->
-

- Here is the complete head.shtml 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
- BrowserMatch "^Mozilla/[2-4]" anigif
- for browser types which support animated GIFs). -

-<!--#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>
-

- and this is the foot.shtml.en file: -

-  </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>
-

- -

More welcome!

- If you have tips to contribute, send mail to martin@apache.org - - - - diff --git a/docs/manual/misc/descriptors.html b/docs/manual/misc/descriptors.html deleted file mode 100644 index 75aaedf874..0000000000 --- a/docs/manual/misc/descriptors.html +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - - Descriptors and Apache - - - - - - -

Descriptors and Apache

- -

A descriptor, also commonly called a file - handle 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 stdin, stdout, and - stderr 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 (i.e., with many virtual hosts).

- -

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 FD_SETSIZE). Or you - may be stuck with a (relatively) low amount. The second limit - is called the hard resource 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 - soft resource 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.

- -

To summarize:

- - -

-  #open files  <=  soft limit  <=  hard limit  <=  kernel limit
-

- - -

You control the hard and soft limits using the - limit (csh) or ulimit (sh) - directives. See the respective man pages for more information. - For example you can probably use ulimit -n - unlimited to raise your soft limit up to the hard limit. - You should include this command in a shell script which starts - your webserver.

- -

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):

- -

BSDI 2.0

Under BSDI 2.0 you can build Apache to support more - descriptors by adding -DFD_SETSIZE=nnn to - EXTRA_CFLAGS (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.

FreeBSD 2.2, BSDI 2.1+

Similar to the BSDI 2.0 case, you should define - FD_SETSIZE and rebuild. But the extra Listen - limitation doesn't exist.

Linux

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 the Linux Information HQ. - 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.

Solaris through 2.5.1

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 -DHIGH_SLACK_LINE=256 added to - EXTRA_CFLAGS. You will be limited to - approximately 240 error logs if you do this.

AIX

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.

SCO OpenServer

Edit the /etc/conf/cf.d/stune file or use - /etc/conf/cf.d/configure choice 7 (User and - Group configuration) and modify the NOFILES - 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.

Compaq Tru64 UNIX/Digital UNIX/OSF

Raise open_max_soft and - open_max_hard to 4096 in the proc subsystem. - Do a man on sysconfig, sysconfigdb, and - sysconfigtab.
Raise max-vnodes 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.
If you are using Tru64 5.0, 5.0A, or 5.1, define - NO_SLACK to work around a bug in the OS. - CFLAGS="-DNO_SLACK" ./configure

Others

If you have details on another operating system, please - submit it through our Bug Report - Page.

- -

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 low slack - line.

- -

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.

- -

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 - LOW_SLACK_LINE and there's a tiny bit of - documentation in the header file httpd.h.

- -

Finally, if you suspect that all this slack stuff is causing - you problems, you can disable it. Add -DNO_SLACK - to EXTRA_CFLAGS and rebuild. But please report it - to our Bug - Report Page so that we can investigate.

- - - - diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html deleted file mode 100644 index 2e97e62907..0000000000 --- a/docs/manual/misc/fin_wait_2.html +++ /dev/null @@ -1,387 +0,0 @@ - - - - - - - Connections in FIN_WAIT_2 and Apache - - - - - - -

Connections in the FIN_WAIT_2 state and - Apache

- -

-
What is the FIN_WAIT_2 state?
- Starting with the Apache 1.2 betas, people are reporting - many more connections in the FIN_WAIT_2 state (as reported - by netstat) 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 TCP RFC for - the technical details of the state transitions. - -
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.
-
-
But why does it happen?
- There are numerous reasons for it happening, some of them - may not yet be fully clear. What is known follows. - -
Buggy clients and persistent connections
- 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 KeepAliveTimeout), - 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: - -
- 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.
- The user exits the client, which on some (most?) - clients causes the OS to fully shutdown the - connection.
- The FIN_WAIT_2 times out, on servers that have a - timeout for this state.
- -
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. This is a bug in the browser or - in its operating system's TCP implementation.
- -
The clients on which this problem has been verified to - exist:
- -
- Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE - i386)
- Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE - i386)
- Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)
- MSIE 3.01 on the Macintosh
- MSIE 3.01 on Windows 95
- -
This does not appear to be a problem on:
- -
- Mozilla/3.01 (Win95; I)
- -
It is expected that many other clients have the same - problem. What a client should do 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 (e.g., Win95 and NT - clients have this capability, but they seem to be ignoring - it).
- -
Apache cannot 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.
- -
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.
- -
A necessary bit of code introduced in 1.2
- 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 lingering_close() 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 - (e.g., 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 appendix for more - details. - -
The code in lingering_close() 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 - lingering_close code that causes the observed - problems.
-
- What can I do about it? There are several possible - workarounds to the problem, some of which work better than - others. - -
Add a timeout for FIN_WAIT_2
- 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: - -
- FreeBSD - versions starting at 2.0 or possibly earlier.
- NetBSD version - 1.2(?)
- OpenBSD all - versions(?)
- BSD/OS 2.1, with - the - K210-027 patch installed.
- Solaris as of - around version 2.2. The timeout can be tuned by using - ndd to modify - tcp_fin_wait_2_flush_interval, but the - default should be appropriate for most servers and - improper tuning can have negative impacts.
- Linux 2.0.x and - earlier(?)
- HP-UX 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 - SO_LINGER socket option which is enabled by - Apache. This parameter can be adjusted by using - nettune to modify parameters such as - tcp_keepstart and tcp_keepstop. - In later revisions, there is an explicit timer for - connections in FIN_WAIT_2 that can be modified; contact - HP support for details.
- SGI IRIX 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.
- NCR's MP RAS Unix - 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).
- Sequent's ptx/TCP/IP - for DYNIX/ptx has had a FIN_WAIT_2 timeout since - around release 4.1 in mid-1994.
- -
The following systems are known to not have a - timeout:
- -
- SunOS 4.x 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.
- -
There is a - patch available 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.
- -
Compile without using - lingering_close()
- It is possible to compile Apache 1.2 without using the - lingering_close() 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. - -
To compile without the lingering_close() - function, add -DNO_LINGCLOSE to the end of the - EXTRA_CFLAGS line in your - Configuration file, rerun - Configure and rebuild the server.
- -
Use SO_LINGER as an alternative to - lingering_close()
- On most systems, there is an option called - SO_LINGER that can be set with - setsockopt(2). It does something very similar - to lingering_close(), except that it is broken - on many systems so that it causes far more problems than - lingering_close. On some systems, it could - possibly work better so it may be worth a try if you have - no other alternatives. - -
To try it, add -DUSE_SO_LINGER - -DNO_LINGCLOSE to the end of the - EXTRA_CFLAGS line in your - Configuration file, rerun - Configure and rebuild the server.
- -
NOTE: Attempting to use - SO_LINGER and lingering_close() - at the same time is very likely to do very bad things, so - don't.
- -
Increase the amount of memory used for storing - connection state
- -
-
BSD based networking code:
- -
- 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. - -
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 NMBCLUSTERS="n", where - n is the number of mbuf clusters you want - to your kernel config file and rebuilding your - kernel.
-
-
- -
Disable KeepAlive
- -
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".
-
-
Appendix
- -
Below is a message from Roy Fielding, one of the authors - of HTTP/1.1.
- -
Why the lingering close functionality is necessary with - HTTP
- 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. - -
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.
- -
There are two conditions under which this is likely to - occur:
- -
1. sending POST or PUT data without proper - authorization
2. sending multiple requests before each response - (pipelining) and one of the middle requests resulting in - an error or other break-the-connection result.
- -
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).
- -
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.
-

- - - - diff --git a/docs/manual/misc/footer.html b/docs/manual/misc/footer.html deleted file mode 100644 index a418ad44c6..0000000000 --- a/docs/manual/misc/footer.html +++ /dev/null @@ -1,5 +0,0 @@ -

- -

Apache HTTP Server Version 2.1

diff --git a/docs/manual/misc/header.html b/docs/manual/misc/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/misc/header.html +++ /dev/null @@ -1,6 +0,0 @@ -

- -

Apache HTTP Server Version 2.1

- diff --git a/docs/manual/misc/known_client_problems.html b/docs/manual/misc/known_client_problems.html deleted file mode 100644 index cb27dfda5e..0000000000 --- a/docs/manual/misc/known_client_problems.html +++ /dev/null @@ -1,345 +0,0 @@ - - - - - - - Apache HTTP Server Project - - - - - - -

Known Problems in Clients

- -

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.

- -

For brevity, Navigator will refer to Netscape's - Navigator product (which in later versions was renamed - "Communicator" and various other names), and MSIE 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.

- -

For reference, RFC1945 - defines HTTP/1.0, and RFC2068 - defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 - server (with an optional HTTP/1.0 proxy).

- -

Various of these workarounds are triggered by environment - variables. The admin typically controls which are set, and for - which clients, by using mod_browser. Unless - otherwise noted all of these workarounds exist in versions 1.2 - and later.

- -

Trailing CRLF on - POSTs

- -

This is a legacy issue. The CERN webserver required - POST data to have an extra CRLF - following it. Thus many clients send an extra CRLF - that is not included in the Content-Length of the - request. Apache works around this problem by eating any empty - lines which appear before a request.

- -

Broken - keepalive

- -

Various clients have had broken implementations of - keepalive (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:

- -

- BrowserMatch Mozilla/2 nokeepalive -

- Note that this matches some earlier versions of MSIE, which - began the practice of calling themselves Mozilla in - their user-agent strings just like Navigator. - -

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 - nokeepalive code prior to 1.2.2 would not work - with HTTP/1.1 clients. You must apply - this patch to version 1.2.1. Then add this to your - config:

- -

- BrowserMatch "MSIE 4\.0b2;" nokeepalive -

- -

Incorrect interpretation of - `HTTP/1.1` in response

- -

To quote from section 3.1 of RFC1945:

- -

- 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. -

- 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. - -

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 - force-response-1.0 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.

- -

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:

- -

- BrowserMatch Java/1.0 force-response-1.0 - BrowserMatch JDK/1.0 force-response-1.0 -

- -

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 User-Agent - as version 4.0. The workaround is still:

- -

- BrowserMatch "RealPlayer 4.0" force-response-1.0 -

- -

Requests use HTTP/1.1 - but responses must be in HTTP/1.0

- -

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 chunked - responses). The workaround is to fool Apache into believing the - request came in HTTP/1.0 format.

- -

- BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 - force-response-1.0 -

- This workaround is available in 1.2.2, and in a - patch against 1.2.1. - -

Boundary problems with - header parsing

- -

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.

- -

Multipart - responses and Quoted Boundary Strings

- -

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.

- -

Byterange requests

- -

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.

- -

A subsequent draft of this standard defines a header - Request-Range, and a response type - multipart/x-byteranges. The HTTP/1.1 standard - includes this draft with a few fixes, and it defines the header - Range and type - multipart/byteranges.

- -

Navigator (versions 2 and 3) sends both Range - and Request-Range headers (with the same value), - but does not accept a multipart/byteranges - response. The response must be - multipart/x-byteranges. As a workaround, if Apache - receives a Request-Range header it considers it - "higher priority" than a Range header and in - response uses multipart/x-byteranges.

- -

The Adobe Acrobat Reader plugin makes extensive use of - byteranges and prior to version 3.01 supports only the - multipart/x-byterange 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 - Range-Request clue that Navigator does. To - workaround this, Apache special cases "MSIE 3" in the - User-Agent and serves - multipart/x-byteranges. Note that the necessity - for this with MSIE 3 is actually due to the Acrobat plugin, not - due to the browser.

- -

Netscape Communicator appears to not issue the non-standard - Request-Range 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.

- -

`Set-Cookie` header is - unmergeable

- -

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 Set-Cookie header is sent - separately. When parsing the headers returned by a CGI, Apache - will explicitly avoid merging any Set-Cookie - headers.

- -

`Expires` headers and GIF89A - animations

- -

Navigator versions 2 through 4 will erroneously re-request - GIF89A animations on each loop of the animation if the first - response included an Expires 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 - 1.2 and for - 1.3.

- -

`POST` without - `Content-Length`

- -

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 information. - There's also - some information about the actual problem.

- -

JDK 1.2 betas lose - parts of responses.

- -

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.

- -

See also Bug-ID's 4124329 and 4125538 at the java developer - connection.

- -

If you are seeing this bug yourself, you can add the - following BrowserMatch directive to work around it:

- -

- BrowserMatch "Java1\.2beta[23]" nokeepalive -

- -

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.

- -

`Content-Type` - change is not noticed after reload

- -

Navigator (all versions?) will cache the - content-type for an object "forever". Using reload - or shift-reload will not cause Navigator to notice a - content-type 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 mime.types - file which does not map .htm to - text/html, in this case Apache will default to - sending text/plain. If the user requests the page - and it is served as text/plain. After the admin - fixes the server, the user will have to flush their caches - before the object will be shown with the correct - text/html type.

- -

MSIE Cookie - problem with expiry date in the year 2000

- -

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.

- -

Lynx incorrectly asking for - transparent content negotiation

- -

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.

- -

MSIE 4.0 mishandles Vary - response header

- -

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 PR#4118.

- -

A workaround is to add the following to your server's - configuration files:

-    BrowserMatch "MSIE 4\.0" force-no-vary
-

- -

(This workaround is only available with releases - after 1.3.6 of the Apache Web server.)

- - - - diff --git a/docs/manual/misc/tutorials.html b/docs/manual/misc/tutorials.html deleted file mode 100644 index 020c760ec0..0000000000 --- a/docs/manual/misc/tutorials.html +++ /dev/null @@ -1,211 +0,0 @@ - - - - - - - Apache Tutorials - - - - - - -

Apache Tutorials

- -

- Warning: 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. -

- -

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 official Apache - Server documentation to verify what you read on external - sites.

- -

Installation & Getting Started

- -

- Getting Started with Apache 1.3 (ApacheToday)
- Configuring Your Apache Server Installation - (ApacheToday)
- Getting, Installing, and Running Apache (on Unix) - (O'Reilly Network Apache DevCenter)
Maximum - Apache: Getting Started (CNET Builder.com)
- How to Build the Apache of Your Dreams (Developer - Shed)

- -

Basic Configuration

- -

- An Amble Through Apache Configuration (O'Reilly Network - Apache DevCenter)
- Using .htaccess Files with Apache (ApacheToday)
- Setting Up Virtual Hosts (ApacheToday)
Maximum - Apache: Configure Apache (CNET Builder.com)
- Getting More Out of Apache (Developer Shed)

- -

Security

- -

- Security and Apache: An Essential Primer - (LinuxPlanet)
Using User - Authentication (Apacheweek)
DBM - User Authentication (Apacheweek)
- An Introduction to Securing Apache (Linux.com)
- Securing Apache - Access Control (Linux.com)
Apache Authentication - Part 1 - - Part 2 - - Part 3 - - Part 4 (ApacheToday)
- mod_access: Restricting Access by Host (ApacheToday)

- -

Logging

- -

- Log Rhythms (O'Reilly Network Apache DevCenter)
Gathering - Visitor Information: Customising Your Logfiles - (Apacheweek)
Apache Guide: Logging - Part 1 - - Part 2 - - Part 3 - - Part 4 - - Part 5 (ApacheToday)

- -

CGI and SSI

- -

- Dynamic Content with CGI (ApacheToday)
- The Idiot's Guide to Solving Perl CGI Problems - (CPAN)
- Executing CGI Scripts as Other Users (LinuxPlanet)
CGI - Programming FAQ (Web Design Group)
Introduction to Server Side Includes - Part 1 - - Part 2 (ApacheToday)
- Advanced SSI Techniques (ApacheToday)
Setting - up CGI and SSI with Apache (CNET Builder.com)

- -

Other Features

- -

Content - Negotiation Explained (Apacheweek)
Using - Apache Imagemaps (Apacheweek)
- Keeping Your Images from Adorning Other Sites - (ApacheToday)
Language - Negotiation Notes (Alan J. Flavell)

- -

If you have a pointer to an accurate and well-written - tutorial not included here, please let us know by submitting it - to the Apache Bug - Database.

- - - -

Using XSSI and ErrorDocument to - configure customized international server error responses

Index

More welcome!

Descriptors and Apache

Connections in the FIN_WAIT_2 state and - Apache

What is the FIN_WAIT_2 state?

But why does it happen?

Buggy clients and persistent connections

A necessary bit of code introduced in 1.2

Add a timeout for FIN_WAIT_2

Compile without using - lingering_close()

Use SO_LINGER as an alternative to - lingering_close()

Increase the amount of memory used for storing - connection state

Disable KeepAlive

Why the lingering close functionality is necessary with - HTTP

Apache HTTP Server Version 2.1

Apache HTTP Server Version 2.1

Known Problems in Clients

Apache Tutorials

Installation & Getting Started

Basic Configuration

Security

Logging

CGI and SSI

Other Features

Using XSSI and `ErrorDocument` to - configure customized international server error responses

Compile without using - `lingering_close()`

Use `SO_LINGER` as an alternative to - `lingering_close()`