Chapter 5. Configuring Tomcat

Table of Contents

Initial Instance Configuration
server.xml
tomcat-users.xml
server.xml
System Properties
Final Setup
J2EE Resources
Authentication user/role lists
Data Sources
Logging

I know of no application server that is hands off. Whether commercial or open source, your success with an application server depends direcly upon how well you understand the configuration facilities. For Tomcat, this means you must be able to edit the following files.

There are Gui web apps to help with many of the common settings, but I guarantee that at some point you will encounter problems which require manual examination or editing of the files above. As a consolation, while the structure of these files is far from straight-forward, they are far more simple than in any other app server which I have seen. Even my favorite commercial app server, WebSphere, suffers from overly complex configuration due to the business case to support (almost) every option graphically.

It's usually best to put your Tomcat application settings into a context.xml file instead of in server.xml. You bundle the context.xml file in the META-INF directory under the root of your web app. If you deploy your application as a war file (as opposed to writing the exploded directory right under CATALINA_BASE/webapps), Tomcat will automatically move the file to CATALINA_BASE/conf/Catalina/localhost/<APPNAME>.xml and will use it from there.

Tip

If you are running Linux (or Cygwin with the Net/inetutil package), it's very useful to run "netstat -tln" and grep for your SHUTDOWN and connector ports. The default settings for the SHUTDOWN, HTTP, and AJP ports all begin with "80", so this works great for a default setup:

    netstat -lnt | grep :80

Initial Instance Configuration

server.xml

Do all of this while Tomcat is not running. Tomcat itself writes to these files, so don't risk it. After installing a new CATALINA_BASE, you need to decide what to use as your starting server.xml. Basically, do you want to start with the default server.xml which has a ton of comments, or a stripped down version, server-minimal.xml. I recommend that you use the last. To use server-minimal.xml, remove server.xml and rename server-minimal.xml to server.xml. (If you want to use templates from the original server.xml, you can always copy and paste from $CATALINA_HOME/conf/server.xml).

If you are going to use a httpd plugin, leave the AJP/1.3 Connector element in place, otherwise wipe it out.

Unless you want to manually edit server.xml and tomcat-users.xml for all future changes, make sure the four<Listener> elements for the Admin server are active. If you started with the minimal file, you'll need to copy and paste these from $CATALINA_HOME/conf/server.xml to right under your opening <Server> tag.

Most users will use any SSL on their Tomcat server, except for securing the administrative web apps (I cover this use case in a different section). If you need to encrpyt some content, and you either aren't running an httpd front end, or the httpd server is on another host without a secure channel, you will need to set up SSL connectors.

Make sure that all ports specified by active attributes are available. A port is not available if it is in use by a different Tomcat instance, or by anything else. If not, change the numbers to available ports. Ports below 1024 are only available to privileged users.

tomcat-users.xml

If you will use neither administrative web app, and you don't want to use this user database realm for your own applications, you should wipe out the UserDatabase portions from server.xml and ignore the tomcat-uses.xml file. Otherwise, wipe out all of the <role> and <user> tags, except for one <user> tag with a roles element to use as a template. Modify this <user> element to set a username and password for yourself, with roles of "manager,admin". Every time that Tomcat starts up, it will create any necessary <role> elements for you, so you don't need to add them.

server.xml

If you are running Tomcat 5.0.x, you can't use Java 1.5 features in Servlets. to enable Java 1.5 features, edit the shared file CATALINA_BASE/conf/web.xml and set the two init parameters compilerSourceVM and compilerSourceVM to the value 1.5. Tomcat 5.5.x fully supports Java 1.5 out of the box.

System Properties

You may want to set the environmental variables CATALINA_PID or CATALINA_OPTS in addition to CATALINA_HOME and JAVA_OPTS. The first specifies a location of where to store the pid file, and this is a must when running multiple instances on UNIX or Cygwin. (The UNIX init script included in the Starting a Tomcat Instance chapter sets this automatically). I don't know the implications of setting a PID file on Windows without Cygwin.

CATALINA_OPTS is immensely useful for setting debug parameters, Java memory settings, etc. One very common use is to set the system property java.awt.headless to true. Most graphical applications (like Jasper, JFreechart, LiquidOffice, StyleReport, etc.) will halt Tomcat when they render if something isn't done to disable display rendering, and this is by far the easiest method. (This problem occurs with most J2EE servers, not just Tomcat). Here's how to make this setting in UNIX.

    export CATALINA_OPTS: CATALINA_OPTS=-Djava.awt.headless=true
BTW, JAVA_OPTS does the same thing as CATALINA_OPTS, but applications other than Tomcat use the variable JAVA_OPTS for this same purpose, so if you want a Java setting to apply only to Tomcat, use CATALINA_OPTS.

Final Setup

Start up Tomcat with the command %CATALINA_HOME%\catalina.bat start on Windows, or $CATALINA_HOME/catalina.sh start on UNIX. You must have the environmental variables CATALINA_HOME and CATALINA_BASE set, or the startup won't work right.

Connect up to the home page and drill down to the Manager web app. Unless you specifically want to use Webdav or Tomcat clustering, undeploy the applications webdav, balancer, host-manager,

Drill down to the Administration web app from the hom page to add more accounts, global J2EE datasources or mail servers, access logs, and IP address restrictions. Make sure to Commit changes that you make (although Committing is not necessary for user/role modifications), but don't expect your changes to become active until Tomcat is restarted. See the Tomcat Quirks chapter about Admin app quirks.

See the Tomcat-Bundled Web Apps chapter about the Tomcat administrative web apps, and the Securing Tomcat's Administrative Web Apps chapter about how to secure them.

CATALINA_BASE/logs will contain the Tomcat logs for this instance.

Shut down Tomcat with the command %CATALINA_HOME%\catalina.bat stop on Windows, or $CATALINA_HOME/catalina.sh stop on UNIX.

J2EE Resources

If you are not using J2EE/JNDI to obtain your resources, then ignore this section because your resources are handled entirely by your application. This would be the case if your web app is coded like a standalone app (w.r.t. obtaining resources), or if you use Spring (without JNDI lookups). The remainder of this chapter assumes that you want to use J2EE or JNDI resources.

With Tomcat, one can define all resources at the application level. I explain the more common J2EE idiom where objects are defined at the global level and these global resources are allocated to the applications.

The basic strategy to use global resources in Tomcat is to define the global resources in CATALINA_BASE/config/server.xml, perhaps using the Tomcat Administration web app, then create application-specific JNDI links to these resources in your applications' <Context> elements of server.xml, or (usually better), in the application's context.xml file. The context.xml file is a Tomcat-specific descriptor which you bundle into your web app's META_INF directory. Tomcat will effectively add the contents of this file to your application's virtual server.xml <Context> element. When you deploy, Tomcat will copy your context.xml file to CATLINA_BASE/conf/Catalina/localhost/<APPNAME>.xml. It functions as a link between vendor-portable J2EE descriptors and Tomcat, in the same way that weblog.xml is the Weblogic-specific links vendor-portable J2EE descriptors to Weblogic.

Authentication user/role lists

I'll explain how to use the single Tomcat Memory Based Realm. This is great for development use, because you can use the single text user/role list for as many applications as you wish, and you can maintain the list with the Tomcat Administration web app or a text editor. You should obviously use https and protect the password file if your application is accessible to external users. Once you have the Memory Based Realm set up and working, it will much easier for you to understand and follow the instructions in the Tomcat docs for production quality realm implementations.

The "User Definition" section of the nav panel of the Tomcat Administration panel can be used to graphically edit the file CATALINA_BASE/conf/tomcat-users.xml. Sometimes changes become active right away, but usually you will have to restart Tomcat.

Tip

If hand editing the tomcat-users.xml file, you don't need to add any <role> elements. When Tomcat starts up, it will automatically create a <role> elements for each role you reference in your <user> elements.

Data Sources

The Admin web app works well to define global J2EE data sources. Tomcat will wrap your data sources with dbcp connection pooling unless you override with custom configuration.

Applications should be able to access data sources with global JNDI names, but I've never been able to get that to work with Tomcat. Using app-specific resource-refs to the global data sources works fine, however.

Logging

Tomcat logs to files in CATALINA_BASE/logs.

stdout and stderr from your running applications will find their way into the file catalina.out. Servet.log() entries make it to the localhost log file.

For application logs, you can use ${catalina.base} in your log4j config files, since tomcat sets this system property for out. This avoids multiple Tomcat instances from clobbering the same appender output files.