The Apache Tomcat Connectors - Common HowTo

Each named worker should also have a few entries to provide additional information on his behalf. This information includes the worker's type and other related worker information. Currently the following worker types that exists are (JK 1.2.5):

Defining workers of a certain type should be done with the following property format:

worker.worker name.type=<worker type> Where worker name is the name assigned to the worker and the worker type is one of the four types defined in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).

# Defines a worker named "local" that uses the ajp12 protocol to forward requests to a Tomcat process.
worker.local.type=ajp12
# Defines a worker named "remote" that uses the ajp13 protocol to forward requests to a Tomcat process.
worker.remote.type=ajp13
# Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
worker.loadbalancer.type=lb

The worker type ajp12 has been deprecated and you should use instead ajp13 instead.

The ajp12 typed workers forward requests to out-of-process Tomcat workers using the ajp12 protocol over TCP/IP sockets. It does not use persistent connections.

The ajp12 worker properties are:

host property sets the host where the Tomcat worker is listening for ajp12 requests.

port property sets the port where the Tomcat worker is listening for ajp12 requests

lbfactor property is used when working with a load balancer worker, this is the load balancing factor for the worker. We'll see more on this in the load balancer worker section.

# worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
worker.worker1.type=ajp12
worker.worker1.host=www.x.com
worker.worker1.port=8007
worker.worker1.lbfactor=2

Note: The default port for ajp12 is 8007

The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajp13 protocol over TCP/IP sockets. The main difference between ajp12 and ajp13 are that:

• ajp13 is a more binary protocol and it tries to compress some of the request data by coding frequently used strings as small integers.
• ajp13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your web server and Tomcat).
• ajp13 has special treatment for SSL information so that the container can implement SSL related methods such as isSecure().

You should note that ajp13 is the recommended protocol to connect to Tomcat.

# worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
worker.worker2.type=ajp13
worker.worker2.host=www2.x.com
worker.worker2.port=8009
worker.worker2.lbfactor=3
# worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
worker.worker2.connection_pool_timeout=600
# worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
worker.worker2.socket_keepalive=1
# mount can be used as an alternative to the JkMount directive
worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*

Notes: In the ajp13 protocol, the default port is 8009

The load balancing worker does not really communicate with Tomcat workers. Instead it is responsible for the management of several "real" workers. This management includes:

• Instantiating the workers in the web server.
• Using the worker's load balancing factor, perform weighted round-robin load balancing where a higher lbfactor means stronger machine (that is going to handle proportionally more requests)
• Keeping requests belonging to the same session executing on the same Tomcat worker (session stickyness).
• Identifying failed Tomcat workers, suspending requests to them and instead failing 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. The following table specifies some properties that the lb worker can accept:

• balance_workers is a comma separated list of workers that the load balancer need to manage. 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. This directive can be used multiple times for the same load balancer.
• sticky_session specifies whether requests with SESSION ID's should be routed back to the same Tomcat worker. 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.

# The worker balance1 while use "real" workers worker1 and worker2
worker.balance1.balance_workers=worker1, worker2

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

# Add the status worker to the worker list
worker.list=jkstatus
# Define a 'jkstatus' worker using status
worker.jkstatus.type=status

Next thing is to mount the requests to the jkstatus worker. For Apache HTTP Servers use:

# Add the jkstatus mount point
JkMount /jkmanager/* jkstatus 

To obtain a higher level of security use the:

# Enable the JK manager access from localhost only
<Location /jkmanager/>
   JkMount jkstatus
   Require ip 127.0.0.1
</Location>

You can define "macros" in the property files. These macros let you define properties and later on use them while constructing other properties.

# property example, like a network base address
mynet=194.226.31
# Using the above macro to simplify the address definitions
# for a farm of workers.
worker.node1.host=$(mynet).11
worker.node2.host=$(mynet).12
worker.node3.host=$(mynet).13

Workers can reference configurations of other workers. If worker "x" references worker "y", then it inherits all configuration parameters from "y", except for the ones that have explicitly been set for "x".

# worker toe defines some default settings
worker.toe.type=ajp13
worker.toe.socket_keepalive=true
worker.toe.connect_timeout=10000
worker.toe.recovery_options=7
# workers tic and tac inherit those values
worker.tic.reference=worker.toe
worker.tac.reference=worker.toe

Please note, that the reference contains the full prefix to the referenced configuration attributes, not only the name of the referenced worker.

References can be nested with a maximum depth of 20. Be careful to avoid loops!

Attributes which are allowed multiple times for a single worker can not be merged from a worker and a reference. An attribute is only inherited from a reference, if it is not already set for the referring worker.

References are especially useful, when configuring load balancers. Try to understand the following two stage references:

# We only use one load balancer
worker.list=lb
# Let's define some defaults
worker.basic.port=8009
worker.basic.type=ajp13
worker.basic.socket_keepalive=true
worker.basic.connect_timeout=10000
worker.basic.recovery_options=7
# And we use them in two groups
worker.lb1.domain=dom1
worker.lb1.distance=0
worker.lb1.reference=worker.basic
worker.lb2.domain=dom2
worker.lb2.distance=1
worker.lb2.reference=worker.basic
# Now we configure the load balancer
worker.lb.type=lb
worker.lb.method=B
worker.lb.balanced_workers=w11,w12,w21,w22
worker.w11.host=myhost11
worker.w11.reference=worker.lb1
worker.w12.host=myhost12
worker.w12.reference=worker.lb1
worker.w21.host=myhost21
worker.w21.reference=worker.lb2
worker.w22.host=myhost22
worker.w22.reference=worker.lb2