rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/workers.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE document [
   3   <!ENTITY project SYSTEM "project.xml">
   4 ]>
   5 <document url="workers.html">
   6
   7   &project;
   8 <copyright>
   9    Licensed to the Apache Software Foundation (ASF) under one or more
  10    contributor license agreements.  See the NOTICE file distributed with
  11    this work for additional information regarding copyright ownership.
  12    The ASF licenses this file to You under the Apache License, Version 2.0
  13    (the "License"); you may not use this file except in compliance with
  14    the License.  You may obtain a copy of the License at
  15
  16        http://www.apache.org/licenses/LICENSE-2.0
  17
  18    Unless required by applicable law or agreed to in writing, software
  19    distributed under the License is distributed on an "AS IS" BASIS,
  20    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21    See the License for the specific language governing permissions and
  22    limitations under the License.
  23 </copyright>
  24 <properties>
  25 <title>Workers HowTo</title>
  26 <author email="hgomez@apache.org">Henri Gomez</author>
  27 <author email="shachor@il.ibm.com">Gal Shachor</author>
  28 <author email="mturk@apache.org">Mladen Turk</author>
  29 <date>$Date: 2010-01-28 20:47:58 +0100 (Thu, 28 Jan 2010) $</date>
  30 </properties>
  31 <body>
  32 <section name="Introduction">
  33 <p>
  34 A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
  35 For example, we can have a web server such as Apache forwarding servlet requests to a
  36 Tomcat process (the worker) running behind it.
  37 </p>
  38 <p>
  39 The scenario described above is a very simple one;
  40 in fact one can configure multiple Tomcat workers to serve servlets on
  41 behalf of a certain web server.
  42 The reasons for such configuration can be:
  43 </p>
  44 <ul>
  45 <li>
  46 We want different contexts to be served by different Tomcat workers to provide a
  47 development environment where all the developers share the same web server but own a Tomcat worker of their own.
  48 </li>
  49 <li>
  50 We want different virtual hosts served by different Tomcat processes to provide a
  51 clear separation between sites belonging to different companies.
  52 </li>
  53 <li>
  54 We want to provide load balancing, meaning run multiple Tomcat workers each on a
  55 machine of its own and distribute the requests between them.
  56 </li>
  57 </ul>
  58
  59 <p>
  60 There are probably more reasons for having multiple workers but I guess that this list is enough...
  61 Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
  62 explains how to work with it.
  63 </p>
  64
  65 <p>
  66 This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
  67 but has been split off for organisational reasons.
  68 </p>
  69 </section>
  70
  71 <section name="Defining Workers">
  72 <p>
  73 Defining workers to the Tomcat web server plugin can be done using a properties file
  74 (a sample file named workers.properties is available in the conf/ directory).
  75 </p>
  76
  77 <p>
  78 the file contains entries of the following form:
  79 </p>
  80
  81 <p>
  82 <b>worker.list</b>=&lt;a comma separated list of worker names&gt;
  83 </p>
  84
  85 <source>
  86   # the list of workers
  87   worker.list= worker1, worker2
  88 </source>
  89
  90 <p>
  91 When starting up, the web server plugin will instantiate the workers whose name appears in the
  92 <b>worker.list</b> property, these are also the workers to whom you can map requests. The directive can be used multiple times.
  93 </p>
  94
  95 <subsection name="Workers Type">
  96 <p>
  97 Each named worker should also have a few entries to provide additional information on his behalf.
  98 This information includes the worker's type and other related worker information.
  99 Currently the following worker types that exists are (JK 1.2.5):
 100 </p>
 101
 102 <table>
 103   <tr><th>Type</th><th>Description</th></tr>
 104   <tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.</td></tr>
 105   <tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.</td></tr>
 106   <tr><td>jni</td><td>DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI.</td></tr>
 107   <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>
 108   <tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
 109 </table>
 110
 111 <p>
 112 Defining workers of a certain type should be done with the following property format:
 113 </p>
 114
 115 <p>
 116 <b>worker</b>.<b>worker name</b>.<b>type</b>=&lt;worker type&gt;
 117 Where worker name is the name assigned to the worker and the worker type is one of the four types defined
 118 in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).
 119 </p>
 120
 121 <source>
 122   # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
 123   worker.local.type=ajp12
 124   # Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
 125   worker.remote.type=ajp13
 126   # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
 127   worker.loadbalancer.type=lb
 128 </source>
 129
 130 </subsection>
 131
 132 </section>
 133
 134 <section name="Setting Worker Properties">
 135 <p>
 136 After defining the workers you can also specify properties for them.
 137 Properties can be specified in the following manner:
 138 </p>
 139
 140 <p>
 141 worker.&lt;worker name&gt;.&lt;property&gt;=&lt;property value&gt;
 142 </p>
 143
 144 Each worker has a set of properties that you can set as specified in the following subsections:
 145
 146 <subsection name="ajp12 Worker properties">
 147 <p><warn>
 148 The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
 149 <b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6.
 150 </warn></p>
 151 <p>
 152 The ajp12 typed workers forward requests to out-of-process Tomcat workers
 153 using the ajpv12 protocol over TCP/IP sockets.
 154 </p>
 155
 156 <p>
 157 the ajp12 worker properties are :
 158 </p>
 159
 160 <p>
 161 <b>host</b> property sets the host where the Tomcat worker is listening for ajp12 requests.
 162 </p>
 163
 164 <p>
 165 <b>port</b> property sets the port where the Tomcat worker is listening for ajp12 requests
 166 </p>
 167
 168 <p>
 169 <b>lbfactor</b> property is used when working with a load balancer worker, this is the load-balancing factor for the worker.
 170 We'll see more on this in the <a href="../generic_howto/loadbalancers.html">lb worker</a> section.
 171 </p>
 172
 173 <source>
 174   # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
 175   worker.worker1.host=www.x.com
 176   worker.worker1.port=8007
 177   worker.worker1.lbfactor=2
 178 </source>
 179
 180 <p>
 181 Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
 182 The default port for ajp12 is 8007
 183 </p>
 184
 185 </subsection>
 186
 187 <subsection name="ajp13 Worker properties">
 188 <p>
 189 The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
 190 The main difference between ajpv12 and ajpv13 are that:
 191 <ul>
 192 <li>
 193 ajpv13 is a more binary protocol and it tries to compress some of the request data by coding
 194 frequently used strings as small integers.
 195 </li>
 196 <li>
 197 ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
 198 web server and Tomcat).
 199 </li>
 200 <li>
 201 ajpv13 has special treatment for SSL information so that the container can implement
 202 SSL related methods such as isSecure().
 203 </li>
 204 </ul>
 205
 206 </p>
 207
 208 <p>
 209 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.
 210 </p>
 211
 212
 213 <source>
 214   # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
 215   worker.worker2.host=www2.x.com
 216   worker.worker2.port=8009
 217   worker.worker2.lbfactor=3
 218   # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
 219   worker.worker2.connection_pool_timeout=600
 220   # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
 221   worker.worker2.socket_keepalive=1
 222   # mount can be used as an alternative to the JkMount directive
 223   worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
 224 </source>
 225
 226 <p>
 227 Notes: In the ajpv13 protocol, the default port is 8009
 228 </p>
 229
 230 </subsection>
 231
 232 <subsection name="lb Worker properties">
 233 <p>
 234 The load-balancing worker does not really communicate with Tomcat workers.
 235 Instead it is responsible for the management of several "real" workers.
 236 This management includes:
 237 </p>
 238
 239 <ul>
 240 <li>
 241 Instantiating the workers in the web server.
 242 </li>
 243 <li>
 244 Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
 245 high lbfactor means stronger machine (that is going to handle more requests)
 246 </li>
 247 <li>
 248 Keeping requests belonging to the same session executing on the same Tomcat worker.
 249 </li>
 250 <li>
 251 Identifying failed Tomcat workers, suspending requests to them and instead falling-back on
 252 other workers managed by the lb worker.
 253 </li>
 254 </ul>
 255
 256 <p>
 257 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.
 258 The following table specifies some properties that the lb worker can accept:
 259 <ul>
 260 <li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
 261 As long as these workers should only be used via the load balancer worker,
 262 there is no need to also put them into the worker.list property.
 263 This directive can be used multiple times for the same load balancer.</li>
 264 <li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
 265 Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which
 266 can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.</li>
 267 </ul>
 268 </p>
 269
 270 <source>
 271   # The worker balance1 while use "real" workers worker1 and worker2
 272   worker.balance1.balance_workers=worker1, worker2
 273 </source>
 274
 275 </subsection>
 276
 277 <subsection name="Status Worker properties">
 278 <p>
 279 The status worker does not communicate with Tomcat.
 280 Instead it is responsible for the load balancer management.
 281 </p>
 282 <source>
 283   # Add the status worker to the worker list
 284   worker.list=jkstatus
 285   # Define a 'jkstatus' worker using status
 286   worker.jkstatus.type=status
 287 </source>
 288 <p>Next thing is to mount the requests to the jkstatus worker. For Apache
 289 web servers use the:</p>
 290 <source>
 291   # Add the jkstatus mount point
 292   JkMount /jkmanager/* jkstatus
 293 </source>
 294 <p>To obtain a higher level of security use the:</p>
 295 <source>
 296   # Enable the JK manager access from localhost only
 297  &lt;Location /jkmanager/&gt;
 298     JkMount jkstatus
 299     Order deny,allow
 300     Deny from all
 301     Allow from 127.0.0.1
 302  &lt;/Location&gt;
 303 </source>
 304
 305 </subsection>
 306
 307 <subsection name="Property file macros">
 308 <p>
 309 You can define "macros" in the property files.
 310 These macros let you define properties and later on use them while
 311 constructing other properties.
 312 </p>
 313
 314 <source>
 315   # property example, like a network base address
 316   mynet=194.226.31
 317   # Using the above macro to simplify the address definitions
 318   # for a farm of workers.
 319   worker.node1.host=$(mynet).11
 320   worker.node2.host=$(mynet).12
 321   worker.node3.host=$(mynet).13
 322 </source>
 323
 324 </subsection>
 325
 326 <subsection name="Hierarchical property configuration">
 327 <p>
 328 Workers can reference configurations of other workers.
 329 If worker "x" references worker "y", then it inherits all
 330 configuration parameters from "y", except for the ones
 331 that have explicitly been set for "x".
 332 </p>
 333
 334 <source>
 335   # worker toe defines some default settings
 336   worker.toe.type=ajp13
 337   worker.toe.socket_keepalive=true
 338   worker.toe.connect_timeout=10000
 339   worker.toe.recovery_options=7
 340   # workers tic and tac inherit those values
 341   worker.tic.reference=worker.toe
 342   worker.tac.reference=worker.toe
 343 </source>
 344
 345 <p>
 346 Please note, that the reference contains
 347 the full prefix to the referenced configuration attributes,
 348 not only the name of the referenced worker.
 349 </p>
 350
 351 <p>
 352 References can be nested. Be careful to avoid loops!
 353 </p>
 354
 355 <p>
 356 Attributes which are allowed multiple times for a single worker
 357 can not be merged from a worker and a reference. An attribute
 358 is only inherited from a reference, if it is not already set
 359 for the referring worker.
 360 </p>
 361
 362 <p>
 363 References are especially useful, when configuring load balancers.
 364 Try to understand the following two stage references:
 365 </p>
 366
 367 <source>
 368   # We only use one load balancer
 369   worker.list=lb
 370   # Let's define some defaults
 371   worker.basic.port=8009
 372   worker.basic.type=ajp13
 373   worker.basic.socket_keepalive=true
 374   worker.basic.connect_timeout=10000
 375   worker.basic.recovery_options=7
 376   # And we use them in two groups
 377   worker.lb1.domain=dom1
 378   worker.lb1.distance=0
 379   worker.lb1.reference=worker.basic
 380   worker.lb2.domain=dom2
 381   worker.lb2.distance=1
 382   worker.lb2.reference=worker.basic
 383   # Now we configure the load balancer
 384   worker.lb.type=lb
 385   worker.lb.method=B
 386   worker.lb.balanced_workers=w11,w12,w21,w22
 387   worker.w11.host=myhost11
 388   worker.w11.reference=worker.lb1
 389   worker.w12.host=myhost12
 390   worker.w12.reference=worker.lb1
 391   worker.w21.host=myhost21
 392   worker.w21.reference=worker.lb2
 393   worker.w22.host=myhost22
 394   worker.w22.reference=worker.lb2
 395 </source>
 396
 397 </subsection>
 398
 399 </section>
 400
 401 <section name="A sample worker.properties">
 402 <p>
 403 Since coping with worker.properties on your own is not an easy thing to do,
 404 a sample worker.properties file is bundled along JK.
 405 </p>
 406
 407 <p>
 408 You could also find here a sample workers.properties defining :
 409 </p>
 410
 411 <ul>
 412 <li>
 413 An ajp12 worker that used the host localhost and the port 8007
 414 </li>
 415 <li>
 416 An ajp13 worker that used the host localhost and the port 8008
 417 </li>
 418 <li>
 419 An lb worker that load balance the ajp12 and ajp13 workers
 420 </li>
 421 </ul>
 422
 423 <source>
 424   # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker
 425   worker.list=worker1, worker2, worker3
 426   # Set properties for worker1 (ajp12)
 427   worker.worker1.type=ajp12
 428   worker.worker1.host=localhost
 429   worker.worker1.port=8007
 430   worker.worker1.lbfactor=1
 431   # Set properties for worker2 (ajp13)
 432   worker.worker2.type=ajp13
 433   worker.worker2.host=localhost
 434   worker.worker2.port=8009
 435   worker.worker2.lbfactor=1
 436   worker.worker2.connection_pool_timeout=600
 437   worker.worker2.socket_keepalive=1
 438   worker.worker2.socket_timeout=60
 439   # Set properties for worker3 (lb) which use worker1 and worker2
 440   worker.worker3.balance_workers=worker1,worker2
 441 </source>
 442
 443 </section>
 444 </body>
 445 </document>