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