tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mt...@apache.org
Subject cvs commit: jakarta-tomcat-connectors/jk/xdocs/config workers.xml
Date Thu, 25 Nov 2004 09:22:59 GMT
mturk       2004/11/25 01:22:59

  Modified:    jk/xdocs/config workers.xml
  Log:
  Add more workers directives to doc.
  
  Revision  Changes    Path
  1.5       +200 -5    jakarta-tomcat-connectors/jk/xdocs/config/workers.xml
  
  Index: workers.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/config/workers.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- workers.xml	22 Nov 2004 16:51:44 -0000	1.4
  +++ workers.xml	25 Nov 2004 09:22:59 -0000	1.5
  @@ -61,6 +61,19 @@
   </warn>
   </p>
   
  +<subsection name="Defining workers">
  +<p>Defining workers to the Tomcat web server plugin can be done using a properties
file
  +(a sample file named workers.properties is available in the conf/ directory).
  +</p>
  +<directives>
  +<directive name="worker.list" required="true">
  +A comma separated list of workers names that the JK will use. When starting up,
  +the web server plugin will instantiate the workers whose name appears in the
  +worker.list property, these are also the workers to whom you can map requests. 
  +</directive>
  +</directives>
  +</subsection>
  +
   <subsection name="Mandatory directives">
   <p>Mandatory directives are the one that each worker <b>must</b> contain.
Without them the worker will
   be unavailable or will misbehave.
  @@ -69,15 +82,18 @@
   <directive name="type" default="ajp13" required="true">
   Type of the worker (can be one of ajp13, ajp14, jni or lb). The type of the worker
   defines the directives that can be applied to the worker.
  +<p>AJP13 worker is the preferred worker type that JK uses for communication
  +between web server and Tomcat. This type of worker uses sockets as communication
  +channel. For detailed description of the AJP13 protocol stack browse to
  +<a href="../common/ajpv13a.html">AJPv13 protocol specification</a>
  +</p>
   </directive>
   </directives>
   </subsection>
   
  -<subsection name="AJP13 worker directives">
  -<p>AJP13 worker directives are the preferred worker type that JK uses for communication
  -between web server and Tomcat. This type of worker uses sockets as communication
  -channel. For detailed description of the AJP13 protocol stack browse to
  -<a href="../common/ajpv13a.html">AJPv13 protocol specification</a>
  +<subsection name="Connection directives">
  +<p>Connection directives defines the parameters needed to connect and maintain
  +the connections pool of persisten connections between JK and remote Tomcat.
   </p>
   <directives>
   
  @@ -130,6 +146,7 @@
   setting this value to a higher level (such as the estimated average concurrent users for
Tomcat).
   If cachesize is not set, the connection cache support is disabled.
   Cachesize determines the minimum number of open connections to backend Tomcat.
  +<warn>Do not use cachesize with <b>prefork mpm</b> or <b>apache
1.3.x</b>!</warn>
   </directive>
   
   <directive name="cache_timeout" default="0" required="false">
  @@ -148,11 +165,189 @@
   </p>
   </directive>
   
  +<directive name="lb_factor" default="1" required="false">
  +Integer number used when the worker will be used inside load balancer worker,
  +this is the load-balancing factor for the worker.
  +The load-balancing factor is <i>how much we expect this worker to work</i>,
or
  +<i>the worker's work quota</i>. Load balancing factor is compared with other
workers
  +that makes the load balancer. For example if one worker has lb_factor 5 times higher then
  +other worker, then it will receive five times more requests. 
  +</directive>
  +
  +</directives>
  +</subsection>
  +
  +<subsection name="Load balancing directives">
  +<p>Loadbalancer directives defines the parameters needed to create a workers that
are
  +connectiong to a remote cluster of backend Tomcat servers. Each cluster node has to
  +have a worker defined.
  +</p>
  +<p>
  +The load-balancing worker does not really communicate with Tomcat workers.
  +Instead it is responsible for the management of several "real" workers. 
  +This management includes:
  +</p>
  +
  +<ul>
  +<li>
  +Instantiating the workers in the web server.
  +</li>
  +<li>
  +Using the worker's load-balancing factor, perform weighed-round-robin load balancing where

  +high lbfactor means stronger machine (that is going to handle more requests)
  +</li>
  +<li>
  +Keeping requests belonging to the same session executing on the same Tomcat worker.
  +</li>
  +<li>
  +Identifying failed Tomcat workers, suspending requests to them and instead fall-backing
on 
  +other workers managed by the lb worker.
  +</li>
  +</ul>
  +
  +<p>
  +The overall result is that workers managed by the same lb worker are load-balanced
  +(based on their lbfactor and current user session) and also fall-backed so a single
  +Tomcat process death will not "kill" the entire site.
  +The following table specifies properties that the lb worker can accept:
  +</p>
  +
  +<directives>
  +<directive name="balanced_workers" required="true">
  +A comma separated list of workers that the load balancer
  +need to manage. 
  +<warn>These workers should <b>not</b> appear in the worker.list property!</warn>
  +</directive>
  +
  +<directive name="sticky_session" default="True" required="false">
  +Specifies whether requests with SESSION ID's should be routed back to the same
  +Tomcat worker. If sticky_session is set to <b>True</b> or <b>1</b>
sessions are sticky, otherwise
  +sticky_session is set to <b>False</b>. Set sticky_session to <b>False</b>
when Tomcat
  +is using a Session Manager which can persist session data across multiple
  +instances of Tomcat. By default sticky_session is set to True.
  +</directive>
  +</directives>
  +
  +</subsection>
  +
  +<subsection name="Advanced worker directives">
  +
  +<directives>
  +<directive name="connect_timeout" required="false">
  +Connect timeout property told webserver to send a PING request on ajp13 connection after

  +connection is established. The parameter is the delay in milliseconds to wait for the PONG
reply.
  +<p>
  +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung
tomcat's and require ajp13 
  +ping/pong support which has been implemented on Tomcat <b>3.3.2+, 4.1.28+ and 5.0.13+</b>.
  +Disabled by default.
  +</p>
  +</directive>
  +
  +<directive name="prepost_timeout" required="false">
  +Prepost timeout property told webserver to send a PING request on ajp13 connection before

  +forwarding to it a request. The parameter is the delay in milliseconds to wait for the
PONG reply.
  +<p>
  +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung
tomcat's and require ajp13 
  +ping/pong support which has been implemented on <b>Tomcat 3.3.2+, 4.1.28+ and 5.0.13+</b>.
  +Disabled by default.
  +</p>
  +</directive>
  +
  +<directive name="reply_timeout" required="false">
  +Reply_timeout property told webserver to wait some time for reply to a forwarded request
  +before considering the remote tomcat is dead and eventually switch to another tomcat in
a cluster
  +group. By default webserver will wait forever which could be an issue for you.
  +The parameter is the number of milliseconds to wait for reply, so adjust it carrefully
if you 
  +have long running servlets.
  +<p>
  +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung
tomcat's and works on all
  +servlet engines supporting ajp13.
  +Disabled by default.
  +</p> 
  +</directive>
  +
  +<directive name="recovery_options" default="0" required="false">
  +Recovery options property told webserver how to handle recovery when
  +it detect that tomcat failed.
  +By default, webserver will forward the request to another tomcat in LB mode
  +(or to another ajp thread in ajp13 mode).
  +values are : 0 (full recovery), 1 (don't recover if tomcat failed after getting the request),
  +2 (don't recover if tomcat failed after sending the headers to client), 3 (don't recover
if tomcat failed 
  +getting the request or after sending the headers to client).
  +<p>
  +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung/broken
tomcat's 
  +and works on all servlet engines supporting ajp13.
  +Full recovery by default.
  +</p>
  +</directive>
   
   </directives>
   </subsection>
   
  +<subsection name="Advanced load balancer directives">
  +<p>
  +With JK 1.2.x, new load-balancing and fault-tolerant support has been added via
  +2 new properties, <b>local_worker_only</b> and <b>local_worker</b>.
  +</p>
  + 
  +<directives>
  +<directive name="local_worker" default="False" required="false">
  +If local_worker is set to <b>True</b> it is marked as local worker. 
  +If in minimum one worker is marked as local worker, lb_worker is in local worker mode.

  +All local workers are moved to the beginning of the internal worker list
  +in lb_worker during validation. 
  +</directive>
   
  +<directive name="local_worker_only" default="False" required="false">
  +If local_worker_only is set to <b>True</b> it is marked as local only worker.

  +If all local worker are in error state, and if set to <b>False</b>
  +lb_worker tries to route the request to another balanced worker. If set to
  +<b>True</b> error is returned.
  +</directive>
  +</directives>
  +
  +<p>
  +The <b>local_worker</b> flag on worker tells the <b>lb_worker</b>
which connections
  +are going to the local worker. 
  +</p>
  +<p>
  +This means that if a request with a session id comes in it would be routed to the appropriate
worker. 
  +If this worker is down it will be send to the first local worker which is not in error
state.
  +</p>
  +<p>
  +If a request without a session comes in, it would be routed to the first local worker.

  +If all local worker are in error state, then the <b>local_worker_only</b> flag
is important. 
  +With set to True, this request gets an error response.
  +If set to False lb_worker tries to route the request to another balanced worker.
  +</p>
  +<p>
  +If one of the worker was in error state and has recovered nothing changes. 
  +The local worker will be check for requests without a session id (and with a session on
himself) and 
  +the other worker will only be checked if a request with a session id of this worker comes
in.
  +</p>
  +<p>
  +Why do we need souch a complex behavior ?
  +</p>
  +<p>
  +We need a graceful shut down of a node for maintenance. The balancer in front asks a special
port on each 
  +node periodically. If we want to remove a node from the cluster, we switch off this port.

  +The loadbalancer can't connect to it and marks the node as down. 
  +But we don't move the sessions to another node. In this environment it is an error
  +if the balancer sends a request without a session to an apache+mod_jk+tomcat which
  +port is switched off. And if the load balancer determines that a node is down no
  +other node is allowed to send a request without a session to it. Only requests with
  +old sessions on the switched off node would be routed to this node. After some time
  +nobody uses the old sessions and the sessions will time out.
  +Then nobody uses this node, because all session are gone and the node is
  +unreachable without a session-id in the request. If someone uses a session which
  +timed out, our servlet system sends a redirect response without a session id to the browser.
  +This is necessary, because on a switched off node apache and tomcat can still be up and
running,
  +but they are in an old state and should only be asked for valid old sessions.
  +After the last session timed out, you can update the node etc. without killing
  +sessions or moving them to another node. Sometimes we have a lot of big objects
  +in our sessions, so it would be really time consuming to move them.
  +</p>
  +</subsection>
   </section>
    
   </body>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org


Mime
View raw message