papyri/md/tomcat_mechanics.md

# 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**

  - <http://tomcat.apache.org/tomcat-5.5-doc/class-loader-howto.html>
  - <http://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html>
  - <http://tomcat.apache.org/tomcat-7.0-doc/class-loader-howto.html>
  - <http://tomcat.apache.org/tomcat-8.0-doc/class-loader-howto.html>

**Resources**

  - <http://archive.apache.org/dist/tomcat/>
  - <http://tomcat.apache.org/whichversion.html>
  - <http://tomcat.apache.org/migration.html>
  - <http://wiki.apache.org/tomcat/FAQ>