3
<!ENTITY project SYSTEM "project.xml">
5
<document url="workers.html">
10
<author email="mturk@apache.org">Mladen Turk</author>
11
<title>workers.properties configuration</title>
16
<section name="Introduction">
19
A <b>Tomcat worker</b> is a Tomcat instance that is waiting to execute servlets or any other content
20
on behalf of some web server. For example, we can have a web server such as
21
Apache forwarding servlet requests to a Tomcat process (the worker) running behind it.
24
The scenario described above is a very simple one;
25
in fact one can configure multiple Tomcat workers to serve servlets on
26
behalf of a certain web server.
27
The reasons for such configuration can be:
31
We want different contexts to be served by different Tomcat workers to provide a
32
development environment where all the developers share the same web server but
33
own a Tomcat worker of their own.
36
We want different virtual hosts served by different Tomcat processes to provide a
37
clear separation between sites belonging to different companies.
40
We want to provide load balancing, meaning run multiple Tomcat workers each on a
41
machine of its own and distribute the requests between them.
46
There are probably more reasons for having multiple workers but I guess that this list is enough...
47
Tomcat workers are defined in a properties file dubbed <b>workers.properties</b> and this tutorial
48
explains how to work with it.
52
<section name="Directives">
54
<p>Each workers.properties directive consists of three words separated by dot. The first word is always
55
<b>worker</b>. The second word is the worker name that can be any name. The worker name reflects the
56
name of the <b>jvmRoute</b> defined in Tomcat's server.xml configuration file.
60
The name of the worker can contain only the alphanumeric characters <b>[a-z][A-Z][0-9]</b> and is case insensitive.
64
<subsection name="Defining workers">
66
<p>The generic workers.properties directive is in the form:</p>
67
<p><strong>worker.<worker name>.<directive>=<value></strong></p>
68
<p>Defining workers to the Tomcat web server plugin can be done using a properties file
69
(a sample file named workers.properties is available in the conf/ directory).
72
<directive name="worker.list" default="ajp13" required="true">
73
A comma separated list of workers names that the JK will use. When starting up,
74
the web server plugin will instantiate the workers whose name appears in the
75
worker.list property, these are also the workers to whom you can map requests.
77
<directive name="worker.maintain" default="60" required="false">
78
Worker connection pool maintain interval in seconds. If set to the positive
79
value JK will scan all connections for all workers specified in worker.list
80
directive and check if connections needs to be recycled.
82
Furthermore any load balancer does a global maintenance every worker.maintain
83
seconds. During global maintenance load counters are decayed and workers
84
in error are checked for recover_time.
87
This feature has been added in <b>jk 1.2.13</b>.
93
<subsection name="Mandatory directives">
95
<p>Mandatory directives are the one that each worker <b>must</b> contain. Without them the worker will
96
be unavailable or will misbehave.
99
<directive name="type" default="ajp13" required="true">
100
Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker
101
defines the directives that can be applied to the worker.
102
<p>AJP13 worker is the preferred worker type that JK uses for communication
103
between web server and Tomcat. This type of worker uses sockets as communication
104
channel. For detailed description of the AJP13 protocol stack browse to
105
<a href="../common/ajpv13a.html">AJPv13 protocol specification</a>
111
<subsection name="Connection directives">
112
<p>Connection directives defines the parameters needed to connect and maintain
113
the connections pool of persistent connections between JK and remote Tomcat.
117
<directive name="host" default="localhost" required="false">
118
Host name or IP address of the backend Tomcat instance. The remote Tomcat must
119
support the ajp13 protocol stack. The host name can have a <b>port</b> number
120
embedded separated by the colon (':') character.
123
<directive name="port" default="8009" required="false">
124
Port number of the remote Tomcat instance listening for defined protocol requests.
125
The default value depends on the worker type. For AJP13 workers the default port is
126
<b>8009</b>, while for AJP14 type of worker that value is <b>8011</b>.
129
<directive name="socket_timeout" default="0" required="false">
130
Socket timeout in seconds used for communication channel between JK and remote host.
131
If remote host does not respond inside that timeout the JK will generate an error,
132
and retry again. If set to value zero (default) the JK will wait for infinite
133
on all socket operations.
136
<directive name="socket_keepalive" default="False" required="false">
137
This directive should be used when you have a firewall between your webserver
138
and the Tomcat engine, who tend to drop inactive connections. This flag will told Operating System
139
to send <code>KEEP_ALIVE</code> message on inactive connections (interval depend on global OS settings,
140
generally 120 minutes), and thus prevent the firewall to cut the connection.
141
To enable keepalive set this property value to the <b>True</b>.
143
The problem with Firewall cutting inactive connections is that sometimes, neither webserver or tomcat
144
have information about the cut and couldn't handle it.
148
<directive name="retries" default="3" required="false">
149
The number of retries that the worker will try in case of error returned from remote
150
Tomcat. If the number of retries set is greater then three (the default value), on
151
each retry after default an extra wait of 100ms will be inserted.
154
<directive name="connection_pool_size" default="1" required="false">
155
This defines the number of connections made to the AJP backend that
156
are maintained as a connection pool.
157
It will limit the number of those connection that each web server child
160
Connection pool size property is used only for multi threaded
161
web servers such as Apache 2.0 (worker), IIS and Netscape. The connection_pool_size property
162
should reflect the number of threads per child process. JK will discover
163
the number of threads per child process on Apache 2 web server with worker-mpm and set
164
its default value to match the ThreadsPerChild Apache directive. For IIS the default
165
value is 10. For other web servers this value has to be set manually.
167
<warn>Do not use connection_pool_size with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn>
170
<directive name="connection_pool_minsize" default="pool/2" required="false">
171
Minimum size of the connection pool that will be maintained.
173
This property is used only when the <b>connection_pool_size</b> is specified.
174
Its default value is connection_pool_size/2.
176
<warn>Do not use connection_pool_size with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn>
178
This feature has been added in <b>jk 1.2.16</b>.
182
<directive name="connection_pool_timeout" default="0" required="false">
183
Cache timeout property should be used with <b>connection_pool_size</b> to specify how long JK should keep
184
an inactive socket in cache before closing it. This property should be used to reduce the number of threads
185
on the Tomcat WebServer.
187
Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating
188
a new ajp13 thread on Tomcat side.
191
The problem is that after an ajp13 connection is created, the child won't drop it
192
until killed. And since the webserver will keep its childs/threads running
193
to handle high-load, even it the child/thread handle only static contents, you could
194
finish having many unused ajp13 threads on the Tomcat side.
198
<directive name="lbfactor" default="1" required="false">
199
Integer number used when the worker will be used inside load balancer worker,
200
this is the load-balancing factor for the worker.
201
The load-balancing factor is <i>how much we expect this worker to work</i>, or
202
<i>the worker's work quota</i>. Load balancing factor is compared with other workers
203
that makes the load balancer. For example if one worker has lb_factor 5 times higher then
204
other worker, then it will receive five times more requests.
209
<p>Some directives have been deprecated in the past. We include their documentation
210
in case you need to use an older version of mod_jk. We urge you to update and not use
211
them any more. Please migrate your existing configurations.
214
<directive name="recycle_timeout" default="0" required="false">
215
<warn>This directive has been deprecated since 1.2.16. See <b>connection_pool_timeout</b> instead.</warn>
216
The number of seconds that told webserver to cut an ajp13 connection after some time of
217
inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be
218
closed if it was not used for the configured time.
219
It's a good way to ensure that there won't too old threads living on Tomcat side,
220
with the extra cost you need to reopen the socket next time a request be forwarded.
221
This property is very similar to <b>cache_timeout</b> but works also in non-cache mode.
222
If set to value zero (default) no recycle will took place.
225
<directive name="cache_timeout" default="0" required="false">
226
<warn>This directive has been deprecated since 1.2.16. See <b>connection_pool_timeout</b> instead.</warn>
227
Cache timeout property should be used with <b>cachesize</b> to specify how to time JK should keep
228
an open socket in cache before closing it. This property should be used to reduce the number of threads
229
on the Tomcat WebServer.
231
Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating
232
a new ajp13 thread on Tomcat side.
235
The problem is that after an ajp13 connection is created, the child won't drop it
236
until killed. And since the webserver will keep its childs/threads running
237
to handle high-load, even it the child/thread handle only static contents, you could
238
finish having many unused ajp13 threads on the Tomcat side.
242
<directive name="cachesize" default="1" required="false">
243
<warn>This directive has been deprecated since 1.2.16. See <b>connection_pool_size</b> instead.</warn>
244
Cachesize defines the number of connections made to the AJP backend that
245
are maintained as a connection pool.
246
It will limit the number of those connection that each web server child
249
Cachesize property is used only for multi threaded
250
web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property
251
should reflect the number of threads per child process. JK will discover
252
the number of threads per child process on Apache 2 web server with worker-mpm and set
253
its default value to match the ThreadsPerChild Apache directive. For IIS the default
254
value is 10. For other web servers this value has to be set manually.
256
<warn>Do not use cachesize with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn>
262
<subsection name="Load balancing directives">
264
<p>Load balancer is a virtual worker that does not really communicate with Tomcat workers.
265
Instead it is responsible for the management of several "real" workers.
266
The worker is supposed to be a load balancer if it's worker type is <b>lb</b>.
267
See worker's <b>type</b> directive. The workers that
268
are member of load balancer must not appear in the <b>worker.list</b> directive.
270
<p>Loadbalancer directives defines the parameters needed to create a workers that are
271
connecting to a remote cluster of backend Tomcat servers. Each cluster node has to
272
have a worker defined.
275
Load balancer management includes:
280
Instantiating the workers in the web server.
283
Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
284
high lbfactor means stronger machine (that is going to handle more requests)
287
Keeping requests belonging to the same session executing on the same Tomcat worker.
290
Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on
291
other workers managed by the lb worker.
296
The overall result is that workers managed by the same lb worker are load-balanced
297
(based on their lbfactor and current user session) and also fall-backed so a single
298
Tomcat process death will not "kill" the entire site.
299
The following table specifies properties that the lb worker can accept:
303
<directive name="balance_workers" default="" required="true">
304
A comma separated list of workers that the load balancer
307
This directive replaces old <b>balanced_workers</b> directive and
308
can be used only with mod_jk versions 1.2.7 and up.
310
<warn>These workers should <b>not</b> appear in the worker.list property!</warn>
313
<directive name="sticky_session" default="True" required="false">
314
Specifies whether requests with SESSION ID's should be routed back to the same
315
Tomcat worker. If sticky_session is set to <b>True</b> or <b>1</b> sessions are sticky, otherwise
316
sticky_session is set to <b>False</b>. Set sticky_session to <b>False</b> when Tomcat
317
is using a Session Manager which can persist session data across multiple
318
instances of Tomcat. By default sticky_session is set to True.
321
<directive name="sticky_session_force" default="False" required="false">
322
Specifies whether requests with SESSION ID's for workers that are in error state
323
should be rejected. If sticky_session_force is set to <b>True</b> or <b>1</b>
324
and the worker that matches that SESSION ID is in error state, client will
325
recieve 500 (Server Error). If set to <b>False</b> or <b>0</b> failover on
326
another worker will be issued with loosing client session. This directive is
327
used only when you set <b>sticky_session=True</b>.
329
This feature has been added in <b>jk 1.2.9</b>.
333
<directive name="method" default="Request" required="false">
334
Specifies what method load balancer is using for electing best worker.
335
If method is set to <b>R[equest]</b> balancer will use number of requests
336
to find the best worker. If set to <b>T[raffic]</b> balancer will use
337
the network traffic between JK and Tomcat to find the best worker.
338
If set to <b>B[usyness]</b> balancer will
339
pick the worker with the lowest current load, based on how many requests the
340
worker is currently serving. This number is divided by the workers lbfactor,
341
and the lowest value (least busy) worker is picked.
343
This feature has been added in <b>jk 1.2.9</b>.
347
<directive name="lock" default="Optimistic" required="false">
348
Specifies what lock method the load balancer will use for synchronizing
349
shared memory runtime data.
350
If lock is set to <b>O[ptimistic]</b> balancer will not use shared memory lock
351
to find the best worker. If set to <b>P[essimistic]</b> balancer will use
352
shared memory lock. The balancer will work more accurately in case of
353
Pessimistic locking, but can slow down the average response time.
355
This feature has been added in <b>jk 1.2.13</b>.
359
<directive name="secret" default="" required="false">
360
Set a default secret word for all defined workers.
361
See worker secret attribute description for more info.
363
This feature has been added in <b>jk 1.2.12</b>.
371
<subsection name="Status Worker directives">
374
The status worker does not communicate with Tomcat.
375
Instead it is responsible for the load balancer management.
378
<directive name="css" default="" required="false">
379
Specifies the url for cascading stylesheet to use.
384
<subsection name="Advanced worker directives">
387
<directive name="connect_timeout" default="0" required="false">
388
Connect timeout property told webserver to send a PING request on ajp13 connection after
389
connection is established. The parameter is the delay in milliseconds to wait for the PONG reply.
391
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung tomcat's and require ajp13
392
ping/pong support which has been implemented on Tomcat <b>3.3.2+, 4.1.28+ and 5.0.13+</b>.
397
<directive name="prepost_timeout" default="0" required="false">
398
Prepost timeout property told webserver to send a PING request on ajp13 connection before
399
forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply.
401
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung tomcat's and require ajp13
402
ping/pong support which has been implemented on <b>Tomcat 3.3.2+, 4.1.28+ and 5.0.13+</b>.
407
<directive name="reply_timeout" default="0" required="false">
408
Reply_timeout property told webserver to wait some time for reply to a forwarded request
409
before considering the remote tomcat is dead and eventually switch to another tomcat in a cluster
410
group. By default webserver will wait forever which could be an issue for you.
411
The parameter is the number of milliseconds to wait for reply, so adjust it carefully if you
412
have long running servlets.
414
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung tomcat's and works on all
415
servlet engines supporting ajp13.
420
<directive name="recover_time" default="60" required="false">
421
The recover time is the time in seconds the load balancer will not try
422
to use a worker, after it went into error state. Only after this time has passed,
423
a worker in error state will be marked as in recovering, so that it will be
424
tried for new requests.
426
This interval is not checked every time a request is being processed.
427
Instead it is being checked during global maintenance. The time between two
428
runs of global maintenance is controlled by worker.maintain.
431
Do not set recover_time to a very short time unless you understand the implications.
432
Every recovery attempt for a worker in error is done by a real request!
436
<directive name="recovery_options" default="0" required="false">
437
Recovery options property told webserver how to handle recovery when
438
it detect that tomcat failed.
439
By default, webserver will forward the request to another tomcat in LB mode
440
(or to another ajp thread in ajp13 mode).
441
values are : 0 (full recovery), 1 (don't recover if tomcat failed after getting the request),
442
2 (don't recover if tomcat failed after sending the headers to client), 3 (don't recover if tomcat failed
443
getting the request or after sending the headers to client).
445
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung/broken tomcat's
446
and works on all servlet engines supporting ajp13.
447
Full recovery by default.
449
<p>If the value 4 is added to the recovery options, the connection
450
between the webserver and tomcat will be closed if the client connection
451
to the webserver is terminated during the request/response cycle. This allows
452
to inform the servlet engine about broken client connections during lengthy operations.
453
This feature has been added in <b>jk 1.2.16</b>
457
<directive name="distance" default="0" required="false">
458
Express preferences between the balanced workers of an lb worker.
459
A load balancer will never choose some balanced worker
460
in case there is another usable worker with lower distance.
462
Only in case all workers below a given distance are in error, disabled or stopped,
463
workers of a larger distance are eligible for balancing.
467
<directive name="domain" default="" required="false">
468
Domain directive can be used only when the worker is a member of the load balancer.
469
Workers that share the same domain name are treated as single worker. If sticky_session
470
is used, then the domain name is used as session route.
471
<p>This directive is used for large system with more then 6 Tomcats, to be able
472
to cluster the Tomcats in two groups and thus lowering the session replication
473
transfer between them.
476
This feature has been added in <b>jk 1.2.8</b>.
480
<directive name="redirect" default="" required="false">
481
Set to the preferred failover worker. If worker matching SESSION ID is in
482
error state then the redirect worker will be used instead. It will be used
483
even if being disabled, thus offering hot standby.
485
This feature has been added in <b>jk 1.2.9</b>.
489
<directive name="disabled" default="False" required="false">
490
If set to <b>True</b> or <b>1</b> the worker will be disabled if member
491
of load balancer. This flag can be changed at runtime using status worker.
493
This feature has been added in <b>jk 1.2.9</b>.
497
<directive name="stopped" default="False" required="false">
498
If set to <b>True</b> or <b>1</b> the worker will be stopped if member
499
of load balancer. The flag is needed for stop complete traffic of a sticky session
500
worker. It is only usefull, when you have a cluster that replicated the sessions.
501
This flag can be changed at runtime using status worker.
503
This feature has been added in <b>jk 1.2.11</b>.
507
<directive name="jvm_route" default="" required="false">
508
Normally the name of a balanced worker in a load balancer is equal to the jvmRoute
509
of the corresponding Tomcat instance. If you want to include a worker corresponding
510
to a Tomcat instance into several load balancers with different balancing configuration
511
(e.g. disabled, stopped) you can use this attribute.
513
Define a seperate worker per lb and per Tomcat instance with an arbitrary worker name and
514
set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance.
517
If this attribute is left empty, the name of the worker will be used.
520
This feature has been added in <b>jk 1.2.16</b>.
524
<directive name="secret" default="" required="false">
525
If set to AJP Connector secret keyword, only request with this keyword are successfull responding.
526
Use <b>request.useSecret="true"</b> and <b>request.secret="secret key word"</b> at your tomcat ajp
527
Connector configuration.
530
<directive name="mount" default="" required="false">
531
Space delimted list of uri maps the worker should handle
added
removed
xdocs/config/workers.xml
