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:

• Jakarta FAQ Page
• Application Development manual - an alternative to the User's Guide, somewhat out-of-date
• Other Tomcat Documentation including HOWTOs for various web servers

Table of Contents

• About Tomcat
  • What is Tomcat?
  • Where can I download Tomcat?
  • What are servlets? What are JSPs?
  • How do/can I contribute?
  • How come X, Y, or Z isn't working? Help!
• Using Tomcat 3.3
  • Installing Tomcat
  • Environment Setup
  • Starting Tomcat
  • Stopping Tomcat
  • Tomcat Shell and Batch Files
  • tomcat.sh/tomcat.bat Actions
  • Tomcat Task Arguments
• Configuring Tomcat
  • Tomcat Directory Structure
  • Configuring Classes
  • Configuring the Server
    • Overview
    • Default Tomcat Configuration
    • Tomcat Server.xml Customization
    • Tomcat's Standard Contexts
    • Adding and Customizing Contexts
    • Deploying WAR Files
• Real World Configuration Tips
• Credits

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 Java^TM 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.

• Download the appropriate jakarta-tomcat-<version> binary archive file. For Linux, RPMs are available.
  
  
• Expand the archive into some directory (say /usr/local or C:\). This should create a new subdirectory named "jakarta-tomcat-<version>". You may rename this directory if you wish. Just remember to adjust the instructions that follow to use the new name. If you are using Linux, RPMs may be installed with the command "rpm -Uvh". Type man rpm for more info.

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.

• In a shell or DOS window, change to the "jakarta-tomcat-<version>" directory.
  
  
• Set the environment variable JAVA_HOME to point to the root directory of your JDK hierarchy. You may optionally add the Java interpreter to your PATH environment variable. The exact directory may vary from system to system. Check your local file system to be sure where Java is installed.
  
  
  1. Win32:
     set JAVA_HOME=c:/jdk1.3.1
     set PATH=%JAVA_HOME%\bin;%PATH%
  2. Unix (bash/sh):
     JAVA_HOME=/usr/local/java/jdk1.3.1; export JAVA_HOME
     PATH=$JAVA_HOME/bin:$PATH; export PATH
     
  3. Unix (tcsh):
     setenv JAVA_HOME=/usr/local/java/jdk1.3.1
     setenv PATH $JAVA_HOME/bin:$PATH
     
  
  
  
• You may optionally set the TOMCAT_HOME environment variable. If the supplied shell/batch scripts are executed from "jakarta-tomcat-<version>" or from its "bin" subdirectory, then they will successfully set TOMCAT_HOME for you if not already set. If you wish to execute these shell/batch scripts from other directories, you must set TOMCAT_HOME explicitly.
  
  
  1. On Win32 systems you should type:
     set TOMCAT_HOME=c:\jakarta-tomcat-<version>
  2. On UNIX (using bash/sh) you should type:
     TOMCAT_HOME=/usr/local/jakarta-tomcat-<version> ; export TOMCAT_HOME
  3. On UNIX (using tcsh) you should type:
     setenv TOMCAT_HOME /usr/local/jakarta-tomcat-<version>
  
  
  
• If you are using Win9x, you will need to deal with the potential "Out of environment space" problem, if you haven't already. In the standard installation of Win9x, the default amount of environment space provided to MS-DOS windows is too small for Tomcat's batch files to run. There are several ways to increase the size of the environment space.
  
  
  1. A global solution is to add a "SHELL" command to your CONFIG.SYS file. Click Start -> Run and enter sysedit. Then click OK. In the C:\CONFIG.SYS window, add the line:

     SHELL=C:\COMMAND.COM /E:4096 /P

     and click File -> Save. Then click File -> Exit and reboot your system. The default amount of environment space will now be 4096 bytes, more than enough for Tomcat.
  2. If you plan on always starting Tomcat 3.3 from the "MS-DOS Prompt", open a "MS-DOS Prompt". Right click on the icon in the upper left corner of the DOS window and select Properties. In this dialog, select the Memory tab and change the "Initial environment:" setting to 4096. Click OK and close the MS-DOS window. Now, whenever you open an "MS-DOS Prompt", you will have enough environment space to start and stop Tomcat.
  3. If you like double-clicking files in Windows Explorer to run them, you can execute sysedit as described in the first method and add the "set JAVA_HOME ..." line from above to the AUTOEXEC.BAT file. Next in Windows Explorer, navigate to Tomcat's bin directory. Right click on the startup.bat file and select Properties. Set the "Initial environment:" as described in the second method. Also select the Program tab and check the "Close on exit" option. Repeat this procedure for the shutdown.bat file. Reboot the system so the change to the AUTOEXEC.BAT file can take effect. Now you should be able to double-click on the startup.bat and shutdown.bat files in Windows Explorer to start and stop Tomcat.

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:

• On UNIX: bin/startup.sh
• On Win32: bin\startup

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.

• You may pass options and system property settings to the Java VM by specifying them in an environment variable called TOMCAT_OPTS (for instance: '-server' is useful as a performance enhancement if you're running Sun's HotSpot VM).
  Note: On Win9x, you will not be able so include system property settings in TOMCAT_OPTS because the SET command won't accept a line with more than one equals sign.
• The "auto-generated" configuration files for external web servers, such as Apache, are not written during a normal startup of Tomcat. To write the configuration files, append jkconf to the startup command. Tomcat will initialize sufficiently to write the files and then exit. This may be done while the Tomcat 3.3 is running as a web server.

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:

• On UNIX: bin/shutdown.sh
• On Win32: bin\shutdown

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

You may have noted that tomcat.sh 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.sh/tomcat.bat Actions

The tomcat.sh 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.sh and tomcat.bat scripts

Except for the env action, each action corresponds to a "task" supported by the org.apache.tomcat.startup.Main class. The tomcat.sh 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

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.

• Configuring classes
• Configuring the server

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.

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

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:

In this classloader hierarchy, classloaders can access classes in classloaders beneath them. They can not access classes in classloaders to the side or above! With this in mind, a brief inspection should reveal that in Tomcat 3.3, web applications, without some intervention, would not have access to an XML parser by default. The crimson.jar and xalan.jar are tucked away in the Server Classloader where they are accessible only within that classloader. However, "intervention" is provided by default. The default configuration for the LoaderInterceptor11 is to provide an XML parser to web applications that don't already contain one.

Also 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. You must place such a jar in 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, place the classes in a jar if they aren't already. Then place the jar in the directory that corresponds to the classloader with the scope you desire. In the Apps Classloader, the classes are shared among all the web applications. In the Common Classloader, the classes are shared among all the web applications and the web server.

A second method is available for adding classes to the Common Classloader and Apps Classloader. Entries found in an org.apache.tomcat.common.classpath System property are added to the Common Classloader and entries found in an org.apache.tomcat.apps.classpath are added to the Apps CLassloader.

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" ... />

<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.

Tomcat Server.xml Customization

The following are some of the more common customization 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.

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.

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.sh/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 servers 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.

Currently the SimpleRealm, JDBCRealm, and Logsetter modules are know 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:

• To set resource limits such as maximum number of descriptors.
• To add new PATH/LD_LIBRARY_PATH entries (for example, JDBC drivers DLLs).
• To modify the JVM command line settings.
• Make sure that you are using a specific JVM (out of the two or three JVMs installed on your machine).
• To switch user from root to some other user using the "su" UNIX command.
• Your pet reason.

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...

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:

• Gal Shachor

With help from (in alphabetical order):

• Jonathan Bnayahu
• Alex Chaffee
• Fiona Czuczman
• Larry Isaacs
• Costin Manolache
• Rob Slifka