This is the first post of a loosely connected series about JVM settings (some of them related to memory, some others not). I got kind of inspired by a series of discussion threads on various CFML-related lists sitting in my inbox for a while now (because I felt the urge to comment on them — but never got round to for various reasons…). I’d really like to get to Inbox-Zero with that particular email account, so let’s get some of those topics out of the way via blog posts then instead.
This first post deals with Railo on Tomcat and where to set JVM options in the first place. It might also be useful for Adobe ColdFusion users with a custom configuration running on Tomcat or users of Adobe ColdFusion 10.
When you install Railo with Tomcat, you might wonder what you can do to influence the default memory behaviour of Railo and Tomcat. Reasons for looking into this might be that you have a server with a lot of memory and want to use it (better) for your CFML server. There are plenty of other reasons, but those are beyond the scope of this post.
If you have installed Railo through one of Jordan‘s installers, it essentially gives you a version of Apache Tomcat with Railo deployed (and potentially, depending on your setup, also connect Railo/Tomcat to Apache or IIS).
For Windows users, the installation process normally ends up in a Windows service being installed on the server. The Apache Foundation provides a few tools that help you manage the service(s) and that are really worthwhile looking into. Also have a look at Paul Kukiel’s blog post – it shows and explains the Railo Tomcat Service Control Panel/App. This will help you to set some basic memory parameters and other Java options. Apparently on Windows, you can also tweak settings in the Windows Registry (ugly).
I’m not sure if there are similar UI-based tools for Linux and OS X, I certainly don’t tend to use them to set up daemons/services or for JVM configuration. So, if you’re on one of those platforms and want to make manual adjustments, you’d be looking into using catalina.sh or catalina.bat in Railo’s resp. Tomcat’s bin directory.
There are multiple approaches how you could shove your custom JVM options into the Tomcat configuration this way. Depending on operating system and your preferences you could tweak the catalina.sh or .bat files and set an environment variable in there or you could use your shell’s or system’s (global) way of setting environment variables or use Tomcat’s idea of setenv.sh or .bat (look in section 3.4). I trust you’d find a good way of how to do that for your own circumstances.
Note: Please be aware that if you are running Railo/Tomcat as a Windows service, the aforementioned manual changes to configuration files will not be picked up. It seems you then have to use Tomcat’s own service management tools as mentioned above to configure memory. For more info please refer to Jason Dean’s very comprehensive blog post on that issue.
However, at first glance Tomcat offers two places (environment variables) you could use: JAVA_OPTS and CATALINA_OPTS. In the vast majority of cases the latter is the correct option. There are a few interesting and very subtle difference between the two (from the docs/config files comments):
CATALINA_OPTS: Java runtime options used when the "start", "run" or "debug" command is executed. Include here and not in JAVA_OPTS all options, that should only be used by Tomcat itself, not by the stop process, the version command etc. Examples are heap size, GC logging, JMX ports etc. JAVA_OPTS: Java runtime options used when any command is executed. Include here and not in CATALINA_OPTS all options, that should be used by Tomcat and also by the stop process, the version command etc. Most options should go into CATALINA_OPTS.
So, what does this tell us? CATALINA_OPTS are specific to the Catalina process (Tomcat), JAVA_OPTS might be used for something else going on in your system. Also CATALINA_OPTS are the ones that are supposed to be used to launch the JVM but not the ones to be used for the process that gets spawned off to stop the JVM.
In most cases that differences is negligible, it does make a noticeable difference though when you’re using JMX (for instance to monitor your JVM remotely) as using JAVA_OPTS instead of CATALINA_OPTS for certain JVM settings might then make the shutdown process of Tomcat server actually break (Side note: This is a common occurrence on Adobe ColdFusion 8 and 9 because there’s no clear, default separation of JVM settings for the various start/stop actions in JRun). If you want to know more about this specific issue, read Roni Licht’s excellent post.
Comments on this entry are closed.