The Jakarta Project The mighty Tomcat - Meow!

Tomcat 3.3 User's Guide

This document is an introduction to the Tomcat 3.3 servlet container. It should be enough for anyone to install, configure and deploy Tomcat 3.3, or it's maintenance releases. As well, it answers many questions common to new users. If you have any comments or suggestions about this document don't hesitate to send them to the Tomcat mailing lists.

Since Tomcat 3.3 is a reference implementation of the Servlet 2.2 and JSP 1.1 specification, it would be very beneficial to become familiar with these documents, to better understand much of the behavior that Tomcat 3.3 implements. The Servlet 2.2 specification may be obtained here and the JSP 1.1 specification obtained here

One of the features of Tomcat 3.3 is its upgradability via add-on modules (though this feature is not yet well documented). Where such an add-on module affects Tomcat's behavior with respect to the Servlet 2.2/JSP 1.1 specifications, Tomcat's status as a reference implementation is invalided.

Tomcat 3.3 can operate as a standalone web server. In addition, it can operate as an out-of-process servlet container for other web servers, such as Apache. For some webservers, such as IIS, it can operate as an in-process servlet container. Most if this document involves information that is independent of the mode of operation. For details about the use of Tomcat 3.3 with other web servers, refer to the "Tomcat Documentation" given below.

Other important documents:

Table of Contents


About Tomcat: Q&A

See also the official Jakarta FAQ Page.

What is Tomcat?
Tomcat is the official reference implementation of the Java Servlet 2.2 and JavaServer Pages 1.1 technologies. Developed under the Apache license in an open and participatory environment, it is intended to be a collaboration of the best-of-breed developers from around the world.
Where can I download Tomcat?
At the Jakarta download page!
What are servlets? What are JSPs?
In a nutshell, servlets are memory-resident Java programs, running inside a servlet container (e.g., Tomcat!). Because they're memory-resident, they can quickly respond to requests, as they do not incur the overhead of process creation and subsequent cleanup, unlike CGI-based scripting, e.g. perl, etc.

From Sun's servlet site:

"The JavaTM Servlet API provides web developers with a simple, consistent mechanism for extending the functionality of a web server and for accessing existing business systems. A servlet can almost be thought of as an applet that runs on the server side -- without a face."

...and about JSPs (JavaServer Pages), again from Sun's servlet site:

"JSP technology is an extension of the servlet technology created to support authoring of HTML and XML pages. It makes it easier to combine fixed or static template data with dynamic content."

JSP is comparable to other technologies such as PHP and ASP, which combine programming/scripting with a markup language like HTML. The key difference being the programming language of choice. For example, PHP uses a C/C++/Java hybrid, ASP uses VBScript, and JSP utilizes the full power of the Java programming language. There have been many comparisons of these technologies, and each has its place in the astute developer's toolbox.

All of the above information is available at Sun's Java website, which is a starting place for all the ins and outs of JSPs, servlets, etc. Your time spent with these technologies will be much more rewarding if you first read through the JavaServer Pages and servlet specifications!

How do/can I contribute?
Please do! See the Jakarta project contribution page, right here. You'll probably want to subscribe to the tomcat-dev mailing list.
How come X, Y, or Z isn't working? Help!
While we hope to cater to many common issues, we have undoubtedly missed some. For more help, try (in this order):
  1. Your log files, in the logs subdirectory of your Tomcat installation. These are an untapped resource!
  2. Have a look through the Jakarta FAQ Page. Most installation and configuration questions can be found here.
  3. Search the Tomcat User List archive here or here and the Tomcat Developer List archive here or here.
  4. Post a question to the tomcat-user mailing list, to which you must first subscribe before posting your question.

Using Tomcat 3.3

A lot of effort has been put into making Tomcat easy to use as well as flexible. It comes with a default configuration which should be a good starting point for most users. Once you have Tomcat 3.3 up and running, there are many customizations from which you can choose.

To help identify which version of Tomcat you have, a "version" name has been incorporated in a number of places. It is in the name of the binary and source archives as well as the directory to which the archives expand. <version> will appear in the text below where this "version" name appears. The version will be "3.3" for the initial Tomcat 3.3 release, and "3.3.x" for subsequent maintenance releases.

Installing Tomcat

This section deals with installing the Tomcat 3.3 binary archive available from the Jakarta Project. It is also possible to install Tomcat 3.3 by building it from source, but that isn't covered in this document.

Environment Setup

There are a number of different methods to start and stop Tomcat 3.3. There are differences in the environmental setup needed for these methods. This section addresses the environmental setup needed for using the shell scripts and batch files provided to simplify starting and stopping Tomcat. This section also assumes you will be manually starting and stopping Tomcat from a shell or MS-DOS window.

Once you're sure they work, you may wish to set the environment variables in a configuration file: C:/AUTOEXEC.BAT for Windows, ~/.bash_profile or ~/.cshrc, etc. Alternatively, you could customize Tomcat's script or batch files to incorporate the environment settings.

Starting Tomcat

Assuming you have opened a shell or MS-DOS window and set the environment as described in the prior section, you are now ready to start and later stop Tomcat 3.3.

To start Tomcat 3.3, execute:

This will start Tomcat 3.3 in the background on Unix based systems, or in a new MS-DOS window on Windows based systems. If you are using Win9x, and you see "Out of environment space", double check your setup for the last item in the prior section.

You will need to wait a short period of time before Tomcat 3.3 is ready to serve requests. The very first use will need a little extra time since some WAR files will be expanded by default.

You can tell when Tomcat 3.3 has completed its startup when text like the following appears in the log output.

2001-09-01 14:23:30 - Http10Interceptor: Starting on 8080
2001-09-01 14:23:30 - Ajp12Interceptor: Starting on 8007
2001-09-01 14:23:30 - Ajp13Interceptor: Starting on 8009

In Tomcat's default configuration, Tomcat's output log is not assigned to a file. Instead, Tomcat's log output goes stderr. On Windows systems, you can switch to the MS-DOS window to see if this test has appeared.

As you might guess from the above log text, the default Tomcat 3.3 configuration will service HTTP requests on port 8080. If you start your browser and open http://localhost:8080/ you will see Tomcat 3.3's Welcome page.

In addition to serving HTTP, the default configuration will service Ajp12 protocol requests on port 8007 and Ajp13 protocol requests on 8009. These protocols are used by the "connectors" which allow Tomcat to be used as a Servlet/JSP container for an external web server, such as Apache. Also, the Ajp12 protocol is used by the Tomcat shutdown process.

Though documented below, here are a couple of items that you may find useful.

Stopping Tomcat

To perform a normal shutdown of Tomcat 3.3, a special "shutdown" request must be send from a separate process, or possibly a different computer. In the default configuration, that "shutdown" request must be made using the Ajp12 protocol. If the shell or MS-DOS window used to start Tomcat is not still open, first open a new one and set the environment the same as for starting Tomcat.

To stop Tomcat 3.3, execute:

The shutdown process incorporates a host, port, and a password. In the default configuration, the host defaults to localhost. This means that Tomcat 3.3 can only be shutdown from the same computer that started it. The port automatically defaults to the port being used by the Ajp12 protocol. The password defaults to "not specified". This means that a password will not be required to shutdown Tomcat 3.3.

Tomcat Shell and Batch Files

Tomcat's shell and batch files are found in Tomcat's bin directory. These files support "actions" beyond starting and stopping Tomcat. To help make better use of the functionality provided, the following table describes each of these files. If desired, you can customize these batch files to suit your needs.

Tomcat Shell and Batch files

FileDescription
cpappend.batThis batch file is used by tomcat.bat to build a classpath in a couple of tomcat.bat's other functions. It is not executed during Tomcat start and stop functions.
jspcShell script to invoke JSPC on Unix based systems. It uses tomcat with the "jspc" option to pre-translate JSP pages to Java files.
jspc.batBatch file to invoke JSPC on Windows based systems. It uses tomcat.bat with the "jspc" option to pre-translate JSP pages to Java files.
shutdown.batBatch file for stopping Tomcat on Windows based systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home directory, or one of its subdirectories. It executes tomcat.bat with the "start" argument. Features and limitations of tomcat.bat apply to this batch file.
shutdownShell script for stopping Tomcat on Unix based systems. It executes tomcat with the "stop" argument. Features and limitations of tomcat apply to this script.
tomcatThe main script for Unix based systems. It can start and stop Tomcat, as well as perform other functions. It makes a number of attempts to guess TOMCAT_HOME if not set explicitly (see script contents for details). It can also guess your JAVA_HOME if it is in your PATH environment variable.
startup.batBatch file for starting Tomcat on Windows based systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home directory, or one of its subdirectories. It executes tomcat.bat with the "start" argument. Features and limitations of tomcat.bat apply to this batch file.
startupShell script for starting Tomcat on Unix based systems. It executes tomcat with the "start" argument. Features and limitations of tomcat apply to this script.
tomcat.batThe main batch file for Windows based systems. It can start and stop Tomcat, as well as perform other functions. It can guess TOMCAT_HOME if it isn't set explicitly, provided this batch file is executed from Tomcat's home directory or one of its subdirectories. JAVA_HOME must be set for this batch file to function. An error message is displayed if not set.
tomcatEnv.batA batch file that executes tomcat.bat with the "env" option to set Tomcat's runtime environment in your MS-DOS window.

You may have noted that tomcat and tomcat.bat are the primary scripts. They are the scripts that actually perform the "actions". The list of actions, as well as additional environment variables they support, are described in the next section.

Note that most actions involve starting the org.apache.tomcat.startup.Main class in a Java VM. This class and some classes it uses also accept arguments. To take advantage of the full capabilities of Tomcat, you will need to become familiar with these arguments as well. See Tomcat Task Arguments for those details.

tomcat/tomcat.bat Actions

The tomcat shell script and tomcat.bat batch files contain the code that invokes the various features of Tomcat 3.3. It supports a number of actions specified by the first argument. The following table lists the supported actions. Almost all of the actions involve starting a Java VM. An environment variable, TOMCAT_OPTS or JSPC_OPTS, is provided for specifying Java VM options, such as "-Xmx256m" and system property settings, such as "-Dmy.prop=myvalue". The jspc action uses the JSPC_OPTS environment variable. All other actions with support this environment variable use TOMCAT_OPTS.

Note: On Win9x, you will not be able to include system property settings in TOMCAT_OPTS or JSPC_OPTS because the SET command will not accept a line with more than one equals sign. If you need an additional system property setting, you will need to modify your tomcat.bat to include it on the command line.

Actions supported by the tomcat and tomcat.bat scripts

ActionDescription
startThis action starts up Tomcat in the background on Unix based systems, and in a new MS-DOS window on Windows based systems. Java VM options may be specified in the TOMCAT_OPTS environment variable.
stopThis actions tries to stop the running Tomcat. Java VM options may be specified in the TOMCAT_OPTS environment variable.
runThis action starts up Tomcat in the foreground on Unix based systems, and in the current MS-DOS window on Windows based systems. Java VM options may be specified in the TOMCAT_OPTS environment variable.
enableAdminRewrites the apps-admin.xml file in Tomcat's conf directory so that the admin web application is "trusted". For security reasons, the admin web application is "untrusted" by default. If you plan to leave the admin web application trusted, you should change the admin password found in the admin-users.xml file in the conf/users directory. Java VM options may be specified in the TOMCAT_OPTS environment variable.
envSets the TOMCAT_HOME and CLASSPATH environment variables to match Tomcat's runtime environment. This is useful for compiling servlets or other Java files for use within Tomcat. For best results, ensure TOMCAT_HOME is set to an absolute path. If set to "." or "..", the CLASSPATH environment variable will be invalid if you leave the current directory.
jspcPre-translates specified JSP pages to Java files. Java VM options may be specified in the JSPC_OPTS environment variable.
estartStarts Tomcat without reading the server.xml file. Instead, the set of modules making up the instance of Tomcat is created internally by org.apache.tomcat.startup.EmbededTomcat. This command is useful for testing customized versions of the EmbededTomcat class when trying to embed Tomcat in an application. Java VM options may be specified in the TOMCAT_OPTS environment variable.

Except for the env action, each action corresponds to a "task" supported by the org.apache.tomcat.startup.Main class. The tomcat and tomcat.bat files, as well as the files that call them, will pass additional arguments on the command line to the Main class as arguments. See the next section for what arguments are supported by each of the tasks.

Also note that the TOMCAT_HOME environment variable is passed to the startup class via a tomcat.home system property.

Tomcat Task Arguments

The org.apache.tomcat.startup.Main class is the primary class used for executing a Tomcat "task", i.e. start, stop, etc. The term "task" is used instead of "action" because it is more than just an argument here. Each task has an associated class which will be executed to perform the task. The first argument passed to the main() method of org.apache.tomcat.startup.Main will determine which "task" class gets executed. Each of the "task" classes supports its own set of arguments. These arguments are documented in the table that follows.

Note: The arguments to each of the tasks may be optionally preceded by a '-'. However, the "task" argument must not be preceded by a '-'. If you specified -stop as the task, the default "start" task would be executed and -stop passed to the "start" task as an argument.

Tasks supported by org.apache.tomcat.startup.Main

TaskArgument Description
start
run
estart
  Starts Tomcat using the org.apache.tomcat.startup.EmbededTomcat class. This is the default action.
 config <file>
or
<file>
Use specified server configuration file instead of the default server.xml.
 debug <level> Set the debug level for the ContextManager.
 estart Starts Tomcat without reading the server.xml file. Instead, the Tomcat instance is constructed internally by this class.
 helpDisplay usage information.
 home <dir>
or
<dir>
Use specified directory as Tomcat's home directory, i.e. the directory under which the conf, webapps, logs, and work directories are found.
 install <dir>
or
<dir>
Use specified directory as Tomcat's install director, i.e. where the lib directory is found.
 sandbox Run Tomcat with a security manager.
 jkconf Generate configuration files instead of starting Tomcat.
stop  Stops Tomcat using the org.apache.tomcat.startup.StopTomcat class.
 ajpid <file>
or
secretFile <file>
Specify the defaults file written by the Ajp12Connector or Ajp13Connector module. It contains default values for port, host, and pass arguments. The default value is TOMCAT_HOME/conf/ajp12.id or TOMCAT_HOME/conf/ajp13.id if ajp12 or ajp13 is specified, respectively. If neither ajp12 or ajp13 is specified, the ajpid file defaults first to TOMCAT_HOME/conf/ajp13.id, and if not found, defaults to TOMCAT_HOME/conf/ajp12.id.
 ajp12Specifies that the ajp12 protocol should be used for shutdown. It implies the format of the ajpid file as that written by the Ajp12Connector.
 ajp13Specifies that the ajp13 protocol should be used for shutdown. It implies the format of the ajpid file as that written by the Ajp13Connector.
 ajpid12 <file>
[Tomcat 3.3.1]
Equivalent to specifying ajpid <file> and ajp12.
 ajpid13 <file>
[Tomcat 3.3.1]
Equivalent to specifying ajpid <file> and ajp13.
 helpDisplay usage information.
 home <dir>
or
<dir>
Use specified directory as Tomcat's home directory, i.e. the directory under which the conf directory is found.
 host <host> The host running the Tomcat instance you wish to shutdown. Defaults to value in defaults file if available. Otherwise it defaults to the local system.
 port <port> The port of the Ajp12Connector in the Tomcat instance you wish to shutdown. Must be specified if a default value can not be read from the defaults file.
 pass <string>
or
secret <string>
The "secret" password string expected by the Ajp12Connector for a shutdown request. The Ajp12Connector defaults to not using a "secret" string, in which case this argument may be omitted. If the Ajp12Connector is using a "secret" string, you must specify the same string if the default can not be read from the defaults file or the shutdown will fail.
enableAdmin  Rewrites the TOMCAT_HOME/conf/apps-admin.xml context configuration file using the org.apache.tomcat.startup.EnableAdmin class.
 home <dir>
or
<dir>
Use specified directory as Tomcat's home directory, i.e. the directory under which the conf/apps-admin.xml file is found.
jspc  Pre-compiles JSP pages using the org.apache.tomcat.startup.Jspc class.
  arguments not yet documented

The start, run, and estart tasks assume a command line argument that doesn't match one of the predefined arguments is a ContextManager property name and the next command line argument is its value. Thus a command such as:

bin/startup myprop myvalue

would define a ContextManager property named "myprop" with a String value of "myvalue". ContextManager properties can used for parameter substitution in the server.xml file. Set the Variable substitution section of the Server.xml document for details. There are also some ContextManager properties supported by certain modules. These are listed in the following table.

Module Context Property Description
Ajp12Connector ajpid12 Overrides the ajpidFile attribute to specify the file in which to record Ajp12 connector info and password.
Ajp13Connector ajpid13 Overrides the ajpidFile attribute to specify the file in which to record Ajp13 connector info and password.
LoaderInterceptor11 additionalJars List of jars to be added to each web application.


Configuring Tomcat 3.3

Customizing Tomcat will involve adding or modifying one or more files involved with Tomcat. The next section describes the directory structure of Tomcat 3.3 to document where files are found. Following that are sections document the two parts to Tomcat configuration.

Tomcat Directory Structure

After installing Tomcat 3.3, you should have the following directory structure under "jakarta-tomcat-<version>". Customization of Tomcat 3.3 will involve adding or modifying files in one or more of these directories.

Directory Contents
bin Startup/shutdown scripts and other useful files.
conf Configuration files, including modules.xml, server.xml, and a number of apps-<name>.xml.
conf/auto Directory where auto-generated configuration files are written.
conf/jk Directory containing mod_jk specific configuration files.
conf/jserv Directory containing mod_jserv specific configuration files.
conf/users Directory containing user name/password configuration files. These are used by the SimpleRealm module for authentication.
doc Miscellaneous documents regarding Tomcat.
lib Jar files that are used for starting and stopping Tomcat.
lib/container Jar files that make up the Tomcat server classes. Any Jar file in this directory is automatically included in Tomcat's Server Classloader. See Configuring Classes.
lib/common Jar files that contain classes shared between the Tomcat server and all web applications. Any Jar file in this directory is automatically included in Tomcat's Common Classloader. See Configuring Classes.
lib/apps Jar files that contain classes shared between all web applications. Any Jar file in this directory is automatically included in Tomcat's Apps Classloader. See Configuring Classes.
logs This is where Tomcat places its log files by default.
modules Directory where "add-on" WARs are placed.
native Base directory for native source code.
src Currently empty. Tomcat's source code isn't currently part of the binary distribution.
webapps Sample web applications. Any .war files placed here will be automatically expanded. See Deploying WAR Files.

Additionally you can, or Tomcat will, create the following directories:

work Where Tomcat places intermediate files (such as compiled JSP files) during its work. If you delete this directory while Tomcat is running you will not be able to execute JSP pages.
classes Any class that you add to this directory will find its place in Tomcat's classpath.

Configuring Classes

Configuring classes refers to configuring what classes are available and the scope of their availability when Tomcat 3.3 is running. You may wish to add additional classes and jars. Also, a web application may need some modification based on what Tomcat 3.3 makes available by default.

The available classes are determined by the classloader hierarchy that Tomcat 3.3 creates when it starts up. The classloader hierarchy built by Tomcat 3.3 looks like this:

Server Classloader
directory:
lib/container
default contents:
crimson.jar
facade22.jar
jasper.jar
tomcat_modules.jar
tomcat_util.jar
xalan.jar
(if RPM)commons-collections.jar
commons-dbcp.jar
commons-pool.jar
   
Webapp Classloader(s)
directory:
WEB-INF/classes
WEB-INF/lib
|
Apps Classloader
directory:
lib/apps
default contents:
empty
 \ / 
  
Common Classloader
directory:
lib/common
default contents:
connector_util.jar
core_util.jar
etomcat.jar
jasper-runtime.jar
servlet.jar
tomcat_core.jar
  
  |  
  
Application Classloader
the CLASSPATH classloader
default contents:
tomcat.jar
  
  |  
  
JDK Extensions Classloader
directory:
jdk/jre/lib/ext
  

In this classloader hierarchy, classloaders can access classes in classloaders beneath them. They can not access classes in classloaders to the side or above! To understand why this is important, consider whether web applications would have access to an XML parser in this classloader hierarchy. A brief inspection should reveal that in Tomcat 3.3, web applications would not normally have access to an XML parser. The crimson.jar and xalan.jar are tucked away in the Server Classloader where they are accessible only within that classloader. The same is true for the other jars in Server Classloader are not visible to web applications as well.

The primary benefit of this new classloader hierarchy is that you can put your own XML parser in your web application without running into conflicts with the XML parser being used by the server. However, since having an XML parser by default has been the norm in the past, Tomcat 3.3 tries to maintain this behavior should your web application not already contain an XML parser. The default configuration for the LoaderInterceptor11 in server.xml is to provide an XML parser to web applications that don't already contain one. It accomplishes this by adding entries to the Webapp Classloader as if you had included the crimson.jar and xalan.jar in your web application's WEB-INF/lib.

Along with this classloader hierarchy comes the need to decide which classloader is the appropriate one in which to add classes or jars. Note that if you have a jar containing classes that depend on servlet.jar, putting that jar on the CLASSPATH wouldn't work. servlet.jar isn't accessible to the Application Classloader. This is why in Tomcat 3.3, your CLASSPATH environment variable is ignored. The appropriate classloader would be the Common Classloader or above.

Classes that are used in one particular web application should be placed in that web application's WEB-INF/classes or in a jar in the WEB-INF/lib as defined by the Servlet 2.2 specification. If you want to give the classes wider scope by putting them in the Common Classloader or Apps Classloader, or want them to be part of the Server Classloader, use one of the following two methods to have those classes included in that classloader:

  1. If the classes are in a jar file, place the jar file in the directory that corresponds to the chosen classloader. If the classes exist as class files, create a classes under the corresponding directory if it doesn't already exist. Then add the class files into the appropriate package directory under the classes directory.
  2. If the chosen classloader is the Common Classloader or Apps classloader you include a directory or jar these classloaders by listing them a System property. For the Common Classloader, include the directory or jar file in a System property named org.apache.tomcat.common.classpath. For the Apps classloader, use a System property named org.apache.tomcat.apps.classpath.

Note: In an instance of Tomcat 3.3 which is using ReloadInterceptor (the default), the Webapp Classloader, Apps Classloader, and Common classloader are "wrapped" into a single classloader. This classloader will be an instance of org.apache.tomcat.util.depend.DependClassLoader or org.apache.tomcat.util.depend.DependClassLoader12, depending on which JDK you are using. This classloader checks for updates when classes are loaded from the "wrapped" classloaders so that reloads can be triggered when needed.

Configuring the Server

Overview

By default, Tomcat's configuration is determined by the contents of the server.xml file found in Tomcat's conf directory. This file specifies the sequence of modules (a.k.a. interceptors) that should participate in the operation of this instance of Tomcat. This file also includes the operating parameters for those modules.

Prior to reading the server.xml file, Tomcat reads the modules.xml file which is also found in the conf directory. This file specifies mappings between module names and the class that implements the module. This simplifies the syntax in servers.xml and allows you to update a module's class by updating just modules.xml. The server.xml, and possibly other files, do not have to change.

To allow for customization of Tomcat's configuration without requiring modification of modules.xml and server.xml, Tomcat will read additional files during startup. In addition to modules.xml, Tomcat will read any file in the conf directory that matches the pattern modules-*.xml. Likewise for server.xml, by default Tomcat will read additional files which match the pattern server-*.xml.

If you specify the configuration file (i.e. the file to use in place of server.xml) as a command line argument, the additional files read will be derived from the base name of the file you specify. For example, if the configuration file specified was myserver.xml, then the file pattern would be myserver-*.xml. Because of this, you should avoid using '-' in your configuration file names except when taking advantage of this feature.

When using additional configuration files in conjunction with server.xml it is important to note that these configuration files apply to a single Tomcat 3.3 server instance. In other words, all <ContextManager> elements in these files refer to the same ContextManager instance. ContextManager is the controlling class for the Tomcat 3.3 server.

Other files may be read as well for configuration. These, however, are determined by the modules that are included by server.xml and associated files. The primary example of this is ContextXmlReader. It is responsible for reading files containing Context declarations in the form:

<Context path="/myapp" docBase="somepath" ... />
or
<Context path="/myapp" docBase="somepath" ...>
    context local modules
</Context>

By separating the reading of "context" configurations from the server configuration, you can manually add additional contexts without modifying the server.xml file.

The ContextXmlReader module supports a config parameter which specifies the file to read. Like server.xml, additional files are read based on the pattern <base>-*.xml. Thus, specifying config="conf/myapps.xml" would read conf/myapps.xml, if it exists, plus all files in the conf directory matching the pattern myapps-*.xml.

Tomcat 3.3's default server.xml includes two instances of the ContextXmlReader module. One reads conf/apps.xml, which reads all the "apps" files found in the conf directory by default. For backward compatibility with having "context" declarations in server.xml, the second instance of ContextXmlReader reads conf/server.xml, processing only the <Context> entries.

For additional information about contexts and their configuration, see Tomcat's Standard Contexts and Adding and Customizing Contexts.

Default Tomcat Configuration

The default server.xml contains the following configuration.

Module EntryStatusDescription
<LoaderInterceptor11 useApplicationLoader="true" />  Constructs and sets the classloader for each context
<TrustedLoader />   Provides special handling for "trusted" contexts which have a interceptors.xml file in their WEB-INF directory.
<LogSetter name="tc_log" timestamps="true"
    verbosityLevel="INFORMATION" />
  Sets up Tomcat's log output channel. In the absence of a path setting, output goes to stderr.
<LogEvents enabled="false" />  When enabled, logs when module methods are called.
<ContextXmlReader config="conf/server.xml" />  Reads context definitions from the server.xml file for backwards compatibility. This may be removed if you don't put context definitions in your server.xml file.
<ContextXmlReader config="conf/apps.xml" />  Reads context definitions from the conf/apps.xml file and any files matching the pattern apps-*.xml in the conf directory.
<AutoDeploy source="modules" target="modules" redeploy="true" />  Expands ".war" files in the modules directory.
<AutoWebApp dir="modules" host="DEFAULT" trusted="true"/>  Auto-creates contexts for subdirectories in the modules directory. These contexts are defaulted to "trusted".
<AutoDeploy source="webapps" target="webapps" />  Expands ".war" files in the webapps directory.
<AutoWebApp dir="webapps" host="DEFAULT" />  Auto-creates contexts for the subdirectories in the webapps directory.
<PolicyLoader
    securityManagerClass="java.lang.SecurityManager"
    policyFile="conf/tomcat.policy" />
  Sets a policy file and security manager if "sandbox" is specified on the command line without also specifying a policy file on the command line.
<SimpleMapper1 />  Handles the mapping of requests to contexts.
<SessionExpirer checkInterval="60" />  Handles the destruction of sessions after they expire.
<SessionIdGenerator
    randomClass="java.security.SecureRandom"
    randomFile="/dev/urandom" />
  Generates session IDs for requests that need a new session.
<LogSetter name="servlet_log"
    timestamps="true"
    verbosityLevel = "INFORMATION"
    path="logs/servlet-${yyyyMMdd}.log" />
  Sets up the "servlet" log output channel.
<LogSetter name="JASPER_LOG"
    timestamps="true"
    path="logs/jasper-${yyyyMMdd}.log"
    verbosityLevel = "INFORMATION" />
  Sets up the Jasper's log output channel.
<WebXmlReader validate="true" />  Reads the web.xml file for each context.
<ErrorHandler showDebugInfo="true" />  Provides error handling for requests that encounter an error.
<WorkDirSetup cleanWorkDir="false" />  Sets the "work" directory for contexts which don't have the "work" directory set explicitly.
<Jdk12Interceptor />  Insures the proper context classloader is in effect during servlet execution.
<InvokerInterceptor />  Handles the "/servlet/class name" legacy method of invoking servlets
<JspInterceptor keepGenerated="true"
    largeFile="false"
    useJspServlet="false" />
  Handles translation, compilation, and loading of JSP pages.
<StaticInterceptor listings="true"
    useAcceptLanguage="true"
    useCharset="locale" />
  Generates the response for requests for static files and directories.
Note: The last two attributes were added in Tomcat 3.3.1 to provide improved behavior with the addition of Japanese resource strings.
<ReloadInterceptor fullReload="true" />   
<SimpleSessionStore maxActiveSessions="-1" />  Creates, stores, and maintains session objects.
<AccessInterceptor />  Checks if requests require authentication. Provides the basic handling for BASIC and FORM authentication.
<CredentialsInterceptor />  Extracts user name and password information for use by an "authentication" module.
<SimpleRealm filename="conf/users/global-users.xml" />  "authentication" module that checks user name and passwords against data obtained from an XML file. Since this module appears outside of a Context definition, the user names and passwords in the specified file apply to all contexts.
<JDBCRealm
    debug="99"
    driverName="sun.jdbc.odbc.JdbcOdbcDriver"
    connectionURL="jdbc:odbc:TOMCAT"
    userTable="users" userNameCol="user_name"
    userCredCol="user_pass"
    userRoleTable="user_roles"
    roleNameCol="role_name" />
Disabled A replacement for SimpleRealm that reads usernames, passwords, and roles from tables using JDBC.
<LoadOnStartupInterceptor />  Pre-loads servlets indicated as <load-on-startup> in a web.xml file.
<Servlet22Interceptor />  Handles miscellaneous tasks that help implement behavior related to the Servlet 2.2 specification.
<LogSetter name="tag_pool_log" timestamps="true"
    path="logs/tagpool-${yyyyMMdd}.log"
    verbosityLevel="INFORMATION" />
Disabled Sets up the "tag_pool_log" log output channel.
<TagPoolManagerInterceptor />Disabled Manages a pool of custom tag libary tag objects.
<DecodeInterceptor />  Handles the determination of the encoding of a request.
<SessionId cookiesFirst="true" noCookies="false" />  Handles associating sessions with requests and responses.
<ApacheConfig noRoot="true" />  Generates a configuration file for use with mod_jk.
<IISConfig noRoot="true" />  Generates a configuration file for use with isapi_redirect.dll.
<NSConfig noRoot="true" />  Generates a configuration file for use with nsapi_redirect.
<AccessLogInterceptor />Disabled Writes a log file like Apache's AccessLog
<Http10Connector port="8080"
    secure="false"
    maxThreads="100"
    maxSpareThreads="50"
    minSpareThreads="10" />
  Handles incoming HTTP requests.
<Http10Connector port="8443" secure="true" />Disabled Handles incoming HTTPS requests.
<JniConnector />  Handles requests processed by Tomcat running in-process, provided Tomcat was started in-process.
<Ajp12Connector port="8007" />  Handles Ajp12 protocol requests and Tomcat shutdown.
<Ajp13Connector port="8009" />  Handles Ajp13 protocol requests.

Tomcat Server.xml Customization

The following are some of the more common customizations made to the server.xml file.

  1. Change ports for Http, Https, and Web Server connectors
  2. Speed up initial session creation for development
  3. Configure whether Tomcat or a web server does authentication
  4. Turn off directory listings
  5. Use Jikes as the Java compiler
  6. Bind a connector to a single IP address
  7. Enable redeploying of WAR files
  8. Disable cookie based sessions

1. Change ports for Http or Web Server connectors

To change a port, search the server.xml file for the default value of the port and change it to the desired value.

ConnectorDefault Port
Http8080
Https8443
Ajp12Connector8007
Ajp13Connector8009

For example:

    <Http10Connector port="80" secure="false"
        maxThreads="100" maxSpareThreads="50" minSpareThreads="10" />

2. Speed up initial session creation for development

The first request that requires a session can incur a delay when the SessionIdGenerator initializes the random number generator. This delay can be relatively long when using the default java.security.SecureRandom class. For development purposes, you can speed this up by switching to the java.util.Random class. For example:

    <SessionIdGenerator randomClass="java.util.Random" randomFile="/dev/urandom" />

You should only use java.util.Random for development since the random sequence generated is predictable.


3. Configure whether Tomcat or a web server does authentication

When Tomcat is used with a web server, such as Apache, the default is to have Tomcat continue to handle authentication. Any authenticated user specified in the request forwarded from the web server to Tomcat will be ignored.

If you want Tomcat to make use of the authenticated user provided by the web server, add:

    tomcatAuthentication="false"

to the Ajp12Connector or Ajp13Connector as appropriate. For example:

    <Ajp13Connector port="8009" tomcatAuthentication="false" />

4. Turn off directory listings

To turn off directory listings, change the listings attribute of the StaticInterceptor to false. For example:

    <StaticInterceptor listings="false" />

5. Use Jikes as the Java compiler

To have Tomcat use Jikes as the Java compiler, add:

    javaCompiler="jikes"

to the JspInterceptor. For example:

    <JspInterceptor javaCompiler="jikes" />

You may want to also set the jikesClasspath attribute to include any jars from the jre/lib/ext extensions directory, or any classes or jars not otherwise found in the WEB-INF/classes and WEB-INF/lib directories.

If the Jikes executable isn't in your PATH environment variable, you will also need to set the jspCompilerPath attribute to the full path of the Jikes executable.


6. Bind a connector to a single IP address

By default, the Ajp12Connector and Ajp13Connector will accept connections from any IP address. To bind the connector to a single IP address, add an address attribute specifying the desired IP address. For example:

    <Ajp13Connector port="8009" address="127.0.0.1" />

7. Enable redeploying of WAR files

The default behavior is to only deploy a WAR file if the target directory doesn't already exists. To enable automatic redeployment of WAR files, add:

    redeploy="true"

to the AutoDeploy with source="webapps". In addition to re-deploying WAR files at startup, because a ReloadInterceptor is part of the default configuration, WAR files will re-deploy and reload if updated while Tomcat is running.


8. Disable cookie based sessions

To assist with testing a web application against browsers that have cookies disabled, you can disable the use of cookie bases sessions. Change the noCookies attribute of the SessionId module to true. For example:

    <SessionId cookiesFirst="true" noCookies="true" />

Tomcat's Standard Contexts

A context is an instance of a web application's resources being served with a unique context path. The default Tomcat 3.3 installation comes with three web applications which are served as the following contexts.

ContextpathdocBaseWAR FileContext Config File
defaultempty, i.e. "" webapps/ROOTROOT.war 
admin/adminwebapps/adminadmin.war apps-admin.xml
examples/exampleswebapps/examples examples.warapps-example.xml

The default context is the context that will handle requests that don't match up with any of the other contexts being served.

Each of these contexts have their WAR file auto-deployed by the AutoDeploy module and the deployed directory auto-served by the AutoWebApp module. The apps-admin.xml and apps-example.xml files found in the conf directory provide additional configuration for the admin and examples contexts, respectively. Both configuration files add a local SimpleRealm module which defines additional users that may use the secure portions of those contexts. The apps-example.xml also configures local log channels for the internal context log and the servlet log.

For the admin context to function properly, you will need to update the apps-admin.xml file to set the context's trusted attribute to true. You can do this from the command line using the "tomcat" script/batch file and the enableAdmin action (see tomcat/tomcat.bat Actions for details). The trusted attribute is set false by default for security reasons. When you change it to true, it is also recommended that you change the password in the conf/users/admin-users.xml file.

There is an additional context configuration file, named apps-127.0.0.1.xml. This file contains a disabled example of defining contexts that are associated with a virtual host. In this case, a host with a name that matches it's IP address, 127.0.0.1. To enable, uncomment the Host element in this file.

Tomcat 3.3 first tries to match a request to a context that has a virtual host name that matches the server name in the request. If unable to do so, the request will be matched to one of the other contexts, which don't have a virtual host associated. Note that this means that contexts associated with a virtual host are separate from other contexts not associated with a virtual host.

In this virtual host example, the default and examples contexts are swapped. Thus, the URL http://127.0.0.1:8080/examples/ will show you the Tomcat main page instead of the examples directory. The URL http://localhost:8080/ would be the normal way to reach the Tomcat main page. To illustrate that a context associated with a virtual host is a separate context, you can invoke http://127.0.0.1:8080/jsp/security/protected/index.jsp in your browser. Since this, default, context is serving the "examples" web application, but without an additional SimpleRealm defined, only the "global user" root (defined by the SimpleRealm in server.xml) can login.

Adding and Customizing Contexts

To serve a context, Tomcat 3.3 requires a directory that contains the resources for the context. This directory must match the structure and requirements defined for a web application. Once this directory exists, it may be served as a context using one or both of the following mechanisms.

  1. Specify the context in a context configuration file read by a ContextXmlReader module. This module will read a specified context configuration file, if it exists, and all files with an associated pattern. The default Tomcat 3.3 installation has a ContextXmlReader that reads the "apps.xml" file. Though this file doesn't exist, the associated pattern is "apps-*.xml" which picks up the apps-admin.xml, apps-example.xml, and apps-127.0.0.1. You can create an apps.xml or apps-myapps.xml file, for example, to add your own context definitions.

  2. If the context's directory is a subdirectory of an directory named in an AutoWebApp module, it will be served using the context's directory name as the context path. The default installation of Tomcat 3.3 has one such AutoWebApp module which serves subdirectories of Tomcat's webapps directory. The contexts served in this manner will receive the default context settings unless overridden by a context configuration file for that context.

    Note: The AutoWebApp module which serves the modules directory is reserved for Tomcat Add-on modules and should not be used for serving contexts.

The format of context configuration files differs depending on whether the context is for the default host or a virtual host. For contexts not associated with a virtual host, use:

<?xml version="1.0" encoding="ISO-8859-1"?>
<webapps>
    <Context ... >
        <local_module ... />
        ...
    </Context>
    ...
</webapps>

For contexts that are to be associated with virtual hosts, use:

<?xml version="1.0" encoding="ISO-8859-1"?>
<Server>
    <Host ... >
        <Alias ... />
        <Context ... >
            <local_module ... />
            ...
        </Context>
        ...
    </Host>
    ...
</Server>

The following table provides the attributes available on these elements.

ElementAttributeDescriptionDefault
Contextpath The URL fragment to use to identify this context. This is a required attribute. none, must be specified
 docBase Path to the directory containing the web application's resources for the context. This is a required attribute. none, must be specified
 reloadableEnables reloading of servlets for this context.true
 trustedControls whether the context is "trusted". If "trusted", the Webapp Classloader's parent will be the Server Classloader rather than the Apps Classloader. This gives the context access to classes in the Tomcat server instance. false
 debugDebug level for logging0
HostnameName of the virtual host. This is a required attribute. none, must be specified
 addressIP address for this virtual host. This attribute is optional. Currently, this attribute only affects how the ApacheConfig module writes the configuration file. none, must be specified.
AliasnameName of the virtual host alias.
Note: All Alias specifications must come before any Context declarations.
none, must be specified

In Tomcat 3.3.1, each attribute value may use the ant-style variable substitution by using "${variable}" in the attribute string, i.e. attribute="text${variable}text".

The variable must specify a Context property, a ContextManager property, or System property. The Context properties take precedence, followed by ContextManager propertiers, and finally System properties. If a matching property isn't found, the attribute string is left as is. Note that properties are not the same as attributes, and attributes are not accessible via "variable substitution".

There are two methods for setting Context properties.

  1. Include a name="value" specification on the Context element, where name doesn't correspond to a Context attribute. For example:
        <Context ... my.prop="myvalue" ... >
  2. Include a Property element within the scope of the Context element. For example:
        <Context ... >
            <Property name="my.prop" value="myvalue" />
            ...
        </Context>
    This form of setting properties is logged if the Context's debug level is one or greater.

Note: The property values may themselves use "variable substitution", provided the specified property is already defined.

Currently the SimpleRealm, JDBCRealm, and Logsetter modules are known to work successfully as "context local" modules. Other modules that can be used as "context local" modules and would be useful have yet to be identified.

To add, or remove, a context while Tomcat 3.3 is running, use the Admin web application provided in the admin context. Note that the admin context must be "trusted" before it can perform the admin functions successfully.

Deploying WAR Files

The Servlet 2.2 specification introduced the Web Application Archive, or WAR file. A WAR file is the deployable version of a web application, where the directory structure and the files they contain are combined into an archive file.

To deploy a WAR file to Tomcat 3.3, you can manually expand the archive to a directory and have that directory served as a context as described above. You can also have the AutoDeploy module do the expansion automatically if the WAR file is placed in its "source" directory. The default installation of Tomcat 3.3 includes an AutoDeploy module which expands WAR files found in Tomcat's webapps directory.

To add a WAR file while Tomcat 3.3 is running, you will need to manually expand the WAR file. Then use the Admin web application to add the context.


Real World Configuration Tips

By default the Tomcat distribution comes with a naive configuration whose main goal is to promote first time user experience and an "out of the box" operation... This configuration however is not the best way to deploy Tomcat on real sites. For example, real sites may require some performance tuning and site-specific settings (additional path elements for example). This section will try to get you started by directing you to the first steps that should be taken before publishing a Tomcat based site.

Modify and Customize the Batch Files

As stated in the previous sections, the startup scripts are here for your convenience. Yet, sometimes the scripts that are needed for deployment should be modified:

Some of these changes can be done without explicit changes to the basic scripts; for example, the tomcat script can use an environment variable named TOMCAT_OPTS to set extra command line parameters to the JVM (such as memory setting etc.). On UNIX you can also create a file named ".tomcatrc" in your home directory and Tomcat will take environment information such as PATH, JAVA_HOME, TOMCAT_HOME and TOMCAT_INSTALL from this file. On NT however (and also on UNIX when the modifications are for something such as the JVM command line) you are forced to rewrite some of the startup script...

Do not hesitate, just do it.

Modify the Default JVM Settings

The default JVM settings in the tomcat script are very naïve; everything is left for defaults. There are a few things that you should consider to improve your Tomcat performance:

  1. Modify your JVM memory configuration. Normally the JVM allocates an initial size for the Java heap and that's it, if you need more then this amount of memory you will not get it.
    Nevertheless, in loaded sites, giving more memory to the JVM improves Tomcat's performance. You should use command line parameters such as -Xms/-Xmx/-ms/-mx to set the minimum/maximum size of the Java heap (and check to see if the performance was improved).
  2. Modify your JVM threading configuration. The SUN JDK1.2.2 for Linux comes with support for both, green and native threads. In general native threads are known to provide improved performance for I/O bound applications, green threads on the other hand put less stress on the machine. You should experiment with these two threading models and see which model is better for your site (in general, native threads are better).
  3. Select the best JVM for the task. If your application does not require a specific JDK functionality, you should benchmark the two JVMs and select the better one.

Disable Servlet Auto-Reloading

Servlet auto-reloading is really useful for development time. However it is very expensive (in performance degradation terms) and may put your application in strange conflicts when classes that were loaded by a certain classloader cannot cooperate with classes loaded by the current classloader.

So, unless you have a real need for class reloading during your deployment you should turn off the reloadable flag in your contexts. You can disable reloading globally by removing the ReloaderInterceptor found in the server.xml file.

Start Tomcat from /etc/inittab

Unfortunately the adapters developed for Apache (or for any of the other servers) cannot start Tomcat yet. On UNIX however, you can use the init table to start Tomcat automatically upon machine startup.

Credits

Tomcat was originally written by Sun Microsystems, and has been improved (we hope) by a cast of thousands.

This document was created by:

With help from (in alphabetical order):

Copyright ©1999-2001 The Apache Software Foundation
Legal Stuff They Make Us Say
Contact Information