ModCFML

Config Options

The default Tomcat Valve config line would look something like this:

<Valve
    className="mod_cfml.core"
    loggingEnabled="false"
    maxContexts="200"
    timeBetweenContexts="2000"
    scanClassPaths="false"
    sharedKey="secret key also set in the Apache/IIS config" />


classname="mod_cfml.core"

Required. Unchangable

Tells Tomcat to run the mod_cfml.core class when this valve is invoked.

loggingenabled="[true|false]"

Optional.
Default: false

This option enables logging within the mod_cfml valve. This is useful for determining if request header data is being passed to the Tomcat valve correctly, or if there are problems, it is useful for determining what those problems could be.

Logs are usually set to the "catalina.out" log on Linux systems, and for Windows Lucee/Railo installs to the "lucee-stdout" / "railo-stdout" log file.

maxContexts="200"

Optional.
Default: 200

The maxContexts value states how many web contexts may be created in Tomcat. Host aliases do not add up to this number, so an Apache VirtualHost with "Alias *.mydomain.com" will count as only 1 context in Tomcat.
The value should be a little bit higher then the total amount of configured websites in your frontend webserver.

If the maxContexts limit is reached, an error will be written to the Tomcat log files stating: "[mod_cfml] MaxContexts limit reached. No more contexts can be created!", and a 503 (Service Unavailable) error will be returned for any new contexts, along with the error message on-screen.

If you find yourself in need to reset the count, simply remove the {tomcat}/mod_cfml.dat file from your system, or restart Tomcat.

timeBetweenContexts="2000"

Optional.
Default: 2000 (2 seconds)

This value (stated in milliseconds) governs the context throttler, and sets the minimum time between the start of each context creation. Like the maxContexts value, this setting is specifically to help discourage certain kinds of Denial of Service attacks. The default setting of 2000 means "a maximum of 1 new website per 2 seconds may be added to Tomcat". In case of a server restart, the default setting may be uncomfortable for you if you have multiple high-traffic sites. In that case, you could change the setting to 0 (zero), which will prevent any errors going to end-users.

If you hit the limit enforced by the "timeBetweenContexts" value, an error will be written to the tomcat logs and a 503 (Service Unavailable) will be returned to the user. The error is specifically: "[mod_cfml] Time Between Contexts has not been fulfilled. Please wait a few moments and try again."

scanClassPaths="true|false"

Optional.
Default: false

This setting enables/disables the Tomcat Jar Scanner on each web context creation. This scan is the reason why web context creation in Tomcat seemed so slow, it takes multiple seconds to complete. For CFML engines, it is usually unnecessary to use it, and makes the web context loading 5 to 10 times faster.

If you are using Java/JSP pages in mod_cfml web contexts, or notice errors with jars which can not be found, then try setting this to True. If you are using Lucee or Railo, you might also be able to fix those errors by moving the missing jars to {web-context}/WEB-INF/lucee/lib/

sharedKey="secret key also set in the Apache/IIS config"

To be sure any context-creating requests come from our frontend webserver, you can set up a shared secret key. We strongly advise you to implement this security measure, as context creation means exposing internal resources to the outside world.

It works really simple: when the valve is invoked, and the necessary X-Tomcat-DocRoot header is given, then we check if a sharedKey is set for the valve. If it is, then we check to see if it matches the value of the incoming request header X-ModCFML-SharedKey. If it does not match, or the incoming header does not exist, an error message "mod_cfml request authentication failed!" is logged, and a 503 error is returned, with the error-message on-screen.

While implementing this, you should first configure and restart your frontend webserver (Apache or IIS). After that, configure the Tomcat valve.

waitforcontext="3"  (deprecated since version 1.1.01)

Optional.
Default: 3

This is the max. number of seconds a check will wait for context files to be created, right after a context is created. This check is still executed, but should never have to wait, because it runs after the context is instantiated. Will probably be removed in a future version.