Apache Tomcat on Linux - Installation and configuration on multiple platforms

Technically, Apache Tomcat is fully compatible with all major Linux distributions, and many users run Tomcat on Linux.  Despite this, many Linux users run into snags during the initial set up process.

Most Linux users are accustomed to differences between Linux distributions causing a process that works on one flavor to fail on another.  However, it can be hard to trace the actual source of the failure, as there are a number of factors other than differences between distributions that can cause problems.  For example, although most Linux distributions include a pre-configured Tomcat package in their repositories, these packages are often out of date or configured in such a way that certain web applications fail. 

In this article, we've rounded up a list of common errors and configuration quirks you might experience when installing Apache Tomcat on a number of major Linux distributions - DebianRed HatUbuntu, and Gentoo.

Basic Linux installation

Although different distributions will require slightly different configurations, these instructions describe the basic process for most flavors of Linux.

Before you begin, make sure your Java runtimes are up to date, and that you are running a version of Java high enough for the Tomcat distribution you are preparing to install.  You can download the latest version of the Java runtimes from Java.com.  

Be careful when using distribution-specific Java packages from repositories, as these can be prone to the same problems as other repackaged Java programs.

1 - Create a low privilege user

Running Tomcat as root introduces the unnecessary risk that a compromised Tomcat instance could yield control over your entire server.  Thus, creating a user with low privileges to run Tomcat should be standard practice when installing new instances.

Logged in as the root user, run the following command:

	# useradd -g 46 -s /sbin/nologin -d /opt/tomcat/temp tomcat

This command creates a new user named 'tomcat' belonging to the nobody group, with the /sbin/nologin/ shell and a locked password.

2 - Download the latest binary release

While there are a number of distribution-specific Tomcat packages available, the quality of these releases varies.  

Unless you are using one of the better maintained releases (for example, the Ubuntu/Debian package, which is maintained by MuleSoft's own Jason Brittain, author of O'Reilly's The Definitive Guide to Apache Tomcat and lead developer of Tcat), downloading the latest release directly from Apache is the only way to be sure that you are getting the latest bug and stability fixes.

The trade-off is that the installation may not be as tightly integrated into the system, and may require extra legwork to monitor or update (as opposed to executing a simple package manager command).

The latest stable release can always be found on the Apache Tomcat download page on Apache's website.

3 - Move distribution into place and uncompress

Next, copy Tomcat to the directory you want to install it in, and extract the package:

# cp apache-tomcat-6.x.x.tar.gz CurrentDirectory/NewHome

# cd $NewHome

# tar zxvf apache-tomcat-6.0.29.tar.gz

4 - Change permissions

Finally, change the permissions of the folder to allow the user you created to run Tomcat in step one to read and write to the folder (you'll need root access again):

# chown -R tomcat apache-tomcat-6.0.29


5 - Start Tomcat

You should now be able to start Tomcat from the command line by running startup.sh, the start script included with Tomcat, or by running catalina.sh with the 'start' parameter.

Platform specific instructions

Debian and Ubuntu Linux

The standard Linux installation instructions provided above can be used without modification to successfully install Tomcat on Debian or Ubuntu Linux.  

However, a number of quirks will affect a manual Debian/Ubuntu installation.  For example, Tomcat's STDOUT and STDERR logs will be appended to the main syslog, instead of appearing in Tomcat's default log file, 'catalina.out'.  

Also, as the Apache distributions of Tomcat include no Debian/Ubuntu-specific init script, a custom script must be written and installed if Tomcat needs to be run as a service. These are not big problems, but they can be a hassle.  

Although it is normally a good idea to avoid re-packaged versions of Tomcat from repositories, the Debian / Ubuntu package (they share the same upstream) is maintained by MuleSoft's own Jason Brittain, author of O'Reilly's Definitive Guide To Apache Tomcat.  

Thanks to Jason's work, most users should find that a simple 'apt get' command is now the easiest and best way to install Tomcat on the Debian and Ubuntu platforms.

Jason's package includes a custom init script that makes Tomcat restarts more reliable, and some custom Tomcat configurations that help users to avoid the most common problems with new manual installations, such as disabling the SecurityManager by default and fixing port binding issues.

If you'd like some more information about the package, Jason has written two in-depth blogs about his improvements, which you can read here and here on the MuleSoft blog.

Red Hat Linux

The standard Linux installation instructions provided above can be used without modification to successfully install Tomcat on Red Hat Linux.  

Although a Tomcat package is provided in the YUM repositories, it is not frequently updated, and so a manual installation is not recommended.

If you want to run Tomcat as a service, as with Debian and Ubuntu, you will need to write a custom init.d script, similar to the bare bones example below, and place it in Red Hat's "/etc/init.d" folder:



# tomcat        


# chkconfig: 

# description:  Start up the Tomcat servlet engine.

# Source function library.

. /etc/init.d/functions



case "$1" in


        if [ -f $CATALINA_HOME/bin/startup.sh ];


   echo $"Starting Tomcat"

           /bin/su -s /bin/bash tomcat $CATALINA_HOME/bin/startup.sh




        if [ -f $CATALINA_HOME/bin/shutdown.sh ];


   echo $"Stopping Tomcat"

            /bin/su tomcat $CATALINA_HOME/bin/shutdown.sh




  echo $"Usage: $0 {start|stop}"

exit 1



exit $RETVAL


Gentoo Linux

The standard Linux installation instructions provided above can be used without modification to successfully install Tomcat on Debian or Ubuntu Linux.  However, the installation will not comply with Gentoo / LHS standards.  

A distribution of Tomcat that splits Tomcat into multiple Gentoo-friendly pieces is available in the Gentoo repositories. Documentation is available on gentoo.org.  However, the guide has not been updated since 2007, so users should proceed with caution.

To install Tomcat from the Gentoo repositories, use the following command:

emerge tomcat

The Gentoo distribution includes a custom init script.  Once you have installed Tomcat, it can be started with the following command:

# /etc/init.d/tomcat-6 start


To enable Tomcat as a service, so that it automatically starts at boot time, use the following command:

rc-update add tomcat-6 default