rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml

   1 <?xml version="1.0"?>
   2 <!--
   3   Licensed to the Apache Software Foundation (ASF) under one or more
   4   contributor license agreements.  See the NOTICE file distributed with
   5   this work for additional information regarding copyright ownership.
   6   The ASF licenses this file to You under the Apache License, Version 2.0
   7   (the "License"); you may not use this file except in compliance with
   8   the License.  You may obtain a copy of the License at
   9
  10       http://www.apache.org/licenses/LICENSE-2.0
  11
  12   Unless required by applicable law or agreed to in writing, software
  13   distributed under the License is distributed on an "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15   See the License for the specific language governing permissions and
  16   limitations under the License.
  17 -->
  18 <!DOCTYPE document [
  19   <!ENTITY project SYSTEM "project.xml">
  20 ]>
  21 <document url="workers.html">
  22
  23     &project;
  24
  25     <properties>
  26         <author email="mturk@apache.org">Mladen Turk</author>
  27         <title>workers.properties configuration</title>
  28     </properties>
  29
  30 <body>
  31
  32 <section name="Introduction">
  33 <br/>
  34 <p>
  35 A <b>Tomcat worker</b> is a Tomcat instance that is waiting to execute servlets or any other content
  36 on behalf of some web server. For example, we can have a web server such as
  37 Apache forwarding servlet requests to a Tomcat process (the worker) running behind it.
  38 </p>
  39 <p>
  40 The scenario described above is a very simple one;
  41 in fact one can configure multiple Tomcat workers to serve servlets on
  42 behalf of a certain web server.
  43 The reasons for such configuration can be:
  44 </p>
  45 <ul>
  46 <li>
  47 We want different contexts to be served by different Tomcat workers to provide a
  48 development environment where all the developers share the same web server but
  49 own a Tomcat worker of their own.
  50 </li>
  51 <li>
  52 We want different virtual hosts served by different Tomcat processes to provide a
  53 clear separation between sites belonging to different companies.
  54 </li>
  55 <li>
  56 We want to provide load balancing, meaning run multiple Tomcat workers each on a
  57 machine of its own and distribute the requests between them.
  58 </li>
  59 </ul>
  60
  61 <p>
  62 There are probably more reasons for having multiple workers but I guess that this list is enough...
  63 </p>
  64 <p>
  65 Tomcat workers are defined in a properties file dubbed <b>workers.properties</b> and this tutorial
  66 explains how to work with it.
  67 </p>
  68 </section>
  69
  70 <section name="Configuration File Basics">
  71 <br/>
  72 <p>Defining workers to the Tomcat web server plugin can be done using a properties file
  73 (a sample file named workers.properties is available in the conf/ directory).
  74 </p>
  75
  76 <subsection name="Format, Comments, Whitespace">
  77 <br/>
  78 <p>
  79 The lines in the file define properties. The general format is
  80 </p>
  81 <p><strong>&lt;name&gt;=&lt;value&gt;</strong></p>
  82 <p>
  83 </p>
  84 Dots are used as part of the name to represent a configuration hierarchy.
  85 <p>
  86 Invalid directives will be logged during web server startup and prevent the web server
  87 from working properly. Some directives have been deprecated. Although they will
  88 still work, you should replace them by their
  89 <a href="#Deprecated Worker Directives">successors</a>.
  90 </p>
  91 <p>
  92 Some directives are allowed multiple times. This will be explicitly
  93 noted in the tables below.
  94 </p>
  95 <p>
  96 Whitespace at the beginning and the end of a property name or value gets ignored.
  97 Comments can be placed in any line and start with a hash sign '#'.
  98 Any line contents behind the hash sign get ignored.
  99 </p>
 100 </subsection>
 101
 102 <subsection name="Global Properties">
 103 <br/>
 104 <p>
 105 These directives have global scope.
 106 </p>
 107 <directives>
 108 <directive name="worker.list" default="ajp13" required="true">
 109 A comma separated list of workers names that the JK will use. When starting up,
 110 the web server plugin will instantiate the workers whose name appears in the
 111 worker.list property, these are also the workers to whom you can map requests.
 112 <p>
 113 This directive can be used multiple times.
 114 </p>
 115 </directive>
 116 <directive name="worker.maintain" default="60" required="false">
 117 Worker connection pool maintain interval in seconds. If set to the positive
 118 value JK will scan all connections for all workers specified in worker.list
 119 directive and check if connections needs to be recycled.
 120 <p>
 121 Furthermore any load balancer does a global maintenance every worker.maintain
 122 seconds. During global maintenance load counters are decayed and workers
 123 in error are checked for recover_time.
 124 </p>
 125 <p>
 126 This feature has been added in <b>jk 1.2.13</b>.
 127 </p>
 128 </directive>
 129 </directives>
 130 </subsection>
 131
 132 <subsection name="Worker Properties">
 133 <br/>
 134 <p>
 135 Each worker configuration directive consists of three words separated by a dot:
 136 </p>
 137 <p><strong>worker.&lt;worker name&gt;.&lt;directive&gt;=&lt;value&gt;</strong></p>
 138 <p>
 139 The first word is always <b>worker</b>.
 140 The second word is the worker name you can choose. In the case of load-balancing,
 141 the worker name has an additional meaning. Please consult the
 142 <a href="../generic_howto/loadbalancers.html">Load Balancer HowTo</a>.
 143 </p>
 144 <warn>
 145 The name of the worker can contain only the alphanumeric characters
 146 <b>[a-z][A-Z][0-9][_\-]</b> and is case sensitive.
 147 </warn>
 148 </subsection>
 149
 150 <subsection name="Variables, Environment Variables">
 151 <br/>
 152 <p>
 153 You can define and use variables in the workers.properties file.
 154 To define a variable you use the syntax:
 155 </p>
 156 <p><strong>&lt;variable_name&gt;=&lt;value&gt;</strong></p>
 157 <p>
 158 Dots are allowed in the variable name, but you have to be careful
 159 not to use variable names, that clash with standard directives.
 160 Therefore variable names should never start with "worker.".
 161 </p>
 162 <p>
 163 To use a variable, you can insert "$(variable_name)" at any place
 164 on the value side of a property line. If a variable has not been
 165 defined before its use, we will search the process environment for
 166 a variable with the same name and use their value.
 167 </p>
 168 </subsection>
 169
 170 <subsection name="Property Inheritance">
 171 <br/>
 172 <p>Often one wants to use the same property values for various workers.
 173 To reduce duplication of configuration lines and to ease the maintenance of
 174 the file, you can inherit properties from one worker to another, or even
 175 from a template to real workers.
 176 </p>
 177 <p>
 178 The directive "reference" allows to copy configurations between workers
 179 in a hierarchical way. If worker castor sets <b>worker.castor.reference=worker.pollux</b>
 180 then it inherits all properties of <b>pollux</b>, except for the ones that
 181 are explicitly set for <b>castor</b>.
 182 </p>
 183 <p>
 184 Please note, that the value of the directive is not only the name of the referred worker,
 185 but the complete prefix including "worker.".
 186 </p>
 187 <p>
 188 To use a template worker simply define it like a real worker, but do not add it
 189 to the "worker.list" or as a member to any load balancer. Such a template worker
 190 does not have to contain mandatory directives. This approach is especially useful,
 191 if one has a lot of balanced workers in a load balancer
 192 and these workers share most of their properties. You can set all of these properties
 193 in a template worker, e.g. using the prefix "worker.template1", and then simply
 194 reference those common properties in all balanced workers.
 195 </p>
 196 <p>
 197 References can be used to inherit properties over multiple hops in a hierarchical way.
 198 </p>
 199 <p>
 200 This feature has been added in <b>jk 1.2.19</b>.
 201 </p>
 202 </subsection>
 203 </section>
 204
 205 <section name="List of All Worker Directives">
 206 <br/>
 207 <subsection name="Mandatory Directives">
 208 <br/>
 209 <p>Mandatory directives are the one that each worker <b>must</b> contain. Without them the worker will
 210 be unavailable or will misbehave. Those directives will be marked with a <strong>strong</strong> font in the following tables.
 211 </p>
 212 <directives>
 213 <directive name="type" default="ajp13" required="true">
 214 Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker
 215 defines the directives that can be applied to the worker.
 216 <p>AJP13 worker is the preferred worker type that JK uses for communication
 217 between web server and Tomcat. This type of worker uses sockets as communication
 218 channel. For detailed description of the AJP13 protocol stack browse to
 219 <a href="../ajp/ajpv13a.html">AJPv13 protocol specification</a>
 220 </p>
 221 <warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn>
 222 </directive>
 223 </directives>
 224 </subsection>
 225
 226 <subsection name="Connection Directives">
 227 <br/>
 228 <p>Connection directives defines the parameters needed to connect and maintain
 229 the connections pool of persistent connections between JK and remote Tomcat.
 230 </p>
 231 <directives>
 232
 233 <directive name="host" default="localhost" required="false">
 234 Host name or IP address of the backend Tomcat instance. The remote Tomcat must
 235 support the ajp13 protocol stack. The host name can have a <b>port</b> number
 236 embedded separated by the colon (':') character.
 237 </directive>
 238
 239 <directive name="port" default="8009" required="false">
 240 Port number of the remote Tomcat instance listening for defined protocol requests.
 241 The default value depends on the worker type. For AJP13 workers the default port is
 242 <b>8009</b>, while for AJP14 type of worker that value is <b>8011</b>.
 243 </directive>
 244
 245 <directive name="socket_timeout" default="0" required="false">
 246 Socket timeout in seconds used for the communication channel between JK and remote host.
 247 If the remote host does not respond inside the timeout specified, JK will generate an error,
 248 and retry again. If set to zero (default) JK will wait for an infinite amount of time
 249 on all socket operations.
 250 </directive>
 251
 252 <directive name="socket_connect_timeout" default="socket_timeout*1000" required="false">
 253 Socket connect timeout in milliseconds used for the communication channel between JK and remote host.
 254 If the remote host does not respond inside the timeout specified, JK will generate an error,
 255 and retry again.
 256 <p>
 257 Note that <code>socket_timeout</code> is in seconds, and
 258 <code>socket_connect_timeout</code> in milliseconds,
 259 so in absolute terms the default <code>socket_connect_timeout</code> is
 260 equal to <code>"socket_timeout</code>.
 261 </p>
 262 <p>
 263 This feature has been added in <b>jk 1.2.27</b>.
 264 </p>
 265 </directive>
 266
 267 <directive name="socket_keepalive" default="False" required="false">
 268 This directive should be used when you have a firewall between your webserver
 269 and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System
 270 to send <code>KEEP_ALIVE</code> messages on inactive connections (interval depend on global OS settings,
 271 generally 120 minutes), and thus prevent the firewall to cut inactive connections.
 272 To enable keepalive set this property value to <b>True</b>.
 273 <p>
 274 The problem with Firewall cutting inactive connections is that sometimes, neither webserver or Tomcat
 275 have information about the cut and couldn't handle it.
 276 </p>
 277 </directive>
 278
 279 <directive name="ping_mode" default="" required="false">
 280 This flag determines, under which conditions established
 281 connections are probed to ensure they are still working.
 282 The probe is done with an empty AJP13 packet (CPing) and
 283 expects to receive an appropriate answer (CPong) within
 284 some timeout.
 285 <p>
 286 The value of the flag can be any combination of the following
 287 flags (multiple values are combined without any separators):
 288 </p>
 289 <p><b>C</b> (connect): If set, the connection will
 290 be probed once after connecting to the backend. The timeout
 291 can be set by <code>connect_timeout</code>. If it is not set,
 292 the value of <code>ping_timeout</code> will be used instead.
 293 </p>
 294 <p><b>P</b> (prepost): If set, the connection will
 295 be probed before sending each request to the backend. The timeout
 296 can be set by <code>prepost_timeout</code>. If it is not set,
 297 the value of <code>ping_timeout</code> will be used instead.
 298 </p>
 299 <p><b>I</b> (interval): If set, the connection will
 300 be probed during the regular internal maintenance cycle,
 301 but only if it is idle longer than
 302 <code>connection_ping_interval</code>. The timeout
 303 can be set by <code>ping_timeout</code>.
 304 </p>
 305 <p><b>A</b> If set, all of the above probes will be used.
 306 </p>
 307 <p>
 308 This feature has been added in <b>jk 1.2.27</b>. Connect and
 309 prepost probing were already available via <code>connect_timeout</code>
 310 and <code>prepost_timeout</code> since version <b>jk 1.2.6</b>.
 311 </p>
 312 </directive>
 313
 314 <directive name="ping_timeout" default="10000" required="false">
 315 Timeout in milliseconds used when waiting for the CPong answer of a
 316 CPing connection probe. The activation of the probes is done via
 317 <code>ping_mode</code>. The timeouts for <code>ping_mode</code>
 318 connect and prepost can be overwritten individually via
 319 <code>connect_timeout</code> and <code>prepost_timeout</code>.
 320 <p>
 321 For compatibility reasons, CPing/CPong is also used, whenever
 322 <code>connect_timeout</code> or <code>prepost_timeout</code> are set,
 323 even if <code>ping_mode</code> is empty.
 324 </p>
 325 <p>
 326 This feature has been added in <b>jk 1.2.27</b>.
 327 </p>
 328 </directive>
 329
 330 The usage depend on the <code>ping_mode</code> flags used.
 331 directive <code>connection_ping_interval</code> was not set, the
 332 value of <code>(ping_timeout/1000) * 10</code> will be used as
 333 <code>connection_ping_interval</code> value.
 334
 335 <directive name="connection_ping_interval" default="0 / (ping_timeout/1000)*10" required="false">
 336 When using interval connection probing, connections idle for longer than this
 337 interval in seconds are probed by CPing packets whether they still work.
 338 <p>Interval probing can be activated either by <code>ping_mode</code>,
 339 or by setting <code>connection_ping_interval</code> to some value bigger
 340 than zero. If you activate interval probing via <code>ping_mode</code>,
 341 then the default value of <code>connection_ping_interval</code> is
 342 <code>(ping_timeout/1000) * 10</code>. Note that <code>ping_timeout</code>
 343 is in milliseconds, and <code>connection_ping_interval</code> in seconds,
 344 so in absolute terms the default <code>connection_ping_interval</code> is
 345 10 times <code>ping_timeout</code>.
 346 </p>
 347 <p>
 348 This feature has been added in <b>jk 1.2.27</b>.
 349 </p>
 350 </directive>
 351
 352 <directive name="connection_pool_size" default="see text" required="false">
 353 This defines the number of connections made to the AJP backend that
 354 are maintained as a connection pool.
 355 It will limit the number of those connection that each web server child
 356 process can made.
 357 <p>
 358 Connection pool size property is only used for multi threaded
 359 web servers such as Apache, IIS and Netscape/Sun. The connection_pool_size property
 360 needs to reflect the number of requests one web server process should
 361 be able to send to a backend in parallel. Usually this is the same as
 362 the number of threads per web server process. JK will discover
 363 this number for the Apache web server automatically and set the pool size to
 364 this value. For IIS the default value is 250 (before version 1.2.20: 10),
 365 for Netscape/Sun the default value is 1.
 366 </p>
 367 <p>We strongly recommend adjusting this value for IIS and the Netscape/Sun
 368 to the number of requests one web server process should
 369 be able to send to a backend in parallel. You should measure how many connections
 370 you need during peak activity without performance problems, and then add some
 371 percentage depending on your growth rate. Finally you should check,
 372 whether your web server processes are able to use at least as many threads,
 373 as you configured as the pool size.
 374 </p>
 375 <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>
 376 </directive>
 377
 378 <directive name="connection_pool_minsize" default="(pool+1)/2" required="false">
 379 Minimum size of the connection pool that will be maintained.
 380 <p>
 381 Its default value is (connection_pool_size+1)/2.
 382 </p>
 383 <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>
 384 <p>
 385 This feature has been added in <b>jk 1.2.16</b>.
 386 </p>
 387 </directive>
 388
 389 <directive name="connection_pool_timeout" default="0" required="false">
 390 Cache timeout property should be used with <b>connection_pool_minsize</b> to specify how many seconds JK should keep
 391 an inactive socket in cache before closing it. This property should be used to reduce the number of threads
 392 on the Tomcat web server. The default value zero disables the closing (infinite timeout).
 393 <p>
 394 Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating
 395 a new ajp13 thread on Tomcat side.
 396 </p>
 397 <p>
 398 The problem is that after an ajp13 connection is created, the child won't drop it
 399 until killed. And since the webserver will keep its childs/threads running
 400 to handle high-load, even it the child/thread handle only static contents, you could
 401 finish having many unused ajp13 threads on the Tomcat side.
 402 </p>
 403 <p>
 404 You should keep this time interval in sync with the <b>connectionTimeout</b> attribute
 405 of your AJP connector in Tomcat's server.xml. Note however, that the value
 406 for mod_jk is given in seconds, the one in server.xml has to use milliseconds.
 407 </p>
 408 </directive>
 409
 410 <directive name="connection_acquire_timeout" default="retries*retry_interval" required="false">
 411 Timeout the worker will wait for a free socket in cache before giving up.
 412 <p>
 413 Its default value is <b>retries * retry_interval</b>.
 414 </p>
 415 <p>
 416 This feature has been added in <b>jk 1.2.27</b>.
 417 </p>
 418 </directive>
 419
 420 <directive name="lbfactor" default="1" required="false">
 421 Only used for a member worker of a load balancer.
 422 <p>
 423 The integer number lbfactor (load-balancing factor) is
 424 <i>how much we expect this worker to work</i>, or
 425 <i>the worker's work quota</i>. Load balancing factor is compared with other workers
 426 that makes the load balancer. For example if one worker has lb_factor 5 times higher then
 427 other worker, then it will receive five times more requests.
 428 </p>
 429 </directive>
 430
 431 </directives>
 432
 433 </subsection>
 434
 435 <subsection name="Load Balancing Directives">
 436 <br/>
 437 <p>Load balancer is a virtual worker that does not really communicate with Tomcat workers.
 438 Instead it is responsible for the management of several "real" workers.
 439 The worker is supposed to be a load balancer if it's worker type is <b>lb</b>.
 440 See worker's <b>type</b> directive.
 441 </p>
 442 <p>Loadbalancer directives define the parameters needed to create the workers that are
 443 connecting to a remote cluster of backend Tomcat servers. Each cluster node has to
 444 have a worker defined.
 445 </p>
 446 <p>
 447 Load balancer management includes:
 448 </p>
 449
 450 <ul>
 451 <li>
 452 Instantiating the workers in the web server.
 453 </li>
 454 <li>
 455 Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
 456 high lbfactor means stronger machine (that is going to handle more requests)
 457 </li>
 458 <li>
 459 Keeping requests belonging to the same session executing on the same Tomcat worker.
 460 </li>
 461 <li>
 462 Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on
 463 other workers managed by the lb worker.
 464 </li>
 465 </ul>
 466
 467 <p>
 468 The overall result is that workers managed by the same lb worker are load-balanced
 469 (based on their lbfactor and current user session) and also fall-backed so a single
 470 Tomcat process death will not "kill" the entire site.
 471 </p>
 472 <warn>
 473 If you want to use session stickiness, you must set different jvmRoute attributes
 474 in the Engine element in Tomcat's server.xml. Furthermore the names of the workers
 475 which are managed by the balancer have to be equal to the jvmRoute of the Tomcat
 476 instance they connect with.
 477 </warn>
 478 <p>
 479 The restriction on the worker names can be lifted, if you use the route attribute for the workers.
 480 </p>
 481 <p>
 482 The following table specifies properties that the lb worker can accept:
 483 </p>
 484
 485 <directives>
 486 <directive name="balance_workers" default="" required="true">
 487 A comma separated list of workers that the load balancer
 488 need to manage.
 489 <p>
 490 This directive can be used multiple times for the same load balancer.
 491 </p>
 492 <p>
 493 This directive replaces old <b>balanced_workers</b> directive and
 494 can be used only with mod_jk versions 1.2.7 and up.
 495 </p>
 496 <warn>As long as these workers should only be used via the load balancer worker,
 497 there is no need to also put them into the <b>worker.list</b> property.</warn>
 498 </directive>
 499
 500 <directive name="sticky_session" default="True" required="false">
 501 Specifies whether requests with SESSION ID's should be routed back to the same
 502 Tomcat worker. If sticky_session is set to <b>True</b> or <b>1</b> sessions are sticky, otherwise
 503 sticky_session is set to <b>False</b>. Set sticky_session to <b>False</b> when Tomcat
 504 is using a Session Manager which can persist session data across multiple
 505 instances of Tomcat.
 506 </directive>
 507
 508 <directive name="sticky_session_force" default="False" required="false">
 509 Specifies whether requests with SESSION ID's for workers that are in error state
 510 should be rejected. If sticky_session_force is set to <b>True</b> or <b>1</b>
 511 and the worker that matches that SESSION ID is in error state, client will
 512 receive 500 (Server Error). If set to <b>False</b> or <b>0</b> failover on
 513 another worker will be issued with loosing client session. This directive is
 514 used only when you set <b>sticky_session=True</b>.
 515 <p>
 516 This feature has been added in <b>jk 1.2.9</b>.
 517 </p>
 518 </directive>
 519
 520 <directive name="method" default="Request" required="false">
 521 Specifies what method load balancer is using for electing the best worker.
 522 Please note, that session stickiness and perfect load balancing are
 523 conflicting targets, especially when the number
 524 of sessions is small, or the usage of sessions is extremely varying
 525 For huge numbers of sessions this usually is not a problem.
 526 <p>
 527 Some methods note, that they aggregate in a sliding time window. They add up
 528 accesses, and on each run of the global maintain method, the load counters
 529 get divided by 2. Usually this happens once a minute, depending on the
 530 setting of worker.maintain. The value of the load counters can be inspected
 531 using the status worker.
 532 </p>
 533 <p>
 534 If method is set to <b>R[equest]</b> the balancer will use number of requests
 535 to find the best worker. Accesses will be distributed according to the
 536 lbfactor in a sliding time window. This is the default value and should be
 537 working well for most applications.
 538 </p>
 539 <p>
 540 If method is set to <b>S[ession]</b> the balancer will use number of sessions
 541 to find the best worker. Accesses will be distributed according to the
 542 lbfactor in a sliding time window. Because the balancer does not keep any state,
 543 it actually does not know the number of sessions. Instead it counts each request
 544 without a session cookie or URL encoding as a new session. This method will neither
 545 know, when a session is being invalidated, nor will it correct its load numbers
 546 according to session timeouts or worker failover. This method should be used,
 547 if sessions are your limiting resource, e.g. when you only have limited memory
 548 and your sessions need a lot of memory.
 549 </p>
 550 <p>
 551 If set to <b>T[raffic]</b> the balancer will use
 552 the network traffic between JK and Tomcat to find the best worker.
 553 Accesses will be distributed according to the lbfactor in a sliding time window.
 554 This method should be used, if network to and from the backends is your
 555 limiting resource.
 556 </p>
 557 <p>
 558 If set to <b>B[usyness]</b> the balancer will
 559 pick the worker with the lowest current load, based on how many requests the
 560 worker is currently serving. This number is divided by the workers lbfactor,
 561 and the lowest value (least busy) worker is picked. This method is especially
 562 interesting, if your request take a long time to process, like for a download
 563 application.
 564 </p>
 565 <p>
 566 This feature has been added in <b>jk 1.2.9</b>.
 567 The Session method has been added in <b>jk 1.2.20</b>.
 568 </p>
 569 </directive>
 570
 571 <directive name="lock" default="Optimistic" required="false">
 572 Specifies what lock method the load balancer will use for synchronising
 573 shared memory runtime data.
 574 If lock is set to <b>O[ptimistic]</b> balancer will not use shared memory lock
 575 to find the best worker. If set to <b>P[essimistic]</b> balancer will use
 576 shared memory lock. The balancer will work more accurately in case of
 577 Pessimistic locking, but can slow down the average response time.
 578 <p>
 579 This feature has been added in <b>jk 1.2.13</b>.
 580 </p>
 581 </directive>
 582
 583 <directive name="retries" default="2" required="false">
 584 <warn>This directive also exists for normal workers.
 585 For those it has a <a href="#Advanced Worker Directives">different meaning</a>.</warn>
 586 If the load balancer can not get a valid member worker or in case of failover,
 587 it will try again a number of times given by <b>retries</b>.
 588 Before each retry, it will make a pause define by <b>retry_interval</b> directive.
 589 <p>
 590 Until version <b>1.2.16</b> the default value was 3.
 591 </p>
 592 </directive>
 593
 594 </directives>
 595
 596 </subsection>
 597
 598 <subsection name="Status Worker Directives">
 599 <br />
 600 <p>
 601 The status worker does not communicate with Tomcat.
 602 Instead it is responsible for the load balancer management.
 603 </p>
 604 <directives>
 605 <directive name="css" default="" required="false">
 606 Specifies the url for cascading stylesheet to use.
 607 </directive>
 608 <directive name="read_only" default="False" required="false">
 609 A status worker with read_only=True will not allow any operations,
 610 that change the runtime state or configuration of the other workers.
 611 These are edit/update/reset/recover.
 612 <p>
 613 This feature has been added in <b>jk 1.2.20</b>.
 614 </p>
 615 </directive>
 616 <directive name="user" default="" required="false">
 617 It is a list of users
 618 which gets compared to the user name authenticated by the web server.
 619 If the name is not contained in this list, access is denied. Per
 620 default the list is empty and then access is allowed to anybody.
 621 <p>
 622 This directive can be used multiple times.
 623 </p>
 624 <p>
 625 This feature has been added in <b>jk 1.2.20</b>.
 626 </p>
 627 </directive>
 628 <directive name="user_case_insensitive" default="False" required="false">
 629 By default, the user names are matched case sensitively. You can set
 630 user_case_insensitive=True to make the comparison case insensitive.
 631 This may be especially useful on the Windows platform.
 632 <p>
 633 This feature has been added in <b>jk 1.2.21</b>.
 634 </p>
 635 </directive>
 636 <directive name="good" default="a.o,a.n,a.b,a.r" required="false">
 637 For every load balancer worker, the status worker shows a summary
 638 of the state of its members. There are three such states,
 639 "good", "bad" and "degraded".
 640 <p>
 641 These states are determined depending on the activation of the members
 642 (active, disabled, stopped) and their runtime state
 643 (ok, n/a, busy, recovering, probing, forced recovery, error).
 644 By default, members are assumed to be "good", if their activation
 645 is "active" and their runtime state is not "error".
 646 </p>
 647 <p>
 648 You can change this mapping, by assigning a list of values to the
 649 attribute "good". Each value gives a possible match for the members,
 650 and one match suffices. Each value is either a single character, or two
 651 characters combined with a dot ".". The single characters are the
 652 first characters in the words "active", "disabled", "stopped",
 653 "ok", "na", "busy", "recovering", "error". The additional states "probing"
 654 and "forced recovery" are always rated equivalent to "recovering".
 655 If a value consists only
 656 of a single character, then all members with this activation or runtime
 657 state will be assumed good. A combination of an activation and a runtime
 658 state concatenated with a dot "." does only apply to a member, that has
 659 exactly this activation and state.
 660 </p>
 661 <p>
 662 Members of a load balancer will first be matched against the state "bad",
 663 if they don't match, the state "good" will be tried, and if they
 664 still don't match, their state will be "degraded".
 665 </p>
 666 <p>
 667 This directive can be used multiple times.
 668 </p>
 669 <p>
 670 This feature has been added in <b>jk 1.2.20</b>.
 671 </p>
 672 </directive>
 673 <directive name="bad" default="s,e" required="false">
 674 See: "good".
 675 <p>
 676 By default, members are assumed to be "bad", if their activation
 677 is "stopped" or their runtime state is "error".
 678 </p>
 679 <p>
 680 This directive can be used multiple times.
 681 </p>
 682 <p>
 683 This feature has been added in <b>jk 1.2.20</b>.
 684 </p>
 685 </directive>
 686 <directive name="prefix" default="worker" required="false">
 687 The prefix, which will be used by the status worker
 688 when producing properties output (mime=prop).
 689 Each property key will be prefixed by this value.
 690 <p>
 691 This feature has been added in <b>jk 1.2.20</b>.
 692 </p>
 693 </directive>
 694 <directive name="ns" default="jk:" required="false">
 695 This directive can be used to customise the XML output from the
 696 status worker. If set to <b>-</b> no namespace will be used.
 697 <p>
 698 This feature has been added in <b>jk 1.2.20</b>.
 699 </p>
 700 </directive>
 701 <directive name="xmlns" default="" required="false">
 702 This directive can be used to customise the XML output from the
 703 status worker. If set to <b>-</b> no xmlns will be used.
 704 <p>
 705 Default value is set to xmlns:jk=&quot;http://tomcat.apache.org&quot;
 706 </p>
 707 <p>
 708 This feature has been added in <b>jk 1.2.20</b>.
 709 </p>
 710 </directive>
 711 <directive name="doctype" default="" required="false">
 712 This directive can be used to customise the XML output from the
 713 status worker. This value will be inserted to the output xml
 714 after the xml header.
 715 <p>
 716 This feature has been added in <b>jk 1.2.20</b>.
 717 </p>
 718 </directive>
 719
 720 </directives>
 721 </subsection>
 722
 723 <subsection name="Advanced Worker Directives">
 724 <br />
 725 <p>
 726 This table lists more advanced configuration options. Most of them only apply to
 727 some types of workers. We use the abbreviations <b>AJP</b> for ajp13/ajp14 workers
 728 used directly via the workers.list, <b>LB</b> for load balancer workers,
 729 and <b>SUB</b> for the workers used indirectly in a load balancer worker
 730 as a sub worker or member.
 731 </p>
 732 <advanceddirectives>
 733 <directive name="connect_timeout" workers="AJP,SUB" default="0" required="false">
 734 Connect timeout property told webserver to send a PING request on ajp13 connection after
 735 connection is established. The parameter is the delay in milliseconds to wait for the PONG reply.
 736 The default value zero disables the timeout (infinite timeout).
 737 <p>
 738 This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13
 739 ping/pong support which has been implemented on Tomcat <b>3.3.2+, 4.1.28+ and 5.0.13+</b>.
 740 Disabled by default.
 741 </p>
 742 </directive>
 743
 744 <directive name="prepost_timeout" workers="AJP,SUB" default="0" required="false">
 745 Prepost timeout property told webserver to send a PING request on ajp13 connection before
 746 forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply.
 747 The default value zero disables the timeout (infinite timeout).
 748 <p>
 749 This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13
 750 ping/pong support which has been implemented on <b>Tomcat 3.3.2+, 4.1.28+ and 5.0.13+</b>.
 751 Disabled by default.
 752 </p>
 753 </directive>
 754
 755 <directive name="reply_timeout" workers="AJP,SUB" default="0" required="false">
 756 The parameter is the number of milliseconds to wait for success during a read event.
 757 So this is not a timeout for the complete answer time of a request, but only
 758 for the maximum time between two packets received from Tomcat. Usually the longest
 759 pause is between sending the request and getting the first packet of the response.
 760 <p>
 761 If the timeout passes without any data received from Tomcat, the webserver will
 762 no longer wait for the rest of the response and send an error to the client (browser).
 763 Usually this does not mean, that the request is also aborted on the Tomcat backend.
 764 If the worker is a member of a load balancer, the load balancer might place the
 765 worker into an error state and retry the request on another member.
 766 See also <b>max_reply_timeouts</b>, <b>retries</b> and <b>recovery_options</b>.
 767 </p>
 768 <p>
 769 By default (value zero) the webserver will wait forever which could be an issue for you.
 770 If you set a reply_timeout, adjust it carefully if you have long running servlets.
 771 </p>
 772 <p>
 773 The reply_timeout can be overwritten using the Apache httpd environment variable
 774 JK_REPLY_TIMEOUT.
 775 </p>
 776 <p>
 777 This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and works on all
 778 servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT has been added in version <b>1.2.27</b>.
 779 </p>
 780 </directive>
 781
 782 <directive name="retries" workers="AJP,SUB" default="2" required="false">
 783 <warn>This directive also exists for load balancer workers.
 784 For those it has a <a href="#Load Balancing Directives">different meaning</a>.</warn>
 785 The maximum number of times that the worker will send a request to Tomcat
 786 in case of a communication error. Each retry will be done over another
 787 connection. The first time already gets counted, so retries=2 means
 788 one retry after error. Before a retry, the worker waits for a configurable
 789 sleeping time.
 790 <p>
 791 See also the attribute <b>recovery_options</b> for a more fine-grained control
 792 of retries and <b>retry_interval</b> for the sleep time configuration.
 793 </p>
 794 <p>
 795 Until version <b>1.2.16</b> the default value was 3.
 796 </p>
 797 </directive>
 798
 799 <directive name="retry_interval" workers="AJP,SUB" default="100" required="false">
 800 The amount of time in milliseconds the worker sleeps before doing any retry.
 801 <p>
 802 This features has been added in <b>jk 1.2.27</b>.
 803 </p>
 804 </directive>
 805
 806 <directive name="recovery_options" workers="AJP,SUB" default="0" required="false">
 807 Recovery options influence, how we should handle retries,
 808 in case we detect a problem with Tomcat.
 809 How often we will retry is controlled by the attribute <b>retries</b>.
 810 <p>
 811 This attribute is a bit mask. The following bits are allowed:<br/>
 812 1: don't recover if Tomcat failed after getting the request<br/>
 813 2: don't recover if Tomcat failed after sending the headers to client<br/>
 814 4: close the connection to Tomcat, if we detect an error when writing back
 815 the answer to the client (browser)<br/>
 816 8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set)<br/>
 817 16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set)<br/>
 818 </p>
 819 <p>
 820 This features has been added in <b>jk 1.2.6</b>.
 821 Option 4 has been added in version <b>1.2.16</b>,
 822 options 8 and 16 in version <b>1.2.24</b>.
 823 </p>
 824 </directive>
 825
 826 <directive name="fail_on_status" workers="AJP,SUB" default="0" required="false">
 827 Set this value to the HTTP status code that will cause a worker to fail
 828 if returned from Servlet container. Use this directive to deal with
 829 cases when the servlet container can temporary return non-200 responses
 830 for a short amount of time, e.g during redeployment.
 831 <p>
 832 The error page, headers and status codes of the original response will not be send back
 833 to the client. Instead the request will result in a 503 response.
 834 If the worker is a member of a load balancer, the member will
 835 be put into an error state. Request failover and worker recovery will be handled
 836 with the usual load balancer procedures.
 837 </p>
 838 <p>
 839 This feature has been added in <b>jk 1.2.20</b>.
 840 </p>
 841 <p>
 842 Starting with <b>jk 1.2.22</b> it is possible to define multiple
 843 status codes separated by space or comma characters.
 844 For example: <code>worker.xxx.fail_on_status=500,503</code>
 845 </p>
 846 <p>
 847 Starting with <b>jk 1.2.25</b> you can also tell the load
 848 balancer to not put a member into an error state, if a
 849 response returned with one of the status codes in
 850 fail_on_status. This feature gets enabled, by putting a minus sign in
 851 front of those status codes.
 852 For example: <code>worker.xxx.fail_on_status=-404,-500,503</code>
 853 </p>
 854 </directive>
 855
 856 <directive name="max_packet_size" workers="AJP,SUB" default="8192" required="false">
 857 This attribute sets the maximal AJP packet size in Bytes.
 858 The maximum value is 65536. If you change it from the default,
 859 you <b>must</b> also change the packetSize attribute of your AJP
 860 connector on the Tomcat side! The attribute packetSize is only available
 861 in Tomcat 5.5.20+ and 6.0.2+.
 862 <p>
 863 Normally it is not necessary to change the maximum packet size. Problems
 864 with the default value have been reported when sending certificates or
 865 certificate chains.
 866 </p>
 867 <p>
 868 This feature has been added in <b>jk 1.2.19</b>.
 869 </p>
 870 </directive>
 871
 872 <directive name="mount" workers="AJP,LB" default="" required="false">
 873 Space delimited list of uri maps the worker should handle. It is only used,
 874 if the worker is included in worker.list.
 875 <p>
 876 This directive can be used multiple times for the same worker.
 877 </p>
 878 </directive>
 879
 880 <directive name="secret" workers="AJP,LB,SUB" default="" required="false">
 881 You can set a secret keyword on the Tomcat AJP Connector. Then only requests
 882 from workers with the same secret keyword will be accepted.
 883 <p>
 884 Use <b>request.secret="secret key word"</b> in your Tomcat AJP Connector configuration.
 885 </p>
 886 <p>
 887 If you set a secret on a load balancer, all its members will inherit this secret.
 888 </p>
 889 <p>
 890 This feature has been added in <b>jk 1.2.12</b>.
 891 </p>
 892 </directive>
 893
 894 <directive name="max_reply_timeouts" workers="LB" default="0" required="false">
 895 If you use a <b>reply_timeout</b> for the members of a load balancer worker,
 896 and you want to tolerate a few requests taking longer than reply_timeout,
 897 you can set this attribute to some positive value.
 898 <p>
 899 Long running requests will still time out after reply_timeout milliseconds waiting for
 900 data, but the corresponding member worker will only be put into an error state,
 901 if more than <b>max_reply_timeouts</b> requests have timed out.
 902 More precisely, the counter for those bad requests will be divided by two,
 903 whenever the load balancer does its internal maintenance (by default every 60
 904 seconds).
 905 </p>
 906 <p>
 907 This features has been added in <b>jk 1.2.24</b> to make <b>reply_timeout</b> less
 908 sensitive for sporadic long running requests.
 909 </p>
 910 </directive>
 911
 912 <directive name="recover_time" workers="LB" default="60" required="false">
 913 The recover time is the time in seconds the load balancer will not try
 914 to use a worker, after it went into error state. Only after this time has passed,
 915 a worker in error state will be marked as in recovering, so that it will be
 916 tried for new requests.
 917 <p>
 918 This interval is not checked every time a request is being processed.
 919 Instead it is being checked during global maintenance. The time between two
 920 runs of global maintenance is controlled by worker.maintain.
 921 </p>
 922 <p>
 923 Do not set recover_time to a very short time unless you understand the implications.
 924 Every recovery attempt for a worker in error is done by a real request!
 925 </p>
 926 </directive>
 927
 928 <directive name="error_escalation_time" workers="LB" default="recover_time / 2" required="false">
 929 Setting a member of a load balancer into an error state is quite serious. E.g.
 930 it means that if you need stickyness, all access to the sessions of the
 931 respective node is blocked.
 932 <p>
 933 Some types of error detection do not provide a precise information, whether
 934 a node is completely broken or not. In those cases an LB will not immediately
 935 put the node into the error state. Only when there have been no successful
 936 responses for <b>error_escalation_time</b> seconds after such an error,
 937 will the node be put into error state.
 938 </p>
 939 <p>
 940 This features has been added in <b>jk 1.2.28</b>.
 941 </p>
 942 </directive>
 943
 944 <directive name="activation" workers="SUB" default="Active" required="false">
 945 Using this directive, a balanced worker of a load balancer
 946 can be configured as disabled or stopped. A disabled worker only gets
 947 requests, which belong to sessions for that worker. A stopped
 948 worker does not get any requests. Users of a stopped worker will
 949 loose their sessions, unless session replication via clustering is used.
 950 <p>
 951 Use <b>d</b> or <b>D</b> to disable and <b>s</b> or <b>S</b> to stop.
 952 If this directive is not present the deprecated directives
 953 "disabled" or "stopped" are used.
 954 </p>
 955 <p>
 956 This flag can be changed at runtime using status worker.
 957 </p>
 958 <p>
 959 This feature has been added in <b>jk 1.2.19</b>.
 960 </p>
 961 </directive>
 962
 963 <directive name="route" workers="SUB" default="worker name" required="false">
 964 Normally the name of a balanced worker in a load balancer is equal to the jvmRoute
 965 of the corresponding Tomcat instance. If you want to include a worker corresponding
 966 to a Tomcat instance into several load balancers with different balancing configuration
 967 (e.g. disabled, stopped) you can use this attribute.
 968 <p>
 969 Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and
 970 set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance.
 971 </p>
 972 <p>
 973 If this attribute is left empty, the name of the worker will be used.
 974 </p>
 975 <p>
 976 This attribute can be changed at runtime using status worker.
 977 </p>
 978 <p>
 979 If the route name contains a period, the part before the first period will be
 980 used as domain name, unless domain is set explicitly.
 981 </p>
 982 <p>
 983 This feature has been added in <b>jk 1.2.16</b>.<br/>
 984 The automatic domain rule has been added in <b>jk 1.2.20</b>.<br/>
 985 The attribute has been renamed from jvm_route to route in <b>jk 1.2.20</b>.
 986 </p>
 987 </directive>
 988
 989 <directive name="distance" workers="SUB" default="0" required="false">
 990 An integer number to express preferences between
 991 the balanced workers of an lb worker.
 992 A load balancer will never choose some balanced worker
 993 in case there is another usable worker with lower distance.
 994 <p>
 995 Only in case all workers below a given distance are in error, disabled or stopped,
 996 workers of a larger distance are eligible for balancing.
 997 </p>
 998 <p>
 999 This feature has been added in <b>jk 1.2.16</b>.
1000 </p>
1001 </directive>
1002
1003 <directive name="domain" workers="SUB" default="" required="false">
1004 Domain directive can be used only when the worker is a member of the load balancer.
1005 Workers that share the same domain name are treated as single worker. If sticky_session
1006 is used, then the domain name is used as session route.
1007 <p>
1008 This directive is used for large system with more then 6 Tomcats, to be able
1009 to cluster the Tomcats in two groups and thus lowering the session replication
1010 transfer between them.
1011 </p>
1012 <p>
1013 This feature has been added in <b>jk 1.2.8</b>.
1014 </p>
1015 </directive>
1016
1017 <directive name="redirect" workers="SUB" default="" required="false">
1018 Set to the name of the preferred failover worker. If worker matching
1019 SESSION ID is in error state then the redirect worker will be used instead.
1020 It will be used even if being disabled, thus offering hot standby.
1021 <p>
1022 If you explicitly set a route via the "route" attribute, you must set "redirect"
1023 to this route of the preferred failover worker and not to its name.
1024 </p>
1025 <p>
1026 This feature has been added in <b>jk 1.2.9</b>.
1027 </p>
1028 </directive>
1029
1030 <directive name="session_cookie" workers="LB" default="JSESSIONID" required="false">
1031 The name of the cookie that contains the routing identifier needed for session stickyness.
1032 The routing identifier is everything after a "." character in the value of the cookie.
1033 <p>
1034 This feature has been added in <b>jk 1.2.27</b>.
1035 </p>
1036 </directive>
1037
1038 <directive name="session_path" workers="LB" default=";jsessionid" required="false">
1039 The name of the path parameter that contains the routing identifier needed for
1040 session stickyness. The routing identifier is everything after a "." character in the value
1041 of the path parameter.
1042 <p>
1043 This feature has been added in <b>jk 1.2.27</b>.
1044 </p>
1045 </directive>
1046
1047 </advanceddirectives>
1048 </subsection>
1049
1050 <subsection name="Deprecated Worker Directives">
1051 <br/>
1052 <p>The following directives have been deprecated in the past. We include their documentation
1053 in case you need to use an older version of mod_jk. We urge you to update and not use
1054 them any more. Please migrate your existing configurations.
1055 </p>
1056 <deprecations>
1057 <directive name="cachesize" successor="connection_pool_size" default="see text" required="false">
1058 <warn>This directive has been deprecated since 1.2.16.</warn>
1059 Cachesize defines the number of connections made to the AJP backend that
1060 are maintained as a connection pool.
1061 It will limit the number of those connection that each web server child
1062 process can make.
1063 <p>
1064 Cachesize property is used only for multi threaded
1065 web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property
1066 should reflect the number of threads per child process. JK will discover
1067 the number of threads per child process on Apache 2 web server with worker-mpm and set
1068 its default value to match the ThreadsPerChild Apache directive. For IIS the default
1069 value is 10. For other web servers than Apache or IIS this value has to be set manually.
1070 </p>
1071 <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>
1072 </directive>
1073
1074 <directive name="cache_timeout" successor="connection_pool_timeout" default="0" required="false">
1075 <warn>This directive has been deprecated since 1.2.16.</warn>
1076 Cache timeout property should be used with <b>cachesize</b> to specify how to time JK should keep
1077 an open socket in cache before closing it. This property should be used to reduce the number of threads
1078 on the Tomcat web server.
1079 <p>
1080 Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating
1081 a new ajp13 thread on Tomcat side.
1082 </p>
1083 <p>
1084 The problem is that after an ajp13 connection is created, the child won't drop it
1085 until killed. And since the webserver will keep its childs/threads running
1086 to handle high-load, even it the child/thread handle only static contents, you could
1087 finish having many unused ajp13 threads on the Tomcat side.
1088 </p>
1089 </directive>
1090
1091 <directive name="recycle_timeout" successor="connection_pool_timeout" default="0" required="false">
1092 <warn>This directive has been deprecated since 1.2.16.</warn>
1093 The number of seconds that told webserver to cut an ajp13 connection after some time of
1094 inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be
1095 closed if it was not used for the configured time.
1096 It's a good way to ensure that there won't too old threads living on Tomcat side,
1097 with the extra cost you need to reopen the socket next time a request be forwarded.
1098 This property is very similar to <b>cache_timeout</b> but works also in non-cache mode.
1099 If set to value zero (default) no recycle will took place.
1100 </directive>
1101
1102 <directive name="balanced_workers" successor="balance_workers" default="" required="true">
1103 <warn>This directive has been deprecated since 1.2.7.</warn>
1104 A comma separated list of workers that the load balancer
1105 need to manage.
1106 </directive>
1107
1108 <directive name="disabled" successor="activation" default="False" required="false">
1109 <warn>This directive has been deprecated since 1.2.19.</warn>
1110 If set to <b>True</b> or <b>1</b> the worker will be disabled if member
1111 of load balancer. This flag can be changed at runtime using status worker.
1112 <p>
1113 This feature has been added in <b>jk 1.2.9</b>.
1114 </p>
1115 </directive>
1116
1117 <directive name="stopped" successor="activation" default="False" required="false">
1118 <warn>This directive has been deprecated since 1.2.19.</warn>
1119 If set to <b>True</b> or <b>1</b> the worker will be stopped if member
1120 of load balancer. The flag is needed for stop complete traffic of a sticky session
1121 worker. It is only useful, when you have a cluster that replicated the sessions.
1122 This flag can be changed at runtime using status worker.
1123 <p>
1124 This feature has been added in <b>jk 1.2.11</b>.
1125 </p>
1126 </directive>
1127
1128 <directive name="jvm_route" successor="route" default="worker name" required="false">
1129 <warn>This directive has been deprecated since 1.2.20.</warn>
1130 Normally the name of a balanced worker in a load balancer is equal to the jvmRoute
1131 of the corresponding Tomcat instance. If you want to include a worker corresponding
1132 to a Tomcat instance into several load balancers with different balancing configuration
1133 (e.g. disabled, stopped) you can use this attribute.
1134 <p>
1135 Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and
1136 set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance.
1137 </p>
1138 <p>
1139 If this attribute is left empty, the name of the worker will be used.
1140 </p>
1141 <p>
1142 This attribute can be changed at runtime using status worker.
1143 </p>
1144 <p>
1145 This feature has been added in <b>jk 1.2.16</b>.
1146 </p>
1147 </directive>
1148
1149 </deprecations>
1150 </subsection>
1151
1152 </section>
1153
1154 </body>
1155 </document>