JakartaTomcat, the servlet engine from the Apache Foundation, can run the Axis servlet and hence can host web and grid services. These are some notes on installing JakartaTomcat with particular emphasis on making it start up when its host computer boots.

Getting the software

Download Tomcat from the Jakarta/Tomcat page at the Apache web-site. Please note that although Tomcat is an HTTP server, the Apache page labelled "HTTP server" is for a different product.

Several versions are available. At the time of writing, vv4.0.x and vv4.1.x are both suitable for web and grid services; vv4.1.x are better. Vv5.x are in beta and are best avoided. Vv3.x are obsolete.

The binary package is sufficient for running and developing web services. You don't need the source code.

The downloads page linked from the Tomcat page covers all of the Jakarta project, so you have to hunt for Tomncat links. Find the "release builds" section and scroll down. The link here take you into a directory tree of various builds.

If you have vv1.4.x of Java, then the preferred version of Tomcat (IMHO) is jakarta-tomcat-4.1.12-LE-jdk14. The "LE" stands for "light edition" and means that it doesn't include an XML parser. Vv1.4.x of Java include a suitable parser. If you use an earlier vesion of Java, then you can't run the "LE" build of Tomcat, so get one of the others.

Where to put it?

You can run Tomcat in either of two ways: experimentally, under your own user-name, or as a proper installation owned and run by root. The account that runs Tomcat writes into the Tomcat installation-tree at run time, so choose the installation site accordingly.

• If you want the experimental version, put it anywhere where you have writeable disc-space.
• If you want the "plumbed-in" version, put it on a disc local to the host computer in a directory owned by root.

If you want root to run it, make sure that root can see the JDK installation at boot time.

If, as at IoA, you have NFS discs shared between computers you need to be careful about which "root" owns each disc. If you have a software disc exported from a disc-server, the root who owns that file-system is not the root on the machines that mount the file-system. In this situation, root running the server may not have write-access at run-time and Tomcat may fail to start up.

Environment variables

In all the following sections, the following definitions are assumed.

• JAVA_HOME points to the top of the JDK installation.
• CATALINA_HOME points to the top of the Tomcat installation.

Tomcat sets its own classpath internally, so you needn't bother tuning your CLASSPATH variable.

Configuring IP ports

Tomcat listens for commands on several IP ports. The choice of ports is defined in $CATALINA_HOME/conf/server.xml. If you have no other servers on the host computer, then the default set of ports should work perfectly. If you need to have more than one instance of Tomcat running, or if you want a specific port for your service, then you need to reconfigure.

In the default configuration for Tomcat 4.1.12, three ports are assigned.

• The main HTTP traffic is through 8080, using something called a "non-SSL Coyote HTTP/1.1 Connector" (no, I don't know what it means either).
• There is an "SSL Coyote HTTP/1.1 Connector" on port 8443.
• There is a "Coyote/JK2 AJP 1.3 Connector" on port 8009.
• The server listens for shutdown commands on port 8005.

You need to reassign all of these ports if you run a second copy of Tomcat.

In Tomcat v4.1.12, the SSL connector (port 8443 by default) prevents Tomcat from starting up. You must not enable this connector. Comment it out.

Configuring administrators and managers

At v4.1.12 of Tomcat (but not, apparently, in vv4.0.x), you have to configure access for privileged users. You may never use this special access (there are alternative methods) but the default configuration is a gaping security hole that you have to plug.

By default, $CATALINA_HOME/conf/tomcat-users.xml looks like this:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="manager"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
</tomcat-users>

i.e. it has standard passwords that will be known to crackers.

You need to change it to something like this:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="gtr" password="********" roles="manager,admin"/>
</tomcat-users>

in which you replace "gtr" with some local user-name and fill in the password of your choice. As far as I can tell, the local user-name doesn't have to be a Unix/Linux user-name that maps to a UID. I.e. the system requires you to enter the user-name when authenticating; it doesn't infer it from a UID.

The "admin" role lets the named user run the adminstration tool for the Tomcat server. It's unclear to me what this is useful for.

The "manager" role lets the named user manage specific servlets. Axis, the web-services container, is a servlet, and OGSI, the grid-services container can occur as a modified copy of Axis, so this management role may be useful.

Both roles apply to privileged access via a web browser. If you look at http://localhost:8080/ (change the port number if your Tomcat is on a non-standard port) you'll see the default home-page for the server. The links to the management screens are at the top of the side-bar.

Starting Tomcat manually

To start Tomcat from the command line:

1. Define the environment variable JAVA_HOME to point to the JDK installation.
2. Define the environment variable CATALINA_HOME to point to the Tomcat installation.
3. Give the command $CATALINA_HOME/bin/startup.sh.

The latter command will start a Tomcat process and exit as soon as that process starts. The startup.sh script doesn't check to see if Tomcat actually runs correctly.

Stopping Tomcat manually

To stop Tomcat from the command line:

1. Define the environment variable JAVA_HOME to point to the JDK installation.
2. Define the environment variable CATALINA_HOME to point to the Tomcat installation.
3. Give the command $CATALINA_HOME/bin/shutdown.sh.

The shutdown.sh command seems to wait for Tomcat to close down and exit before returning.

Starting Tomcat at boot time

Normally, a production server should start when its hosts boots up.

In Solaris, this is done by adding a script to the directory /etc/rc3.d such that the operating system runs the script when the machine enters run-level 3. On cass123.ast.cam.ac.uk, the script is S99tomcat. The S99 prefix implies that it's just about the last thing to start up in run-level 3, which is as it should be; nothing else in the system depends on Tomcat, but Tomcat depends on many aspects of the OS. Note that the script takes one parameter which may be start stop or restart. The script is attached.

Linux start-up is probably similar, but the details need checking by someone with a Linux server:

• the directory for daemon scripts is probably different;
• the bourne shell might not be /sbin/sh;
• the default arguments for the script may be different.

If you look in the script itself you'll see that it's trivial. The command $CATALINA_HOME/bin/startup.sh does almost all the work and only requires the environment variables to be set.

-- GuyRixon - 20 Nov 2002