Tuning ColdFusion IIS Connectors

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 workers.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 workers.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 formula 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 in workers.properties and the connectionTimeout setting found in server.xml 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.