The Apache Tomcat Connector - Reference

Guide
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

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.
Global Properties

These directives have global scope.

worker.list

Default

ajp13

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

worker.maintain

60

Furthermore any load balancer does a global maintenance every

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

type

ajp13

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
JNI workers have been deprecated. They 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

host

port

socket_timeout

Default

localhost

8009

Description
Host name or IP address of the backend
Tomcat instance. The remote Tomcat must
support the ajp13 protocol stack. The host
name can have aport number embedded
separated by the colon (':') character.
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 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