Tomcat Mechanics

Jump to: navigation, search
Articles in this series

Common Variables

Installing Tomcat generically (non distribution packaging) is straight forward; download the appropriate archive and unpack it. Once unpacked there are several environment variables commonly referred to by most Tomcat admins:

Variable Default Description
CATALINA_HOME (none) The main directory that represents the unpacked archive
CATALINA_BASE $CATALINA_HOME (Optional) Base directory for resolving dynamic portions of a Catalina installation
CATALINA_OUT $CATALINA_BASE/logs/catalina.out (Optional) Full path to a file where stdout and stderr will be redirected
CATALINA_OPTS (none) (Optional) Java runtime options used when the "start" command is executed
CATALINA_TMPDIR $CATALINA_BASE/temp (Optional) Temporary directory the JVM should use (
JAVA_HOME (none) Points at the Java Development Kit installation
JRE_HOME $JAVA_HOME Points at the Java Runtime Environment installation
JAVA_OPTS (none) (Optional) Java runtime options used when the "start" or "stop" command is executed

Configuration Files

Selected configuration files of the most interest:

File Function
conf/server.xml The main configuration file where most items are configured
conf/ Configuration for the logging infrastructure (juli, log4j, etc.)
conf/web.xml Common to all web application deployments (.jsp servlet mappings, mime types, etc.)
conf/catalina.policy Controls security policies when Java is started with -security
conf/ Controls class loading order and behaviour
conf/context.xml Contexts that will be loaded for every web application (sets WEB-INF/web.xml up)
conf/tomcat-users.xml User roles that can be used with various internal security classes

Filesystem Locations


Common subdirectories within the unpacked Tomcat directory for all versions:

Directory Purpose
bin/ Executable scripts such as, and
conf/ Configuration files such as server.xml, web.xml and
logs/ Default directory for logfiles
temp/ Various temporary files as needed (
webapps/ Location for .war (web archive) or unpacked web applications
work/ Location where .jsp files are pre-compiled

Tomcat 6 and above

Directory Purpose
lib/ Fundamental .jar (java archive) files for Tomcat operation common directory

Tomcat 5 and below

common/ Classes visible to both internal Tomcat and all web applications
common/lib/ Classes and resources in .jar format
common/il8n/ Translation .jar files
common/classes/ Unpacked classes and resources
common/endorsed/ Deployment specific .jar files
server/ Classes visible to internal Tomcat only (Catalina)
server/lib/ Classes and resources in .jar format
server/classes/ Unpacked classes and resources
server/webapps/ Core web applications for management such as host-manager and manager
shared/ Classes visible to all web applications
shared/classes/ Unpacked classes and resources
shared/libs/ Classes and resources in .jar format

Operational Scripts

Some of the commonly used scripts in $CATALINA_HOME/bin:

Script Function The main script for starting/stopping Tomcat Resolves symlinks and launches start $@ Resolves symlinks and launches stop $@ Resolves symlinks and launches version $@ stop|run|version (run stays attached to console) Resolves symlinks and launches configtest $@ (Tomcat 7 and above)

Classpath Usage

The script overwrites the standard $CLASSPATH environment variable common to java use; the CLASSPATH is first nulled then constructed manually. It loads scripts and files in this order common to all versions:

  1. $CATALINA_BASE/bin/
  2. $CATALINA_HOME/bin/
  3. $CATALINA_HOME/bin/bootstrap.jar

From this point onward the classes are loaded internally within Tomcat's java code and varies depending on version; see the Classloaders section of the References for links to each version's documentation.