Tomcat workers

Previously, the article about webapp installation under Apache/Tomcat showed us how to put Apache and Tomcat to work together. One interesting concept appeared there. It is the idea of workers which will be presented now.

This short article will be divided on 3 parts. On the first part, we will define the worker. After we will see the which types of workers exist. At the end we will pass to a practical part and configure a sample worker to our hosting environment.

What is a worker on Tomcat ?

As we could see, worker helps Apache to sends the HTTP request to Tomcat. More precisely, workers are the Tomcat process which treat the request intercepted by web server like Apache.

For exemple, we can use workers on shared hosting to provide separate worker to each hosted web application. In this situation, each <VirtualHost /> will have their own worker. Other workers, thank to their specific types, can do more sophisticated stuff as supporting the requests's load balancing between multiple servers.

Which are the types of Tomcat's workers

Three worker types exist :
- ajp13 : represents Tomcat's instance and permits to transfer the request through the protocole ajpv13.
- lb : its name comes from first letters of "load balancer". This worker is a kind of "fake worker" because it doesn't handle the requests as the ajp13. Instead, it manages the "real workers" by checking their healthy or by initializing them on the other servers. His property, balance_workers, regroups all managed workers.
- status : responsible for load balancing management. For exemple, by setting JkMount /jkmanager/* jkstatus we will able to see the load balancing status under the URL http://myserver.com/jkmanager

Each worker has several properties. There are some of them :

Type Property Description
ajp13 host the hosts of woker (www2.x.com)
ajp13 port the port that AJP 1.3 Connector Tomcat is listenning (8009 by default)
ajp13 lbfactor the factor of the tasks which will be balanced to a worker. For exemple, if worker 'A' has lbfactor=10 and the worker 'B' lbfactor=1, the 'A' will receive the tasks 10 times more often than the 'B' one. If the 'B' would have lbfactor=5, the 'A' will receive the tasks only 2 times more than the 'B'.
ajp13 connection_pool_timeout The number of seconds in which the worker connections will stay on the connection pool
lb balance_workers a liste of workers managed by load balancer worker
lb sticky_session indicates if a session must be considered like "sticky". If true, the session is sticky. That means that every request of one session will be dispatched to the same worker. If this worker goes down, the session will be transferd to a new living worker. But the new worker doesn't know the data of the previous worker and loss of some session data is inevitable. To avoid the loss, we have to enable the session replication.

How to activate workers on the Apache side ?

When we want to activate workers, we need to do that on two sides : Apache's and Tomcat's. First, we will do it for the web server. In our case, we'll use the module called mod_jk. The mod_jk permits to connect Apache web server to the AJP port of a Java Server. AJP is a binary version of HTTP. Apache and Tomcat etablish the TCP connection and exchange the binary packages across it.

The etablishing of the connection is greedy. It's why the web server will try to make a persistent connection and send all packages across it. The data dispatch is assigned to the request. First sending data is the informations about the request like HTTP headers. The second package contains the request content.

The connections can have one of two states :
- idle : when it hasn't assigned request.
- assigned : when one request is assigned to it.

How to configure Tomcat's workers

Once mod_jk installed, we can pass to the next step and configure Tomcat's workers. For do that, we need to find the file called workers.properties. Usually it's stored at /etc/apache2/workers.properties.

We define a simple worker like this :

worker.list=mainWorker
worker.mainWorker.type=ajp13

This configuration means that one worker is called mainWorker and that its type is ajp13. The mainWorker is next defined on worker's list property. This property is very important because it's there where Tomcat is looking for workers to load on starting up.

But like we saw it above, the workers can have another properties. To define them, we replace just "type" by desired property. This is an exemple for host and port :

worker.mainWorker.host=www.myTestSite.com
worker.mainWorker.port=8080

What is a Tomcat's connector ?

We must also check if the appropriate AJP connector is active on /etc/tomcat7/server.xml. We look for an entry :


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

If it's commented, we decomment it. Otherwise, we don't change anything. This entry represents a connector. The connector is an endpoint by which requests are received and responses are returned. It's configured with the <Connector /> tag. The two most important attributes represent :
- a specific port to listen (port attribute)
- a special protocol to communicate (protocol).

In our case, we have also a redirectPort attribute. It means the port to which the SSL request will be redirected. The redirection has only place when the connector is supporting non-SSL requests and when the received requests needs the SSL transport.

Finally we need to put workers into Apache's virtual host configuration file, for example like that:

JkMount /* mainWorker
This entry means that all requests will pass through mainWorker defined previously.

This article explained the basics of Tomcat's workers. We saw that thanks to connectors, they are a kind of links between Apache web server and Tomcat servlet container. The links in which the binary representations of requests and response are exchanged. After, we saw how to configure workers on Apache and Tomcat side.


If you liked it, you should read:

📚 Newsletter Get new posts, recommended reading and other exclusive information every week. SPAM free - no 3rd party ads, only the information about waitingforcode!