Configuring Tomcat5 and Apache2 with Virtual Hosts using mod_jk

Version 1.0

Author: C. Troy Popplewell

Visit the forums at .

Last edited: 02/10/2006


This tutorial explains how I was able to setup a web server in order to support Java Server Pages (JSP) and Servlets using virtually hosted websites. Although this setup worked for this particular environment, I can make no guarantees that it will work for yours, but it should with some tweaking. I’ll explain later on. I have spent a lot of time gathering several resources in order to get this to work. Many portions of these resources have been deprecated and required a few workarounds. It is my intention that this tutorial will help anyone that has attempted to install such a system without success. If you find any inconsistencies within this tutorial, please notify me at the email address above.


The ultimate goal is to provide instructions on how to incorporate JSP/Servlet support on the ISPConfig web hosting software. I felt it was necessary to provide this first segment separately for those that do not wish to use the ISPConfig web hosting control panel.

System Details

The system used in this tutorial has the following installed:

Operating System: Debian Sarge (3.1)

Webserver: Apache 2.0.54

JDK: JDK 5.0

Servlet Container: Tomcat

Tomcat Connector: Jakarta Tomcat Connector mod_jk (not mod_jk2)

Debian Sarge (3.1)

If you plan on utilizing ISPConfig to host your websites with Debian Sarge, I highly recommend the how-to provided by Falko Timme here: The Perfect Setup - Debian Sarge (3.1) which prepares your system to support ISPConfig. There are “Perfect Setup� tutorials for other distributions as well. Otherwise, you should be able to find many other resources on the internet for installing Debian. This tutorial is specifically based on configuring Apache and Tomcat to work on Debian using the mod_jk connector.


Since installing Apache is beyond the scope of this tutorial, I will assume that you already have Apache 2.0.x installed and running. If you need instructions on installing and configuring Apache 2.0.x please refer to the documentation at the Apache website. Again, you can also find instruction here: The Perfect Setup - Debian Sarge (3.1).

Installing JDK (Java Development Kit)

In order to run Tomcat, you will need to install JDK and set the JAVA_HOME environment variable to identify the location of the JDK environment on your system. I have chosen to use JDK 5.0.

  1. You can download JDK 5.0 at

  1. Click on Download JDK 5.0 Update 6 to go to the download page.

  1. Click Accept to accept the license agreement.

  1. Next choose the Linux self-extracting file. This is the download for the self-extracting binary file rather than the rpm.

  1. Download to your preferred download directory. Change to that directory and make it executable by executing the following command:

chmod +x jdk-1_5_0_06-linux-i586.bin

  1. Now execute the file:


  1. You should now have a new directory called j2sdk1.5-sun. Now move this directory to the location where it should be run. I chose /usr/lib/.

mv j2sdk1.5-sun /usr/lib

  1. Now create a symbolic link called jdk to JAVA_HOME by the following command. This allows you to easily switch back and forth between different jvms should you ever need to

cd /usr/lib

ln -s j2sdk1.5-sun jdk

  1. Now we need to set the JAVA_HOME environment variable. Add the following at the end of /etc/profile just after export PATH.


export JAVA_HOME

/etc/profile is executed at startup and when a user logs into the system. In order to update the environment you will need to log out and log back in to the system.

  1. Check to make sure JAVA_HOME is defined correctly by executing the command below. This should report the location of the Java SDK which should be /usr/lib/jdk.


  1. Now test Java with the following command. You should be returned with /usr/bin/java. If so, you have successfully completed this section.

which java

Installing Tomcat

In this section you will download and install Apache Tomcat 5.5.15. For this particular setup, there is no need to build the package from source, we will download the binary version.

  1. Download the binary version to your preferred download directory from here: Choose the tar.gz from the core section for 5.5.15.

  1. Now change to that directory and extract the files using the following command:

cd /mydownloads (be sure to change to your download directory)

tar xvzf apache-tomcat-5.5.15.tar.gz

  1. You should now have a new directory called apache-tomcat-5.5.15. Now move this directory to the location where it should be installed. Again, I chose /usr/lib/. Note that this location will be referred to as CATALINA_HOME in the Tomcat documentation.

mv apache-tomcat-5.5.15 /usr/lib

  1. Next change to the /usr/lib/ directory.

cd /usr/lib

  1. Now create a symbolic link called apache-tomcat to CATALINA_HOME by the following command.

ln -s apache-tomcat-5.5.15 apache-tomcat

This will save you from having to make changes to startup and shutdown scripts each time you upgrade Tomcat and if you so desire, it also allows you to keep several versions of Tomcat on your system and easily switch amongst them.

  1. You should now be able to start and stop Tomcat from the CATALINA_HOME/bin directory. If you are using another shell other than the bash shell you will nee to add sh to the beginning of the command. You should now be able to test that Tomcat is installed by starting it and opening your browser and entering http://localhost:8080 into your browser. Port 8080 is the default port for Tomcat and can be easily changed in the /usr/lib/apache-tomcat/conf/server.xml file. (We will work with this file later on.) If you plan to access this page remotely, be sure to forward the respective port to your server’s IP address within your router. You should now see the Tomcat welcome page that contains links to Tomcat documentation as well as sample JSP/Servlet scripts. Verify that Tomcat is running by executing some of the examples found on the welcome page.

cd /usr/lib/apache-tomcat/bin


To shutdown the server, you will need to execute the following command. Feel free to try it, but for now we will leave Tomcat running.


Share this page:

21 Comment(s)

Add comment


From: Anonymous at: 2006-02-13 23:23:05

Great article! It will be very helpful for those people using Apache and tomcat to handle JSP etc.

The newly released Apache server 2.2 includes AJP Proxy support by default and other new features, I haven't tried it, but I think it should ease the configuration bridging apache and tomcat using the jk module. maybe you can look into it and give us another wonderful HOWTO :)

thank you!

From: Anonymous at: 2006-03-06 07:10:09

The "Debian-way" of using the JVM would be to convert it to an deb first. This is very simple

apt-get install mpkg-j2sdk

Then simply

mpkg-j2sdk jdk-1_5_0_06-linux-i586.bin

afterwards you can install the correspondig deb by doing a

dpkg -i jdk...deb

From: Anonymous at: 2006-03-06 07:56:58

- JDK is not a requirement anymore, you only need JRE. From Tomcat web site:

"Tomcat 5.5 uses the Eclipse JDT Java compiler for compiling JSP pages. This means you no longer need to have the complete Java Development Kit (JDK) to run Tomcat, but a Java Runtime Environment (JRE) is sufficient. The Eclipse JDT Java compiler is bundled with the binary Tomcat distributions."

- One other thing that you should add in your howto is to configure Tomcat to run as a non-root user. The default is to run as root which is not secure, should tomcat be compromised, and not required, as tomcat listen to port 8080. You will find below an example of init.d file.





# tomcat This shell script takes care of starting and stopping

# tomcat.

# description: tomcat is a servlet/JSP engine, which can be used

# standalone or in conjunction with Apache


# Provides: Tomcat

# Required-Start: $local_fs $network $remote_fs apache2

# Required-Stop: $local_fs $network $remote_fs apache2

# Default-Start: 3 5

# Default-Stop: 0 1 2 6

# Short-Description: Tomcat

# Description: Tomcat



# See how we were called.

case "$1" in


# Start daemons.

echo -n "Starting tomcat: "

cd ~tomcat

su - tomcat -c '/opt/jakarta/tomcat/bin/ start'


[ $RETVAL -eq 0 ] && touch /var/lock/subsys/tomcat




# Stop daemons.

echo -n "Shutting down tomcat: "

cd ~tomcat

su - tomcat -c '/opt/jakarta/tomcat/bin/ stop'


[ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/tomcat




$0 stop

$0 start




echo "Usage: tomcat {start|stop|restart}"

exit 1


exit $RETVAL

From: Anonymous at: 2006-03-06 12:57:39

I appreciate your efforts and that you share your work with others.

But if you use Debian why don't you do things the Debian way and reduce your howto to around 5 "apt-get install" statements and a reference to /usr/share/doc/libapache2-mod-jk?


jan (yeah (ät) yeahrock (dot) de)

From: Anonymous at: 2006-03-06 20:59:17

mod_jk has a bevy of options that should, in general, be set in in order to tune the connection to Apache as well as Tomcat. By default it's pretty wide open as far as connections and timeouts are concerned; it's very easy for Apache to accept way, way way more load than Tomcat sitting behind it can handle. Here are some of the important ones I've found and what I typically set them to, the actual reading of the docs is left up to you. :)

# Specify the size of the open connection cache.
# below are in seconds

# Advanced ping-pong options
# 0 (full recovery)
# 1 (don't recover if tomcat failed after getting the request)
# 2 (don't recover if tomcat failed after sending the headers to client)
# 3 (don't recover if tomcat failed getting the request or after sending
# the headers to client).
# below are in milliseconds
# under load it can take awhile to get a reply when doing an initial JSP compile

From: noota at: 2006-10-27 09:46:32

great article, man! helped me a lot and the best thing is that it actually works)

From: at: 2007-07-17 19:14:16

Thank you for the very good article. Besides the valuable configuration hints you are providing I took benefit from the advanced worker properties posted by Anonymous on Mon, 2006-03-06 21:59.

 I want to add that for "heavy" load on the tomcat workers it can be necessary to increase to maximum amount of threads. I specifiied that in each of the server.xml of my tomcats

  enableLookups="false" redirectPort="8443" protocol="AJP/1.3"
  useBodyEncodingForURI="false" URIEncoding="UTF-8"
  maxThreads="350" minSpareThreads="25" maxSpareThreads="75" />
-Toddy (info (the-at) tinyimage (the-dot) com)

From: atc at: 2008-11-27 22:54:27
From: lwpro2 at: 2010-10-05 04:05:25

for me, the easy to overlook part is that, apache forward the request to tomcat ajp1.3 connector port 8009(by default), not the container service port 8080(most of the time).

 so should be carefully as,



From: Anonymous at: 2006-02-14 08:26:06

In step 6, the command should be

./configure --with-apxs=/usr/bin/apxs2

but not ./configure --with-apxs2=/usr/bin/apxs2

I've tried using the second one and ended in some very needless confusion down the road: "./configure" wasn't finished successfully with the the second one and complained that the "webserver" (parameter) is missing. But that should not be the case because we are configuring for a shared library, not a static one.

From: ctroyp at: 2006-02-24 21:02:30

Thanks for catching that.


From: Anonymous at: 2006-03-06 11:42:46

if you're on a RPM based distribution it is probably wise to stick to using RPMs, provides RPMs for all things java.

From: Anonymous at: 2006-03-30 19:22:14

Please Note that by default Ubuntu does not come with a C++ compiler (At least Hoary 5.04). It may be necessary to get it so that the ./ command doesn't bomb. you can get that using the command:
sudo aptitude install build-essential

From: Anonymous at: 2006-05-08 15:38:18

Your tutorial is really good, but on a debian (ubuntu) with jdk1.5 and apache2 you only need to do:

$ apt-get
install libapache2-mod-jk2

And then enable the mod_jk module with 2 symbolic
links on /etc/apache2/mod-enable

Thanks a lot for your work.

From: Anonymous at: 2006-07-18 12:41:16

mod_jk and mod_jk2 are two different connectors! As sarge only offers the deprecated mod_jk2 through the official repositories, you either have use or build mod_jk from the source.

From: at: 2007-09-19 10:49:21

I checked out the repository, and the version available now via the apt-get command is version JK NOT version jk2, so a simple

apt-get install libapache2-mod-jk

seems to work for me.

The version of debian under Ubuntu 7.04 is apparently debian 4.0 

From: Lalit Negi at: 2012-01-25 15:16:23


 I tried following all steps , on step 6 i got stuck , it always gives below error :

could not find /usr/bin/apxs2

configure: error: You must specify a valid --with-apxs path


I tried with other location of the apxs2 files like : 

/home/lnegi/SETUPS/apache2-threaded-dev_2.2.21-5_i386/usr/bin/apxs2 but get the same error everytime.


Kindly help.

From: Anonymous at: 2006-03-07 07:06:22

If you setup tomcat this way 1 tomcat to rule them all, every user can read another users home dir, isn't that a major security issue?

From: Anonymous at: 2006-04-07 08:15:42

It is not recommeded to place <Context> elements directly in the server.xml file. See

From: at: 2007-06-10 20:10:46

I get a "Useless use of AllowOverride" message when I start Apache2. I guess thats because the <LocationMatch> does now support AllowOverride option. Only <Directory> support it according to

From: Dan Kelleher at: 2011-11-01 20:02:46

The clearest and easiest to follow guide for mod_jk I found. Thanks very much.