[PATCH] Wokers How To Documentation

[Andrew Gilbert <ag...@soundbite.com>]

Had a bad run in with firewalls using Apache 1.3 and AJP13. Thought the following changes might help the next victim.

Andrew Gilbert


Index: workershowto.xml
===================================================================
RCS file: /home/cvspublic/jakarta-tomcat-connectors/jk/xdocs/jk/workershowto.xml,v
retrieving revision 1.8
diff -u -r1.8 workershowto.xml
--- workershowto.xml	20 Sep 2002 21:35:30 -0000	1.8
+++ workershowto.xml	15 Nov 2002 20:41:40 -0000
@@ -170,8 +170,7 @@
 frequently used strings as small integers.
 </li>
 <li>
-ajpv13 reuse open sockets and leaves them open for future requests (remember when you've got a Firewall between your 
-WebServer and Tomcat).
+ajpv13 reuses open sockets and leaves them open for future requests. When you've got a firewall between your WebServer and Tomcat you need to ensure these connections aren't torn down during periods of inactivity. See <b>socket_keepalive</b> for more information.
 </li>
 <li>
 ajpv13 has special treatment for SSL information so that the container can implement 
@@ -204,53 +203,36 @@
 </p>
 
 <p>
-<b>cachesize</b> property is usefull when you're using JK in multithreaded 
-web servers such as Apache 2.0, IIS and Netscape. They will benefit the most by 
-setting this value to a higher level (such as the estimated average concurrent users for Tomcat).
+<b>cachesize</b> property is useful when you're using JK in multithreaded 
+web servers such as Apache 2.0, IIS and Netscape. The default value is 1. Multithreaded web servers will benefit by setting this value to a higher level, such as the estimated average concurrent users for Tomcat. With forking model web servers you probably want to use the default.
 </p>
 
 <p>
-<b>cache_timeout</b> property should be used with <b>cachesize</b> to specify how to time JK should keep
-an open socket in cache before closing it. This property should be used to reduce the number of threads 
-on the Tomcat WebServer.
+<b>cache_timeout</b> property should be used with <b>cachesize</b> to specify how long JK should keep inactive connections in the cache before cleaning them up and closing them. Note that this property will have no affect with the default cachesize of 1.
 </p>
 
 <p>
-You should know that under heavy load some WebServers, for example Apache's create many childs/threads
-to handle the load and they destroy the childs/threads only when the load decrease.
+In a multithreaded web server scenario an AJP13 worker will use the cache to manage connection load to Tomcat. As load increases the web server will create threads to handle the load, and the AJP13 worker will create, cache and reuse connections to Tomcat as required, up to <b>cachesize</b>. As load decreases the web server is responsible for reaping extra threads, and the worker will clean out connections to Tomcat per the <b>cache_timeout</b> property. Note this clean up occurs only when new activity resumes following idle time. There is no reaper thread.
 </p>
 
-<p> 
-Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating
-a new ajp13 thread on Tomcat side.
+<p>
+Tomcat creates a new thread to handle each connection. By recovering unused connections from the cache, threads on Tomcat that are servicing idle connections will be recovered as well.
 </p>
 
-<p>
-The problem is that after an ajp13 connection is created, the child won't drop it
-until killed. And since the webserver will keep its childs/threads running
-to handle high-load, even it the child/thread handle only static contents, you could
-finish having many unused ajp13 threads on the Tomcat side.
+<p> 
+In a forking model scenario, the web server will create new processes to handle load. Each process will have it's own cache. Each cache will probably not extend beyond one connection. The benefit of the cache in this scenario is marginal. Connections that exist to Tomcat will be cleaned only when inactive child processes are cleaned by the web server.
 </p>
 
 <p>
-<b>socket_keepalive</b> property should be used when you have a firewall between your webserver
-and the Tomcat engine, who tend to drop inactive connections. This flag will told Operating System
-to send <code>KEEP_ALIVE</code> message on inactive connections (interval depend on global OS settings,
-generally 120mn), and sus prevent the firewall to cut the connection.
+<b>socket_keepalive</b> property should be used when you have a firewall that drops inactive connections between your webserver and Tomcat. This property will cause the keep alive flag to be set on socket connections to Tomcat. The operating system will then send <code>KEEP_ALIVE</code> packets on inactive connections. The keep alive timeout is often a global OS setting, usually of 120 minutes. The keep alive packets will prevent the firewall from cutting the connection because of no activity. Be sure to adjust either the firewall or operating system so that keep alives happen inside the window of firewall timeouts.
 </p>
 
 <p>
-The problem with Firewall cutting inactive connections is that sometimes, neither webserver or tomcat
-have informations about the cut and couldn't handle it.
+A firewall cutting inactive connections can result in either the webserver or Tomcat using what appear to be valid connections. The packets will get dropped, often without the other side having any awareness of the problem. Typical problems include sporadic hanging issues after periods of inactivity, and accumulated idle threads and stale connections on Tomcat.
 </p>
 
 <p>
-<b>socket_timeout</b> property told webserver to cut an ajp13 connection after some time of 
-inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be
-closed if it was not used for the configured time.
-It's a good way to ensure that there won't too old threads living on Tomcat side, 
-with the extra cost you need to reopen the socket next time a request be forwarded.
-This property is very similar to <b>cache_timeout</b> but works also in non-cache mode.
+<b>socket_timeout</b> property tells the webserver to close an ajp13 connection after some period of inactivity. It's a good way to guard against stale connections and idle threads on the Tomcat side, with the extra cost of reopening the socket. Unlike <b>cache_timeout</b> this property will apply to any existing connection between the web server and Tomcat, not just N-1 connections that have been cached. In forking webserver scenarios or when <b>cache_size</b> is defaulted to 1, it is probably more useful and reliable than <b>cache_timeout</b>. As with <b>cache_timeout</b> there is no reaper thread, and connections will only be closed on reuse following inactivity.
 </p>
 
 <screen>


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>