Top Ten Tomcat Configuration Tips by Jason Brittain and Ian F. Darwin, authors of Tomcat: The Definitive Guide 06/25/2003

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.

Related Reading Tomcat: The Definitive Guide By Jason?Brittain, Ian F.?Darwin

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 https://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 https://localhost/manager/list to see the plain-text manager interface, or https://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>