Administration Basics

This chapter is from the book

Tomcat 5 Unleashed

Learn More Buy

This chapter is from the book

This chapter is from the book 

Tomcat 5 Unleashed

Learn More Buy

Running Tomcat 5

So far, I've had you run Tomcat by typing catalina run. Some of you already familiar with Tomcat might wonder why I chose that method. As I pointed out before, I like it because if I have any startup errors, I get them in the same console window I used to type the command. For development, or for the initial setup of a Tomcat instance, it is good practice, but for production use, you generally choose another method.

Tomcat 5 bin files

Before I discuss the options, take a look at the contents of the bin directory. Figure 3.1 shows what's inside.

Figure 3.1 Tomcat 5 bin directory contents.

Looks daunting, doesn't it? Well, if I group files together, it is not so bad.

First, there are a few jar files, or Java libraries, which Tomcat uses when it starts. They are described in Table 3.2.

Table 3.2 Tomcat Startup Jars

Next, we can identify the main shell scripts, catalina.bat and catalina.sh, which we have already been using. They are called, in turn, by a few other scripts, shown in Table 3.3.

Table 3.3 Tomcat Startup Scripts

There are two Windows executables available for installing Tomcat as a service: tomcat.exe and tomcatw.exe. The only difference is that the latter runs a graphical version.

The launcher is a new concept in Tomcat 5. It used Apache Ant to start and stop Tomcat, as well as to invoke various Tomcat tools. This method uses the LauncherBootstrap.class, catalina.xml, launcher.properties, and *-using-launcher* files.

Table 3.4 describes a number of other files—utility scripts mostly—in the bin directory.

Table 3.4 Miscellaneous bin Files

Tomcat 5 Run Options

Now I can talk about the options for running Tomcat. Basically, you have three: you can start Tomcat manually on the command line and run it as an application until you stop it, as you have been doing; you can start Tomcat as a daemon so that it starts automatically on machine boot; and you can start Tomcat with the Ant-based launcher. I discuss the latter in Chapter 17, "Administering Tomcat."

Running Tomcat 5 Manually

If you are happy starting Tomcat the way I showed earlier, you can continue to do so. But if you'd prefer the "standard" way, you can type the following on Unix:

startup.sh

Use the following on Windows:

startup

Note that startup simply invokes either catalina.bat or catalina.sh with the start argument.

Similarly, for stopping Tomcat, type the following on Unix:

shutdown.sh

Type this on Windows:

shutdown

In this case, the command invokes either catalina.bat or catalina.sh with the stop argument.

Running Tomcat 5 Automatically

In any production system, you want Tomcat to start when the machine boots and run as a daemon or unattended, system-owned process. On Unix, this means you'll typically create a startup script that the operating system (OS) will execute on the boot and shutdown of the machine. On Windows, you'll typically install Tomcat as a service for the same results.

The key to a daemon process is that the application can respond to signals from the OS and take appropriate startup or shutdown measures. In a Unix daemon, the application responds to signals sent by the OS. For a Windows daemon, or service, the application implements various methods that the OS makes calls to.

In fact, a Java process is not naturally a daemon: it is meant to be invoked by some client via the main method, which is the entry point to the application. To run a Java process as a daemon, you must provide a native wrapper around it that provides the proper interface to the OS so it can be run as a daemon. The Tomcat distribution comes with just such a wrapper, or daemonizer, from the Jakarta Commons Daemon project. This project actually has two different flavors: JSVC, the daemonizer for Unix, and procrun, for Windows. The latter comes by default with Tomcat, in the form of tomcat.exe and tomcatw.exe in the $CATALINA_HOME/bin directory. I'll save the discussion on JSVC for Chapter 17. For Unix, you also have the option to create a simple startup/shutdown script, which is what we'll do here.

Running Tomcat 5 Automatically on Unix

To run a process automatically on Unix, you usually create a startup script in a predefined directory that the OS can then find and execute as it starts up. As you probably know, Unix runs at various run or init levels. At each level, it starts various services. Although there are technically 10 possible levels, the ones that typically concern you are 1, which is when the system is running in single-user mode; 2, which is when the system is running in multi-user mode with Network File Service (NFS); 3, for full multi-user mode; and 5, which is full multi-user mode plus X Windows.

To tell Unix which services should start at which run level, a collection of directories under /etc/rc.d contains service startup scripts. Figure 3.2 shows a typical example (on a Linux server).

Figure 3.2 Unix /etc/rc.d contents.

What you see is a directory for each Unix run level from 0 to 6, named rc[n].d, where [n] is the run level. The convention is to put the scripts in the init.d directory and then create symbolic links in the various run-level directories as appropriate. The convention also provides a way to determine the order of script execution at a particular run level: the symbolic links are named S[n][scriptname], where [n] is a two-digit number and [scriptname] is the actual name of the script in the /etc/rc.d/init.d directory that is being pointed to. There is a similar convention for stopping services, whereby Unix executes scripts as it descends through run levels. Scripts that need to execute to stop services are named K[n][scriptname], where [n] is a two-digit number and [scriptname] is the actual name of the script in the /etc/rc.d/init.d directory that is being pointed to. To make this work, you must configure the actual script to handle both start and stop situations, as you'll do in a minute.

You usually want Tomcat, or any Web server for that matter, to start at run level 3. I like to start Tomcat after any database server that my application depends on starts but before Apache starts (assuming that I am running Tomcat behind an Apache server). So I start by creating a script file called tomcat5 in /etc/rc.d/init.d that looks something like Listing 3.1.

Listing 3.1 Tomcat rc File

#!/bin/sh
#
# Startup script for Tomcat
#
 
case "$1" in
 start)
    echo -n "Starting Tomcat"
    JAVA_HOME="/usr/java/jdk1.3.1_08" ; export JAVA_HOME && 
/usr/tomcat5/bin/startup.sh
    ;;
 stop)
    echo -n "Stopping Tomcat"
    JAVA_HOME="/usr/java/jdk1.3.1_08" ; export JAVA_HOME && 
/usr/tomcat5/bin/shutdown.sh
    ;;
 restart)
    $0 stop
    $0 start
    ;;
 *)
    echo "Usage: $0 {start|stop|restart}"
    exit 1
esac
 
exit 0

This script expects to be called with one of three arguments: start, stop, or restart. All I do for the startup is set the $JAVA_HOME environment variable, which Tomcat needs, and then call startup.sh in the bin directory of the Tomcat installation. And that is all there is to it.

After you create the script, you need to create a symbolic link for it in the appropriate rc directory. Because I usually use rc3.d for Tomcat, I type

cd /etc/rc.d/rc3.d
ln -f ../init.d/tomcat5 K90tomcat5
ln -f ../init.d/tomcat5 S90tomcat5

What you are doing here is providing a startup link, S99tomcat5, which the OS will then call with the start argument. Because you want to gracefully shut down Tomcat when the machine stops, you'll also provide a shutdown link so that the OS will call with the stop argument. Obviously, both links point to the same script, which you've already coded to handle both arguments. Note too that I made the sequence number 90 because I want Tomcat to be one of the last things to start at run level 3. I make sure that MySQL (or whatever database I'm using) has a lower sequence number so it starts first. I also have Apache start after Tomcat by using a higher sequence number.

In Chapter 17, we'll go into building and using JSVC from the Commons Daemon project so that Tomcat can run as a true daemon.

Running Tomcat 5 as a Service on Windows

There are two ways you can install Tomcat as a daemon on Windows. The easiest is to download and execute the Windows installation of Tomcat. When you do, Tomcat is automatically installed as a service. The second option is to manually execute tomcat.exe in $CATALINA_HOME/bin.

Using the Tomcat Installer for Windows

Go back to the Tomcat binary download page, http://jakarta.apache.org/site/binindex.cgi, find the Tomcat 5 section, and download the *.exe distribution. After you download it, double-click to start the installation. You'll be prompted for the install location (by default, c:\Program Files\Apache Software Foundation\Tomcat 5.0), Java location, and a few other things. Once it is installed, however, you have a service now available called Apache Tomcat.

Manually Installing Tomcat as a Service

First, make sure you set the %JAVA_HOME% and %CATALINA_HOME% system environment variables in Control Panel, System, Environment Variables. Then, run the script shown in Listing 3.2.

Listing 3.2 Tomcat 5 Service Install Script

%CATALINA_HOME%\bin\tomcat //IS//Tomcat5 --DisplayName "Tomcat5" \
--Description "Tomcat5" --ImagePath "%CATALINA_HOME%\bin\bootstrap.jar" \
--StartupClass org.apache.catalina.startup.Bootstrap;main;start \
--ShutdownClass org.apache.catalina.startup.Bootstrap;main;stop \
--Java "%JAVA_HOME%\jre\bin\client\jvm.dll" \
--JavaOptions -Xrs \
--StdErrorFile "%CATALINA_HOME%\logs\stderr.log" \
--StdOutputFile "%CATALINA_HOME%\logs\stdout.log"

When you type this command, put everything on one line; I show line breaks only for readability. What you are doing here is telling Windows to install Tomcat as the service named Tomcat5. This service will run tomcat.exe, which is really just procrun from Commons Daemon, with various parameters as indicated.

Because the service silently installed, you have to go to Control Panel, Administrative Tools, Services, and you should see the Tomcat service listed as Tomcat5, as defined in the script.

Running the Tomcat Service

From the Services window, Control Panel, Administrative Tools, Services, you can set Tomcat to start automatically when the machine boots. You can also manually start and stop Tomcat from this window, or if you prefer, you can run the service from the command line and start Tomcat with

net start Tomcat5

You can stop Tomcat with

net stop Tomcat5

Finally, if you want to remove the service, just type

"%CATALINA_HOME%\bin\tomcat //RS/Tomcat5 

Depending on how you installed the service, you might have a different name from mine. When I install it manually, I usually call the Tomcat 5 service Tomcat5, but the Windows installer calls it Apache Tomcat