# Tomcat Mechanics ## Contents - [Common Variables](#common-variables) - [Configuration Files](#configuration-files) - [Filesystem Locations](#filesystem-locations) - [Common](#common) - [Tomcat 6 and above](#tomcat-6-and-above) - [Tomcat 5 and below](#tomcat-5-and-below) - [Operational Scripts](#operational-scripts) - [Classpath Usage](#classpath-usage) - [References](#references) Articles in this series - **Tomcat Mechanics** - [Tomcat Configuration](tomcat_configuration.md) - [Tomcat Packaging](tomcat_packaging.md) - [Tomcat Logging](tomcat_logging.md) ## 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.io.tmpdir) | | `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/logging.properties` | 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/catalina.properties` | 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 Common subdirectories within the unpacked Tomcat directory for all versions: | **Directory** | **Purpose** | | ------------- | ---------------------------------------------------------------------------- | | `bin/` | Executable scripts such as `catalina.sh`, `startup.sh` and `shutdown.sh` | | `conf/` | Configuration files such as `server.xml`, `web.xml` and `logging.properties` | | `logs/` | Default directory for logfiles | | `temp/` | Various temporary files as needed (`java.io.tmpdir`) | | `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 | **Directory** | **Purpose** | | ------------------ | ------------------------------------------------------------------------- | | `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** | | --------------- | ------------------------------------------------------------------------------- | | `catalina.sh` | The main script for starting/stopping Tomcat | | `startup.sh` | Resolves symlinks and launches `catalina.sh start $@` | | `shutdown.sh` | Resolves symlinks and launches `catalina.sh stop $@` | | `version.sh` | Resolves symlinks and launches `catalina.sh version $@` | | `daemon.sh` | `stop`|`run`|`version` (_run_ stays attached to console) | | `configtest.sh` | Resolves symlinks and launches `catalina.sh configtest $@` (Tomcat 7 and above) | ## Classpath Usage The script `catalina.sh` 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/setenv.sh` 2. `$CATALINA_HOME/bin/setclasspath.sh` 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. ## References **Classloaders** - - - - **Resources** - - - -