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.
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 tomcat.apache.org, 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 catalina.sh[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
|
Purpose | |
|---|---|
|
|
The main Tomcat script. This runs the |
|
|
This is used internally, and then only on Windows systems, to append items to Tomcat classpath environment variables. |
|
|
This makes a |
|
|
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 |
|
|
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/catalina.sh 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:
/usr/java/jdk1.5.0_06/bin/../jre/bin:/usr/lib
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 /0.0.0.0:8009
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 msIf 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
|
Option |
Purpose |
|---|---|
|
|
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. |
|
|
This starts Tomcat as a Java Platform Debugger Architecture-compliant debugger. See Sun's JPDA documentation at http://java.sun.com/products/jpda. |
|
|
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. |
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
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.14Echo 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 startup.sh script like
this:
$ bin/startup.sh
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_02You 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 shutdown.sh script to shut Tomcat
down:
$ bin/shutdown.sh
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_02If 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 startIf you installed the JPackage.org Tomcat
RPM package, the name of the init script is
tomcat55, so the command would be:
# /etc/rc.d/init.d/tomcat55 startThen, check to see if it's running:
# ps auwwx | grep catalina.startup.BootstrapYou 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.
Tip
If Tomcat fails to startup correctly, go back and make sure that the /opt/tomcat/conf/tomcat-env.sh file has all the right settings for your server computer (in the JPackage.org 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 stopOr (shorter):
# service tomcat stopTo 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 startAnd, you can stop it like this:
# /etc/init.d/cswtomcat5 stopWatch your catalina.out logfile in /opt/csw/share/tomcat5/logs so that you'll know if there are any errors.
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
^C
Stopping service Tomcat-Standalone
C:\>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.
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 8080You 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/startup.sh; cd -Tomcat can be stopped with the following command:
$ cd /; sudo -u nobody /usr/local/tomcat/bin/shutdown.sh; 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/startup.sh$sudo -u nobody /usr/local/tomcat/bin/shutdown.sh
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!
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/tomcat60.sh. By default, this ends up being /usr/local/etc/rc.d/tomcat60.sh. 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/tomcat60.sh start
Starting tomcat60.This will only work if you have added this line to your /etc/rc.conf file:
tomcat60_enable="YES"
You may use the tomcat60.sh 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/.
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
ServerandConnectorelements in the server.xml files must be different between instances. For more information on these elements, consult Chapter 7.
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 shutdown.sh 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.
If you installed Tomcat "by hand" by downloading and unpacking an official binary release archive (tar.gz or .zip) from tomcat.apache.org, regardless of the operating system you're using, here is the standard way to restart Tomcat:
Change directory into the root of the Tomcat installation directory (commonly known as the CATALINA_HOME directory):
$
cd apache-tomcat-6.0.14Issue a shutdown via the
shutdown.shscript:$
bin/shutdown.shDecide 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.
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 j
pscommand to look for any remaining Tomcat processes that are your Tomcat's Java virtual machine. Thejpscommand comes with Java. Try this:$ jps | grep BootstrapIf 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 SolarisIf 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
TERMsignal to the processes you find, asking the JVM to perform a shutdown (ensuring you have the correct user permissions):$
kill -TERM <process-ID-list>Do another
pslike 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>Once you're sure that Tomcat's JVM is no longer running, start a new Tomcat process:
$
bin/startup.sh
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.).
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 JPackage.org, restarting Tomcat is easy. If you installed the RPM package from this book, do:
# service tomcat restartAnd, if you installed the JPackage.org RPM package, do:
# service tomcat55 restartwhich should reliably restart Tomcat. Be sure to check your logfiles for any startup problems.
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 restartThat 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.
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).
Be sure to check your logfiles for any startup problems.
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 shutdown.sh. 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 8080tcp46 0 0 *.8080 *.* LISTEN $cd /; sudo -u nobody /usr/local/tomcat/bin/shutdown.sh; 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 8080You 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/startup.sh; 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/bartAfter 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 *.* LISTENIf 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
[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 catalina.sh.
[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 books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
