Tuning Tomcat IIS Connectors worker.properties and server.xml
By Pete Freitag
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
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 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 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
This formual also means that if you only have one site,
max_reuse_connections should be equal to
maxThreads setting is on the Tomcat side, and is located in the
server.xml file in the
<Connector> tag where the
maxThreads setting should be set to the sum of all
connection_pool_size values in all
worker.properties files that connect to this
maxThreads = ∑ connection_pool_size
connection_pool_timeout and connectionTimeout
Two other settings worth mention are the
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.
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
<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.
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:
- OpenSSL and ColdFusion / Lucee / Tomcat
- False TemplateNotFoundException ColdFusion 9
- J2EE Sessions in CF10 Uses Secure Cookies
- HashDOS and ColdFusion
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.