1
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Tomcat Connector - Workers HowTo</title><meta value="Henri Gomez" name="author"><meta value="hgomez@apache.org" name="email"><meta value="Gal Shachor" name="author"><meta value="shachor@il.ibm.com" name="email"><meta value="Mladen Tur" name="author"><meta value="mturk@apache.org" name="email"><link rel="stylesheet" type="text/css" href="../style.css"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="4" width="100%" border="0"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="Apache Tomcat" align="left" src="../images/tomcat.gif"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="http://www.apache.org/images/asf-logo.gif"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Generic Howto</strong></p><ul><li><a href="quick.html">For the impatient</a></li><li><a href="workers.html">All about workers</a></li><li><a href="loadbalancers.html">Load Balancing</a></li></ul><p><strong>Webservers</strong></p><ul><li><a href="apache.html">Apache</a></li><li><a href="iis.html">IIS</a></li><li><a href="domino.html">Domino</a></li><li><a href="nes.html">SunOne (Netscape)</a></li></ul><p><strong>Get Involved</strong></p><ul><li><a href="doccontrib.html">Contribute documentation</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Tomcat Connector</h1><h2>Workers HowTo</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/workers.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
2
</a></small></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
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.
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:
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.
20
We want different virtual hosts served by different Tomcat processes to provide a
21
clear separation between sites belonging to different companies.
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.
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.
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 organizational reasons.
39
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Defining Workers"><strong>Defining Workers</strong></a></font></td></tr><tr><td><blockquote>
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).
46
the file contains entries of the following form:
50
<b>worker.list</b>=<a comma separated list of worker names>
53
<div class="example"><pre>
55
worker.list= worker1, worker2
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.
63
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Workers Type"><strong>Workers Type</strong></a></font></td></tr><tr><td><blockquote>
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):
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>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>
80
Defining workers of a certain type should be done with the following property format:
84
<b>worker</b>. <b>worker name</b>.<b>type</b>=<worker type>
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 not contain any space (a good naming convention for queue named should
87
follow the Java variable naming rules).
90
<div class="example"><pre>
91
# Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
92
worker.local.type=ajp12
93
# Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
94
worker.remote.type=ajp13
95
# Defines a worker named "fast" that uses JNI to forward requests to a Tomcat process.
97
# Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
98
worker.loadbalancer.type=lb
101
</blockquote></td></tr></table>
103
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Setting Worker Properties"><strong>Setting Worker Properties</strong></a></font></td></tr><tr><td><blockquote>
105
After defining the workers you can also specify properties for them.
106
Properties can be specified in the following manner:
110
worker.<worker name>.<property>=<property value>
113
Each worker has a set of properties that you can set as specified in the following subsections:
115
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="ajp12 Worker properties"><strong>ajp12 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
116
<p><p><font color="#ff0000">
117
The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
118
<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5.
121
The ajp12 typed workers forward requests to out-of-process Tomcat workers
122
using the ajpv12 protocol over TCP/IP sockets.
126
the ajp12 worker properties are :
130
<b>host</b> property set the host where the Tomcat worker is listening for ajp12 requests.
134
<b>port</b> property set The port where the Tomcat worker is listening for ajp12 requests
138
<b>lbfactor</b>property is used when working with a load balancer worker, this is the load-balancing factor for the worker.
139
We'll see more on this in the lb worker section.
142
<div class="example"><pre>
143
# worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
144
worker.worker1.host=www.x.com
145
worker.worker1.port=8007
146
worker.worker1.lbfactor=2
150
Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
151
The default port for ajp12 is 8007
154
</blockquote></td></tr></table>
156
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="ajp13 Worker properties"><strong>ajp13 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
158
The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
159
The main difference between ajpv12 and ajpv13 are that:
162
ajpv13 is a more binary protocol and it try to compress some of the request data by coding
163
frequently used strings as small integers.
166
ajpv13 reuse open sockets and leaves them open for future requests (remember when you've got a Firewall between your
167
WebServer and Tomcat).
170
ajpv13 has special treatment for SSL information so that the container can implement
171
SSL related methods such as isSecure().
178
You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x and 5.
182
<div class="example"><pre>
183
# worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
184
worker.worker2.host=www2.x.com
185
worker.worker2.port=8009
186
worker.worker2.lbfactor=3
187
# worker "worker2" use up to 10 sockets, which will stay no more than 10mn in the connection pool
188
worker.worker2.connection_pool_size=10
189
worker.worker2.connection_pool_timeout=600
190
# worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
191
worker.worker2.socket_keepalive=1
192
# mount can be used as an alternative to the JkMount directive
193
worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
197
Notes: In the ajpv13 protocol, the default port is 8009
200
</blockquote></td></tr></table>
202
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="lb Worker properties"><strong>lb Worker properties</strong></a></font></td></tr><tr><td><blockquote>
204
The load-balancing worker does not really communicate with Tomcat workers.
205
Instead it is responsible for the management of several "real" workers.
206
This management includes:
211
Instantiating the workers in the web server.
214
Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
215
high lbfactor means stronger machine (that is going to handle more requests)
218
Keeping requests belonging to the same session executing on the same Tomcat worker.
221
Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on
222
other workers managed by the lb worker.
227
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.
228
The following table specifies properties that the lb worker can accept:
230
<li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
231
These workers should not appear in the worker.list property.</li>
232
<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
233
Tomcat worker. If sticky_session is an flag and if it is set to True and sessions are sticky, otherwise
234
sticky_session is set to false. Set sticky_session to False when Tomcat is using a Session Manager which
235
can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.</li>
239
<div class="example"><pre>
240
The worker balance1 while use "real" workers worker1 and worker2
241
worker.balance1.balance_workers=worker1, worker2
244
</blockquote></td></tr></table>
246
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Advanced lb Worker properties"><strong>Advanced lb Worker properties</strong></a></font></td></tr><tr><td><blockquote>
248
With JK 1.2.x, new load-balancing and fault-tolerant support has been added via
249
2 new properties, <b>redirect</b> and <b>disabled</b>.
253
Let's take an example environment:
257
A cluster with two nodes (worker1+worker2), running a webserver + tomcat tandem on each node and
258
a loadbalancer in front of the nodes.
261
<div class="example"><pre>
262
# The advanced router LB worker
265
# Define a worker using ajp13
266
worker.worker1.port=8009
267
worker.worker1.host=node1.domain.org
268
worker.worker1.type=ajp13
269
worker.worker1.lbfactor=1
270
# Define prefered failover node for worker1
271
worker.worker1.redirect=worker2
273
# Define another worker using ajp13
274
worker.worker2.port=8009
275
worker.worker2.host=node2.domain.org
276
worker.worker2.type=ajp13
277
worker.worker2.lbfactor=1
278
# Disable worker2 for all requests except failover
279
worker.worker2.disabled=True
281
# Define the LB worker
282
worker.router.type=lb
283
worker.router.balance_workers=worker1,worker2
287
The <b>redirect</b> flag on worker1 tells the <b>lb_worker</b> to redirect the requests
288
to worker2 only if worker1 is in error state. In other cases worker2 will not receive
289
any requests, thus acting like a hot standby.
293
</blockquote></td></tr></table>
295
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Status Worker properties"><strong>Status Worker properties</strong></a></font></td></tr><tr><td><blockquote>
297
The status worker does not communicate with Tomcat.
298
Instead it is responsible for the load balancer management.
300
<div class="example"><pre>
301
# Add the status worker to the worker list
303
# Define a 'jkstatus' worker using status
304
worker.jkstatus.type=status
306
<p>Next thing is to mount the requests to the jkstatus worker. For Apache
307
web servers use the:</p>
308
<div class="example"><pre>
309
# Add the jkstatus mount point
310
JkMount /jkmanager/* jkstatus
312
<p>To obtain a higher level of security use the:</p>
313
<div class="example"><pre>
314
# Enable the JK manager access from localhost only
315
<Location /jkmanager/>
323
</blockquote></td></tr></table>
325
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Property file macros"><strong>Property file macros</strong></a></font></td></tr><tr><td><blockquote>
327
You can define "macros" in the property files.
328
These macros let you define properties and later on use them while
329
constructing other properties and it's very usefull when you want to
330
change your Java Home, Tomcat Home or OS path separator
333
<div class="example"><pre>
334
# property example, don't hardcode path separator
336
workers.tomcat_home=d:\tomcat
337
workers.java_home=d:\sdk\jdk1.2.2
338
# Using macros we'll have : worker.inprocess.class_path=d:\tomcat\classes
339
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes
340
# Using macros we'll have : worker.inprocess.class_path=d:\sdk\jdk1.2.2\lib\tools.jar
341
worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar
344
</blockquote></td></tr></table>
346
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="A sample worker.properties"><strong>A sample worker.properties</strong></a></font></td></tr><tr><td><blockquote>
348
Since coping with worker.properties on your own is not an easy thing to do,
349
a sample worker.properties file is bundled along JK.
353
You could also find here a sample workers.properties defining :
358
An ajp12 worker that used the host localhost and the port 8007
361
An ajp13 worker that used the host localhost and the port 8008
367
A lb worker that load balance the ajp12 and ajp13 workers
371
<div class="example"><pre>
372
# Define some properties
373
workers.apache_log=/var/log/httpd/
374
workers.tomcat_home=/var/tomcat3
375
workers.java_home=/opt/IBMJava2-131/
377
# Define 4 workers, 3 real workers using ajp12, ajp13, jni, the last one being a loadbalancing worker
378
worker.list=worker1, worker2, worker3, worker4
379
# Set properties for worker1 (ajp12)
380
worker.worker1.type=ajp12
381
worker.worker1.host=locahost
382
worker.worker1.port=8007
383
worker.worker1.lbfactor=1
384
# Set properties for worker2 (ajp13)
385
worker.worker2.type=ajp13
386
worker.worker2.host=locahost
387
worker.worker2.port=8009
388
worker.worker2.lbfactor=1
389
worker.worker2.connection_pool_size=10
390
worker.worker2.connection_pool_timeout=600
391
worker.worker2.socket_keepalive=1
392
worker.worker2.socket_timeout=60
393
# Set properties for worker3 (jni)
394
worker.worker3.type=jni
395
# Set worker3 bridge type, here Tomcat 3.3
396
worker.worker3.bridge=tomcat33
397
# Set worker3 classpath
398
worker.worker3.class_path=$(workers.tomcat_home)$(ps)classes
399
worker.worker3.class_path=$(workers.tomcat_home)$(ps)lib$(ps)tomcat.jar
400
# Set worker3 tomcat command line
401
worker.worker3.cmd_line=-home
402
worker.worker3.cmd_line=$(workers.tomcat_home)
403
# Set worker3 Tomcat/JVM settings
404
worker.worker3.jvm_lib=$(workers.java_home)$(ps)jre$(ps)bin$(ps)classic$(ps)libjvm.so
405
worker.worker3.stdout=$(workers.apache_log)$(ps)inprocess.stdout
406
worker.worker3.stderr=$(workers.apache_log)$(ps)inprocess.stderr
407
worker.worker3.sysprops=tomcat.home=$(workers.tomcat_home)
408
# Set properties for worker4 (lb) which use worker1 and worker2
409
worker.worker4.balance_workers=worker1,worker2
412
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
413
Copyright © 1999-2005, Apache Software Foundation
414
</em></font></div></td></tr></table></body></html>
b'\\ No newline at end of file'
added
removed
docs/howto/workers.html
