Starting, Stopping, and Restarting Tomcat

Once you have the installation completed, you will probably be eager to start Tomcat and see if it works. This section details how to start up and shut down Tomcat, including specific information on each supported operating system. It also details common errors that you may encounter, enabling you to quickly identify and resolve any problems you run into.

Starting Up and Shutting Down

The correct way to start and stop Tomcat depends on how you installed it. For example, if you installed Tomcat from a Linux RPM package, you should use the init script that came with that package to start and stop Tomcat. Or, if you installed Tomcat on Windows via the graphical installer from, you should start and stop Tomcat as you would any Windows service. Details about each of these package-specific cases are given in the next several sections. If you installed Tomcat by downloading the binary release archive (.zip or .tar.gz) from the Tomcat downloads page—what we'll call the generic installation case—you should use the command-line scripts that reside in the CATALINA_HOME/bin directory.

There are several scripts in the bin directory that you will use for starting and stopping Tomcat. All the scripts you will need to invoke directly are provided both as shell script files for Unix (.sh) and batch files for Windows (.bat). Table 1-1 lists these scripts and describes each. When referring to these, we have omitted the filename extension because catalina.bat has the same meaning for Microsoft Windows users that[3] has for Unix users. Therefore, the name in the table appears simply as catalina. You can infer the appropriate file extension for your system.

Table 1-1. Tomcat invocation scripts




The main Tomcat script. This runs the java command to invoke the Tomcat startup and shutdown classes.


This is used internally, and then only on Windows systems, to append items to Tomcat classpath environment variables.


This makes a crypto digest of Tomcat passwords. Use it to generate encrypted passwords.


This script installs and uninstalls Tomcat as a Windows service.


This is also only used internally and sets the Tomcat classpath and several other environment variables.


This runs catalina stop and shuts down Tomcat.


This runs catalina start and starts up Tomcat.


This is a generic Tomcat command-line tool wrapper script that can be used to set environment variables and then call the main method of any fully qualified class that is in the classpath that is set. This is used internally by the digest script.


This runs the catalina version, which outputs Tomcat's version information.

The main script, catalina, is invoked with one of several arguments. The most common arguments are start, run, or stop. When invoked with start (as it is when called from startup), it starts up Tomcat with the standard output and standard error streams directed into the file CATALINA_HOME/logs/catalina.out. The run argument causes Tomcat to leave the standard output and error streams where they currently are (such as to the console window) useful for running from a terminal when you want to see the startup output. This output should look similar to Example 1-1.

Example 1-1. Output from catalina run

ian:389$ bin/ start
Using CATALINA_BASE:   /home/ian/apache-tomcat-6.0.14
Using CATALINA_HOME:   /home/ian/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /home/ian/apache-tomcat-6.0.14/temp
Using JRE_HOME:       /usr/java/jdk1.6.0_02
Sep 27, 2007 10:42:16 PM org.apache.catalina.core.AprLifecycleListener lifecycleEvent
INFO: The Apache Tomcat Native library which allows optimal performance in produ ction
environments was not found on the java.library.path:
Sep 27, 2007 10:42:17 PM org.apache.coyote.http11.Http11BaseProtocol init
INFO: Initializing Coyote HTTP/1.1 on http-8080
Sep 27, 2007 10:42:17 PM org.apache.catalina.startup.Catalina load
INFO: Initialization processed in 948 ms
Sep 27, 2007 10:42:17 PM org.apache.catalina.core.StandardService start
INFO: Starting service Catalina
Sep 27, 2007 10:42:17 PM org.apache.catalina.core.StandardEngine start
INFO: Starting Servlet Engine: Apache Tomcat/6.0.14
Sep 27, 2007 10:42:17 PM org.apache.catalina.core.StandardHost start
INFO: XML validation disabled
Sep 27, 2007 10:42:27 PM org.apache.coyote.http11.Http11BaseProtocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
Sep 27, 2007 10:42:28 PM org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /
Sep 27, 2007 10:42:29 PM org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/106  config=null
INFO: Find registry server-registry.xml at classpath resource
Sep 27, 2007 10:42:30 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 1109 ms

If you use catalina with the start option or invoke the startup script instead of using the run argument, you see only the first few Using... lines on your console; all the rest of the output is redirected into the catalina.out logfile. The shutdown script invokes catalina with the argument stop, which causes Tomcat to connect to the default port specified in your Server element (discussed in Chapter 7) and send it a shutdown message. A complete list of startup options is listed in Table 1-2.

Table 1-2. Startup options



-config [server.xml file]

This specifies an alternate server.xml configuration file to use. The default is to use the server.xml file that resides in the $CATALINA_BASE/conf directory. See the "server.xml" section in Chapter 7 for more information about server.xml's contents.


This prints out a summary of the command-line options.


This disables the use of JNDI within Tomcat.


This enables the use of the catalina.policy file.


This starts Tomcat in debugging mode.


This allows Tomcat to be tested in an embedded mode, and is usually used by application server developers.

jpda start

This starts Tomcat as a Java Platform Debugger Architecture-compliant debugger. See Sun's JPDA documentation at


This starts up Tomcat without redirecting the standard output and errors.


This starts up Tomcat, with standard output and errors going to the Tomcat logfiles.


This stops Tomcat.


This outputs Tomcat's version information.

Environment variables

To prevent runaway programs from overwhelming the operating system, Java runtime environments feature limits such as "maximum heap size." These limits were established when memory was more expensive than at present; for JDK 1.3, for example, the default limit was only 32 MB. However, there are options supplied to the java command that let you control the limits. The exact form depends upon the Java runtime, but if you are using the Sun runtime, you can enter:

java -Xmx=256M MyProg

This will run a class file called MyProg with a maximum memory size of 256 MB for the entire Java runtime process.

These options become important when using Tomcat, as running servlets can begin to take up a lot of memory in your Java environment. To pass this or any other option into the java command that is used to start Tomcat, you can set the option in the environment variable JAVA_OPTS before running one of the Tomcat startup scripts.

Windows users should set this environment variable from the Control Panel, and Unix users should set it directly in a shell prompt or login script:

$ export JAVA_OPTS="-Xmx256M"  # Korn and Bourne shell
C:\> set JAVA_OPTS="-Xmx256M"  # MS-DOS
$ setenv JAVA_OPTS "-Xmx256M"  # C-shell

Other Tomcat environment variables you can set are listed in Table 1-3.

Table 1-3. Tomcat environment variables





This sets the base directory for writable or customized portions of a Tomcat installation tree, such as logging files, work directories, Tomcat's conf directory, and the webapps directory. It is an alias for CATALINA_HOME.

Tomcat installation directory


This sets the base directory for static (read-only) portions of Tomcat, such as Tomcat's lib directories and command-line scripts.

Tomcat installation directory


This passes through Tomcat-specific command-line options to the java command.



This sets the directory for Tomcat temporary files.



This sets the location of the Java runtime or JDK that Tomcat will use.



This is an alias to JAVA_HOME.



This is where you may set any Java command-line options.



This variable may set the transport protocol used for JPDA debugging.



This sets the address for the JPDA used with the catalina jpda start command.



This sets the location of the Java Secure Sockets Extension used with HTTPS.



This variable may optionally hold the path to the process ID file that Tomcat should use when starting up and shutting down.


Starting and stopping: The general case

If you have installed Tomcat via an Apache binary release archive (either a .zip file or a .tar.gz file), change directory into the directory where you installed Tomcat:

$ cd apache-tomcat-6.0.14

Echo your $JAVA_HOME environment variable. Make sure it's set to the absolute path of the directory where the Java installation you want Tomcat to use resides. If it's not, set it and export it now. It's OK if the java interpreter is not on your $PATH because Tomcat's scripts are smart enough to find and use Java based on your setting of $JAVA_HOME.

Make sure you're not running a TCP server on port 8080 (the default Tomcat HTTP server socket port), nor on TCP port 8005 (the default Tomcat shutdown server socket port). Try running telnet localhost 8080 and telnet localhost 8005 to see if any existing server accepts a connection, just to be sure.

Start up Tomcat with its script like this:

$ bin/
Using CATALINA_BASE:   /home/jasonb/apache-tomcat-6.0.14
Using CATALINA_HOME:   /home/jasonb/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /home/jasonb/apache-tomcat-6.0.14/temp
Using JAVA_HOME:       /usr/java/jdk1.6.0_02

You should see output similar to this when Tomcat starts up. Once started, it should be able to serve web pages on port 8080 (if the server is localhost, try http://localhost:8080 in your web browser).

Invoke the script to shut Tomcat down:

$ bin/
Using CATALINA_BASE:   /home/jasonb/apache-tomcat-6.0.14
Using CATALINA_HOME:   /home/jasonb/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /home/jasonb/apache-tomcat-6.0.14/temp
Using JAVA_HOME:       /usr/java/jdk1.6.0_02

Starting and stopping on Linux

If you've installed Tomcat via the RPM package on Linux, you can test it out by issuing a start command via Tomcat's init script, like this:

# /etc/rc.d/init.d/tomcat start
Starting tomcat:                                          [  OK  ]

Or, on some Linux distributions, such as Fedora and Red Hat, to do the same thing, you may instead type the shorter command:

# service tomcat start

If you installed the Tomcat RPM package, the name of the init script is tomcat55, so the command would be:

# /etc/rc.d/init.d/tomcat55 start

Then, check to see if it's running:

# ps auwwx | grep catalina.startup.Bootstrap

You should see several Java processes scroll by. Another way to see whether Tomcat is running is to request a web page from the server over TCP port 8080.


If Tomcat fails to startup correctly, go back and make sure that the /opt/tomcat/conf/ file has all the right settings for your server computer (in the RPM installation case, it's the /etc/tomcat55/tomcat55.conf file). Also check out the "Common Errors" section, later in this chapter.

To stop Tomcat, issue a stop command like this:

# /etc/rc.d/init.d/tomcat stop

Or (shorter):

# service tomcat stop

Starting and stopping on Solaris

To use Tomcat's init script on Solaris, you must be the root user. Switch to root first. Then, you can start Tomcat like this:

# /etc/init.d/cswtomcat5 start

And, you can stop it like this:

# /etc/init.d/cswtomcat5 stop

Watch your catalina.out logfile in /opt/csw/share/tomcat5/logs so that you'll know if there are any errors.

Starting and stopping on Windows

On Microsoft Windows, Tomcat can be started and stopped either as a windows service or by running a batch file. If you arrange for automatic startup (detailed later in this chapter), you may manually start Tomcat in the control panel. If not, you can start Tomcat from the desktop icon.

If you have Tomcat running in a console window, you can interrupt it (usually with Ctrl-C) and it will catch the signal and shut down:

Apache Tomcat/6.0.14
Stopping service Tomcat-Standalone

If the graceful shutdown does not work, you need to find the running process and terminate it. The JVM running Tomcat will usually be identified as a Java process; be sure you get the correct Java if other people or systems may be using Java. Use Ctrl-Alt-Delete to get to the task manager, select the correct Java process, and click on End Task.

Starting and stopping on Mac OS X

The Mac OS X installation of Tomcat is simply the binary distribution, which means you can use the packaged shell scripts that come with the Apache binary release. This provides a quick and easy set of scripts to start and stop Tomcat as required. First, we will show you the general case for starting and stopping Tomcat on Mac OS X.

Mac OS X sets all your paths for you so all you need to do is ensure that there are no TCP services already running on port 8080 (the default Tomcat HTTP server socket port), nor on port 8005 (the default Tomcat shutdown port). This can be done easily by running the netstat command:

$ netstat -an | grep 8080

You should see no output. If you do, it means another program is listening on port 8080, and you should shut it down first, or you must change the port numbers in your CATALINA_HOME/conf/server.xml configuration file. Do the same for port 8005.

Tomcat can be started on OS X with the following command:

$ cd /; sudo -u nobody /usr/local/tomcat/bin/; cd -

Tomcat can be stopped with the following command:

$ cd /; sudo -u nobody /usr/local/tomcat/bin/; cd -

Because the user nobody is an unprivileged user, a lot of folders on your disk are not accessible to it. This is of course a good thing, but because the scripts for starting and stopping Tomcat attempt to determine the current directory, you will get errors if the scripts are not being called from a folder to which the user nobody has read access. To avoid this, the above commands consist of three subcommands. First, they change to the root folder (/), next they call script to start or stop Tomcat as the user nobody, and finally they return to the folder they started in. If you are running the commands from a folder to which the user nobody has read access (e.g., /), you can shorten the commands by leaving out the first and last parts as follows:

$ sudo -u nobody /usr/local/tomcat/bin/
$ sudo -u nobody /usr/local/tomcat/bin/

Later in the "Automatic Startup on Mac OS X" section, we show you how to create and install init scripts via Apple's launchd, as you see in the Linux RPM installations and the BSD port installs, to allow you to not only start and stop Tomcat, but also to automatically start Tomcat on boot—the Mac OS X way!

Starting and stopping on FreeBSD

This port installs Tomcat into the root path /usr/local/tomcat6.0/. The behavior of Tomcat may be configured through variables in your /etc/rc.conf file, which override settings that are contained in the /etc/defaults/rc.conf file. This port includes an RCng script named ${PREFIX}/etc/rc.d/ By default, this ends up being /usr/local/etc/rc.d/ Read the top of this file to see what Tomcat variable settings you may apply in your /etc/rc.conf file.

Try starting Tomcat like this:

# /usr/local/etc/rc.d/ start
Starting tomcat60.

This will only work if you have added this line to your /etc/rc.conf file:


You may use the script to start, stop, and restart Tomcat 6.

By default, this FreeBSD port of Tomcat 6.0 sets Tomcat's default HTTP port to be 8180, which is different than the default that is originally set (for all operating systems) in the Apache Software Foundation's distribution of Tomcat (which is 8080). Try accessing your FreeBSD Tomcat port via the URL http://localhost:8180/.

Common Errors

Several common problems can result when you try to start up Tomcat. While there are many more errors that you can run into, these are the ones we most often encounter.

Another server is running on port 80 or 8080

Ensure that you don't have Tomcat already started. If you don't, check to see if other programs, such as another Java application server or Apache Web Server, are running on these ports.

Another instance of Tomcat is running

Remember that not only must the HTTP port of different Tomcat instances (JVMs) be different, every port number in the Server and Connector elements in the server.xml files must be different between instances. For more information on these elements, consult Chapter 7.

Restarting Tomcat

At the time of this writing, there is no restart script that is part of the Tomcat 6.0 distribution because it is tough to write a script that can make sure that when Tomcat stops, it shuts down properly before being started up again. The reasons outlined below for Tomcat shutdowns being unreliable are almost exclusively edge conditions. That means they don't usually happen, but that they can occur in unusual situations. Here are some reasons why shutdowns may be unreliable:

  • The Java Servlet Specification does not mandate any time limit for how long a Java servlet may take to perform its work. Writing a servlet that takes forever to perform its work does not break compliance with the Java Servlet Specification, but it can prevent Tomcat from shutting down.

  • The Java Servlet Specification also dictates that on shutdowns, servlet containers must wait for each servlet to finish serving all requests that are in progress before taking the servlet out of service, or wait a container-specific timeout duration before taking servlets out of service. For Tomcat 6, that timeout duration is a maximum of a half-second per servlet. When a servlet misbehaves and takes too long to finish serving requests, it's up to Tomcat to figure out that the servlet has taken too long and forcibly take it out of service so that Tomcat can shut down. This processing takes time, though, and slows Tomcat's own shutdown processing.

  • Multithreading in Java virtual machines is specified in a way that means that Java code will not always be able to tell exactly how much real time is going by (Java SE is not a real-time programming environment). Also, due to the way Java threads are scheduled on the CPU, threads can become blocked and stay blocked. Because of these limitations, the Java code that is called on invocations of will not always know how long to wait for Tomcat to shut down, nor can Tomcat always know it's taking too long to shut down. That means that shutdowns are not completely reliable when written in pure Java. An external program would need to be written in some other programming language to reliably shut down Tomcat.

  • Because Tomcat is an embeddable servlet container, it tries not to call System.exit(0) when shutting down the server because Tomcat does not know what else may need to stay running in the same Java virtual machine. Instead, Tomcat shuts down all of its own threads so that the VM can exit gracefully if nothing else needs to run. Because of that, a servlet could spawn a thread that would keep the VM from exiting even when Tomcat's threads are all shut down.

  • The Java Servlet Specification allows servlets to create additional Java threads that perform work as long as any security manager allows it.[4] Once another thread is spawned from a servlet, it can raise its own priority higher than Tomcat's threads' priorities (if the security manager allows) and could keep Tomcat from shutting down or from running at all. Usually if this happens, it's not malicious code but buggy code. Try not to do this!

  • If your Tomcat instance has run completely out of memory (as evidenced by the dreaded "Permgen memory" error in the logs), it will usually be unable to accept new connections on its web port or on its shutdown port.

To fix some of the problems, you may want to configure and use a security manager. See Chapter 6 for more information on how to place limits on webapps to guard against some of these problems.

The general case

If you installed Tomcat "by hand" by downloading and unpacking an official binary release archive (tar.gz or .zip) from, regardless of the operating system you're using, here is the standard way to restart Tomcat:

  1. Change directory into the root of the Tomcat installation directory (commonly known as the CATALINA_HOME directory):

    $ cd apache-tomcat-6.0.14
  2. Issue a shutdown via the script:

    $ bin/
  3. Decide how long you want to wait for Tomcat to shut down gracefully, and wait that period of time. Reasonable maximum shutdown durations depend on your web application, your server computer's hardware, and how busy your server computer is, but in practice, Tomcat often takes several seconds to completely shut down.

  4. Query your operating system for java processes to make sure it shut down. On Windows, hit Ctrl-Alt-Delete to get to the task manager, and scroll through the list to look for it. On all other operating systems, use the jps command to look for any remaining Tomcat processes that are your Tomcat's Java virtual machine. The jps command comes with Java. Try this:

    $ jps | grep Bootstrap

    If that fails, use an OS-dependent Process Status (ps) command, such as this:

    $ ps auwwx | grep catalina.startup.Bootstrap \
        # On Linux or *BSD
    $ /usr/ucb/ps auwwx | grep catalina.startup.Bootstrap \
        # On Solaris
  5. If no Tomcat java processes are running, skip to step 6. Otherwise, because the Tomcat JVM is not shutting down in the time you've allowed, you may want to force it to exit. Send a TERM signal to the processes you find, asking the JVM to perform a shutdown (ensuring you have the correct user permissions):

    $ kill -TERM <process-ID-list>
  6. Do another ps like you did in step 4. If the Tomcat JVM processes remain, repeat step 5 until they're gone. If they persist, have your operating system kill the java process. On Windows, use the task manager to end the task(s). On all other operating systems, use the kill command to tell the kernel to kill the process(es) like this:

    $ kill -KILL <process-ID-list>
  7. Once you're sure that Tomcat's JVM is no longer running, start a new Tomcat process:

    $ bin/

Usually, the shutdown process goes smoothly and Tomcat JVMs shut down quickly. But, because there are situations when they don't, the above procedure should always suffice. We realize this is not a very convenient way to restart Tomcat; however, if you try to cut corners here, you will likely not always shut down Tomcat and get errors due to the new Tomcat JVM bumping into the existing Tomcat JVM when you go to start it again. Luckily, for most operating systems, there are scripts that automate this entire procedure, implemented as a "restart" command. You'll find these integrated into most OS-specific Tomcat installation packages (Linux RPM packages, the FreeBSD port, etc.).

Restarting Tomcat on Linux

The following outlines how to reliably restart Tomcat on Linux. If you have installed Tomcat via an RPM package, either the one from this book or the one from, restarting Tomcat is easy. If you installed the RPM package from this book, do:

# service tomcat restart

And, if you installed the RPM package, do:

# service tomcat55 restart

which should reliably restart Tomcat. Be sure to check your logfiles for any startup problems.

Restarting Tomcat on Solaris

The following outlines how to reliably restart Tomcat on Solaris. If you have installed Tomcat via a Blastwave Solaris CSW package, restarting Tomcat is easy:

# /etc/init.d/cswtomcat5 restart

That should restart Tomcat. Be sure to check your logfiles for any startup problems.

As of this writing, the Blastwave package's init script does not contain any code to reliably restart Tomcat—it does not watch the processes to make sure that they came down all the way, nor does it try to force the processes down if they do not come down on their own. Read the init script source and you'll see what we mean. So, it is up to the Solaris administrator to ensure (by hand) that the restart actually occurred.

Restarting the Tomcat Windows Service

If you have Tomcat running as a Windows Service, you can restart it from the control panel. Either right-click on the service and select Restart from the pop-up menu or, if it exists on your version of Windows, use the Restart button near the upper-right corner of the dialog box (see Figure 1-6).

Restart button in Control Panel

Figure 1-6. Restart button in Control Panel

Be sure to check your logfiles for any startup problems.

Restarting Tomcat on Mac OS X

The standard way to restart Tomcat on OS X is to stop and then start Tomcat.

If you have chosen to use the generic way to start Tomcat, there is no easy way to restart Tomcat in Mac OS X and the best solution is to call Then, just as described in the Linux section of this chapter, you would decide how long you will wait for Tomcat to shut down and take the appropriate steps, as outlined above.

A simple way to see if Tomcat is running is to check if there is a service listening on TCP port 8080 with the netstat command. This will, of course, only work if you are running Tomcat on the port you specify (its default port of 8080, for example) and not running any other service on that port.

First, shut down the currently running Tomcat instance:

$ netstat -an | grep 8080
tcp46      0      0  *.8080                 *.*                    LISTEN
$ cd /; sudo -u nobody /usr/local/tomcat/bin/; cd -
Using CATALINA_BASE:   /usr/local/tomcat
Using CATALINA_HOME:   /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JRE_HOME:       /Library/Java/Home/Users/bart

Then, check to make sure Tomcat is no longer running:

$ netstat -an | grep 8080

You should see no output, meaning that Tomcat has shut down. Then, you may start it back up again, like this:

$ cd /; sudo -u nobody /usr/local/tomcat/bin/; cd -
Using CATALINA_BASE:   /usr/local/tomcat
Using CATALINA_HOME:   /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JRE_HOME:       /Library/Java/Home/Users/bart

After waiting some seconds, check to make sure that Tomcat is running and listening on port 8080 again:

$ netstat -an | grep 8080
tcp46      0      0  *.8080                 *.*                    LISTEN

If you have chosen to use the automatic startup and shutdown scripts for Tomcat via Apple's launchd (see the section "Automatic Startup on Mac OS X," later in this chapter, for details about how to set that up), it's very easy to restart Tomcat simply by unloading the service and reloading it into launchd:

$ sudo launchctl unload /Library/LaunchDaemons/tomcat.plist
$ sudo launchctl load /Library/LaunchDaemons/tomcat.plist

Restarting Tomcat on FreeBSD

The following outlines how to reliably restart Tomcat on FreeBSD. You can restart the Tomcat 6 port by running:

# /usr/local/etc/rc.d/ restart

That should reliably restart Tomcat. Be sure to check your logfiles for any startup problems.

[3] * Linux, BSD, and Unix users may object to the .sh extension for all of the scripts. However, renaming these to your preferred conventions is only temporary, as the .sh versions will reappear on your next upgrade. You are better off getting used to typing

[4] * An urban legend about developing Java webapps says that according to the Java Servlet Specification, servlets in webapps are not allowed to spawn any Java threads. That is false. The servlet specification does not preclude doing this, so it is OK to spawn one or more threads as long as the thread(s) are well behaved. This is often the rub, since webapp developers often report bugs against Tomcat that turn out to be caused by their own code running in a separate thread.

Get Tomcat: The Definitive Guide, 2nd Edition now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.