Apache mod_cfml.so

Configuration Options

The default Apache configuration of mod_cfml is as follows:

LoadModule modcfml_module modules/mod_cfml.so
CFMLHandlers ".cfm .cfc .cfml"
ModCFML_SharedKey "secret key also set in the Tomcat valve config"
# Optional, all for logging and debugging:
# LogHeaders true
# LogHandlers true
# LogAliases true
# VDirHeader false

The following describes what these options do and how to utilize them...

LoadModule cfml_module modules/mod_cfml.so

This line tells Apache to load the mod_cfml module when Apache starts, so that it can be run in system memory. Mod_cfml is *very* small, and generates almost no memory-resident system footprint whatsoever.

CFMLHandlers ".cfm .cfc .cfml"

Optional
Values: [variable]
Default: ".cfm .cfc .cfml"

This variable is a space-delimited list of file extensions for mod_cfml to look for in an incoming request URI. All items need to start with the "." character.

The actual check is done on anything following the first "." (dot) in the requested filename. If the requested filename contains multiple dots, eg. "my.strange.name.cfm", then a match will be done on "strange.name.cfm", which will not match ".cfm".

Also be aware that the web directories do not contain a dot (".") in their name, as anything following the first dot will be regarded as file extension.

If the file extension is matched, then mod_cfml will add the mod_cfml headers to the incoming request. Tomcat will then use this information for a new web context (or web context host alias), in case it has not set up the web context before.

For example, you could add the value ".jsp" to this attribute, and automatically create Tomcat hosts for JSP-based sites. Strangely enough, there is nothing about mod_cfml that requires it to only be useful for CFML sites.

ModCFML_SharedKey "secret key also set in the Tomcat valve config"

This is a two-way setting: it must either be set both in Apache httpd and in Tomcat, or at none of them. The Apache side simply adds an incoming header with the shared key value. The Tomcat side checks if a secret key is set in it's config, and if so, requires any incoming request to have the shared key in it's incoming "X-ModCFML-SharedKey" header.

Logheaders false|true

Optional
Values: true or false
Default: false

This variable tells mod_cfml to log the incoming request headers that it sees. The logs will contain the incoming request headers as they are after mod_cfml has done it's job. The main purpose of this logging function is to make sure mod_cfml is detecting incoming requests (load balanced instances, for example) and ensure that headers are being modifed as the request passes through mod_cfml.

Logs sent from mod_cfml are sent as "Notices" - which means they will bypass typical Apache loglevels. It is fairly important to keep these set to "false" for large sites, as setting it to "true" can put a huge strain on both processing time and IO Waits, as massive log files are written. The main purpose of the mod_cfml logging options are for debugging purposes to ensure things are working properly. The logging functions were not written for or intended for every-day use.

IMPORTANT: Enabling logging is not recommended for production sites.

LogHandlers false|true

Optional
Values: true or false
Default: false

This variable tells mod_cfml to log how handlers are interpreted. First mod_cfml will log what it currently sees it's handlers as being (good for making sure you have your handlers set right), then it will log if the incoming request matches a handler value.

Again, all logs are sent to Apache as "Notices", so they bypass any Apache loglevel you may have set. Further, they are very IO and processing intensive. Logging is not recommended for every-day use.

LogAliases false|true

Optional
Values: true or false
Default: false

This variable tells mod_cfml if it needs to log the directory aliases it finds. This setting only has an effect if the VDirHeader setting underneath, is set to true (the default).

As said before, all logs are sent to Apache as "Notices", so they bypass any Apache loglevel you may have set. Further, they are very IO and processing intensive. Logging is not recommended for every-day use.

VDirHeader false|true

Optional
Values: true or false
Default: false

This variable tells mod_cfml if it needs to add the header X-VDirs. This header will contain a list of the directory mappings / virtual directories for the current web context.The information in this header is currently only used in Lucee, where it will recreate these mappings for the current request.

Frequently Asked Questions

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.