ModCFML

An In Depth Look at Mod_cfml

What is mod_cfml.so?

Mod_cfml.so is one of the Web Server Components that are part of the mod_cfml suite. In particular, it is the Apache module that sends the web site configuration information off to the mod_cfml Tomcat Component.

What kind of configuration information is mod_cfml.so passing to Tomcat?

Specifically, mod_cfml records the "Document Root", the "Server Name", and available mappings of the current Virtual host. If you would have a VirtualHost in Apache like the following, written in httpd.conf:

<VirtualHost *:80>
    ServerName  www.luceerocks.com
    DocumentRoot  /var/www/luceerocks.com/data
    Alias /sharedimg   /var/www/shared/images
</VirtualHost>

Then the following request headers would be sent to Tomcat:

X-Webserver-Context  www.luceerocks.com-httpd.confl123
X-Tomcat-DocRoot  /var/www/luceerocks.com/data
x-vdirs  /sharedimg,/var/www/shared/images

The "x-vdirs" header is optional, and enabled by default. You can turn it off by setting "VDirHeader false" in the httpd configuration.

The X-Webserver-Context value is a combination of the ServerName, the config filename, and the line in the config file where the definition is at. This way, we can make sure this value is unique per Apache server.

Exactly how does mod_cfml get the document root and other information to Tomcat?

The approach that mod_cfml takes is to "ride" existing methods. That is, mod_cfml modifies the INCOMING request headers to include additional headers. These headers, as well as additional host information such as the "hostname" is read and utilized by the Tomcat Valve to dynamically create a host or host alias for all hosts on the server.

How does mod_cfml know which incoming requests to modify, and which not?

Modifying the incoming request header information for specific requests can cause problems depending on the kind of request that's being passed. Requests for images, for example, do not always complete properly if they contain stange headers like a "X-Tomcat-DocRoot" header.

To protect from these potential problems, mod_cfml reviews incoming requests and only modifies those requests that match its "CFMLHandlers" directive. That is. the kinds of files mod_cfml is supposed to "handle". By default, the CFMLHandlers attribute is set to a value of ".cfm .cfc .cfml". This means that only incoming requests for files that contain that string will be modified. Default documents are also modified as a built-in function of mod_cfml.

Can mod_cfml handle SES URL's?

Yes. Better even, since version 1.1, mod_cfml makes it possible to use SES URLs with a Tomcat backend, which is normally impossible to do.
If mod_cfml encounters path_info after the file extension, eg. /blog.cfm/id/17, the original request uri in Apache will be modified by stripping off the "/id/17", and re-adding that value in a new request header called "x-ajp-path-info". The CFML engines Lucee, Railo, and Open Blue Dragon support this header as a replacement for the regular path_info. The idea behind this comes from Bilal Soylu, who already implemented this in the BonCode connector.

What are the performance implications of mod_cfml.so?

Mod_cfml, thankfully, is a very very small piece of software in terms of most software. It's memory footprint and compile times are almost imperceptable. However, mod_cfml will add a small amount of time to each request. No official benchmarking has been done, our simplistic tests indicate that mod_cfml.so adds less then 1ms to each request.

Can I run mod_cfml.so in a cluster environment?

Yes. Mod_cfml.so works well in a cluster systems that deal with many domains and system administrators can potentially save a great deal of configuration time by using mod_cfml.so.

Can I use mod_cfml with web languages other then CFML?

Yes. mod_cfml was developed by the CFML community, but can easily be utilized by other languages that are supported in Tomcat, such as JSP.