Monthly Archives: March 2014

Start Tomcat automatically on OS X using launchd

Using launchd with Tomcat

The Tomcat standalone distribution ships with Tomcat. There is a mismatch between how launchd expects a daemon to behave, and how the default startup scripts for Tomcat operate:

  • OS X’s launchd expects the process it starts to run forever, but ‘ start‘ starts the JVM to run Tomcat and then exits.
  • Tomcat provides ‘ stop‘ to shut down Tomcat cleanly by connecting to a socket which Tomcat listens on, but launchd stops daemons by sending them a signal that kills the process immediately if no specific handling is included.

You will need a wrapper shell script and properties list to make launchd work with Tomcat.

Step 1. Add a Wrapper Shell Script

Add the following wrapper shell script to $CATALINA_HOME/bin:
function shutdown()
        echo "Shutting down Tomcat"
        $CATALINA_HOME/bin/ stop
echo "Starting Tomcat"
export CATALINA_PID=/tmp/$$
# Uncomment to increase Tomcat's maximum heap allocation
# export JAVA_OPTS=-Xmx512M $JAVA_OPTS
. $CATALINA_HOME/bin/ start
# Allow any signal which would kill a process to stop Tomcat
echo "Waiting for `cat $CATALINA_PID`"
wait `cat $CATALINA_PID`


The above shell script starts Tomcat and then waits for the process to complete, so launchd is happy that Tomcat is still running. The script also installs a signal handler, which calls the shutdown() function to cleanly shut down Tomcat when launchd signals the script.

You can try this script manually: Start the script, watch Tomcat start, and then type ctrl-C and see Tomcat shut down cleanly. (Note that it will not shut down cleanly if Tomcat has not started yet. It takes a few seconds for Tomcat to start listening on the shutdown socket.)

Step 2. Add a launchd Property List

The launchd property list (.plist) tells launchd how to start Tomcat.

Add the following plist file to /Library/LaunchDaemons, which is the location for system-wide services which are not part of base OS X:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
<plist version="1.0">


  1. Replace ‘/Users/myname/conf/tomcat-6.0‘ with the path to your Tomcat installation. The string occurs four times in the above script.
  2. JAVA_HOME is set to use the default JDK. On OS X version 10.4.4, the default JDK is 1.4.2. You will need to change this value if you want to use a different version of Java. For example, if you want to use JDK 1.5, you will need to change JAVA_HOME to /System/Library/Frameworks/JavaVM.framework/Versions/1.5.
  3. In the above script, we have specified ‘root‘ as the UserName. If necessary, change the UserName to the user you want Tomcat to run as.

Starting and Stopping Tomcat Manually

To start and stop Tomcat manually, use the following commands:

  • Start:
    cd /Library/LaunchDaemons
    sudo launchctl load -w tomcat.plist
  • Stop:
    cd /Library/LaunchDaemons
    sudo launchctl unload -w tomcat.plist


  • Make sure both files and tomcat.plist have the necessary file privileges.
  • Check the console logging and log file for any abnormalities.