Pete Freitag Pete Freitag

Tuning Tomcat IIS Connectors worker.properties and server.xml

Published on August 12, 2019
By Pete Freitag
coldfusion

Through my consulting practice, I've helped out a number of people with IIS/Tomcat connector issues over the years. Here are some general guidelines you can use to tune the worker.properties and server.xml files when connecting Tomcat / ColdFusion to IIS using the AJP protocol.

It helps to understand that the IIS process is separate from the Tomcat process, so they need to talk to each other. They do this by communicating over the the network using either the HTTP protocol or the AJP protocol. The AJP protocol is an optimized protocol that should be more efficient than using HTTP, also Adobe has made some customization in the data that is sent in their version of the connector for the ColdFusion connectors.

There are two key files for configuration - the first is the worker.properties this controls the settings used on the IIS side of things. The server.xml controls the Tomcat side of things. When the settings are mismatched it can cause some problems. Such as: Service Temporary Unavailable - The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.

connection_pool_size

The connection_pool_size setting in worker.properties is arbitrary but sets the upper bound for the number of requests that can be processed at a given time (concurrently). If you set it too low throughput will suffer, if you set it too high throughput may also suffer.

max_reuse_connections

The max_reuse_connections setting in worker.properties tells the IIS connector how many connections is can reuse at a time, if you set this too high and have multiple sites using the same Tomcat / ColdFusion instance, then one of the sites starts hogging all of the total connection_pool_size. This is by far the most common cause of problem that I've seen. So for that reason you generally want to set this value to be:

max_reuse_connections = connection_pool_size / number_of_sites

Note that the number_of_sites here is the number of sites using the same connector instance, or sharing the same worker.properties file. The max_reuse_connections should never be larger than connection_pool_size.

This formual also means that if you only have one site, max_reuse_connections should be equal to connection_pool_size

maxThreads

The maxThreads setting is on the Tomcat side, and is located in the server.xml file in the <Connector> tag where the protocol="AJP/1.3".

The maxThreads setting should be set to the sum of all connection_pool_size values in all worker.properties files that connect to this Connector port.

maxThreads =  ∑	connection_pool_size

connection_pool_timeout and connectionTimeout

Two other settings worth mention are the connection_pool_timeout and connectionTimeout in server.xml also located in the Connector tag. These values should match, although the connection_pool_timeout is in seconds and the connectionTimeout is in milliseconds, so:

connectionTimeout = 1000 * connection_pool_timeout

In early versions of ColdFusion 10 these settings may have been out of sync causing some issues, in more recent versions of CF they are both usually set to 60 seconds.

Note that the connection_pool_timeout specifies when a connector thread is idle it will wait this many seconds before killing the thread. This setting does not mean that it will cancel a long running request after 60 seconds of processing.

In Conclusion

If you have one important site and high traffic, and a bunch of less important sites on the same server, using the same connector for all those sites may place some unnecessary bottlenecks on your important site. In a scenario like that you may want to create two connectors one for the important site, and another for less important sites.

For example if we have 1 high traffic site and 3 low traffic sites:

#high traffic site worker.properites
connection_pool_size=1000
max_reuse_connections=1000
#low traffic site worker.properites (3 sites)
connection_pool_size=150
max_reuse_connections=50

And in server.xml we might specify 1150 as the maxThreads

<Connector maxThreads="1150" ...>

Much of this article was inspired by Anit's ColdFusion 11 IIS Connector Tuning article, which goes into a bit more detail on some of these points.



coldfusion tomcat iis jakarta connectors

Tuning Tomcat IIS Connectors worker.properties and server.xml was first published on August 12, 2019.

If you like reading about coldfusion, tomcat, iis, jakarta, or connectors then you might also like:

Fixinator

The Fixinator Code Security Scanner for ColdFusion & CFML is an easy to use security tool that every CF developer can use. It can also easily integrate into CI for automatic scanning on every commit.


Try Fixinator

CFBreak
The weekly newsletter for the CFML Community


Comments

Hi Pete,
Thanks for an informative article on Tomcat connector settings in ColdFusion. May I add a suggestion. It's about the phrase, "Two other settings worth mention are the connection_pool_timeout and connectionTimeout in server.xml". This suggests that connection_pool_timeout is a connector setting in server.xml, which is incorrect. It is a worker setting in workers.properties.
by BKBK on 11/04/2019 at 10:20:59 AM UTC
This article, as well as Anit's, refer to worker.properties, but my recent CF2018 install where I just ran Update 8 has only workers.properties (plural workerS).

I assume that's the same thing, right? The entries in it appear at first glance to the the ones expected. Not a big deal, just confusing.
by Dave Merrill on 10/26/2020 at 3:45:12 PM UTC