Basic Tomcat Configuration

Tomcat 6 server is configured by setting parameter values for the components of Tomcat 6 before starting the server. Tomcats configuration is always stored within one or more XML files, the files contain numerous elements that are configurable. This web pages details the two most important files server.xml and context.xml, I will also discuss configuration files that the Service, Servers, Engine, Connectors, Realm and Valves use.

There is a Web-based GUI configuration tool called the Admin Web application, hopefully it should be bundled very soon.

Configuration Essentials

Tomcat uses 3 files to start with

server.xml The primary configuration file, this file configures the Service, Connector, Engine, Realm, Valves, Hosts, etc. You also configure the virtual hosts in this file.
context.xml

Default version of the per-application configuration file for server components. Any components in this file are applied to all applications running on the server. You can override this file by placing a context.xml within the applications META-INF directory.

Components such as session persistence managers, Realms and resources such as JDBC connections are all configured here.

web.xml

Default version of the standard Java EE deployment descriptor for web applications, this is used by all applications unless it has been overridden by the application own web.xml file.

It provides servlet definition and MIME mappings common to all Web applications.

These files are kept in the conf directory, there are a number of other files that are used in this directory, i have already touched on these files in Tomcat Architecture

tomcat-users.xml this file contains user authentication and authorization and role-mapping information for setting up a UserDatabase realm.
catalina.policy Java SE has a fine-grained security model that enables the administrator to control in detail the accessibility of system resources
catalina.properties This file provides for internal package access and definition control as well as control over contents of Tomcat class loaders
logging.properties Tomcat uses it own logging to write log files, you can control the level of logging in this file and can change the destination if so desired

Basic Server Configuration

The default configuration is held in the file server.xml, the file consists of nested elements (components) that make up the Tomcat server, the nested configuration looks something like below

I will now talk in depth about the four main files that are used by Tomcat server.xml, context.xml, tomcat-users.xml and web.xml.

Server Component (server.xml)

We first start with the Server component which can have a number of attributes and subelements

Server Component Attributes
Attribute Description
Required?
className The Java class that the Server uses by default it uses org.apache.catalina.core.StandardServer
No
port The TCP port to listen to for the command specified by the shutdown attribute.
Yes
shutdown The command text string that the server should monitor for at the TCP port specified by the port attribute.
Yes
Server Component Subelements
Subelement Description
How Many?
<service> A grouping of Connectors associated with an Engine, the Connectors handle different client protocols (HTTP, HTTPS, AJP, etc) and manage concurrency while the Engine processes requests
1 or more
<Listener> Lifecycle listener for interception of the server's lifecycle events (start, stop, before-start, before-stop, after-stop, after-start). Lifecycle events can be used to add custom components, additional logging, management, resource allocation.
0 or more
<GlobalNamingResources> JNDI resources that are defined to be globally available throughout this server component instance
0 or more

Service Component

The main purpose of the Service component is to group a request-processing Engine with its configured set of protocols/concurrency handling Connectors

Service Component Attributes
Attribute Description
Required?
className The Java class that the Service uses by default it uses org.apache.catalina.core.StandardServer
No
name A name for the service, this is used for logging, administration, management.
Yes
Service Component Subelements
Subelement Description
How Many?
Connector This is a nested component that handles external clients connections and feeds then to the Engine for processing. A Connector also manages the number of threads and their allocation for request handling.
1 or more
Engine This is the request-processing component in Tomcat: Catalina
1 Only

Connector Component

Tomcat can operate in two different modes

I am only going to talk about using Tomcat in application server mode, there are two modes that you can use to connect to the Connector

HTTP/1.1 Connects the browser to the Catalina Engine using HTTP/1.1 but falls back to HTTP/1.0 if not supported, you can also use HTTPS/SSL connections
AJP/1.3 Uses the AJP/1.3 protocol, normally use with Apache web server. It's a special designed protocol that is more efficient that HTTP. For more information on the Connector take a look at Tomcat 6 Architecture

By default Tomcat sets up two connectors one for HTTP on port 8080 and one for AJP on port 8009, this should be more than enough to cope with most situations.

Engine Component

There is only one Engine component associated with the Catalina Service, the Engine is a container which is essentially representing a running instance of the servlet processor. The Engine can redirect requests to the correct virtual hosts but the defaultHost attribute if a virtual host is not specified.

Again there are many attributes and subelements that can be used

Engine Component Attributes
Attribute Description
Required?
className Java class for the Engine, by default org.apache.catalina.core.StandardEngine is used.
No
backgroundProcessDelay The delay in seconds before the background processing is enabled for this Engine and other nested Host and Context components It is used by components to perform low-priority tasks such as lazy reclamation of unused resources. The default is 10 seconds
No
defaultHost select one of the virtual hosts within this Engine to process all incoming requests by default, it's only used if it cannot find the virtual host name
Yes
jvmRoute This is a identifier used in load-balancing Tomcat, it is used in sticky -sessions
No
name A name given to this Engine, which will be used in logging and management applications
Yes
Engine Component Subelements
Subelement Description
How Many?
Host Each <host> is a virtual host handled by the Engine, this is similar to Apache's virtual hosts.
1 or more
Context Creates a Context for the Web applications that are automatically deployed when Tomcat starts. The properties in this file are available to all Web applications
0 or 1
Realm Is used to support security mapping usernames to roles for authentication purposes. Each virtual host can have its own realm, otherwise this global one is used.
0 or 1
Valve Valves add processing logic into the request and response handling at the Engine level. They are used for logging, single sign-on, etc.
0 or more
Listener This is used to configure lifecycle listeners that monitor the starting and stopping of the Engine.
0 or more

Realm Component

The default server.xml file configures a UserDatabase Realm to load the tomcat-user.xml file into memory, which is used for authentication by Web applications such as the manager application.

There are several methods that Realms can use to store data

Realm Component Attributes
Attribute Description
Required?
className Java class for the Realm, by default org.apache.catalina.realm.UserDatabaseRealm is used.
Yes
resourceName the resource name of the realm
Yes

Host Component

A Host component is a container, it can contain other nested components. It represents a virtual host similar to Apache's virtual hosts. Each virtual host can have it's own specific Web application.

Service Component Attributes
Attribute Description
Required?
className The Java class that the Host uses by default it uses org.apache.catalina.core.StandardHost
No
appBase used to set the default application-deployment directory
Yes
autoDeploy Web applications will be automatically deployed or redeployed while Tomcat is running. Default is true and background processing must be enable for this to work
No
name The resolvable name of this virtual host
Yes
backgroundProcessDelay The delay in seconds before background processing thread is enabled for this host and other nested components. The delay delay is -1 indicating that the parents background processing thread should be used.
No
deployOnStartup automatically deploys Web applications from this host during component startup, the default is true
No
deployXML Used primary in security sensitive installations to restrict the processing of context.xml embedded with the Web application.
No
errorReportValveClass Specifies the Java Class that implements the error-reporting, by default org.apache.catalina.valves.ErrorReportValve is used
No
unpackWARs Set this to false if you want Tomcat to run Web applications without unarchiving the WAR files found at the directory specified by the appBase attribute, the default is true. The trade off is performance against storage.
No
workdir Specifies a temp directory for servlets (and JSPs) that run within this host.
No
Service Component Subelements
Subelement Description
How Many?
Context you can configure a set of property values for a Web application deployed within a host
0 or more
DefaultContext configures the set of property values for a Web application that is deployed within this host but does not have its own Context specified.
0 or 1
Realm a realm that can be accessed across all Web applications running within this host, unless a lower-level component specifies its own realm
0 or 1

Context Definitions (context.xml)

In Tomcat, administrator-controlled application Context Descriptors XML files are placed in the conf/<engine name>/<host name> directory. This is done to maximize the decoupling between server and application configuration and to improve deployment security

Web application specific Context descriptors can be deployed in WAR file, under the META-INF directory.

The context.xml is a global file and is used by all Web applications that run within Tomcat (the DefaultContext nested component has the same affect, but across all Web applications in a single host).

The context.xml file has many attributes and subelements

Context Component Attributes
Attribute Description
Required?
className The Java class that the Service uses by default it uses org.apache.catalina.core.StandardContext
No
allowLinking this allows you to use symbolic links in the Unix environment, the default is false
No
antiJARLocking uses specialized classloaders code to avoid locking up JAR files as much as possible while accessing class information inside a JAR file. Default is false
No
antiResourceLocking uses specialized code to avoid file locking as much as possible. Default is false
No
backgroundProcessDelay The delay in seconds before background processing thread is enabled for this host and other nested components. The delay delay is -1 indicating that the parents background processing thread should be used.
No
cacheMaxSize sets the maximum size for the resource cache, in KB. Default size is 1024
No
cacheTTL Time between attempts to revalidate items in the cache in milliseconds. Default is 5000
No
cachingAllowed Determines if static resource cache should be turned on, default is true
No
caseSentitive should case sensitivity checks should be performed, default is true. Leave this on especially with if using Windows.
No
cookies use cookies to track session information from client access, default is true
No
crossContext Enables cross-Context access when servletContext.getContext() is called by a Web application, default is false
No
docBase the document base path of the Web application running in the Context, default is set to webapps/<name of war file>
No
override indicates if settings in the local context.xml should be allowed to override settings in the DefaultContext specified in server.xml
No
path Specifies the context path of the WEb application, default is to use the attribute docBase
No
privileged only should be changed if using the manager application, default is false
No
processTlds specifies that TLDs should be processed when the Context is started up, default is true
No
reloadable monitor for changes in /WEB-INF/classes and /WEB-INF/lib for every application and reload when the application changes
No
swallowOutput Determines if any output to System.out or System.err should be captured and displayed in Tomcats logs
No
tldNamespaceAware Determines if TLD processing and validation should be namespace-aware, default is false. Use this for debugging TLD problems
No
tldValidation Determines if TLD validation should be performed during processing, default is false. Use this for debugging TLD problems.
No
unloadDelay The number of seconds that Tomcat waits for the Web application to unload, default is 2000 approx 33mins
No
unpackWAR Tomcat unarchives the WAR file into the docBase directory before running it, default is true
No
useNaming Creates and provides to applications a Java EE JNDI-compatible initialContext for resource lookup, default is true.
No
workdir Specifies a temporary working directory for servlets and JSPs that run within this host.
No
wrapperClass Specifies a wrapper class that implements the org.apache.catalina.Wrapper for wrapping servlets
No
Context Component Subelements
Subelement Description
How Many?
Loader Configures the class loader used to load classes for the Web application
0 or 1
Manager Configures the session manager for the context, the session manage creates, manages and persists server-side sessions.
0 or 1
Realm A Realm that can be accessed in the Web application running within this Context
0 or 1
Resources The resource manager used to obtain resources, the default is org.apache.naming.resources.FileDirContext
0 or 1
WatchedResource Tells the auto deployer to redeploy the Web application if any specified resources have changed
0 or 1

Authentication (tomcat-users.xml)

The tomcat-users.xml file is used by Tomcat to authenticate manager tools, it uses the UserDatabase Realm to accomplish this.

Deployment Descriptor (web.xml)

The file web.xml is the deployment descriptor file, every Web application should have one, the file is placed in the Web applications WEB-INF directory, there is also a global one in the conf directory.

There is a default servlet definition, it is used to serve any static resources (HTML, GIF, etc) within all Web application and also to serve directory listings, so basically act like a Web server. You can customize the default servlet by changing the following parameters

listings Determines if directory listings should be shown when a URL reaches the root of a directory. Set this to false to tighten security or if some directories are large
readonly Controls if write HTTP methods such as PUT and POST are allowed, default is true
input The buffer size used when reading resources, default value is 2048 (2KB)
output The buffer size used when writing resources, default value is 2048 (2KB)
globalXsltFilelocalXsltFile Specifies an XSLT stylesheet to use when displaying directory listings
sendfilesSize sets the threshold of file size before a file is considered for transmission, default is 48KB

Invoker Servlet

By default Tomcat has the invoker servlet configuration commented out thus you cannot directly invoke a servlet from the browser, this increases security, uncomment in the web.xml file if you want to be able to do this.

JspServlet

The Jspservlet converts JSP pages to servlets and executes them, it has the development name of Jasper, it is used to process JSP pages. It is configured in the web.xml file. It uses the class org.apache.jasper.servlet.JspServlet and can be configured using a number of parameters

development Indicates that JSP is under development and that Jasper should honor the modificationTestInterval parameter to update/recompile JSPs if modified , default is true
fork Indicates that a separate JVM should be forked to compile JSPs, default is true
checkInterval The time interval specified in seconds between which Jasper will check to see if a JSP needs to be recompiled, default is 0, indicating that checks are performed with background processing
modificationTestInterval The threshold value specified in seconds since the last compile, that a JSP is eligible for modification check again, default is 4
compiler The buffer size used when reading resources, default value is 2048 (2KB)
classdebuginfo The buffer size used when writing resources, default value is 2048 (2KB)
keepgenerated Causes Jasper to retain the compiled JSPs between invocations, this can speed up startup times
mappedfilegenStrAsChar
Array dumpSmaptrimSpaces supressSmap
These are optimization and debugging options for JSP developers
scratchdir Temporary directory required during JSP compilation, default is the work directory
xpowerBy Generates the X-Powered-By special header, default is false
compilerTargetVM The target VM for the compiled servlets, default is 1.4
compilerSourceVM The source VM for the generated servlets, default is 1.4

SSI and CGI Servlets

If you plan to use Apache-style server-side include (SSI) or CGI processing, you need to uncomment this in the web.xml file.

Matching URLs

Servlet mapping specifies how incoming requests containing a specific URL pattern are handled, basically the URL is mapped to a specific servlet.

          http://www.datadisk.co.uk/<context path>/

The <context path> portion defaults to the name of the applications WAR file, if not explicitly specified in a <context path>. Just to recap org.apache.catalina.servlets.DefaultServlet will handle the request.

Putting all together

So how does all these files work together, using a the URL http://www.datadisk.co.uk/bookstore/BuyBook/proTomcat it breaks down into the following

https:// Coyote Connector with SSL support (conf/server.xml) deals with this passing to the Engine
www.datadisk.co.uk Virtual host name (conf/server.xml) is dealt with the Engine passing to the correct virtual host
bookstore Context Path (Context Descriptor XML file), the bookstore is the Web application to handle the request
BuyBook Servlet mapping using URL pattern "/BuyBook/" (applications web.xml), the servlet will be used to process proTomcat
proTomcat processed by the servlet

Session Timeout (web.xml)

The <session-config> element configures the amount of time (minutes) during which Tomcat will maintain a session on the server side on behalf of a client. The example of this is a shopping cart and the user disappears for 30 mins, which case the cart may now be empty and he has to start all over again. Do not configure this to a to high value as each session consumes resources.

MIME Mappings (web.xml)

This is pretty much the same as the Apache server MIME mapping where you map a files Content-Type to an application, for an example mapping a video/x-mpeg to Microsoft media player.

Welcome File (web.xml)

The last item in web.xml is the welcome file handling, it is only used in Tomcats standalone mode of operation. It will display a welcome file if the incoming URI is terminated

Fine-Grain Access Control (catalina.policy)

By default any resources that is not explicitly allowed is prohibited. Tomcat does not startup by default with security enabled, you need to add the -security option to the startup script, the catalina.policy file will only be read if this option is set. The file is in the format of

        grant <security principle> { permission list.....};

I will go into much more detail in the Tomcat security topic

Finer-Grain Control over Access Checks (catalina.properties)

You can control what Java packages are allowed to be accessed, a SecurityException error message is display if access is violated.

Web-Based GUI Configurator

In Tomcat version 5.5 there was GUI configurator called the "admin Web application". At the moment it is not supported by Tomcat 6 but hopefully it will be, I have screen shot of the tool below.