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