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