The Jakarta Project
    Jakarta Tomcat Connector

Jakarta Tomcat Connector

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 Apache 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.

Directives

Each workers.properties directive consists of three words separated by dot. The first word is always worker. The second word is the worker name that can be any name. The worker name reflects the name of the jvmRoute defined in Tomcat's server.xml configuration file.

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

Defining workers

The generic workers.properties directive is in the form:

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

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).

DirectiveDefaultDescription
worker.listajp13 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.
Mandatory directives

Mandatory directives are the one that each worker must contain. Without them the worker will be unavailable or will misbehave.

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

AJP13 worker is the preferred worker type that JK uses for communication between web server and Tomcat. This type of worker uses sockets as communication channel. For detailed description of the AJP13 protocol stack browse to AJPv13 protocol specification

Connection directives

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

DirectiveDefaultDescription
hostlocalhost 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.
port8009 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.
socket_timeout0 Socket timeout in seconds used for communication channel between JK and remote host. If remote host does not respond inside that timeout the JK will generate an error, and retry again. If set to value zero (default) the JK will wait for infinite on all socket operations.
socket_keepaliveFalse This directive should be used when you have a firewall between your webserver and the Tomcat engine, who tend to drop inactive connections. This flag will told Operating System to send KEEP_ALIVE message on inactive connections (interval depend on global OS settings, generally 120ms), and thus prevent the firewall to cut the connection. To enable keepalive set this property value to the number greater then 0.

The problem with Firewall cutting inactive connections is that sometimes, neither webserver or tomcat have information about the cut and couldn't handle it.

recycle_timeout0 The number of seconds that told webserver to cut an ajp13 connection after some time of inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be closed if it was not used for the configured time. It's a good way to ensure that there won't too old threads living on Tomcat side, with the extra cost you need to reopen the socket next time a request be forwarded. This property is very similar to cache_timeout but works also in non-cache mode. If set to value zero (default) no recycle will took place.
retries3 The number of retries that the worker will try in case of error returned from remote Tomcat. If the number of retries set is greater then three (the default value), on each retry after default an extra wait of 100ms will be inserted.
cachesize1 Cachesize defines the number of connections made to the AJP backend that are maintained as a connection pool. It does not limit the number of those connection.

Cachesize property is useful when you're using JK in multi threaded web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property should reflect the number of threads per child process. The JK 1.2.8 will discover the number of threads per child process on Apache 2 web server with worker-mpm. For other web servers to will have to set that value manually.

Do not use cachesize with values higher then 1 on prefork mpm or apache 1.3.x!

cache_timeout0 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 WebServer.

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 webserver will keep its childs/threads running to handle high-load, even it the child/thread handle only static contents, you could finish having many unused ajp13 threads on the Tomcat side.

.
lbfactor1 Integer number used when the worker will be used inside load balancer worker, this is the load-balancing factor for the worker. The 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 lb_factor 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. The workers that are member of load balancer must not appear in the worker.list directive.

Loadbalancer directives defines the parameters needed to create a 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 weighed-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 fall-backing 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 fall-backed so a single Tomcat process death will not "kill" the entire site. The following table specifies properties that the lb worker can accept:

DirectiveDefaultDescription
balance_workers- A comma separated list of workers that the load balancer need to manage.

This directive replaces old balanced_workers directive and can be used only with mod_jk versions 1.2.7 and up.

These workers should not appear in the worker.list property!

sticky_sessionTrue Specifies whether requests with SESSION ID's should be routed back to the same Tomcat worker. If sticky_session is set to True or 1 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. By default sticky_session is set to True.
Advanced worker directives

DirectiveDefaultDescription
connect_timeout0 Connect timeout property told webserver to send a PING request on ajp13 connection after connection is established. The parameter is the delay in milliseconds to wait for the PONG reply.

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_timeout0 Prepost timeout property told webserver to send a PING request on ajp13 connection before forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply.

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_timeout0 Reply_timeout property told webserver to wait some time for reply to a forwarded request before considering the remote tomcat is dead and eventually switch to another tomcat in a cluster group. By default webserver will wait forever which could be an issue for you. The parameter is the number of milliseconds to wait for reply, so adjust it carefully if you have long running servlets.

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. Disabled by default.

recovery_options0 Recovery options property told webserver how to handle recovery when it detect that tomcat failed. By default, webserver will forward the request to another tomcat in LB mode (or to another ajp thread in ajp13 mode). values are : 0 (full recovery), 1 (don't recover if tomcat failed after getting the request), 2 (don't recover if tomcat failed after sending the headers to client), 3 (don't recover if tomcat failed getting the request or after sending the headers to client).

This features has been added in jk 1.2.6 to avoid problem with hung/broken tomcat's and works on all servlet engines supporting ajp13. Full recovery by default.

Advanced load balancer directives

With JK 1.2.x, new load-balancing and fault-tolerant support has been added via 2 new properties, local_worker_only and local_worker.

DirectiveDefaultDescription
local_workerFalse If local_worker is set to True it is marked as local worker. If in minimum one worker is marked as local worker, lb_worker is in local worker mode. All local workers are moved to the beginning of the internal worker list in lb_worker during validation.
local_worker_onlyFalse If local_worker_only is set to True it is marked as local only worker. If all local worker are in error state, and if set to False lb_worker tries to route the request to another balanced worker. If set to True error is returned.

The local_worker flag on worker tells the lb_worker which connections are going to the local worker.

This means that if a request with a session id comes in it would be routed to the appropriate worker. If this worker is down it will be send to the first local worker which is not in error state.

If a request without a session comes in, it would be routed to the first local worker. If all local worker are in error state, then the local_worker_only flag is important. With set to True, this request gets an error response. If set to False lb_worker tries to route the request to another balanced worker.

If one of the worker was in error state and has recovered nothing changes. The local worker will be check for requests without a session id (and with a session on himself) and the other worker will only be checked if a request with a session id of this worker comes in.

Why do we need such a complex behavior ?

We need a graceful shut down of a node for maintenance. The balancer in front asks a special port on each node periodically. If we want to remove a node from the cluster, we switch off this port. The loadbalancer can't connect to it and marks the node as down. But we don't move the sessions to another node. In this environment it is an error if the balancer sends a request without a session to an apache+mod_jk+tomcat which port is switched off. And if the load balancer determines that a node is down no other node is allowed to send a request without a session to it. Only requests with old sessions on the switched off node would be routed to this node. After some time nobody uses the old sessions and the sessions will time out. Then nobody uses this node, because all session are gone and the node is unreachable without a session-id in the request. If someone uses a session which timed out, our servlet system sends a redirect response without a session id to the browser. This is necessary, because on a switched off node apache and tomcat can still be up and running, but they are in an old state and should only be asked for valid old sessions. After the last session timed out, you can update the node etc. without killing sessions or moving them to another node. Sometimes we have a lot of big objects in our sessions, so it would be really time consuming to move them.


Copyright © 1999-2004, Apache Software Foundation