rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/workers.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Workers HowTo</title><meta name="author" value="Henri Gomez"><meta name="email" value="hgomez@apache.org"><meta name="author" value="Gal Shachor"><meta name="email" value="shachor@il.ibm.com"><meta name="author" value="Mladen Turk"><meta name="email" value="mturk@apache.org"><link href="../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Reference Guide</strong></p><ul><li><a href="../reference/workers.html">workers.properties</a></li><li><a href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a href="../reference/status.html">Status Worker</a></li><li><a href="../reference/apache.html">Apache HTTP Server</a></li><li><a href="../reference/iis.html">IIS</a></li></ul><p><strong>Generic HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the impatient</a></li><li><a href="../generic_howto/workers.html">All about workers</a></li><li><a href="../generic_howto/timeouts.html">Timeouts</a></li><li><a href="../generic_howto/loadbalancers.html">Load Balancing</a></li><li><a href="../generic_howto/proxy.html">Reverse Proxy</a></li></ul><p><strong>Webserver HowTo</strong></p><ul><li><a href="../webserver_howto/apache.html">Apache HTTP Server</a></li><li><a href="../webserver_howto/iis.html">IIS</a></li><li><a href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>AJP Protocol Reference</strong></p><ul><li><a href="../ajp/ajpv13a.html">AJPv13</a></li><li><a href="../ajp/ajpv13ext.html">AJPv13 Extension Proposal</a></li></ul><p><strong>Miscellaneous Documentation</strong></p><ul><li><a href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a href="../miscellaneous/changelog.html">Changelog</a></li><li><a href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;product=Tomcat+Connectors&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;emailassigned_to1=1&amp;emailtype1=substring&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailcc2=1&amp;emailtype2=substring&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=">Current Tomcat Connectors bugs</a></li><li><a href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html">Old JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a href="../news/20110701.html">2011</a></li><li><a href="../news/20100101.html">2010</a></li><li><a href="../news/20090301.html">2009</a></li><li><a href="../news/20081001.html">2008</a></li><li><a href="../news/20070301.html">2007</a></li><li><a href="../news/20060101.html">2006</a></li><li><a href="../news/20050101.html">2005</a></li><li><a href="../news/20041100.html">2004</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Generic HowTo</h1><h2>Workers HowTo</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/workers.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
   2                     </a></small></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
   3 <p>
   4 A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
   5 For example, we can have a web server such as Apache forwarding servlet requests to a
   6 Tomcat process (the worker) running behind it.
   7 </p>
   8 <p>
   9 The scenario described above is a very simple one;
  10 in fact one can configure multiple Tomcat workers to serve servlets on
  11 behalf of a certain web server.
  12 The reasons for such configuration can be:
  13 </p>
  14 <ul>
  15 <li>
  16 We want different contexts to be served by different Tomcat workers to provide a
  17 development environment where all the developers share the same web server but own a Tomcat worker of their own.
  18 </li>
  19 <li>
  20 We want different virtual hosts served by different Tomcat processes to provide a
  21 clear separation between sites belonging to different companies.
  22 </li>
  23 <li>
  24 We want to provide load balancing, meaning run multiple Tomcat workers each on a
  25 machine of its own and distribute the requests between them.
  26 </li>
  27 </ul>
  28
  29 <p>
  30 There are probably more reasons for having multiple workers but I guess that this list is enough...
  31 Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
  32 explains how to work with it.
  33 </p>
  34
  35 <p>
  36 This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
  37 but has been split off for organisational reasons.
  38 </p>
  39 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Defining Workers"><strong>Defining Workers</strong></a></font></td></tr><tr><td><blockquote>
  40 <p>
  41 Defining workers to the Tomcat web server plugin can be done using a properties file
  42 (a sample file named workers.properties is available in the conf/ directory).
  43 </p>
  44
  45 <p>
  46 the file contains entries of the following form:
  47 </p>
  48
  49 <p>
  50 <b>worker.list</b>=&lt;a comma separated list of worker names&gt;
  51 </p>
  52
  53 <div class="example"><pre>
  54   # the list of workers
  55   worker.list= worker1, worker2
  56 </pre></div>
  57
  58 <p>
  59 When starting up, the web server plugin will instantiate the workers whose name appears in the
  60 <b>worker.list</b> property, these are also the workers to whom you can map requests. The directive can be used multiple times.
  61 </p>
  62
  63 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Workers Type"><strong>Workers Type</strong></a></font></td></tr><tr><td><blockquote>
  64 <p>
  65 Each named worker should also have a few entries to provide additional information on his behalf.
  66 This information includes the worker's type and other related worker information.
  67 Currently the following worker types that exists are (JK 1.2.5):
  68 </p>
  69
  70 <table>
  71   <tr><th>Type</th><th>Description</th></tr>
  72   <tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.</td></tr>
  73   <tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.</td></tr>
  74   <tr><td>jni</td><td>DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI.</td></tr>
  75   <tr><td>lb</td><td>This is a load-balancing worker; it knows how to provide round-robin based sticky load balancing with a certain level of fault-tolerance.</td></tr>
  76   <tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
  77 </table>
  78
  79 <p>
  80 Defining workers of a certain type should be done with the following property format:
  81 </p>
  82
  83 <p>
  84 <b>worker</b>.<b>worker name</b>.<b>type</b>=&lt;worker type&gt;
  85 Where worker name is the name assigned to the worker and the worker type is one of the four types defined
  86 in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).
  87 </p>
  88
  89 <div class="example"><pre>
  90   # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
  91   worker.local.type=ajp12
  92   # Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
  93   worker.remote.type=ajp13
  94   # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
  95   worker.loadbalancer.type=lb
  96 </pre></div>
  97
  98 </blockquote></td></tr></table>
  99
 100 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Setting Worker Properties"><strong>Setting Worker Properties</strong></a></font></td></tr><tr><td><blockquote>
 101 <p>
 102 After defining the workers you can also specify properties for them.
 103 Properties can be specified in the following manner:
 104 </p>
 105
 106 <p>
 107 worker.&lt;worker name&gt;.&lt;property&gt;=&lt;property value&gt;
 108 </p>
 109
 110 Each worker has a set of properties that you can set as specified in the following subsections:
 111
 112 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="ajp12 Worker properties"><strong>ajp12 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
 113 <p><p><font color="#ff0000">
 114 The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
 115 <b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6.
 116 </font></p></p>
 117 <p>
 118 The ajp12 typed workers forward requests to out-of-process Tomcat workers
 119 using the ajpv12 protocol over TCP/IP sockets.
 120 </p>
 121
 122 <p>
 123 the ajp12 worker properties are :
 124 </p>
 125
 126 <p>
 127 <b>host</b> property sets the host where the Tomcat worker is listening for ajp12 requests.
 128 </p>
 129
 130 <p>
 131 <b>port</b> property sets the port where the Tomcat worker is listening for ajp12 requests
 132 </p>
 133
 134 <p>
 135 <b>lbfactor</b> property is used when working with a load balancer worker, this is the load-balancing factor for the worker.
 136 We'll see more on this in the <a href="../generic_howto/loadbalancers.html">lb worker</a> section.
 137 </p>
 138
 139 <div class="example"><pre>
 140   # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
 141   worker.worker1.host=www.x.com
 142   worker.worker1.port=8007
 143   worker.worker1.lbfactor=2
 144 </pre></div>
 145
 146 <p>
 147 Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
 148 The default port for ajp12 is 8007
 149 </p>
 150
 151 </blockquote></td></tr></table>
 152
 153 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="ajp13 Worker properties"><strong>ajp13 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
 154 <p>
 155 The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
 156 The main difference between ajpv12 and ajpv13 are that:
 157 <ul>
 158 <li>
 159 ajpv13 is a more binary protocol and it tries to compress some of the request data by coding
 160 frequently used strings as small integers.
 161 </li>
 162 <li>
 163 ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
 164 web server and Tomcat).
 165 </li>
 166 <li>
 167 ajpv13 has special treatment for SSL information so that the container can implement
 168 SSL related methods such as isSecure().
 169 </li>
 170 </ul>
 171
 172 </p>
 173
 174 <p>
 175 You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6.
 176 </p>
 177
 178
 179 <div class="example"><pre>
 180   # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
 181   worker.worker2.host=www2.x.com
 182   worker.worker2.port=8009
 183   worker.worker2.lbfactor=3
 184   # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
 185   worker.worker2.connection_pool_timeout=600
 186   # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
 187   worker.worker2.socket_keepalive=1
 188   # mount can be used as an alternative to the JkMount directive
 189   worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
 190 </pre></div>
 191
 192 <p>
 193 Notes: In the ajpv13 protocol, the default port is 8009
 194 </p>
 195
 196 </blockquote></td></tr></table>
 197
 198 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="lb Worker properties"><strong>lb Worker properties</strong></a></font></td></tr><tr><td><blockquote>
 199 <p>
 200 The load-balancing worker does not really communicate with Tomcat workers.
 201 Instead it is responsible for the management of several "real" workers.
 202 This management includes:
 203 </p>
 204
 205 <ul>
 206 <li>
 207 Instantiating the workers in the web server.
 208 </li>
 209 <li>
 210 Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
 211 high lbfactor means stronger machine (that is going to handle more requests)
 212 </li>
 213 <li>
 214 Keeping requests belonging to the same session executing on the same Tomcat worker.
 215 </li>
 216 <li>
 217 Identifying failed Tomcat workers, suspending requests to them and instead falling-back on
 218 other workers managed by the lb worker.
 219 </li>
 220 </ul>
 221
 222 <p>
 223 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.
 224 The following table specifies some properties that the lb worker can accept:
 225 <ul>
 226 <li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
 227 As long as these workers should only be used via the load balancer worker,
 228 there is no need to also put them into the worker.list property.
 229 This directive can be used multiple times for the same load balancer.</li>
 230 <li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
 231 Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which
 232 can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.</li>
 233 </ul>
 234 </p>
 235
 236 <div class="example"><pre>
 237   # The worker balance1 while use "real" workers worker1 and worker2
 238   worker.balance1.balance_workers=worker1, worker2
 239 </pre></div>
 240
 241 </blockquote></td></tr></table>
 242
 243 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Status Worker properties"><strong>Status Worker properties</strong></a></font></td></tr><tr><td><blockquote>
 244 <p>
 245 The status worker does not communicate with Tomcat.
 246 Instead it is responsible for the load balancer management.
 247 </p>
 248 <div class="example"><pre>
 249   # Add the status worker to the worker list
 250   worker.list=jkstatus
 251   # Define a 'jkstatus' worker using status
 252   worker.jkstatus.type=status
 253 </pre></div>
 254 <p>Next thing is to mount the requests to the jkstatus worker. For Apache
 255 web servers use the:</p>
 256 <div class="example"><pre>
 257   # Add the jkstatus mount point
 258   JkMount /jkmanager/* jkstatus
 259 </pre></div>
 260 <p>To obtain a higher level of security use the:</p>
 261 <div class="example"><pre>
 262   # Enable the JK manager access from localhost only
 263  &lt;Location /jkmanager/&gt;
 264     JkMount jkstatus
 265     Order deny,allow
 266     Deny from all
 267     Allow from 127.0.0.1
 268  &lt;/Location&gt;
 269 </pre></div>
 270
 271 </blockquote></td></tr></table>
 272
 273 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Property file macros"><strong>Property file macros</strong></a></font></td></tr><tr><td><blockquote>
 274 <p>
 275 You can define "macros" in the property files.
 276 These macros let you define properties and later on use them while
 277 constructing other properties.
 278 </p>
 279
 280 <div class="example"><pre>
 281   # property example, like a network base address
 282   mynet=194.226.31
 283   # Using the above macro to simplify the address definitions
 284   # for a farm of workers.
 285   worker.node1.host=$(mynet).11
 286   worker.node2.host=$(mynet).12
 287   worker.node3.host=$(mynet).13
 288 </pre></div>
 289
 290 </blockquote></td></tr></table>
 291
 292 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Hierarchical property configuration"><strong>Hierarchical property configuration</strong></a></font></td></tr><tr><td><blockquote>
 293 <p>
 294 Workers can reference configurations of other workers.
 295 If worker "x" references worker "y", then it inherits all
 296 configuration parameters from "y", except for the ones
 297 that have explicitly been set for "x".
 298 </p>
 299
 300 <div class="example"><pre>
 301   # worker toe defines some default settings
 302   worker.toe.type=ajp13
 303   worker.toe.socket_keepalive=true
 304   worker.toe.connect_timeout=10000
 305   worker.toe.recovery_options=7
 306   # workers tic and tac inherit those values
 307   worker.tic.reference=worker.toe
 308   worker.tac.reference=worker.toe
 309 </pre></div>
 310
 311 <p>
 312 Please note, that the reference contains
 313 the full prefix to the referenced configuration attributes,
 314 not only the name of the referenced worker.
 315 </p>
 316
 317 <p>
 318 References can be nested. Be careful to avoid loops!
 319 </p>
 320
 321 <p>
 322 Attributes which are allowed multiple times for a single worker
 323 can not be merged from a worker and a reference. An attribute
 324 is only inherited from a reference, if it is not already set
 325 for the referring worker.
 326 </p>
 327
 328 <p>
 329 References are especially useful, when configuring load balancers.
 330 Try to understand the following two stage references:
 331 </p>
 332
 333 <div class="example"><pre>
 334   # We only use one load balancer
 335   worker.list=lb
 336   # Let's define some defaults
 337   worker.basic.port=8009
 338   worker.basic.type=ajp13
 339   worker.basic.socket_keepalive=true
 340   worker.basic.connect_timeout=10000
 341   worker.basic.recovery_options=7
 342   # And we use them in two groups
 343   worker.lb1.domain=dom1
 344   worker.lb1.distance=0
 345   worker.lb1.reference=worker.basic
 346   worker.lb2.domain=dom2
 347   worker.lb2.distance=1
 348   worker.lb2.reference=worker.basic
 349   # Now we configure the load balancer
 350   worker.lb.type=lb
 351   worker.lb.method=B
 352   worker.lb.balanced_workers=w11,w12,w21,w22
 353   worker.w11.host=myhost11
 354   worker.w11.reference=worker.lb1
 355   worker.w12.host=myhost12
 356   worker.w12.reference=worker.lb1
 357   worker.w21.host=myhost21
 358   worker.w21.reference=worker.lb2
 359   worker.w22.host=myhost22
 360   worker.w22.reference=worker.lb2
 361 </pre></div>
 362
 363 </blockquote></td></tr></table>
 364
 365 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="A sample worker.properties"><strong>A sample worker.properties</strong></a></font></td></tr><tr><td><blockquote>
 366 <p>
 367 Since coping with worker.properties on your own is not an easy thing to do,
 368 a sample worker.properties file is bundled along JK.
 369 </p>
 370
 371 <p>
 372 You could also find here a sample workers.properties defining :
 373 </p>
 374
 375 <ul>
 376 <li>
 377 An ajp12 worker that used the host localhost and the port 8007
 378 </li>
 379 <li>
 380 An ajp13 worker that used the host localhost and the port 8008
 381 </li>
 382 <li>
 383 An lb worker that load balance the ajp12 and ajp13 workers
 384 </li>
 385 </ul>
 386
 387 <div class="example"><pre>
 388   # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker
 389   worker.list=worker1, worker2, worker3
 390   # Set properties for worker1 (ajp12)
 391   worker.worker1.type=ajp12
 392   worker.worker1.host=localhost
 393   worker.worker1.port=8007
 394   worker.worker1.lbfactor=1
 395   # Set properties for worker2 (ajp13)
 396   worker.worker2.type=ajp13
 397   worker.worker2.host=localhost
 398   worker.worker2.port=8009
 399   worker.worker2.lbfactor=1
 400   worker.worker2.connection_pool_timeout=600
 401   worker.worker2.socket_keepalive=1
 402   worker.worker2.socket_timeout=60
 403   # Set properties for worker3 (lb) which use worker1 and worker2
 404   worker.worker3.balance_workers=worker1,worker2
 405 </pre></div>
 406
 407 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
 408         Copyright &copy; 1999-2011, Apache Software Foundation
 409         </em></font></div></td></tr></table></body></html>