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
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Reference Guide - workers.properties configuration</title><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 - Reference Guide</h1><h2>workers.properties configuration</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>
<br>
<p>
A <b>Tomcat worker</b> is a Tomcat instance that is waiting to execute servlets or any other content
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...
</p>
<p>
Tomcat workers are defined in a properties file dubbed <b>workers.properties</b> and this tutorial
explains how to work with it.
</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="Configuration File Basics"><strong>Configuration File Basics</strong></a></font></td></tr><tr><td><blockquote>
<br>
<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>
<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Format, Comments, Whitespace"><strong>Format, Comments, Whitespace</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
The lines in the file define properties. The general format is
</p>
<p><strong><name>=<value></strong></p>
<p>
</p>
Dots are used as part of the name to represent a configuration hierarchy.
<p>
Invalid directives will be logged during web server startup and prevent the web server
from working properly. Some directives have been deprecated. Although they will
still work, you should replace them by their
<a href="#Deprecated Worker Directives">successors</a>.
</p>
<p>
Some directives are allowed multiple times. This will be explicitly
noted in the tables below.
</p>
<p>
Whitespace at the beginning and the end of a property name or value gets ignored.
Comments can be placed in any line and start with a hash sign '#'.
Any line contents behind the hash sign get ignored.
</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="Global Properties"><strong>Global Properties</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
These directives have global scope.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="75%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>worker.list</code></strong></td><td align="center" valign="center"><code>ajp13</code></td><td align="left" valign="center">
A comma separated list of workers names that the JK will use. When starting up,
the web server plugin will instantiate the workers whose name appears in the
worker.list property, these are also the workers to whom you can map requests.
<p>
This directive can be used multiple times.
</p>
</td></tr><tr><td align="left" valign="center"><code>worker.maintain</code></td><td align="center" valign="center"><code>60</code></td><td align="left" valign="center">
Worker connection pool maintain interval in seconds. If set to the positive
value JK will scan all connections for all workers specified in worker.list
directive and check if connections needs to be recycled.
<p>
Furthermore any load balancer does a global maintenance every worker.maintain
seconds. During global maintenance load counters are decayed and workers
in error are checked for recover_time.
</p>
<p>
This feature has been added in <b>jk 1.2.13</b>.
</p>
</td></tr></table>
</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="Worker Properties"><strong>Worker Properties</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
Each worker configuration directive consists of three words separated by a dot:
</p>
<p><strong>worker.<worker name>.<directive>=<value></strong></p>
<p>
The first word is always <b>worker</b>.
The second word is the worker name you can choose. In the case of load-balancing,
the worker name has an additional meaning. Please consult the
<a href="../../generic_howto/loadbalancers.html">Load Balancer HowTo</a>.
</p>
<p><font color="#ff0000">
The name of the worker can contain only the alphanumeric characters
<b>[a-z][A-Z][0-9][_\-]</b> and is case sensitive.
</font></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="Variables, Environment Variables"><strong>Variables, Environment Variables</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
You can define and use variables in the workers.properties file.
To define a variable you use the syntax:
</p>
<p><strong><variable_name>=<value></strong></p>
<p>
Dots are allowed in the variable name, but you have to be careful
not to use variable names, that clash with standard directives.
Therefore variable names should never start with "worker.".
</p>
<p>
To use a variable, you can insert "$(variable_name)" at any place
on the value side of a property line. If a variable has not been
defined before its use, we will search the process environment for
a variable with the same name and use their value.
</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="Property Inheritance"><strong>Property Inheritance</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>Often one wants to use the same property values for various workers.
To reduce duplication of configuration lines and to ease the maintenance of
the file, you can inherit properties from one worker to another, or even
from a template to real workers.
</p>
<p>
The directive "reference" allows to copy configurations between workers
in a hierarchical way. If worker castor sets <b>worker.castor.reference=worker.pollux</b>
then it inherits all properties of <b>pollux</b>, except for the ones that
are explicitly set for <b>castor</b>.
</p>
<p>
Please note, that the value of the directive is not only the name of the referred worker,
but the complete prefix including "worker.".
</p>
<p>
To use a template worker simply define it like a real worker, but do not add it
to the "worker.list" or as a member to any load balancer. Such a template worker
does not have to contain mandatory directives. This approach is especially useful,
if one has a lot of balanced workers in a load balancer
and these workers share most of their properties. You can set all of these properties
in a template worker, e.g. using the prefix "worker.template1", and then simply
reference those common properties in all balanced workers.
</p>
<p>
References can be used to inherit properties over multiple hops in a hierarchical way.
</p>
<p>
This feature has been added in <b>jk 1.2.19</b>.
</p>
</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="List of All Worker Directives"><strong>List of All Worker Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Mandatory Directives"><strong>Mandatory Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>Mandatory directives are the one that each worker <b>must</b> contain. Without them the worker will
be unavailable or will misbehave. Those directives will be marked with a <strong>strong</strong> font in the following tables.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="75%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="center" valign="center"><code>ajp13</code></td><td align="left" valign="center">
Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker
defines the directives that can be applied to the worker.
<p>AJP13 worker is the preferred worker type that JK uses for communication
between web server and Tomcat. This type of worker uses sockets as communication
channel. For detailed description of the AJP13 protocol stack browse to
<a href="../../ajp/ajpv13a.html">AJPv13 protocol specification</a>
</p>
<p><font color="#ff0000">JNI workers have been deprecated. They will likely not work. Do not use them.</font></p>
</td></tr></table>
</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="Connection Directives"><strong>Connection Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>Connection directives defines the parameters needed to connect and maintain
the connections pool of persistent connections between JK and remote Tomcat.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="75%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>host</code></td><td align="center" valign="center"><code>localhost</code></td><td align="left" valign="center">
Host name or IP address of the backend Tomcat instance. The remote Tomcat must
support the ajp13 protocol stack. The host name can have a <b>port</b> number
embedded separated by the colon (':') character.
</td></tr><tr><td align="left" valign="center"><code>port</code></td><td align="center" valign="center"><code>8009</code></td><td align="left" valign="center">
Port number of the remote Tomcat instance listening for defined protocol requests.
The default value depends on the worker type. For AJP13 workers the default port is
<b>8009</b>, while for AJP14 type of worker that value is <b>8011</b>.
</td></tr><tr><td align="left" valign="center"><code>socket_timeout</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Socket timeout in seconds used for the communication channel between JK and remote host.
If the remote host does not respond inside the timeout specified, JK will generate an error,
and retry again. If set to zero (default) JK will wait for an infinite amount of time
on all socket operations.
</td></tr><tr><td align="left" valign="center"><code>socket_connect_timeout</code></td><td align="center" valign="center"><code>socket_timeout*1000</code></td><td align="left" valign="center">
Socket connect timeout in milliseconds used for the communication channel between JK and remote host.
If the remote host does not respond inside the timeout specified, JK will generate an error,
and retry again.
<p>
Note that <b class="code">socket_timeout</b> is in seconds, and
<b class="code">socket_connect_timeout</b> in milliseconds,
so in absolute terms the default <b class="code">socket_connect_timeout</b> is
equal to <b class="code">"socket_timeout</b>.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>socket_keepalive</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
This directive should be used when you have a firewall between your webserver
and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System
to send <b class="code">KEEP_ALIVE</b> messages on inactive connections (interval depend on global OS settings,
generally 120 minutes), and thus prevent the firewall to cut inactive connections.
To enable keepalive set this property value to <b>True</b>.
<p>
The problem with Firewall cutting inactive connections is that sometimes, neither webserver or Tomcat
have information about the cut and couldn't handle it.
</p>
</td></tr><tr><td align="left" valign="center"><code>ping_mode</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
This flag determines, under which conditions established
connections are probed to ensure they are still working.
The probe is done with an empty AJP13 packet (CPing) and
expects to receive an appropriate answer (CPong) within
some timeout.
<p>
The value of the flag can be any combination of the following
flags (multiple values are combined without any separators):
</p>
<p><b>C</b> (connect): If set, the connection will
be probed once after connecting to the backend. The timeout
can be set by <b class="code">connect_timeout</b>. If it is not set,
the value of <b class="code">ping_timeout</b> will be used instead.
</p>
<p><b>P</b> (prepost): If set, the connection will
be probed before sending each request to the backend. The timeout
can be set by <b class="code">prepost_timeout</b>. If it is not set,
the value of <b class="code">ping_timeout</b> will be used instead.
</p>
<p><b>I</b> (interval): If set, the connection will
be probed during the regular internal maintenance cycle,
but only if it is idle longer than
<b class="code">connection_ping_interval</b>. The timeout
can be set by <b class="code">ping_timeout</b>.
</p>
<p><b>A</b> If set, all of the above probes will be used.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>. Connect and
prepost probing were already available via <b class="code">connect_timeout</b>
and <b class="code">prepost_timeout</b> since version <b>jk 1.2.6</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>ping_timeout</code></td><td align="center" valign="center"><code>10000</code></td><td align="left" valign="center">
Timeout in milliseconds used when waiting for the CPong answer of a
CPing connection probe. The activation of the probes is done via
<b class="code">ping_mode</b>. The timeouts for <b class="code">ping_mode</b>
connect and prepost can be overwritten individually via
<b class="code">connect_timeout</b> and <b class="code">prepost_timeout</b>.
<p>
For compatibility reasons, CPing/CPong is also used, whenever
<b class="code">connect_timeout</b> or <b class="code">prepost_timeout</b> are set,
even if <b class="code">ping_mode</b> is empty.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>connection_ping_interval</code></td><td align="center" valign="center"><code>0 / (ping_timeout/1000)*10</code></td><td align="left" valign="center">
When using interval connection probing, connections idle for longer than this
interval in seconds are probed by CPing packets whether they still work.
<p>Interval probing can be activated either by <b class="code">ping_mode</b>,
or by setting <b class="code">connection_ping_interval</b> to some value bigger
than zero. If you activate interval probing via <b class="code">ping_mode</b>,
then the default value of <b class="code">connection_ping_interval</b> is
<b class="code">(ping_timeout/1000) * 10</b>. Note that <b class="code">ping_timeout</b>
is in milliseconds, and <b class="code">connection_ping_interval</b> in seconds,
so in absolute terms the default <b class="code">connection_ping_interval</b> is
10 times <b class="code">ping_timeout</b>.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>connection_pool_size</code></td><td align="center" valign="center"><code>see text</code></td><td align="left" valign="center">
This defines the number of connections made to the AJP backend that
are maintained as a connection pool.
It will limit the number of those connection that each web server child
process can made.
<p>
Connection pool size property is only used for multi threaded
web servers such as Apache, IIS and Netscape/Sun. The connection_pool_size property
needs to reflect the number of requests one web server process should
be able to send to a backend in parallel. Usually this is the same as
the number of threads per web server process. JK will discover
this number for the Apache web server automatically and set the pool size to
this value. For IIS the default value is 250 (before version 1.2.20: 10),
for Netscape/Sun the default value is 1.
</p>
<p>We strongly recommend adjusting this value for IIS and the Netscape/Sun
to the number of requests one web server process should
be able to send to a backend in parallel. You should measure how many connections
you need during peak activity without performance problems, and then add some
percentage depending on your growth rate. Finally you should check,
whether your web server processes are able to use at least as many threads,
as you configured as the pool size.
</p>
<p><font color="#ff0000">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>!</font></p>
</td></tr><tr><td align="left" valign="center"><code>connection_pool_minsize</code></td><td align="center" valign="center"><code>(pool+1)/2</code></td><td align="left" valign="center">
Minimum size of the connection pool that will be maintained.
<p>
Its default value is (connection_pool_size+1)/2.
</p>
<p><font color="#ff0000">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>!</font></p>
<p>
This feature has been added in <b>jk 1.2.16</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>connection_pool_timeout</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Cache timeout property should be used with <b>connection_pool_minsize</b> to specify how many seconds JK should keep
an inactive socket in cache before closing it. This property should be used to reduce the number of threads
on the Tomcat web server. The default value zero disables the closing (infinite timeout).
<p>
Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating
a new ajp13 thread on Tomcat side.
</p>
<p>
The problem is that after an ajp13 connection is created, the child won't drop it
until killed. And since the webserver will keep its childs/threads running
to handle high-load, even it the child/thread handle only static contents, you could
finish having many unused ajp13 threads on the Tomcat side.
</p>
<p>
You should keep this time interval in sync with the <b>connectionTimeout</b> attribute
of your AJP connector in Tomcat's server.xml. Note however, that the value
for mod_jk is given in seconds, the one in server.xml has to use milliseconds.
</p>
</td></tr><tr><td align="left" valign="center"><code>connection_acquire_timeout</code></td><td align="center" valign="center"><code>retries*retry_interval</code></td><td align="left" valign="center">
Timeout the worker will wait for a free socket in cache before giving up.
<p>
Its default value is <b>retries * retry_interval</b>.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>lbfactor</code></td><td align="center" valign="center"><code>1</code></td><td align="left" valign="center">
Only used for a member worker of a load balancer.
<p>
The integer number lbfactor (load-balancing factor) is
<i>how much we expect this worker to work</i>, or
<i>the worker's work quota</i>. Load balancing factor is compared with other workers
that makes the load balancer. For example if one worker has lb_factor 5 times higher then
other worker, then it will receive five times more requests.
</p>
</td></tr></table>
</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="Load Balancing Directives"><strong>Load Balancing Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>Load balancer is a virtual worker that does not really communicate with Tomcat workers.
Instead it is responsible for the management of several "real" workers.
The worker is supposed to be a load balancer if it's worker type is <b>lb</b>.
See worker's <b>type</b> directive.
</p>
<p>Loadbalancer directives define the parameters needed to create the workers that are
connecting to a remote cluster of backend Tomcat servers. Each cluster node has to
have a worker defined.
</p>
<p>
Load balancer 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 fall-backing 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.
</p>
<p><font color="#ff0000">
If you want to use session stickiness, you must set different jvmRoute attributes
in the Engine element in Tomcat's server.xml. Furthermore the names of the workers
which are managed by the balancer have to be equal to the jvmRoute of the Tomcat
instance they connect with.
</font></p>
<p>
The restriction on the worker names can be lifted, if you use the route attribute for the workers.
</p>
<p>
The following table specifies properties that the lb worker can accept:
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="75%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>balance_workers</code></strong></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
A comma separated list of workers that the load balancer
need to manage.
<p>
This directive can be used multiple times for the same load balancer.
</p>
<p>
This directive replaces old <b>balanced_workers</b> directive and
can be used only with mod_jk versions 1.2.7 and up.
</p>
<p><font color="#ff0000">As long as these workers should only be used via the load balancer worker,
there is no need to also put them into the <b>worker.list</b> property.</font></p>
</td></tr><tr><td align="left" valign="center"><code>sticky_session</code></td><td align="center" valign="center"><code>True</code></td><td align="left" valign="center">
Specifies whether requests with SESSION ID's should be routed back to the same
Tomcat worker. If sticky_session is set to <b>True</b> or <b>1</b> sessions are sticky, otherwise
sticky_session is set to <b>False</b>. Set sticky_session to <b>False</b> when Tomcat
is using a Session Manager which can persist session data across multiple
instances of Tomcat.
</td></tr><tr><td align="left" valign="center"><code>sticky_session_force</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
Specifies whether requests with SESSION ID's for workers that are in error state
should be rejected. If sticky_session_force is set to <b>True</b> or <b>1</b>
and the worker that matches that SESSION ID is in error state, client will
receive 500 (Server Error). If set to <b>False</b> or <b>0</b> failover on
another worker will be issued with loosing client session. This directive is
used only when you set <b>sticky_session=True</b>.
<p>
This feature has been added in <b>jk 1.2.9</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>method</code></td><td align="center" valign="center"><code>Request</code></td><td align="left" valign="center">
Specifies what method load balancer is using for electing the best worker.
Please note, that session stickiness and perfect load balancing are
conflicting targets, especially when the number
of sessions is small, or the usage of sessions is extremely varying
For huge numbers of sessions this usually is not a problem.
<p>
Some methods note, that they aggregate in a sliding time window. They add up
accesses, and on each run of the global maintain method, the load counters
get divided by 2. Usually this happens once a minute, depending on the
setting of worker.maintain. The value of the load counters can be inspected
using the status worker.
</p>
<p>
If method is set to <b>R[equest]</b> the balancer will use number of requests
to find the best worker. Accesses will be distributed according to the
lbfactor in a sliding time window. This is the default value and should be
working well for most applications.
</p>
<p>
If method is set to <b>S[ession]</b> the balancer will use number of sessions
to find the best worker. Accesses will be distributed according to the
lbfactor in a sliding time window. Because the balancer does not keep any state,
it actually does not know the number of sessions. Instead it counts each request
without a session cookie or URL encoding as a new session. This method will neither
know, when a session is being invalidated, nor will it correct its load numbers
according to session timeouts or worker failover. This method should be used,
if sessions are your limiting resource, e.g. when you only have limited memory
and your sessions need a lot of memory.
</p>
<p>
If set to <b>T[raffic]</b> the balancer will use
the network traffic between JK and Tomcat to find the best worker.
Accesses will be distributed according to the lbfactor in a sliding time window.
This method should be used, if network to and from the backends is your
limiting resource.
</p>
<p>
If set to <b>B[usyness]</b> the balancer will
pick the worker with the lowest current load, based on how many requests the
worker is currently serving. This number is divided by the workers lbfactor,
and the lowest value (least busy) worker is picked. This method is especially
interesting, if your request take a long time to process, like for a download
application.
</p>
<p>
This feature has been added in <b>jk 1.2.9</b>.
The Session method has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>lock</code></td><td align="center" valign="center"><code>Optimistic</code></td><td align="left" valign="center">
Specifies what lock method the load balancer will use for synchronising
shared memory runtime data.
If lock is set to <b>O[ptimistic]</b> balancer will not use shared memory lock
to find the best worker. If set to <b>P[essimistic]</b> balancer will use
shared memory lock. The balancer will work more accurately in case of
Pessimistic locking, but can slow down the average response time.
<p>
This feature has been added in <b>jk 1.2.13</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>retries</code></td><td align="center" valign="center"><code>2</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive also exists for normal workers.
For those it has a <a href="#Advanced Worker Directives">different meaning</a>.</font></p>
If the load balancer can not get a valid member worker or in case of failover,
it will try again a number of times given by <b>retries</b>.
Before each retry, it will make a pause define by <b>retry_interval</b> directive.
<p>
Until version <b>1.2.16</b> the default value was 3.
</p>
</td></tr></table>
</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 Directives"><strong>Status Worker Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
The status worker does not communicate with Tomcat.
Instead it is responsible for the load balancer management.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="75%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>css</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
Specifies the url for cascading stylesheet to use.
</td></tr><tr><td align="left" valign="center"><code>read_only</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
A status worker with read_only=True will not allow any operations,
that change the runtime state or configuration of the other workers.
These are edit/update/reset/recover.
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>user</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
It is a list of users
which gets compared to the user name authenticated by the web server.
If the name is not contained in this list, access is denied. Per
default the list is empty and then access is allowed to anybody.
<p>
This directive can be used multiple times.
</p>
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>user_case_insensitive</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
By default, the user names are matched case sensitively. You can set
user_case_insensitive=True to make the comparison case insensitive.
This may be especially useful on the Windows platform.
<p>
This feature has been added in <b>jk 1.2.21</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>good</code></td><td align="center" valign="center"><code>a.o,a.n,a.b,a.r</code></td><td align="left" valign="center">
For every load balancer worker, the status worker shows a summary
of the state of its members. There are three such states,
"good", "bad" and "degraded".
<p>
These states are determined depending on the activation of the members
(active, disabled, stopped) and their runtime state
(ok, n/a, busy, recovering, probing, forced recovery, error).
By default, members are assumed to be "good", if their activation
is "active" and their runtime state is not "error".
</p>
<p>
You can change this mapping, by assigning a list of values to the
attribute "good". Each value gives a possible match for the members,
and one match suffices. Each value is either a single character, or two
characters combined with a dot ".". The single characters are the
first characters in the words "active", "disabled", "stopped",
"ok", "na", "busy", "recovering", "error". The additional states "probing"
and "forced recovery" are always rated equivalent to "recovering".
If a value consists only
of a single character, then all members with this activation or runtime
state will be assumed good. A combination of an activation and a runtime
state concatenated with a dot "." does only apply to a member, that has
exactly this activation and state.
</p>
<p>
Members of a load balancer will first be matched against the state "bad",
if they don't match, the state "good" will be tried, and if they
still don't match, their state will be "degraded".
</p>
<p>
This directive can be used multiple times.
</p>
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>bad</code></td><td align="center" valign="center"><code>s,e</code></td><td align="left" valign="center">
See: "good".
<p>
By default, members are assumed to be "bad", if their activation
is "stopped" or their runtime state is "error".
</p>
<p>
This directive can be used multiple times.
</p>
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>prefix</code></td><td align="center" valign="center"><code>worker</code></td><td align="left" valign="center">
The prefix, which will be used by the status worker
when producing properties output (mime=prop).
Each property key will be prefixed by this value.
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>ns</code></td><td align="center" valign="center"><code>jk:</code></td><td align="left" valign="center">
This directive can be used to customise the XML output from the
status worker. If set to <b>-</b> no namespace will be used.
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>xmlns</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
This directive can be used to customise the XML output from the
status worker. If set to <b>-</b> no xmlns will be used.
<p>
Default value is set to xmlns:jk="http://tomcat.apache.org"
</p>
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>doctype</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
This directive can be used to customise the XML output from the
status worker. This value will be inserted to the output xml
after the xml header.
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
</td></tr></table>
</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="Advanced Worker Directives"><strong>Advanced Worker Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>
This table lists more advanced configuration options. Most of them only apply to
some types of workers. We use the abbreviations <b>AJP</b> for ajp13/ajp14 workers
used directly via the workers.list, <b>LB</b> for load balancer workers,
and <b>SUB</b> for the workers used indirectly in a load balancer worker
as a sub worker or member.
</p>
<table border="1" cellpadding="5"><tr><th width="10%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Worker Type</font></th><th width="8%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="72%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>connect_timeout</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Connect timeout property told webserver to send a PING request on ajp13 connection after
connection is established. The parameter is the delay in milliseconds to wait for the PONG reply.
The default value zero disables the timeout (infinite timeout).
<p>
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13
ping/pong support which has been implemented on Tomcat <b>3.3.2+, 4.1.28+ and 5.0.13+</b>.
Disabled by default.
</p>
</td></tr><tr><td align="left" valign="center"><code>prepost_timeout</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Prepost timeout property told webserver to send a PING request on ajp13 connection before
forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply.
The default value zero disables the timeout (infinite timeout).
<p>
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13
ping/pong support which has been implemented on <b>Tomcat 3.3.2+, 4.1.28+ and 5.0.13+</b>.
Disabled by default.
</p>
</td></tr><tr><td align="left" valign="center"><code>reply_timeout</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
The parameter is the number of milliseconds to wait for success during a read event.
So this is not a timeout for the complete answer time of a request, but only
for the maximum time between two packets received from Tomcat. Usually the longest
pause is between sending the request and getting the first packet of the response.
<p>
If the timeout passes without any data received from Tomcat, the webserver will
no longer wait for the rest of the response and send an error to the client (browser).
Usually this does not mean, that the request is also aborted on the Tomcat backend.
If the worker is a member of a load balancer, the load balancer might place the
worker into an error state and retry the request on another member.
See also <b>max_reply_timeouts</b>, <b>retries</b> and <b>recovery_options</b>.
</p>
<p>
By default (value zero) the webserver will wait forever which could be an issue for you.
If you set a reply_timeout, adjust it carefully if you have long running servlets.
</p>
<p>
The reply_timeout can be overwritten using the Apache httpd environment variable
JK_REPLY_TIMEOUT.
</p>
<p>
This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and works on all
servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT has been added in version <b>1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>retries</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>2</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive also exists for load balancer workers.
For those it has a <a href="#Load Balancing Directives">different meaning</a>.</font></p>
The maximum number of times that the worker will send a request to Tomcat
in case of a communication error. Each retry will be done over another
connection. The first time already gets counted, so retries=2 means
one retry after error. Before a retry, the worker waits for a configurable
sleeping time.
<p>
See also the attribute <b>recovery_options</b> for a more fine-grained control
of retries and <b>retry_interval</b> for the sleep time configuration.
</p>
<p>
Until version <b>1.2.16</b> the default value was 3.
</p>
</td></tr><tr><td align="left" valign="center"><code>retry_interval</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>100</code></td><td align="left" valign="center">
The amount of time in milliseconds the worker sleeps before doing any retry.
<p>
This features has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>recovery_options</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Recovery options influence, how we should handle retries,
in case we detect a problem with Tomcat.
How often we will retry is controlled by the attribute <b>retries</b>.
<p>
This attribute is a bit mask. The following bits are allowed:<br>
1: don't recover if Tomcat failed after getting the request<br>
2: don't recover if Tomcat failed after sending the headers to client<br>
4: close the connection to Tomcat, if we detect an error when writing back
the answer to the client (browser)<br>
8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set)<br>
16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set)<br>
</p>
<p>
This features has been added in <b>jk 1.2.6</b>.
Option 4 has been added in version <b>1.2.16</b>,
options 8 and 16 in version <b>1.2.24</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>fail_on_status</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
Set this value to the HTTP status code that will cause a worker to fail
if returned from Servlet container. Use this directive to deal with
cases when the servlet container can temporary return non-200 responses
for a short amount of time, e.g during redeployment.
<p>
The error page, headers and status codes of the original response will not be send back
to the client. Instead the request will result in a 503 response.
If the worker is a member of a load balancer, the member will
be put into an error state. Request failover and worker recovery will be handled
with the usual load balancer procedures.
</p>
<p>
This feature has been added in <b>jk 1.2.20</b>.
</p>
<p>
Starting with <b>jk 1.2.22</b> it is possible to define multiple
status codes separated by space or comma characters.
For example: <b class="code">worker.xxx.fail_on_status=500,503</b>
</p>
<p>
Starting with <b>jk 1.2.25</b> you can also tell the load
balancer to not put a member into an error state, if a
response returned with one of the status codes in
fail_on_status. This feature gets enabled, by putting a minus sign in
front of those status codes.
For example: <b class="code">worker.xxx.fail_on_status=-404,-500,503</b>
</p>
</td></tr><tr><td align="left" valign="center"><code>max_packet_size</code></td><td align="left" valign="center"><code>AJP,SUB</code></td><td align="center" valign="center"><code>8192</code></td><td align="left" valign="center">
This attribute sets the maximal AJP packet size in Bytes.
The maximum value is 65536. If you change it from the default,
you <b>must</b> also change the packetSize attribute of your AJP
connector on the Tomcat side! The attribute packetSize is only available
in Tomcat 5.5.20+ and 6.0.2+.
<p>
Normally it is not necessary to change the maximum packet size. Problems
with the default value have been reported when sending certificates or
certificate chains.
</p>
<p>
This feature has been added in <b>jk 1.2.19</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>mount</code></td><td align="left" valign="center"><code>AJP,LB</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
Space delimited list of uri maps the worker should handle. It is only used,
if the worker is included in worker.list.
<p>
This directive can be used multiple times for the same worker.
</p>
</td></tr><tr><td align="left" valign="center"><code>secret</code></td><td align="left" valign="center"><code>AJP,LB,SUB</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
You can set a secret keyword on the Tomcat AJP Connector. Then only requests
from workers with the same secret keyword will be accepted.
<p>
Use <b>request.secret="secret key word"</b> in your Tomcat AJP Connector configuration.
</p>
<p>
If you set a secret on a load balancer, all its members will inherit this secret.
</p>
<p>
This feature has been added in <b>jk 1.2.12</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>max_reply_timeouts</code></td><td align="left" valign="center"><code>LB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
If you use a <b>reply_timeout</b> for the members of a load balancer worker,
and you want to tolerate a few requests taking longer than reply_timeout,
you can set this attribute to some positive value.
<p>
Long running requests will still time out after reply_timeout milliseconds waiting for
data, but the corresponding member worker will only be put into an error state,
if more than <b>max_reply_timeouts</b> requests have timed out.
More precisely, the counter for those bad requests will be divided by two,
whenever the load balancer does its internal maintenance (by default every 60
seconds).
</p>
<p>
This features has been added in <b>jk 1.2.24</b> to make <b>reply_timeout</b> less
sensitive for sporadic long running requests.
</p>
</td></tr><tr><td align="left" valign="center"><code>recover_time</code></td><td align="left" valign="center"><code>LB</code></td><td align="center" valign="center"><code>60</code></td><td align="left" valign="center">
The recover time is the time in seconds the load balancer will not try
to use a worker, after it went into error state. Only after this time has passed,
a worker in error state will be marked as in recovering, so that it will be
tried for new requests.
<p>
This interval is not checked every time a request is being processed.
Instead it is being checked during global maintenance. The time between two
runs of global maintenance is controlled by worker.maintain.
</p>
<p>
Do not set recover_time to a very short time unless you understand the implications.
Every recovery attempt for a worker in error is done by a real request!
</p>
</td></tr><tr><td align="left" valign="center"><code>error_escalation_time</code></td><td align="left" valign="center"><code>LB</code></td><td align="center" valign="center"><code>recover_time / 2</code></td><td align="left" valign="center">
Setting a member of a load balancer into an error state is quite serious. E.g.
it means that if you need stickyness, all access to the sessions of the
respective node is blocked.
<p>
Some types of error detection do not provide a precise information, whether
a node is completely broken or not. In those cases an LB will not immediately
put the node into the error state. Only when there have been no successful
responses for <b>error_escalation_time</b> seconds after such an error,
will the node be put into error state.
</p>
<p>
This features has been added in <b>jk 1.2.28</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>activation</code></td><td align="left" valign="center"><code>SUB</code></td><td align="center" valign="center"><code>Active</code></td><td align="left" valign="center">
Using this directive, a balanced worker of a load balancer
can be configured as disabled or stopped. A disabled worker only gets
requests, which belong to sessions for that worker. A stopped
worker does not get any requests. Users of a stopped worker will
loose their sessions, unless session replication via clustering is used.
<p>
Use <b>d</b> or <b>D</b> to disable and <b>s</b> or <b>S</b> to stop.
If this directive is not present the deprecated directives
"disabled" or "stopped" are used.
</p>
<p>
This flag can be changed at runtime using status worker.
</p>
<p>
This feature has been added in <b>jk 1.2.19</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>route</code></td><td align="left" valign="center"><code>SUB</code></td><td align="center" valign="center"><code>worker name</code></td><td align="left" valign="center">
Normally the name of a balanced worker in a load balancer is equal to the jvmRoute
of the corresponding Tomcat instance. If you want to include a worker corresponding
to a Tomcat instance into several load balancers with different balancing configuration
(e.g. disabled, stopped) you can use this attribute.
<p>
Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and
set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance.
</p>
<p>
If this attribute is left empty, the name of the worker will be used.
</p>
<p>
This attribute can be changed at runtime using status worker.
</p>
<p>
If the route name contains a period, the part before the first period will be
used as domain name, unless domain is set explicitly.
</p>
<p>
This feature has been added in <b>jk 1.2.16</b>.<br>
The automatic domain rule has been added in <b>jk 1.2.20</b>.<br>
The attribute has been renamed from jvm_route to route in <b>jk 1.2.20</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>distance</code></td><td align="left" valign="center"><code>SUB</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
An integer number to express preferences between
the balanced workers of an lb worker.
A load balancer will never choose some balanced worker
in case there is another usable worker with lower distance.
<p>
Only in case all workers below a given distance are in error, disabled or stopped,
workers of a larger distance are eligible for balancing.
</p>
<p>
This feature has been added in <b>jk 1.2.16</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>domain</code></td><td align="left" valign="center"><code>SUB</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
Domain directive can be used only when the worker is a member of the load balancer.
Workers that share the same domain name are treated as single worker. If sticky_session
is used, then the domain name is used as session route.
<p>
This directive is used for large system with more then 6 Tomcats, to be able
to cluster the Tomcats in two groups and thus lowering the session replication
transfer between them.
</p>
<p>
This feature has been added in <b>jk 1.2.8</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>redirect</code></td><td align="left" valign="center"><code>SUB</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
Set to the name of the preferred failover worker. If worker matching
SESSION ID is in error state then the redirect worker will be used instead.
It will be used even if being disabled, thus offering hot standby.
<p>
If you explicitly set a route via the "route" attribute, you must set "redirect"
to this route of the preferred failover worker and not to its name.
</p>
<p>
This feature has been added in <b>jk 1.2.9</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>session_cookie</code></td><td align="left" valign="center"><code>LB</code></td><td align="center" valign="center"><code>JSESSIONID</code></td><td align="left" valign="center">
The name of the cookie that contains the routing identifier needed for session stickyness.
The routing identifier is everything after a "." character in the value of the cookie.
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>session_path</code></td><td align="left" valign="center"><code>LB</code></td><td align="center" valign="center"><code>;jsessionid</code></td><td align="left" valign="center">
The name of the path parameter that contains the routing identifier needed for
session stickyness. The routing identifier is everything after a "." character in the value
of the path parameter.
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</td></tr></table>
</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="Deprecated Worker Directives"><strong>Deprecated Worker Directives</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>The following directives have been deprecated in the past. We include their documentation
in case you need to use an older version of mod_jk. We urge you to update and not use
them any more. Please migrate your existing configurations.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Directive</font></th><th width="15%" bgcolor="#023264"><font color="#ffffff">Successor</font></th><th width="10%" bgcolor="#023264"><font color="#ffffff">Default</font></th><th width="60%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>cachesize</code></td><td align="center" valign="center"><code>connection_pool_size</code></td><td align="center" valign="center"><code>see text</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.16.</font></p>
Cachesize defines the number of connections made to the AJP backend that
are maintained as a connection pool.
It will limit the number of those connection that each web server child
process can make.
<p>
Cachesize property is used only for multi threaded
web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property
should reflect the number of threads per child process. JK will discover
the number of threads per child process on Apache 2 web server with worker-mpm and set
its default value to match the ThreadsPerChild Apache directive. For IIS the default
value is 10. For other web servers than Apache or IIS this value has to be set manually.
</p>
<p><font color="#ff0000">Do not use cachesize with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</font></p>
</td></tr><tr><td align="left" valign="center"><code>cache_timeout</code></td><td align="center" valign="center"><code>connection_pool_timeout</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.16.</font></p>
Cache timeout property should be used with <b>cachesize</b> to specify how to time JK should keep
an open socket in cache before closing it. This property should be used to reduce the number of threads
on the Tomcat web server.
<p>
Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating
a new ajp13 thread on Tomcat side.
</p>
<p>
The problem is that after an ajp13 connection is created, the child won't drop it
until killed. And since the webserver will keep its childs/threads running
to handle high-load, even it the child/thread handle only static contents, you could
finish having many unused ajp13 threads on the Tomcat side.
</p>
</td></tr><tr><td align="left" valign="center"><code>recycle_timeout</code></td><td align="center" valign="center"><code>connection_pool_timeout</code></td><td align="center" valign="center"><code>0</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.16.</font></p>
The number of seconds that told webserver to cut an ajp13 connection after some time of
inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be
closed if it was not used for the configured time.
It's a good way to ensure that there won't too old threads living on Tomcat side,
with the extra cost you need to reopen the socket next time a request be forwarded.
This property is very similar to <b>cache_timeout</b> but works also in non-cache mode.
If set to value zero (default) no recycle will took place.
</td></tr><tr><td align="left" valign="center"><code>balanced_workers</code></td><td align="center" valign="center"><code>balance_workers</code></td><td align="center" valign="center"><code>-</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.7.</font></p>
A comma separated list of workers that the load balancer
need to manage.
</td></tr><tr><td align="left" valign="center"><code>disabled</code></td><td align="center" valign="center"><code>activation</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.19.</font></p>
If set to <b>True</b> or <b>1</b> the worker will be disabled if member
of load balancer. This flag can be changed at runtime using status worker.
<p>
This feature has been added in <b>jk 1.2.9</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>stopped</code></td><td align="center" valign="center"><code>activation</code></td><td align="center" valign="center"><code>False</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.19.</font></p>
If set to <b>True</b> or <b>1</b> the worker will be stopped if member
of load balancer. The flag is needed for stop complete traffic of a sticky session
worker. It is only useful, when you have a cluster that replicated the sessions.
This flag can be changed at runtime using status worker.
<p>
This feature has been added in <b>jk 1.2.11</b>.
</p>
</td></tr><tr><td align="left" valign="center"><code>jvm_route</code></td><td align="center" valign="center"><code>route</code></td><td align="center" valign="center"><code>worker name</code></td><td align="left" valign="center">
<p><font color="#ff0000">This directive has been deprecated since 1.2.20.</font></p>
Normally the name of a balanced worker in a load balancer is equal to the jvmRoute
of the corresponding Tomcat instance. If you want to include a worker corresponding
to a Tomcat instance into several load balancers with different balancing configuration
(e.g. disabled, stopped) you can use this attribute.
<p>
Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and
set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance.
</p>
<p>
If this attribute is left empty, the name of the worker will be used.
</p>
<p>
This attribute can be changed at runtime using status worker.
</p>
<p>
This feature has been added in <b>jk 1.2.16</b>.
</p>
</td></tr></table>
</blockquote></td></tr></table>
</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>
|
