Tomcat supports multiple instances, and you should consider installing Tomcat so that a single binary runtime directory supports multiple instances as a means of adhering to security best practices.
While the documentation on multiple instances is in the RUNNNING.txt file at the root of the Tomcat binary distribution file hierarchy, many people aren’t necessarily aware of the feature or why you might use it. To provide some insight, let’s look at how this functionality works and provide some insight to the related best practice for security.
To run multiple instances, two types of directories will exist:
1. Tomcat runtime as distributed by ASF and common to all instances – the path here is in environment variable
2. Another directory for each individual instance – the path to the active configuration (i.e. instance) is in environment variable
CATALINA_BASE directory will contain subdirectories bin, conf, logs, webapps, work, and temp. Let’s run through the purpose of each of those directories. (Note that this document presumes Tomcat running on a Unix variant, but for Windows the techniques are analogous. For instance, substitute the suffix .bat for .sh.)
·bin -- Optional. When present, contains setenv.sh to set instance specific environment variables and the variant of tomcat-juli.jar you wish to use for that instance (depending on whether you want to use log4j).
·conf -- Server configuration files, including server.xml
·lib -- Libraries and classes, specific to that instance. Jar and class files here will take precedence over the same ones in CATALINA_HOME/lib.
·logs -- Log and output files.
·webapps -- Automatically loaded web applications.
·work -- Temporary working directories for web applications.
·temp -- Directory used by the JVM for temporary files.
To start up a separate instance, you set
CATALINA_HOME and appropriately, along with other required environment variables, such as
JRE_HOME and then run
$CATALINA_HOME/bin/startup.sh. CATALINA_HOME must be set; however, if
CATALINA_BASE is not set, then the Tomcat script catalina.sh (invoked by startup.sh) sets it to the value of
Of course, when running multiple instances simultaneously on the same system, you have to make sure that certain configuration parameters, such as port numbers for Connectors, are unique.
One nice benefit of a separate
CATALINA_BASE directory is being able to easily run Tomcat with different Java runtime arguments. You may want to run one instance with a 2GB heap, and another instance with a 256MB heap. This is accomplished by editing
$CATALINA_BASE/bin/setenv.sh to set
CATALINA_OPTS to the appropriate value, -Xmx2G or -Xmx256M.
In addition, there are a number of significant advantages to having separate
CATALINA_BASE directories. For one, it makes upgrading to a new release clean and easy. All you need to do is unpack the Tomcat distribution in its own directory and then set
CATALINA_HOME to this new directory before running startup.sh. (Note that this works only for point releases; the differences between major releases of Tomcat, such as 6 and 7, are too significant for this to work in most cases.) Similarly, you can simultaneously run multiple instances that use different minor versions of Tomcat.
Let’s assume the Tomcat distribution has been installed in a directory owned by root and is /usr/local/apache-tomcat-7.0.30. In a well-controlled environment, it makes sense for root (or another privileged user) to have exclusive write permission to the Tomcat install hierarchy. You don’t want random users to be able to modify the runtime used by every Tomcat instance. A consequence of this is that non-privileged users cannot run Tomcat without setting
CATALINA_BASE to a suitable directory for which they have write permission. This is because a running Tomcat needs to have permission to create directories and files (e.g. exploded war files in the webapps directory, log files in the logs directory) under
CATALINA_BASE is not set, it defaults to
CATALINA_HOME and since this directory has restricted access, non-privileged users cannot create the files and directories required for Tomcat to run.
For Tomcat, one would designate a directory, such as /var/local/tomcat, as the standard location for all
CATALINA_BASE directories. This directory’s ownership, group, and permissions could be configured to allow members of a designated group, say tomcat, to create subdirectories therein. By convention, any
CATALINA_BASE directory would be located there, and Tomcat would be invoked with this sequence of commands:
prompt% export CATALINA_HOME=/usr/local/apache-tomcat-7.0.30
# node1 configured with proper subdirectories: bin, conf, logs, temp, webapps, work
prompt% export CATALINA_BASE=/var/local/tomcat/node;
>> If you would like read a version of this article that also covers how these practices are embedded within VMware’s vFabric tc Server, then please check out this link.