Table of Contents
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.
CATALINA_BASE/conf/server.xml
Primary configuration for the Tomcat server
instance at this CATALINA_BASE.
This contains critical settings like what port to
run on, what protocols to serve, plugin configuration,
many other things.
CATALINA_BASE/conf/Catalina/localhost/*.xml
and
CATALINA_BASE/webapps/*/META-INF/context.xml
External <Context> elements, exactly
the same as <Context> elements inside the
server.xml
instance at this CATALINA_BASE.
These contain all of the Tomcat-specific settings
for one web application.
If you are looking for the Tomcat-specific settings
for a web app, you need to look for a
<Context> element in
server.xml
; and in a file named
CATALINA_BASE/conf/Catalina/localhost/<APPNAME>.xml
for apps installed with a .war file or
CATALINA_BASE/conf/Catalina/localhost/<APPNAME>.xml
for apps installed in exploded directory format.
Some of the things found here are JNDI mappings for
the application, access control lists, access log
setup, deployment modes like auto-redeploy.
CATALINA_BASE/conf/tomcat-users.xml
The username/role list used by default for accessing
the Management and Administration web apps, as well
as any of your apps which use the default Memory
Based Realm for authentication.
CATALINA_BASE/conf/tomcat-users.xml
Simple text file describing roles and users for the
Tomcat-supplied web apps, and any of your web apps which
wish to use it.
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.
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
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.
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.
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.
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
JAVA_OPTS
for this same purpose, so if you
want a Java setting to apply only to Tomcat, use
CATALINA_OPTS
.
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.
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.
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.
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.
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.
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.