An in-depth look at mod_cfml's Tomcat valve

What is the mod_cfml Tomcat valve?

The mod_cfml Tomcat Valve is the part of the mod_cfml suite of software that dynamically creates hosts in Tomcat based on the request headers of the incoming request.

Does the mod_cfml Tomcat Valve check EVERY incoming request?

No. The suggested installation of the Valve is to install it in the default host of the Tomcat instance it's running in. Therefore, it only checks requests that get sent to the default host: hosts that don't exist yet and Tomcat doesn't know where else to send them.

How does the mod_cfml Tomcat Valve know when to add new hosts / aliases?

Incoming requests that are sent to Tomcat should contain at least one additional HTTP request header, the "X-Tomcat-DocRoot" header. This will be placed there by one of the mod_cfml web server components, either or the BonCode Connector).

Incoming requests that Tomcat doesn't know how to resolve get sent to the default host. In a default Tomcat installation, the default host is "localhost", so if Tomcat gets a request for, and doesn't know how to resolve that request, it will send it to "localhost". The mod_cfml Tomcat Valve takes advantage of this feature and uses it to catch any host that Tomcat doesn't know how to resolve.

The "magic" of the mod_cfml Tomcat Valve happens when Tomcat gets a request for, but that request gets sent to the default host because Tomcat doesn't know how to resolve it. Mod_cfml will see this "unknown host", and create a new host for it in Tomcat's memory while it's running.
If the request header "X-Webserver-Context" is also available, then the Tomcat valve will instead create a host with the header's value as a name (if it doesn't exist yet), and then add the current host as a host alias. This way, you can have one webserver context ("website"), with multiple hostnames, all running in the same Tomcat host context.
The Tomcat valve does this work by calling on the same libraries that the Tomcat "Host Manager" uses. So, realistically, mod_cfml uses pre-existing methods to make dynamically creating hosts in Tomcat very very easy.

Will there be a performance hit if I use the mod_cfml Tomcat Valve?

Yes, but ONLY on the first request for a new domain. The process of creating a new host entry in a running instance of Tomcat is somewhat complex, and requires many files to be written to the HDD to be read by Tomcat when the host is initialized. This process can take some time, depending on the speed of your drives and how busy they are. The average wait period for a new host context to be created is heavily dependent on the new setting "enableScanClassPaths". With enableScanClassPaths=false, the wait period is below 1 second; with enableScanClassPaths=true, it becomes around 3 to 5 seconds.
The wait time for a new host alias to be created is about 100 to 300 milliseconds.

If the request times out before the new host is created the request is passed to the default host and the default host site is displayed. HOWEVER, know that the host creation process threads are not killed even when the request times out. Instead, they continue and the host is eventually created. This means you can hit the "Refresh" button on your browser again and you will probably get your actual site rather then the default host. If this happens, you may increase the timeout limit for the initial request and mod_cfml will wait longer before timing out the request.

IMPORTANT: After the host/alias is created, mod_cfml is no longer involved, so there is no performance loss at all.

How can I remove or "re-install" a host that has been created wrong?

Accidents happen. Usually this just means that the host wasn't configured in the web server correctly before the config was copied to Tomcat. To clear out a host created in Tomcat with mod_cfml, go to the Tomcat Host Manager and remove the host. Mod_cfml will then create a new host entry whenever another request for that domain comes in.

The Tomcat Host Manager can usually be found here:

-> http://localhost:8888/host-manager/html (try port 8080 if this link doesn't work)

How can I upgrade mod_cfml whenever there is an update?

To update the mod_cfml Tomcat Valve, just stop Tomcat for a moment, remove the mod_cfml valve JAR file from the {tomcat}/lib/ directory, and drop the latest version of the mod_cfml Tomcat Valve jar file into the Tomcat lib folder again. Restart Tomcat, and you're all set. Any questions, feel free to post to the mailing list!

-> Mod_cfml Google Group