Top Ten Tomcat Configuration Tips(转)

lig

　　Coauthor's note: Now that writing Java web applications has become a common way to
create and deploy new web content, people around the globe are finding
the Jakarta Tomcat servlet and JSP container useful. It's free, it's
multiplatform, it's rich in features, it's rapidly evolving and
improving, and it's never been more popular.

　　The only catch seems to be this: how can you configure Tomcat to do
what you want it to do? Tomcat is capable, as long as you can
configure it to suit your needs. Below is my list of ten Tomcat
configuration tips, taken from
Tomcat: The Definitive Guide, to help you do just that. -- Jason Brittain


1. Configuring the Admin Web Application
　　Most commercial J2EE servers provide a fully functional
administrative interface, and many of these are accessible as
web applications. The Tomcat Admin application is on its way to
becoming a full-blown Tomcat administration tool rivaling these
commercial offerings. First included in Tomcat 4.1, Admin already
provides control over contexts, data sources, and users and
groups. You can also control resources such as initialization
parameters, as well as users, groups, and roles in a variety of
user databases. The list of capabilities will be expanded upon
in future releases, but the present implementation has proven
itself to be quite useful.
　　The Admin web application is defined in the auto-deployment file
CATALINA_BASE/webapps/admin.xml
.
　　You must edit this file to ensure that the path specified in
the docBase
attribute of the Context
element is absolute; that is,
the absolute path of CATALINA_HOME/server/webapps/admin
.
Alternatively, you could just remove the auto-deployment file
and specify the Admin context manually in your server.xml
file. On machines that will not be managed by this application,
you should probably disable it altogether by simply removing
CATALINA_BASE/webapps/admin.xml
.
　　If you're using a UserDatabaseRealm
(the default), you'll
need to add a user and a role to the CATALINA_BASE/conf/tomcat-users.xml
file.
For now, just edit this file, and add a role named "admin" to your users
database:

<role name="admin"/>


　　You must also have a user who is assigned to the "admin" role.
Add a user line like this after the existing user entries
(changing the password to something a bit more secure):

<user name="admin" password="deep_dark_secret" roles="admin"/>


　　Once you've performed these steps and restarted Tomcat, visit
the URL http://localhost:8080/admin
, and you should see a login
screen. The Admin application is built using container-managed
security and the Jakarta Struts framework. Once you have logged
in as a user assigned to the admin role, you will be able to use
the Admin application to configure Tomcat.

2. Configuring the Manager Web Application
　　The Manager web application lets you perform simple
management tasks on your web applications through a more
simplified web user interface than that of the Admin web app.
　　The Manager web application is defined in the auto-deployment
file CATALINA_BASE/webapps/manager.xml
.
　　You must edit this file to ensure that the path specified in
the docBase
attribute of the Context
element is absolute; that is,
the absolute path of CATALINA_HOME/server/webapps/manager
.
　　If you're using the default UserDatabaseRealm
, you'll
need to add a user and role to the CATALINA_BASE/conf/tomcat-users.xml
file. For now, just edit this file, and add a role named "manager"
to your users database:

<role name="manager"/>


　　You must also have a user who is assigned the "manager" role.
Add a user line like this after the existing user entries
(changing the password to something a bit more secure):

<user name="manager" password="deep_dark_secret" roles="manager"/>


　　Then restart Tomcat and visit the URL
http://localhost/manager/list
to see the plain-text manager interface,
or http://localhost/manager/html/list
for the simple HTML manager
interface. Either way, your Manager application should now be
working.
　　The Manager application lets you install new web applications
on a non-persistent basis, for testing. If we have a web
application in /home/user/hello
and want to test it by
installing it under the URI /hello
, we put "/hello" in the first
text input field (for Path) and "file:/home/user/hello" in the
second text input field (for Config URL).
　　The Manager also allows you to stop, reload, remove, or
undeploy a web application. Stopping an application makes it
unavailable until further notice, but of course it can then be
restarted. Users attempting to access a stopped application will
receive an error message, such as 503 - This application is not
currently available
.
　　Removing a web application removes it only from the running
copy of Tomcat -- if it was started from the configuration
files, it will reappear the next time you restart Tomcat (i.e.,
removal does not remove the web application's content from
disk).

3. Deploying a Web Application
　　There are two ways of deploying a web application on the filesystem:
　　1. Copy your WAR file or your web application's directory
(including all of its content) to the $CATALINA_BASE/webapps
directory.
　　2. Create an XML fragment file with just the Context
element for
your web application, and place this XML file in
$CATALINA_BASE/webapps
. The web application itself can then be
stored anywhere on your filesystem.
　　If you have a WAR file, you can deploy it by simply copying
the WAR file into the directory CATALINA_BASE/webapps
. The
filename must end with an extension of ".war". Once Tomcat
notices the file, it will (by default) unpack it into a
subdirectory with the base name of the WAR file. It will then
create a context in memory, just as though you had created one
by editing Tomcat's server.xml
file. However, any necessary
defaults will be obtained from the DefaultContext
element in
Tomcat's server.xml
file.
　　Another way to deploy a web app is by writing a Context XML
fragment file and deploying it into the CATALINA_BASE/webapps
directory. A context fragment is not a complete XML document,
but just one Context
element and any subelements that are
appropriate for your web application. These files are like
Context
elements cut out of the server.xml
file, hence the name
"context fragment."
　　For example, if we wanted to deploy the WAR file MyWebApp.war
along with a realm for accessing parts of that web application,
we could use this fragment:


<!--  
Context fragment for deploying MyWebApp.war  
-->
<Context path="/demo" docBase="webapps/MyWebApp.war"
debug="0" privileged="true">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"               
resourceName="UserDatabase"/>
</Context>



　　Put that in a file called "MyWebApp.xml," and copy it into
your CATALINA_BASE/webapps
directory.
　　These context fragments provide a convenient method of
deploying web applications; you do not need to edit the
server.xml
file and, unless you have turned off the default
liveDeploy
feature, you don't have to restart Tomcat to install
a new web application.

4. Configuring Virtual Hosts
　　The Host
element normally needs modification only when you
are setting up virtual hosts. Virtual hosting is a mechanism
whereby one web server process can serve multiple domain names,
giving each domain the appearance of having its own server. In
fact, the majority of small business web sites are implemented
as virtual hosts, due to the expense of connecting a computer
directly to the Internet with sufficient bandwidth to provide
reasonable response times and the stability of a permanent IP
address.
　　Name-based virtual hosting is created on any web server
by establishing an aliased IP address in the Domain Name Service
(DNS) data and telling the web server to map all requests
destined for the aliased address to a particular directory of
web pages. Since this article is about Tomcat, we don't try to
show all of the ways to set up DNS data on various operating
systems. If you need help with this, please refer to DNS and
Bind
, by Paul Albitz and Cricket Liu (O'Reilly). For
demonstration purposes, I'll use a static hosts file, since
that's the easiest way to set up aliases for testing
purposes.
　　To use virtual hosts in Tomcat, you just need to set up the
DNS or hosts data for the host. For testing, making an IP alias
for localhost is sufficient. You then need to add a few lines to
the server.xml
configuration file:


<Server port="8005" shutdown="SHUTDOWN" debug="0">
<Service name="Tomcat-Standalone">
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"/>
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8443" minProcessors="5" maxProcessors="75"
acceptCount="10" debug="0" scheme="https" secure="true"/>
<Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
clientAuth="false" protocol="TLS" />
</Connector>
<Engine name="Standalone" defaultHost="localhost" debug="0">
<!-- This Host is the default Host -->
<Host name="localhost" debug="0" appBase="webapps"
unpackWARs="true" autoDeploy="true">
<Context path="" docBase="ROOT" debug="0"/>
<Context path="/orders" docBase="/home/ian/orders" debug="0"
reloadable="true" crossContext="true">
</Context>
</Host>

<!-- This Host is the first "Virtual Host": www.example.com -->
<Host name="www.example.com" appBase="/home/example/webapp">
<Context path="" docBase="."/>
</Host>



</Engine>
</Service>
</Server>


　　Tomcat's server.xml
file, as distributed, contains only one
virtual host, but it is easy to add support for additional
virtual hosts. The simplified version of the server.xml
file in
the previous example shows in bold the overall additional
structure needed to add one virtual host. Each Host
element must
have one or more Context
elements within it; one of these must
be the default Context
for this host, which is specified by
having its relative path set to the empty string (for example,
path=""
).

5. Configuring Basic Authentication
　　Container-managed authentication methods control how a user's
credentials are verified when a web app's protected resource is
accessed.  When a web application uses basic authentication
(BASIC
in the web.xml
file's auth-method
element), Tomcat uses
HTTP basic authentication to ask the web browser for a username
and password whenever the browser requests a resource of that
protected web application. With this authentication method, all
passwords are sent across the network in base64-encoded
text.
　　Note: using basic authentication is generally considered
insecure because it does not strongly encrypt passwords, unless
the site also uses HTTPS or some other form of encryption
between the client and the server (for instance, a virtual
private network). Without this extra encryption, network
monitors can intercept (and misuse) users' passwords.  But, if
you're just starting to use Tomcat, or if you just want to test
container-managed security with your web app, basic
authentication is easy to set up and test.  Just add
<security-constraint>
and <login-config>
elements to
your web app's web.xml
file, and add the appropriate <role>
and <user>
elements to your
CATALINA_BASE/conf/tomcat-users.xml
file, restart Tomcat, and
Tomcat takes care of the rest.
　　The example below shows a web.xml
excerpt from a club
membership web site with a members-only subdirectory that is
protected using basic authentication. Note that this effectively
takes the place of the Apache web server's .htaccess
files.


<!--
Define the Members-only area, by defining
a "Security Constraint" on this Application, and
mapping it to the subdirectory (URL) that we want
to restrict.
-->
<security-constraint>
<web-resource-collection>
<web-resource-name>
Entire Application
</web-resource-name>
<url-pattern>/members/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>member</role-name>
</auth-constraint>
</security-constraint>
<!-- Define the Login Configuration for this Application -->
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>My Club Members-only Area</realm-name>
</login-config>




6. Configuring Single Sign-On
　　Once you've set up your realm and method of authentication,
you'll need to deal with the actual process of logging the user
in. More often than not, logging into an application is a
nuisance to an end user, and you will need to minimize the
number of times they must authenticate. By default, each web
application will ask the user to log in the first time the user
requests a protected resource. This can seem like a hassle to
your users if you run multiple web applications and each
application asks the user to authenticate. Users cannot tell how
many separate applications make up any single web site, so they
won't know when they're making a request that crosses a context
boundary, and will wonder why they're being repeatedly asked to
log in.
　　The "single sign-on" feature of Tomcat 4 allows a user to
authenticate only once to access all of the web applications
loaded under a virtual host. To use this feature, you need only
add a SingleSignOn
Valve
element at the host level. This looks
like the following:


<Valve className="org.apache.catalina.authenticator.SingleSignOn"
debug="0"/>



　　The Tomcat distribution's default server.xml
contains a
commented-out single sign-on Valve
configuration example that
you can uncomment and use. Then, any user who is considered
valid in a context within the configured virtual host will be
considered valid in all other contexts for that same host.
　　There are several important restrictions for using the single sign-on
valve:

• 　　The valve must be configured and nested within the same
  Host
  element that the web applications (represented by Context
  elements) are nested within.
  
  
• 　　The Realm
  that contains the shared user information must
  be configured either at the level of the same Host
  or in an
  outer nesting.
  
  
• 　　The Realm
  cannot be overridden at the Context
  level.
  
  
• 　　The web applications that use single sign-on must use one
  of Tomcat's built-in authenticators (in the
  <auth-method>
  element of web.xml
  ), rather than a custom
  authenticator. The built-in methods are basic
  , digest
  , form
  ,
  and client-cert
  authentication.
  
  
• 　　If you're using single sign-on and wish to integrate
  another third-party web application into your web site, and
  the new web application uses only its own authentication code
  that doesn't use container-managed security, you're basically
  stuck. Your users will have to log in once for all of the web
  applications that use single sign-on, and then once again if
  they make a request to the new third-party web application. Of
  course, if you get the source and you're a developer, you
  could fix it, but that's probably not so easy to do.
  
  
• 　　The single sign-on valve requires the use of HTTP cookies.
  
  

7. Configuring Customized User Directories
　　Some sites like to allow individual users to publish a
directory of web pages on the server. For example, a university
department might want to give each student a public area, or an
ISP might make some web space available on one of its servers to
customers that don't have a virtually hosted web server. In such
cases, it is typical to use the tilde character (~) plus the
user's name as the virtual path of that user's web site:

http://www.cs.myuniversity.edu/~username
http://members.mybigisp.com/~username


　　Tomcat gives you two ways to map this on a per-host basis,
using a couple of special Listener
elements. The Listener
's
className
attribute should be org.apache.catalina.startup.UserConfig
, with the userClass
attribute
specifying one of several mapping classes. If your system runs
Unix, has a standard /etc/passwd
file that is readable by the
account running Tomcat, and that file specifies users' home
directories, use the PasswdUserDatabase
mapping class:

<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>


　　Web files would need to be in directories such as
/home/users/ian/public_html
or /users/jbrittain/public_html
. Of
course, you can change public_html
to be whatever subdirectory
into which your users put their personal web pages.
　　In fact, the directories don't have to be inside of a user's
home directory at all. If you don't have a password file but
want to map from a user name to a subdirectory of a common
parent directory such as /home
, use the HomesUserDatabase
class:

<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html" homeBase="/home"
userClass="org.apache.catalina.startup.HomesUserDatabase"/>


　　In this case, web files would be in directories such as
/home/ian/public_html
or /home/jasonb/public_html
.  This format
is more useful on Windows, where you'd likely use a directory
such as C:\home
.
　　These Listener
elements, if present, must be inside of a Host
element, but not inside of a Context
element, as they apply to the
Host
itself.

8. Using CGI Scripts with Tomcat
　　Tomcat is primarily meant to be a servlet/JSP container, but
it has many capabilities rivalling a traditional web server. One
of these is support for the Common Gateway Interface (CGI),
which provides a means for running an external program in
response to a browser request, typically to process a web-based
form. CGI is called "common" because it can invoke programs in
almost any programming or scripting language: Perl, Python, awk
,
Unix shell scripting, and even Java are all supported
options. However, you probably wouldn't run a Java application as
a CGI due to the start-up overhead; elimination of this overhead
was what led to the original design of the servlet
specification. Servlets are almost always more efficient than
CGIs because you're not starting up a new operating-system-level
process every time somebody clicks on a link or button.
　　Tomcat includes an optional CGI servlet that allows you to
run legacy CGI scripts; the assumption is that most new back-end
processing will be done by user-defined servlets and JSPs.
　　To enable Tomcat's CGI servlet, you must do the following:

• 　　Rename the file servlets-cgi.renametojar
  (found in
  CATALINA_HOME/server/lib/
  ) to servlets-cgi.jar
  , so that the
  servlet that processes CGI scripts will be on Tomcat's
  CLASSPATH
  .
  
  
• 　　In Tomcat's CATALINA_BASE/conf/web.xml
  file, uncomment the
  definition of the servlet named cgi
  (this is around line 241
  in the distribution).
  
  
• 　　Also in Tomcat's web.xml
  , uncomment the servlet mapping
  for the cgi
  servlet (around line 299 in the distributed
  file). Remember, this specifies the HTML links to the CGI
  script.
  
  
• 　　Either place the CGI scripts under the WEB-INF/cgi
  directory (remember that WEB-INF
  is a safe place to hide
  things that you don't want the user to be able to view, for
  security reasons), or place them in some other directory
  within your context and adjust the cgiPathPrefix
  initialization parameter of the CGIServlet
  to identify the
  directory containing the files. This specifies the actual
  location of the CGI scripts, which typically will not be the
  same as the URL in the previous step.
  
  
• 　　Restart Tomcat, and your CGI processing should now be
  operational.
  
  

　　The default directory for the servlet to locate the actual
scripts is WEB-INF/cgi
. As has been noted, the WEB-INF
directory
is protected against casual snooping from browsers, so this is a
good place to put CGI scripts, which may contain passwords or
other sensitive information. For compatibility with other
servers, though, you may prefer to keep the scripts in the
traditional directory, /cgi-bin
, but be aware that files in this
directory may be viewable by the curious web surfer.  Also, on
Unix, be sure that the CGI script files are executable by the
user under which you are running Tomcat.

9. Changing Tomcat's JSP Compiler
　　In Tomcat 4.1 (and above, presumably), compilation of JSPs
is performed by using the Ant program controller directly from
within Tomcat. This sounds a bit strange, but it's part of what
Ant was intended for; there is a documented API that lets
developers use Ant without starting up a new JVM. This is one
advantage of having Ant written in Java. Plus, it means you can
now use any compiler supported by the javac
task within Ant;
these are listed in the javac
page
of the Apache Ant manual. It is
easy to use because you need only an <init-param>
with a
name of "compiler" and a value of one of the supported compiler
names:


<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>
org.apache.jasper.servlet.JspServlet
</servlet-class>
<init-param>
<param-name>logVerbosityLevel</param-name>
<param-value>WARNING</param-value>
</init-param>
<init-param>
<param-name>compiler</param-name>
<param-value>jikes</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>


　　Of course, the given compiler must be installed on your
system, and the CLASSPATH
may need to be set, depending on which
compiler you choose.

10. Restricting Access to Specific Hosts
　　Sometimes you'll only want to restrict access to Tomcat's web app
to only specified host names or IP addresses. This way, only clients
at those specified sites will be served content. Tomcat comes with
two Valve
s that you can configure and use for this purpose:
RemoteHostValve
and RemoteAddrValve
.
　　These Valve
s allow you to filter requests by host name or by
IP address, and to allow or deny hosts that match, similar to
the per-directory Allow/Deny directives in Apache httpd
. If you
run the Admin application, you might want to only allow access to it
from localhost, as follows:


<Context path="/path/to/secret_files" ...>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127.0.0.1" deny=""/>
</Context>



　　If no allow pattern is given, then patterns that match the
deny attribute patterns will be rejected, and all others will be
allowed. Similarly, if no deny pattern is given, patterns that
match the allow
attribute will be allowed, and all others will
be denied.
　　
Jason Brittain
is a Senior Software Engineer at Symantec Corporation
's Network and Gateway Security Solutions Team, working on the AntiSpam
product.  He has contributed
to many Apache Jakarta projects, and has been an active open source software developer for several years.


　　
Ian F. Darwin
has worked in the computer industry for three decades: with Unix since
1980, Java since 1995, and OpenBSD since 1998. He is the author of two
O'Reilly books, Checking C Programs with lint
and Java Cookbook
, and co-author of
Tomcat:
The Definitive Guide

with Jason Brittain.