1
<?xml version="1.0" encoding="ISO-8859-1"?>
3
<!ENTITY project SYSTEM "project.xml">
5
<document url="workers.html">
9
Copyright 1999-2004 The Apache Software Foundation
11
Licensed under the Apache License, Version 2.0 (the "License");
12
you may not use this file except in compliance with the License.
13
You may obtain a copy of the License at
15
http://www.apache.org/licenses/LICENSE-2.0
17
Unless required by applicable law or agreed to in writing, software
18
distributed under the License is distributed on an "AS IS" BASIS,
19
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20
See the License for the specific language governing permissions and
21
limitations under the License.
24
<title>Workers HowTo</title>
25
<author email="hgomez@apache.org">Henri Gomez</author>
26
<author email="shachor@il.ibm.com">Gal Shachor</author>
27
<author email="mturk@apache.org">Mladen Tur</author>
28
<date>$Date: 2005/04/25 06:53:25 $</date>
31
<section name="Introduction">
33
A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
34
For example, we can have a web server such as Apache forwarding servlet requests to a
35
Tomcat process (the worker) running behind it.
38
The scenario described above is a very simple one;
39
in fact one can configure multiple Tomcat workers to serve servlets on
40
behalf of a certain web server.
41
The reasons for such configuration can be:
45
We want different contexts to be served by different Tomcat workers to provide a
46
development environment where all the developers share the same web server but own a Tomcat worker of their own.
49
We want different virtual hosts served by different Tomcat processes to provide a
50
clear separation between sites belonging to different companies.
53
We want to provide load balancing, meaning run multiple Tomcat workers each on a
54
machine of its own and distribute the requests between them.
59
There are probably more reasons for having multiple workers but I guess that this list is enough...
60
Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
61
explains how to work with it.
65
This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
66
but has been split off for organizational reasons.
70
<section name="Defining Workers">
72
Defining workers to the Tomcat web server plugin can be done using a properties file
73
(a sample file named workers.properties is available in the conf/ directory).
77
the file contains entries of the following form:
81
<b>worker.list</b>=<a comma separated list of worker names>
86
worker.list= worker1, worker2
90
When starting up, the web server plugin will instantiate the workers whose name appears in the
91
<b>worker.list</b> property, these are also the workers to whom you can map requests.
94
<subsection name="Workers Type">
96
Each named worker should also have a few entries to provide additional information on his behalf.
97
This information includes the worker's type and other related worker information.
98
Currently the following worker types that exists are (JK 1.2.5):
102
<tr><th>Type</th><th>Description</th></tr>
103
<tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.</td></tr>
104
<tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.</td></tr>
105
<tr><td>jni</td><td>This worker knows how to forward requests to in-process Tomcat workers using JNI.</td></tr>
106
<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>
107
<tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
111
Defining workers of a certain type should be done with the following property format:
115
<b>worker</b>. <b>worker name</b>.<b>type</b>=<worker type>
116
Where worker name is the name assigned to the worker and the worker type is one of the four types defined
117
in the table (a worker name may not contain any space (a good naming convention for queue named should
118
follow the Java variable naming rules).
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 "fast" that uses JNI to forward requests to a Tomcat process.
128
# Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
129
worker.loadbalancer.type=lb
136
<section name="Setting Worker Properties">
138
After defining the workers you can also specify properties for them.
139
Properties can be specified in the following manner:
143
worker.<worker name>.<property>=<property value>
146
Each worker has a set of properties that you can set as specified in the following subsections:
148
<subsection name="ajp12 Worker properties">
150
The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
151
<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5.
154
The ajp12 typed workers forward requests to out-of-process Tomcat workers
155
using the ajpv12 protocol over TCP/IP sockets.
159
the ajp12 worker properties are :
163
<b>host</b> property set the host where the Tomcat worker is listening for ajp12 requests.
167
<b>port</b> property set The port where the Tomcat worker is listening for ajp12 requests
171
<b>lbfactor</b>property is used when working with a load balancer worker, this is the load-balancing factor for the worker.
172
We'll see more on this in the lb worker section.
176
# worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
177
worker.worker1.host=www.x.com
178
worker.worker1.port=8007
179
worker.worker1.lbfactor=2
183
Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
184
The default port for ajp12 is 8007
189
<subsection name="ajp13 Worker properties">
191
The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
192
The main difference between ajpv12 and ajpv13 are that:
195
ajpv13 is a more binary protocol and it try to compress some of the request data by coding
196
frequently used strings as small integers.
199
ajpv13 reuse open sockets and leaves them open for future requests (remember when you've got a Firewall between your
200
WebServer and Tomcat).
203
ajpv13 has special treatment for SSL information so that the container can implement
204
SSL related methods such as isSecure().
211
You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x and 5.
216
# worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
217
worker.worker2.host=www2.x.com
218
worker.worker2.port=8009
219
worker.worker2.lbfactor=3
220
# worker "worker2" use up to 10 sockets, which will stay no more than 10mn in cache
221
worker.worker2.cachesize=10
222
worker.worker2.cache_timeout=600
223
# worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
224
worker.worker2.socket_keepalive=1
225
# worker "worker2" want ajp13 connection to be dropped after 5mn (recycle)
226
worker.worker2.recycle_timeout=300
230
Notes: In the ajpv13 protocol, the default port is 8009
235
<subsection name="lb Worker properties">
237
The load-balancing worker does not really communicate with Tomcat workers.
238
Instead it is responsible for the management of several "real" workers.
239
This management includes:
244
Instantiating the workers in the web server.
247
Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
248
high lbfactor means stronger machine (that is going to handle more requests)
251
Keeping requests belonging to the same session executing on the same Tomcat worker.
254
Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on
255
other workers managed by the lb worker.
260
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.
261
The following table specifies properties that the lb worker can accept:
263
<li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
264
These workers should not appear in the worker.list property.</li>
265
<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
266
Tomcat worker. If sticky_session is an flag and if it is set to True and sessions are sticky, otherwise
267
sticky_session is set to false. Set sticky_session to False when Tomcat is using a Session Manager which
268
can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.</li>
273
The worker balance1 while use "real" workers worker1 and worker2
274
worker.balance1.balance_workers=worker1, worker2
279
<subsection name="Advanced lb Worker properties">
281
With JK 1.2.x, new load-balancing and fault-tolerant support has been added via
282
2 new properties, <b>redirect</b> and <b>disabled</b>.
286
Let's take an example environment:
290
A cluster with two nodes (worker1+worker2), running a webserver + tomcat tandem on each node and
291
a loadbalancer in front of the nodes.
295
# The advanced router LB worker
298
# Define a worker using ajp13
299
worker.worker1.port=8009
300
worker.worker1.host=node1.domain.org
301
worker.worker1.type=ajp13
302
worker.worker1.lbfactor=1
303
# Define prefered failover node for worker1
304
worker.worker1.redirect=worker2
306
# Define another worker using ajp13
307
worker.worker2.port=8009
308
worker.worker2.host=node2.domain.org
309
worker.worker2.type=ajp13
310
worker.worker2.lbfactor=1
311
# Disable worker2 for all requests except failover
312
worker.worker2.disabled=True
314
# Define the LB worker
315
worker.router.type=lb
316
worker.router.balance_workers=worker1,worker2
320
The <b>redirect</b> flag on worker1 tells the <b>lb_worker</b> to redirect the requests
321
to worker2 only if worker1 is in error state. In other cases worker2 will not receive
322
any requests, thus acting like a hot standby.
328
<subsection name="Status Worker properties">
330
The status worker does not communicate with Tomcat.
331
Instead it is responsible for the load balancer management.
334
# Add the status worker to the worker list
336
# Define a 'jkstatus' worker using status
337
worker.jkstatus.type=status
339
<p>Next thing is to mount the requests to the jkstatus worker. For Apache
340
web servers use the:</p>
342
# Add the jkstatus mount point
343
JkMount /jkmanager/* jkstatus
345
<p>To obtain a higher level of security use the:</p>
347
# Enable the JK manager access from localhost only
348
<Location /jkmanager/>
358
<subsection name="Property file macros">
360
You can define "macros" in the property files.
361
These macros let you define properties and later on use them while
362
constructing other properties and it's very usefull when you want to
363
change your Java Home, Tomcat Home or OS path separator
367
# property example, don't hardcode path separator
369
workers.tomcat_home=d:\tomcat
370
workers.java_home=d:\sdk\jdk1.2.2
371
# Using macros we'll have : worker.inprocess.class_path=d:\tomcat\classes
372
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes
373
# Using macros we'll have : worker.inprocess.class_path=d:\sdk\jdk1.2.2\lib\tools.jar
374
worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar
381
<section name="A sample worker.properties">
383
Since coping with worker.properties on your own is not an easy thing to do,
384
a sample worker.properties file is bundled along JK.
388
You could also find here a sample workers.properties defining :
393
An ajp12 worker that used the host localhost and the port 8007
396
An ajp13 worker that used the host localhost and the port 8008
402
A lb worker that load balance the ajp12 and ajp13 workers
407
# Define some properties
408
workers.apache_log=/var/log/httpd/
409
workers.tomcat_home=/var/tomcat3
410
workers.java_home=/opt/IBMJava2-131/
412
# Define 4 workers, 3 real workers using ajp12, ajp13, jni, the last one being a loadbalancing worker
413
worker.list=worker1, worker2, worker3, worker4
414
# Set properties for worker1 (ajp12)
415
worker.worker1.type=ajp12
416
worker.worker1.host=locahost
417
worker.worker1.port=8007
418
worker.worker1.lbfactor=1
419
# Set properties for worker2 (ajp13)
420
worker.worker2.type=ajp13
421
worker.worker2.host=locahost
422
worker.worker2.port=8009
423
worker.worker2.lbfactor=1
424
worker.worker2.cachesize=10
425
worker.worker2.cache_timeout=600
426
worker.worker2.socket_keepalive=1
427
worker.worker2.socket_timeout=60
428
# Set properties for worker3 (jni)
429
worker.worker3.type=jni
430
# Set worker3 bridge type, here Tomcat 3.3
431
worker.worker3.bridge=tomcat33
432
# Set worker3 classpath
433
worker.worker3.class_path=$(workers.tomcat_home)$(ps)classes
434
worker.worker3.class_path=$(workers.tomcat_home)$(ps)lib$(ps)tomcat.jar
435
# Set worker3 tomcat command line
436
worker.worker3.cmd_line=-home
437
worker.worker3.cmd_line=$(workers.tomcat_home)
438
# Set worker3 Tomcat/JVM settings
439
worker.worker3.jvm_lib=$(workers.java_home)$(ps)jre$(ps)bin$(ps)classic$(ps)libjvm.so
440
worker.worker3.stdout=$(workers.apache_log)$(ps)inprocess.stdout
441
worker.worker3.stderr=$(workers.apache_log)$(ps)inprocess.stderr
442
worker.worker3.sysprops=tomcat.home=$(workers.tomcat_home)
443
# Set properties for worker4 (lb) which use worker1 and worker2
444
worker.worker4.balance_workers=worker1,worker2
added
removed
jk/xdocs/howto/workers.xml
