Links Reference Guide Generic HowTo Webserver HowTo AJP Protocol Reference Miscellaneous Documentation News | | 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 sensitive.
| 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).
| 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.
|
|
| Mandatory directives |
Mandatory directives are the one that each worker must contain. Without them the worker will
be unavailable or will misbehave.
| Directive | Default | Description |
|---|
type | ajp13 |
Type of the worker (can be one of ajp13, ajp14, jni, lb or status). 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.
| 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.
| socket_timeout | 0 |
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_keepalive | False |
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 120 minutes), and thus prevent the firewall to cut the connection.
To enable keepalive set this property value to the True.
The problem with Firewall cutting inactive connections is that sometimes, neither webserver or tomcat
have information about the cut and couldn't handle it.
| retries | 2 |
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 than two (the default value), on
each retry after default an extra wait of 100ms will be inserted.
| 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 used only for multi threaded
web servers such as Apache 2.0 (worker), IIS and Netscape. The connection_pool_size property
should reflect the number of threads per child process. JK will discover
the number of threads per child process on Apache 2 web server with worker-mpm and set
its default value to match the ThreadsPerChild Apache directive. For IIS the default
value is 10. For other web servers than Apache or IIS this value has to be set manually.
Do not use connection_pool_size with values higher then 1 on Apache 2.x prefork 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_size with values higher then 1 on Apache 2.x prefork 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_size 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 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.
| 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 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:
| 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.
These workers should not appear in 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 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.
| 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 or 1
and the worker that matches that SESSION ID is in error state, client will
recieve 500 (Server Error). If set to False or 0 failover on
another worker will be issued with loosing 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 stickyness 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 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 number of sessions
to find the best worker. Accesses will be distributed according to the
lbfactor in a sliding time window. 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. 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.
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.
This feature has been added in jk 1.2.9.
The Session method has been added in jk 1.2.20.
| lock | Optimistic |
Specifies what lock method the load balancer will use for synchronizing
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.
| secret | - |
Set a default secret word for all defined workers.
See worker secret attribute description for more info.
This feature has been added in jk 1.2.12.
|
|
| 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 customize 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 customize 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 customize 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 |
| Directive | Default | Description |
|---|
connect_timeout | 0 |
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.
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 | 0 |
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.
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 | 0 |
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 (value zero) the 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.
| recover_time | 60 |
Only used for load balancer workers.
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!
| max_packet_size | 8192 |
This attribute sets the maximal AJP packet size in Bytes.
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 only available
in Tomcat 5.5.20+ and 6.0.2+.
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.
| recovery_options | 0 |
Only used for a member worker of a load balancer.
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.
If the value 4 is added to the recovery options, the connection
between the webserver and tomcat will be closed if the client connection
to the webserver is terminated during the request/response cycle. This allows
to inform the servlet engine about broken client connections during lengthy operations.
This feature has been added in jk 1.2.16
| distance | 0 |
Only used for a member worker of a load balancer.
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 | - |
Only used for a member worker of a load balancer.
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 | - |
Only used for a member worker of a load balancer.
Set to 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.
This feature has been added in jk 1.2.9.
| activation | Active |
Only used for a member worker of a load balancer.
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 will loose 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 | 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 seperate 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.
| reference | - |
This attribute can be used for normal workers and for load balancer workers.
This directive allows to copy configurations between workers
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 explicitely 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.".
This directive 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 phantom worker, e.g. using the prefix "worker.template1", and then simply
reference those common properties in all balanced workers.
This feature has been added in jk 1.2.19.
| secret | - |
This attribute can be used for normal workers and for load balancer workers.
If set to AJP Connector secret keyword, only request with this keyword are successfull responding.
Use request.useSecret="true" and request.secret="secret key word" at your tomcat ajp
Connector configuration.
| mount | - |
This attribute can be used for normal workers and for load balancer workers.
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.
| fail_on_status | 0 |
Set this value to the HTTP status code that will cause a worker to fail
if returned from Servlet contatiner. 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.
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 coma characters.
For example: worker.xxx.fail_on_status=500,503
|
|
| 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 2.0 (worker), IIS and Netscape. The cachesize property
should reflect the number of threads per child process. JK will discover
the number of threads per child process on Apache 2 web server with worker-mpm and set
its default value to match the ThreadsPerChild Apache directive. For IIS the default
value is 10. For other web servers than Apache or IIS this value has to be set manually.
Do not use cachesize with values higher then 1 on Apache 2.x prefork 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 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.
| recycle_timeout | connection_pool_timeout | 0 |
This directive has been deprecated since 1.2.16.
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.
| 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 or 1 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 or 1 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 usefull, 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 seperate 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.
|
|
|
|
