Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Architecture and Install

Starting and Stopping Tomcat

Learn the Tomcat launch scripts, catalina.sh commands, setenv.sh with CATALINA_OPTS and JAVA_OPTS, the shutdown port protocol, systemd and Windows services, and graceful shutdown.

You can start Tomcat by double-clicking nothing at all: one script is enough. But a server that must survive reboots, accept JVM tuning and shut down without dropping requests needs a little more. This lesson covers the launch scripts, how to pass JVM options, how the shutdown command really works, and how to run Tomcat as a service on Linux and Windows.

All commands are read-only here. The runnable programs reproduce the shutdown-port protocol and a graceful stop with plain Java.

The scripts

In bin you find a pair for each operating system (.sh for Unix-like, .bat for Windows):

Script What it does
startup Starts Tomcat in the background (calls catalina start).
shutdown Stops it (calls catalina stop).
catalina The real launcher; takes a command.
configtest Parses server.xml and reports errors without starting.
version Prints Tomcat, OS and JVM versions.
digest Creates hashed passwords for realms.

catalina.sh accepts these commands:

Terminal
catalina.sh run          # start in the foreground, log to the console (good for Docker and debugging)
catalina.sh start        # start in the background, output to logs/catalina.out
catalina.sh stop 10      # stop, wait up to 10 seconds, then continue
catalina.sh stop -force  # stop and kill the process if it hangs
catalina.sh configtest   # validate configuration
catalina.sh version
catalina.sh jpda start   # start with the Java debugger enabled (port 8000)

Choosing the command

run Foreground, logs on the console
start Background, logs in catalina.out
stop Sends SHUTDOWN, optional wait
configtest Check config before restart

Use run inside containers and services.

1 / 2

JVM options: setenv.sh

Do not edit catalina.sh. Create bin/setenv.sh (in CATALINA_BASE/bin); the launcher sources it if it exists:

Terminal
# bin/setenv.sh
export JAVA_HOME=/usr/lib/jvm/temurin-21-jdk
export CATALINA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -Dfile.encoding=UTF-8"
export CATALINA_PID="$CATALINA_BASE/tomcat.pid"
  • CATALINA_OPTS applies only to the Tomcat server process. Use it for heap size, GC and your own -D properties.
  • JAVA_OPTS applies to the server and to the helper commands (stop, version, configtest), which are also Java processes. Putting -Xmx2g there makes even version reserve a large heap, so avoid it for memory settings.
  • CATALINA_PID names a file where the process id is written; scripts use it to stop a hung server.

On Windows the same file is bin\setenv.bat with set "CATALINA_OPTS=-Xmx2g".

What "stop" actually does

shutdown.sh is a small Java client. It opens a TCP connection to the shutdown port (8005 by default, on localhost), sends the text from the shutdown attribute of the <Server> element (SHUTDOWN by default) and disconnects. The server, which has a thread waiting on that port, receives the string, compares it and begins an orderly stop: connectors stop accepting, in-flight requests finish, applications are undeployed in turn.

This explains a security rule: the default string is public knowledge, so keep the port bound to localhost (the default) or set the port to -1 to disable it, and then stop the server with signals (SIGTERM, as systemd does) instead.

The stand-in reproduces the protocol with a server socket on a free loopback port:

Java The shutdown port protocol (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Graceful stop: finish what is running

When the stop begins, requests already running should be allowed to finish within a limit. The stand-in below uses an ExecutorService the way a connector's worker pool behaves: shutdown() refuses new work, awaitTermination waits for running tasks, and shutdownNow() interrupts what remains after a timeout.

Java Graceful shutdown of a worker pool (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In Tomcat the equivalent limits are the unloadDelay of a context (how long to wait for servlets to finish) and the connector's own shutdown behavior; the stop <seconds> argument of catalina.sh controls how long the script waits for the JVM to exit.

Running as a service

Linux (systemd). A unit file runs Tomcat in the foreground-style with a PID file and restarts it if it dies:

INI
# /etc/systemd/system/tomcat.service
[Unit]
Description=Apache Tomcat
After=network.target

[Service]
Type=forking
User=tomcat
Group=tomcat
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment=CATALINA_PID=/opt/tomcat/tomcat.pid
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then sudo systemctl daemon-reload, sudo systemctl enable --now tomcat and journalctl -u tomcat for troubleshooting.

Windows. bin\service.bat install registers a service called Tomcat10 using the bundled tomcat10.exe (procrun). tomcat10w.exe //ES//Tomcat10 opens a settings window for JVM options and the service account.

Docker. The official image's command is catalina.sh run, so logs go to the container's standard output.

Common mistakes

  • Starting with startup.sh in a container: the script returns immediately and the container exits. Use catalina.sh run.
  • Putting memory flags in JAVA_OPTS, which also inflates the stop helper.
  • Using kill -9 as the routine stop; sessions and applications cannot clean up.
  • Leaving the shutdown port reachable from other machines.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which catalina.sh command keeps Tomcat in the foreground and prints logs to the console?

    run is ideal for containers and debugging; start forks into the background and writes to catalina.out.
  2. 2. Where should you set the Tomcat heap size permanently?

    setenv.sh is sourced by the launcher; CATALINA_OPTS affects only the server JVM.
  3. 3. What does shutdown.sh send to the shutdown port?

    The client connects to the port and sends the configured command string; the server then stops in an orderly way.
  4. 4. How can you disable the shutdown port?

    With -1 no socket is opened; you then stop Tomcat with signals such as SIGTERM, which systemd uses.

Summary

  • catalina.sh (run, start, stop, configtest, version, jpda) is the real launcher; startup and shutdown are shortcuts.
  • Put JVM settings into bin/setenv.sh: CATALINA_OPTS for the server, CATALINA_PID for the PID file.
  • Stopping works through a secret string sent to the shutdown port; guard or disable that port.
  • Stop gracefully so in-flight requests can finish.
  • Use systemd, service.bat or catalina.sh run in Docker to make Tomcat start with the machine.

Next: WAR files and the webapps folder