The Apache Tomcat Connectors - Reference Guide (1.2.50)

workers.properties configuration

Introduction

A Tomcat worker is a Tomcat instance that is waiting to execute servlets or any other content on behalf of some web server. For example, we can have a web server such as the Apache HTTP Server forwarding servlet requests to a Tomcat process (the worker) running behind it.

The scenario described above is a very simple one; in fact one can configure multiple Tomcat workers to serve servlets on behalf of a certain web server. The reasons for such configuration can be:

We want different contexts to be served by different Tomcat workers to provide a development environment where all the developers share the same web server but own a Tomcat worker of their own.
We want different virtual hosts served by different Tomcat processes to provide a clear separation between sites belonging to different companies.
We want to provide load balancing, meaning run multiple Tomcat workers each on a machine of its own and distribute the requests between them.

There are probably more reasons for having multiple workers but I guess that this list is enough...

Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial explains how to work with it.

Configuration File Basics

Defining workers to the Tomcat web server plugin can be done using a properties file (a sample file named workers.properties is available in the conf/ directory).

Format, Comments, Whitespace

The lines in the file define properties. The general format is

<name>=<value>

Dots are used as part of the name to represent a configuration hierarchy.

Invalid directives will be logged during web server startup and prevent the web server from working properly. Some directives have been deprecated. Although they will still work, you should replace them by their successors.

Some directives are allowed multiple times. This will be explicitly noted in the tables below.

Whitespace at the beginning and the end of a property name or value gets ignored. Comments can be placed in any line and start with a hash sign '#'. Any line contents behind the hash sign get ignored.

Boolean properties can be set either using the numbers 0 (false) and 1 (true) as values, or off (false) and on (true) or any other string starting with the letters f (false), n (false), t (true) or y (true). The values are taken case insensitive. In this documentation we will stick to false and true.

Global Properties

These directives have global scope.

Directive Default Description

Directive	Default	Description
`worker.list`	`ajp13`	A comma separated list of workers names that the JK will use. When starting up, the web server plugin will instantiate the workers whose name appears in the worker.list property, these are also the workers to whom you can map requests. This directive can be used multiple times.
`worker.maintain`	`60`	Worker connection pool maintain interval in seconds. If set to the positive value JK will scan all connections for all workers specified in worker.list directive and check if connections needs to be recycled. Furthermore any load balancer does a global maintenance every worker.maintain seconds. During global maintenance load counters are decayed and workers in error are checked for recover_time. This feature has been added in jk 1.2.13.

worker.list

ajp13

A comma separated list of workers names that the JK will use. When starting up, the web server plugin will instantiate the workers whose name appears in the worker.list property, these are also the workers to whom you can map requests.

This directive can be used multiple times.

worker.maintain

60

Worker connection pool maintain interval in seconds. If set to the positive value JK will scan all connections for all workers specified in worker.list directive and check if connections needs to be recycled.

Furthermore any load balancer does a global maintenance every worker.maintain seconds. During global maintenance load counters are decayed and workers in error are checked for recover_time.

This feature has been added in jk 1.2.13.

Worker Properties

Each worker configuration directive consists of three words separated by a dot:

worker.<worker name>.<directive>=<value>

The first word is always worker. The second word is the worker name you can choose. In the case of load balancing, the worker name has an additional meaning. Please consult the Load Balancer HowTo.

The name of the worker can contain only the alphanumeric characters [a-z][A-Z][0-9][_\-] and is case sensitive.

Variables, Environment Variables

You can define and use variables in the workers.properties file. To define a variable you use the syntax:

<variable_name>=<value>

Dots are allowed in the variable name, but you have to be careful not to use variable names, that clash with standard directives. Therefore variable names should never start with "worker.".

To use a variable, you can insert "$(variable_name)" at any place on the value side of a property line. If a variable has not been defined before its use, we will search the process environment for a variable with the same name and use their value.

Property Inheritance

Often one wants to use the same property values for various workers. To reduce duplication of configuration lines and to ease the maintenance of the file, you can inherit properties from one worker to another, or even from a template to real workers.

The directive "reference" allows to copy configurations between workers or worker templates in a hierarchical way. If worker castor sets worker.castor.reference=worker.pollux then it inherits all properties of pollux, except for the ones that are explicitly set for castor.

Please note, that the value of the directive is not only the name of the referred worker, but the complete prefix including "worker.".

To use a template worker simply define it like a real worker, but do not add it to the worker.list or as a member to any load balancer. Such a template worker does not have to contain mandatory directives. This approach is especially useful, if one has a lot of balanced workers in a load balancer and these workers share most of their properties. You can set all of these properties in a template worker, e.g. using the prefix "worker.template1", and then simply reference those common properties in all balanced workers.

References can be used to inherit properties over multiple hops in a hierarchical way. The maximum depth for nesting references is 20. Be careful not to introduce a reference loop!

This feature has been added in jk 1.2.19.

List of All Worker Directives

Mandatory Directives

Mandatory directives are the one that each worker must contain. Without them the worker will be unavailable or will misbehave. Those directives will be marked with a strong font in the following tables.

Directive Default Description

Directive	Default	Description
`type`	`ajp13`	Type of the worker (can be one of ajp12, ajp13, ajp14, jni, lb or status). The type of the worker defines the directives that can be applied to the worker. Type ajp13 is the preferred worker type that JK uses for communication between web server and Tomcat. This type of worker uses sockets as communication channel. For detailed description of the ajp13 protocol stack browse to AJPv13 protocol specification. Type lb is used for load balancing workers, type status for status workers. Type ajp14 is experimental and not recommended, type ajp12 is obsolete. JNI workers are no longer supported and will likely not work. Do not use them.

type

ajp13

Type of the worker (can be one of ajp12, ajp13, ajp14, jni, lb or status). The type of the worker defines the directives that can be applied to the worker.

Type ajp13 is the preferred worker type that JK uses for communication between web server and Tomcat. This type of worker uses sockets as communication channel. For detailed description of the ajp13 protocol stack browse to AJPv13 protocol specification. Type lb is used for load balancing workers, type status for status workers.

Type ajp14 is experimental and not recommended, type ajp12 is obsolete.

JNI workers are no longer supported and will likely not work. Do not use them.

Connection Directives

Connection directives defines the parameters needed to connect and maintain the connections pool of persistent connections between JK and remote Tomcat.

Directive	Default	Description
`host`	`localhost`	Host name or IP address of the backend Tomcat instance. The remote Tomcat must support the AJP13 protocol stack. The host name can have a port number embedded separated by the colon (':') character.
`port`	`8009`	Port number of the remote Tomcat instance listening for defined protocol requests. The default value depends on the worker type. For ajp13 workers the default port is 8009, while for ajp14 type of worker that value is 8011.
`source`	`-`	Name or IP address used for the connection source (outgoing address). It should only be used on multi-homed hosts. This feature is experimental and has been added in jk 1.2.41.
`socket_timeout`	`0`	Socket timeout in seconds used for the communication channel between JK and remote host. If the remote host does not respond inside the timeout specified, JK will generate an error, and retry again. If set to zero (default) JK will wait for an infinite amount of time on all socket operations.
`socket_connect_timeout`	`socket_timeout*1000`	Socket connect timeout in milliseconds used for the communication channel between JK and remote host. If the remote host does not respond inside the timeout specified, JK will generate an error, and retry again. Note that `socket_timeout` is in seconds, and `socket_connect_timeout` in milliseconds, so in absolute terms the default `socket_connect_timeout` is equal to `socket_timeout`. This feature has been added in jk 1.2.27.
`socket_keepalive`	`false`	This directive should be used when you have a firewall between your web server and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System to send `KEEP_ALIVE` messages on inactive connections (interval depend on global OS settings, generally 120 minutes), and thus prevent the firewall to cut inactive connections. To enable keepalive set this property value to true. The problem with Firewall cutting inactive connections is that sometimes, neither web server or Tomcat have information about the cut and couldn't handle it.
`ping_mode`	`-`	This flag determines, under which conditions established connections are probed to ensure they are still working. The probe is done with an empty AJP13 packet (CPing) and expects to receive an appropriate answer (CPong) within some timeout. The value of the flag can be any combination of the following flags (multiple values are combined without any separators): C (connect): If set, the connection will be probed once after connecting to the backend. The timeout can be set by `connect_timeout`. If it is not set, the value of `ping_timeout` will be used instead. P (prepost): If set, the connection will be probed before sending each request to the backend. The timeout can be set by `prepost_timeout`. If it is not set, the value of `ping_timeout` will be used instead. I (interval): If set, the connection will be probed during the regular internal maintenance cycle, but only if it is idle longer than `connection_ping_interval`. The timeout can be set by `ping_timeout`. A If set, all of the above probes will be used. This feature has been added in jk 1.2.27. Connect and prepost probing were already available via `connect_timeout` and `prepost_timeout` since version jk 1.2.6.
`ping_timeout`	`10000`	Timeout in milliseconds used when waiting for the CPong answer of a CPing connection probe. The activation of the probes is done via `ping_mode`. The timeouts for `ping_mode` connect and prepost can be overwritten individually via `connect_timeout` and `prepost_timeout`. For compatibility reasons, CPing/CPong is also used, whenever `connect_timeout` or `prepost_timeout` are set, even if `ping_mode` is empty. This feature has been added in jk 1.2.27.
`connection_ping_interval`	`0 / (ping_timeout/1000)*10`	When using interval connection probing, connections idle for longer than this interval in seconds are probed by CPing packets whether they still work. Interval probing can be activated either by `ping_mode`, or by setting `connection_ping_interval` to some value bigger than zero. If you activate interval probing via `ping_mode`, then the default value of `connection_ping_interval` is `(ping_timeout/1000) * 10`. Note that `ping_timeout` is in milliseconds, and `connection_ping_interval` in seconds, so in absolute terms the default `connection_ping_interval` is 10 times `ping_timeout`. This feature has been added in jk 1.2.27.
`connection_pool_size`	`see text`	This defines the number of connections made to the AJP backend that are maintained as a connection pool. It will limit the number of those connection that each web server child process can made. Connection pool size property is only used for multi threaded web servers such as the Apache HTTP Server and Microsoft IIS. The connection_pool_size property needs to reflect the number of requests one web server process should be able to send to a backend in parallel. Usually this is the same as the number of threads per web server process. JK will discover this number for the Apache HTTP Server automatically and set the pool size to this value. For IIS the default value is 250 (before version 1.2.20: 10). We strongly recommend adjusting this value for IIS to the number of requests one web server process should be able to send to a backend in parallel. You should measure how many connections you need during peak activity without performance problems, and then add some percentage depending on your growth rate. Finally you should check, whether your web server processes are able to use at least as many threads, as you configured as the pool size. Do not use connection_pool_size with values higher then 1 on Apache 2.x with prefork MPM or Apache 1.3.x!
`connection_pool_minsize`	`(pool+1)/2`	Minimum size of the connection pool that will be maintained. Its default value is (connection_pool_size+1)/2. Do not use connection_pool_minsize with values higher then 1 on Apache 2.x with prefork MPM or Apache 1.3.x! This feature has been added in jk 1.2.16.
`connection_pool_timeout`	`0`	Cache timeout property should be used with connection_pool_minsize to specify how many seconds JK should keep an inactive socket in cache before closing it. This property should be used to reduce the number of threads on the Tomcat web server. The default value zero disables the closing (infinite timeout). Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating a new ajp13 thread on Tomcat side. The problem is that after an ajp13 connection is created, the child won't drop it until killed. And since the web server will keep its childs/threads running to handle high-load, even it the child/thread handle only static contents, you could finish having many unused ajp13 threads on the Tomcat side. You should keep this time interval in sync with the keepAliveTimeout attribute (if it is set explicitly) or connectionTimeout attribute of your AJP connector in Tomcat's server.xml. Note however, that the value for mod_jk is given in seconds, the one in server.xml has to use milliseconds.
`connection_acquire_timeout`	`retries*retry_interval`	Timeout the worker will wait for a free socket in cache before giving up. Its default value is *retries retry_interval. This feature has been added in jk 1.2.27**.
`lbfactor`	`1`	Only used for a member worker of a load balancer. The integer number lbfactor (load balancing factor) is how much we expect this worker to work, or the worker's work quota. Load balancing factor is compared with other workers that makes the load balancer. For example if one worker has lbfactor 5 times higher then other worker, then it will receive five times more requests.

Load Balancing Directives

Load balancer is a virtual worker that does not really communicate with Tomcat workers. Instead it is responsible for the management of several "real" workers. The worker is supposed to be a load balancer if it's worker type is lb. See worker's type directive.

Loadbalancer directives define the parameters needed to create the workers that are connecting to a remote cluster of backend Tomcat servers. Each cluster node has to have a worker defined.

Load balancer management includes:

Instantiating the workers in the web server.
Using the worker's load balancing factor, perform weighted round-robin load balancing where high lbfactor means stronger machine (that is going to handle more requests)
Keeping requests belonging to the same session executing on the same Tomcat worker.
Identifying failed Tomcat workers, suspending requests to them and instead fail over on other workers managed by the lb worker.

The overall result is that workers managed by the same lb worker are load balanced (based on their lbfactor and current user session) and also fail over so a single Tomcat process death will not "kill" the entire site.

If you want to use session stickiness, you must set different jvmRoute attributes in the Engine element in Tomcat's server.xml. Furthermore the names of the workers which are managed by the balancer have to be equal to the jvmRoute of the Tomcat instance they connect with.

The restriction on the worker names can be lifted, if you use the route attribute for the workers.

The following table specifies properties that the lb worker can accept:

Directive	Default	Description
`balance_workers`	`-`	A comma separated list of workers that the load balancer need to manage. This directive can be used multiple times for the same load balancer. This directive replaces old balanced_workers directive and can be used only with mod_jk versions 1.2.7 and up. As long as these workers should only be used via the load balancer worker, there is no need to also put them into the worker.list property.
`sticky_session`	`true`	Specifies whether requests with SESSION ID's should be routed back to the same Tomcat worker. If sticky_session is set to true sessions are sticky, otherwise sticky_session is set to false. Set sticky_session to false when Tomcat is using a Session Manager which can persist session data across multiple instances of Tomcat. The sticky_session setting can be overwritten using the Apache HTTP Server environment variable JK_STICKY_IGNORE and the worker map extension for sticky_ignore. This has been added in version 1.2.33.
`sticky_session_force`	`false`	Specifies whether requests with SESSION ID's for workers that are in error state should be rejected. If sticky_session_force is set to true and the worker that matches that SESSION ID is in error state, client will receive 500 (Server Error). If set to false failover on another worker will be issued with losing client session. This directive is used only when you set sticky_session=true. This feature has been added in jk 1.2.9.
`method`	`Request`	Specifies what method load balancer is using for electing the best worker. Please note, that session stickiness and perfect load balancing are conflicting targets, especially when the number of sessions is small, or the usage of sessions is extremely varying For huge numbers of sessions this usually is not a problem. Some methods note, that they aggregate in a sliding time window. They add up accesses, and on each run of the global maintain method, the load counters get divided by 2. Usually this happens once a minute, depending on the setting of worker.maintain. The value of the load counters can be inspected using the status worker. If method is set to R[equest] the balancer will use the number of requests to find the best worker. Accesses will be distributed according to the lbfactor in a sliding time window. This is the default value and should be working well for most applications. If method is set to S[ession] the balancer will use the number of sessions to find the best worker. Accesses will be distributed according to the lbfactor in a sliding time window. This method should be used, if sessions are your limiting resource, e.g. when you only have limited memory and your sessions need a lot of memory. Because the balancer does not keep any state, it actually does not know the number of sessions. Instead it counts each request without a session cookie or URL encoding as a new session. This method will neither know, when a session is being invalidated, nor will it correct its load numbers according to session timeouts or worker failover. If you know request URLs, that will be called without a session ID but should not be counted as new sessions, you should add them to the stateless mapping rule extension or set the Apache HTTP Server environment variable JK_STATELESS for them. If method is set to N[ext] the balancer will again use the number of sessions to find the best worker. All remarks concerning the Session method apply as well. The difference to the Session method is how the session count is handled in the sliding time window. The Next method does not divide by 2, instead it subtracts the current minimum number. This should effectively result in a round-robin session balancing, thus the name Next. Under high load, the two session balancing methods will result in a similar distribution, but Next will be better if you need to distribute small numbers of sessions. If set to T[raffic] the balancer will use the network traffic between JK and Tomcat to find the best worker. Accesses will be distributed according to the lbfactor in a sliding time window. This method should be used, if network to and from the backends is your limiting resource. If set to B[usyness] the balancer will pick the worker with the lowest current load, based on how many requests the worker is currently serving. This number is divided by the workers lbfactor, and the lowest value (least busy) worker is picked. This method is especially interesting, if your request take a long time to process, like for a download application. The method is not recommended for general use, because under high load on some hardware architectures the busy counter can become wrong. This feature has been added in version 1.2.9. The Session method has been added in version 1.2.20, the Next method in version 1.2.33.
`lock`	`Optimistic`	Specifies what lock method the load balancer will use for synchronising shared memory runtime data. If lock is set to O[ptimistic] balancer will not use shared memory lock to find the best worker. If set to P[essimistic] balancer will use shared memory lock. The balancer will work more accurately in case of Pessimistic locking, but can slow down the average response time. This feature has been added in jk 1.2.13.
`retries`	`2`	This directive also exists for normal workers. For those it has a different meaning. When making a request, the load-balancer worker will allocate the request to a member worker. If that member worker is either unable to service the request or fails to service the request, the request will be passed to another member worker until the request is processed, every member worker has attempted to process the request or lb_retries member workers have attempted to process the request. If the request remains unprocessed, the load-balancer worker will repeat the above process a maximum of retries times (including the original attempt). Before each retry, the load-balancer worker will pause for a time defined by the retry_interval directive. Note that this means that, if all workers fail, there will be a total of worker.retries * min(lb.lb_retries,member worker count) * lb.retries requests before a 504 response is returned to the client. So for an lb worker with four members and a default configuration, if all workers fail there will be a total of 8 requests before a 504 response is returned to the client. Until version 1.2.16 the default value was 3.
`lb_retries`	`2`	When making a request, the load-balancer worker will allocate the request to a member worker. If that member worker is either unable to service the request or fails to service the request, the request will be passed to another member worker until the request is processed, every member worker has attempted to process the request or lb_retries member workers have attempted to process the request. If the request remains unprocessed, the load-balancer worker will repeat the above process a maximum of retries times (including the original attempt). Before each retry, the load-balancer worker will pause for a time defined by the retry_interval directive. Note that this means that, if all workers fail, there will be a total of worker.retries * min(lb.lb_retries,member worker count) * lb.retries requests before a 504 response is returned to the client. So for an lb worker with four members and a default configuration, if all workers fail there will be a total of 8 requests before a 504 response is returned to the client. This feature has been added in jk 1.2.44. Prior to this feature being added, the load-balancer worker behaved as if lb_retries was equal to the number of member workers.

Status Worker Directives

The status worker does not communicate with Tomcat. Instead it is responsible for the load balancer management.

Directive	Default	Description
`css`	`-`	Specifies the url for cascading stylesheet to use.
`read_only`	`false`	A status worker with read_only=true will not allow any operations, that change the runtime state or configuration of the other workers. These are edit/update/reset/recover. This feature has been added in jk 1.2.20.
`user`	`-`	It is a list of users which gets compared to the user name authenticated by the web server. If the name is not contained in this list, access is denied. Per default the list is empty and then access is allowed to anybody. This directive can be used multiple times. This feature has been added in jk 1.2.20.
`user_case_insensitive`	`false`	By default, the user names are matched case sensitively. You can set user_case_insensitive=true to make the comparison case insensitive. This may be especially useful on the Windows platform. This feature has been added in jk 1.2.21.
`good`	`a.o,a.n,a.b,a.r`	For every load balancer worker, the status worker shows a summary of the state of its members. There are three such states, "good", "bad" and "degraded". These states are determined depending on the activation of the members (active, disabled, stopped) and their runtime state (ok, n/a, busy, recovering, probing, forced recovery, error). By default, members are assumed to be "good", if their activation is "active" and their runtime state is not "error". You can change this mapping, by assigning a list of values to the attribute "good". Each value gives a possible match for the members, and one match suffices. Each value is either a single character, or two characters combined with a dot ".". The single characters are the first characters in the words "active", "disabled", "stopped", "ok", "na", "busy", "recovering", "error". The additional states "probing" and "forced recovery" are always rated equivalent to "recovering". If a value consists only of a single character, then all members with this activation or runtime state will be assumed good. A combination of an activation and a runtime state concatenated with a dot "." does only apply to a member, that has exactly this activation and state. Members of a load balancer will first be matched against the state "bad", if they don't match, the state "good" will be tried, and if they still don't match, their state will be "degraded". This directive can be used multiple times. This feature has been added in jk 1.2.20.
`bad`	`s,e`	See: "good". By default, members are assumed to be "bad", if their activation is "stopped" or their runtime state is "error". This directive can be used multiple times. This feature has been added in jk 1.2.20.
`prefix`	`worker`	The prefix, which will be used by the status worker when producing properties output (mime=prop). Each property key will be prefixed by this value. This feature has been added in jk 1.2.20.
`ns`	`jk:`	This directive can be used to customise the XML output from the status worker. If set to `-` no namespace will be used. This feature has been added in jk 1.2.20.
`xmlns`	`-`	This directive can be used to customise the XML output from the status worker. If set to `-` no xmlns will be used. Default value is set to xmlns:jk="http://tomcat.apache.org" This feature has been added in jk 1.2.20.
`doctype`	`-`	This directive can be used to customise the XML output from the status worker. This value will be inserted to the output xml after the xml header. This feature has been added in jk 1.2.20.

Advanced Worker Directives

This table lists more advanced configuration options. Most of them only apply to some types of workers. We use the abbreviations AJP for ajp13/ajp14 workers used directly via the workers.list, LB for load balancer workers, and SUB for the workers used indirectly in a load balancer worker as a sub worker or member.

Directive	Worker Type	Default	Description
`connect_timeout`	`AJP,SUB`	`0`	Connect timeout property told web server to send a PING request on ajp13 connection after connection is established. The parameter is the delay in milliseconds to wait for the PONG reply. The default value zero disables the timeout (infinite timeout). This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. Disabled by default.
`prepost_timeout`	`AJP,SUB`	`0`	Prepost timeout property told web server to send a PING request on ajp13 connection before forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply. The default value zero disables the timeout (infinite timeout). This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. Disabled by default.
`reply_timeout`	`AJP,SUB`	`0`	The parameter is the number of milliseconds to wait for success during a read event. So this is not a timeout for the complete answer time of a request, but only for the maximum time between two packets received from Tomcat. Usually the longest pause is between sending the request and getting the first packet of the response. If the timeout passes without any data received from Tomcat, the web server will no longer wait for the rest of the response and send an error to the client (browser). Usually this does not mean, that the request is also aborted on the Tomcat backend. If the worker is a member of a load balancer, the load balancer might place the worker into an error state and retry the request on another member. See also max_reply_timeouts, retries and recovery_options. By default (value zero) the web server will wait forever which could be an issue for you. If you set a reply_timeout, adjust it carefully if you have long running servlets. The reply_timeout can be overwritten using the Apache HTTP Server environment variable JK_REPLY_TIMEOUT and the worker map extension for reply_timeout. This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and works on all servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT and the worker map extension have been added in version 1.2.27.
`retries`	`AJP,SUB`	`2`	This directive also exists for load balancer workers. For those it has a different meaning. The maximum number of times that the worker will send a request to Tomcat in case of a communication error. Each retry will be done over another connection. The first time already gets counted, so retries=2 means one retry after error. Before a retry, the worker waits for a configurable sleeping time. See also the attribute recovery_options for a more fine-grained control of retries and retry_interval for the sleep time configuration. Until version 1.2.16 the default value was 3.
`retry_interval`	`AJP,SUB`	`100`	The amount of time in milliseconds the worker sleeps before doing any retry. This features has been added in jk 1.2.27.
`recovery_options`	`AJP,SUB`	`0`	Recovery options influence, how we should handle retries, in case we detect a problem with Tomcat. How often we will retry is controlled by the attribute retries. This attribute is a bit mask. The following bits are allowed: 1: don't recover if Tomcat failed after getting the request 2: don't recover if Tomcat failed after sending the headers to client 4: close the connection to Tomcat, if we detect an error when writing back the answer to the client (browser) 8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set) 16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set) This features has been added in jk 1.2.6. Option 4 has been added in version 1.2.16, options 8 and 16 in version 1.2.24.
`fail_on_status`	`AJP,SUB`	`0`	Set this value to the HTTP status code that will cause a worker to fail if returned from Servlet container. Use this directive to deal with cases when the servlet container can temporary return non-200 responses for a short amount of time, e.g during redeployment. The error page, headers and status codes of the original response will not be send back to the client. Instead the request will result in a 503 response. If the worker is a member of a load balancer, the member will be put into an error state. Request failover and worker recovery will be handled with the usual load balancer procedures. This feature has been added in jk 1.2.20. Starting with jk 1.2.22 it is possible to define multiple status codes separated by space or comma characters. For example: `worker.xxx.fail_on_status=500,503` Starting with jk 1.2.25 you can also tell the load balancer to not put a member into an error state, if a response returned with one of the status codes in fail_on_status. This feature gets enabled, by putting a minus sign in front of those status codes. For example: `worker.xxx.fail_on_status=-404,-500,503`
`busy_limit`	`AJP,SUB`	`0`	If set to a positive number, the worker will only be used for a request, if it is currently working on less than this number of concurrent requests. Note that this is not related to the Busyness load balancing method. This feature is experimental and has been added in jk 1.2.41.
`max_packet_size`	`AJP,SUB`	`8192`	This attribute sets the maximal AJP packet size in Bytes. It should be a multiple of 1024. Configuration values that are not a multiple of 1024 will be aligned to the next multiple of 1024. The maximum value is 65536. If you change it from the default, you must also change the packetSize attribute of your AJP connector on the Tomcat side! The attribute packetSize is available in Tomcat 6.0.2 onwards. Normally it is not necessary to change the maximum packet size. Problems with the default value have been reported when sending certificates or certificate chains. This feature has been added in jk 1.2.19.
`prefer_ipv6`	`AJP,SUB`	`false`	When compiled with IPV6 support, this directive forces IPV6 address resolution for host names which have both IPV6 and IPV4 addresses. In case there is no IPV6 address defined for the given hostname this directive in ineffective. This directive will be also ineffective if there is only IPV6 address defined or if IP address is used for "host", either in IPV4 or IPV6 notation. This feature has been added in jk 1.2.38.
`secret`	`AJP,SUB,LB`	`-`	You can set a secret keyword on the Tomcat AJP Connector. Then only requests from workers with the same secret keyword will be accepted. Use attribute secret="secret key word" in your Tomcat AJP Connector configuration. (Historical note: the attribute name was requiredSecret in Tomcat 9.0, 8.x, 7.0 versions released earlier than February 2020, request.secret in Tomcat 6.0 and earlier.) If you set a secret on a load balancer, all its members will inherit this secret. This feature has been added in jk 1.2.12.
`mount`	`AJP,LB`	`-`	Space delimited list of uri maps the worker should handle. It is only used, if the worker is included in worker.list. This directive can be used multiple times for the same worker.
`max_reply_timeouts`	`LB`	`0`	If you use a reply_timeout for the members of a load balancer worker, and you want to tolerate a few requests taking longer than reply_timeout, you can set this attribute to some positive value. Long running requests will still time out after reply_timeout milliseconds waiting for data, but the corresponding member worker will only be put into an error state, if more than max_reply_timeouts requests have timed out. More precisely, the counter for those bad requests will be divided by two, whenever the load balancer does its internal maintenance (by default every 60 seconds). This features has been added in jk 1.2.24 to make reply_timeout less sensitive for sporadic long running requests.
`recover_time`	`LB`	`60`	The recover time is the time in seconds the load balancer will not try to use a worker, after it went into error state. Only after this time has passed, a worker in error state will be marked as in recovering, so that it will be tried for new requests. This interval is not checked every time a request is being processed. Instead it is being checked during global maintenance. The time between two runs of global maintenance is controlled by worker.maintain. Do not set recover_time to a very short time unless you understand the implications. Every recovery attempt for a worker in error is done by a real request!
`error_escalation_time`	`LB`	`recover_time / 2`	Setting a member of a load balancer into an error state is quite serious. E.g. it means that if you need stickyness, all access to the sessions of the respective node is blocked. Some types of error detection do not provide a precise information, whether a node is completely broken or not. In those cases an LB will not immediately put the node into the error state. Only when there have been no successful responses for error_escalation_time seconds after such an error, will the node be put into error state. This features has been added in jk 1.2.28.
`session_cookie`	`LB`	`JSESSIONID`	The name of the cookie that contains the routing identifier needed for session stickyness. The routing identifier is everything after a "." character in the value of the cookie. This feature has been added in jk 1.2.27.
`session_path`	`LB`	`;jsessionid`	The name of the path parameter that contains the routing identifier needed for session stickyness. The routing identifier is everything after a "." character in the value of the path parameter. This feature has been added in jk 1.2.27.
`set_session_cookie`	`LB`	`false`	Activates generation of session stickyness cookies. Typically you don't need this. Some web frameworks replace Tomcat session management and use a different way of generating session IDs. As a consequence the routing ID added by Tomcat to the end of the session ID is lost and we no longer can do sticky load balancing. As a workaround you can use the following steps: Choose a non-standard cookie name using the "session_cookie" attribute. Activate cookie sending by setting the attribute "set_session_cookie" to true. Set the attribute "session_cookie_path" to the correct application URI, like e.g. "/myapp/". The cookie will only be send if the request does not already contain a cookie of the same name, or that cookie does not contain a routing ID which the load balancer can fulfill. Especially after a node failover we will send a new cookie to switch stickyness to the new node. This feature has been added in jk 1.2.38.
`session_cookie_path`	`LB`	`-`	This attribute is only used if "set_session_cookie" is set to true. See "set_session_cookie" for a description. If the value of "session_cookie_path" is empty (default), then the send cookie will not contain a PATH information. This feature has been added in jk 1.2.38.
`activation`	`SUB`	`Active`	Using this directive, a balanced worker of a load balancer can be configured as disabled or stopped. A disabled worker only gets requests, which belong to sessions for that worker. A stopped worker does not get any requests. Users of a stopped worker will lose their sessions, unless session replication via clustering is used. Use d or D to disable and s or S to stop. If this directive is not present the deprecated directives "disabled" or "stopped" are used. This flag can be changed at runtime using status worker. This feature has been added in jk 1.2.19.
`route`	`SUB`	`worker name`	Normally the name of a balanced worker in a load balancer is equal to the jvmRoute of the corresponding Tomcat instance. If you want to include a worker corresponding to a Tomcat instance into several load balancers with different balancing configuration (e.g. disabled, stopped) you can use this attribute. Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance. If this attribute is left empty, the name of the worker will be used. This attribute can be changed at runtime using status worker. If the route name contains a period, the part before the first period will be used as domain name, unless domain is set explicitly. This feature has been added in jk 1.2.16. The automatic domain rule has been added in jk 1.2.20. The attribute has been renamed from jvm_route to route in jk 1.2.20.
`distance`	`SUB`	`0`	An integer number to express preferences between the balanced workers of an lb worker. A load balancer will never choose some balanced worker in case there is another usable worker with lower distance. Only in case all workers below a given distance are in error, disabled or stopped, workers of a larger distance are eligible for balancing. This feature has been added in jk 1.2.16.
`domain`	`SUB`	`-`	Domain directive can be used only when the worker is a member of the load balancer. Workers that share the same domain name are treated as single worker. If sticky_session is used, then the domain name is used as session route. This directive is used for large system with more then 6 Tomcats, to be able to cluster the Tomcats in two groups and thus lowering the session replication transfer between them. This feature has been added in jk 1.2.8.
`redirect`	`SUB`	`-`	Set to the name of the preferred failover worker. If worker matching SESSION ID is in error state then the redirect worker will be used instead. It will be used even if being disabled, thus offering hot standby. If you explicitly set a route via the "route" attribute, you must set "redirect" to this route of the preferred failover worker and not to its name. This feature has been added in jk 1.2.9.

Deprecated Worker Directives

The following directives have been deprecated in the past. We include their documentation in case you need to use an older version of mod_jk. We urge you to update and not use them any more. Please migrate your existing configurations.

Directive	Successor	Default	Description
`cachesize`	`connection_pool_size`	`see text`	This directive has been deprecated since 1.2.16. Cachesize defines the number of connections made to the AJP backend that are maintained as a connection pool. It will limit the number of those connection that each web server child process can make. Cachesize property is used only for multi threaded web servers such as Apache HTTP Server 2.x (all MPMs except prefork) and IIS. The cachesize property should reflect the number of threads per child process. JK will discover the number of threads per child process on the Apache HTTP Server with threaded MPM and set its default value to match the current ThreadsPerChild Apache configuration. For IIS the default value is 10. Do not use cachesize with values higher then 1 on Apache 2.x with prefork MPM or Apache 1.3.x!
`cache_timeout`	`connection_pool_timeout`	`0`	This directive has been deprecated since 1.2.16. Cache timeout property should be used with cachesize to specify how to time JK should keep an open socket in cache before closing it. This property should be used to reduce the number of threads on the Tomcat web server. Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating a new ajp13 thread on Tomcat side. The problem is that after an ajp13 connection is created, the child won't drop it until killed. And since the web server will keep its childs/threads running to handle high-load, even it the child/thread handle only static contents, you could finish having many unused ajp13 threads on the Tomcat side.
`recycle_timeout`	`connection_pool_timeout`	`0`	This directive has been deprecated since 1.2.16. The number of seconds that told web server to cut an ajp13 connection after some time of inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be closed if it was not used for the configured time. It's a good way to ensure that there won't too old threads living on Tomcat side, with the extra cost you need to reopen the socket next time a request be forwarded. This property is very similar to cache_timeout but works also in non-cache mode. If set to value zero (default) no recycle will took place.
`balanced_workers`	`balance_workers`	`-`	This directive has been deprecated since 1.2.7. A comma separated list of workers that the load balancer need to manage.
`disabled`	`activation`	`false`	This directive has been deprecated since 1.2.19. If set to true the worker will be disabled if member of load balancer. This flag can be changed at runtime using status worker. This feature has been added in jk 1.2.9.
`stopped`	`activation`	`false`	This directive has been deprecated since 1.2.19. If set to true the worker will be stopped if member of load balancer. The flag is needed for stop complete traffic of a sticky session worker. It is only useful, when you have a cluster that replicated the sessions. This flag can be changed at runtime using status worker. This feature has been added in jk 1.2.11.
`jvm_route`	`route`	`worker name`	This directive has been deprecated since 1.2.20. Normally the name of a balanced worker in a load balancer is equal to the jvmRoute of the corresponding Tomcat instance. If you want to include a worker corresponding to a Tomcat instance into several load balancers with different balancing configuration (e.g. disabled, stopped) you can use this attribute. Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance. If this attribute is left empty, the name of the worker will be used. This attribute can be changed at runtime using status worker. This feature has been added in jk 1.2.16.