rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/workers.html

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