Connecting Apache's Web Server to Multiple Instances of Tomcat

Learn how to use mod_jk to forward requests to specific hosts when more than one Tomcat instance is running.

Recently, I was asked to reorganize some of our Web applications to improve their stability. The major push was to get each of our applications running in its own instance of Tomcat. These applications all are in various stages of development, and if a single instance allocates all of the memory available, the entire Tomcat server must be restarted. This, in turn, brings down all of the other applications.

An obstacle to running multiple instances is each instance would have to run on a unique port. Enter Apache's Web server. With the use of mod_jk, we were able to forward requests to specific hosts and contexts to the respective running instance of Tomcat.

Pulling all of this together was not the hardest thing I've done; however, it did prove challenging due to a lack of documentation. By no means, though, is this statement a stab at any of the development teams. In fact, the developers themselves helped me on numerous occasions when I found myself in over my head. When the documentation had me confused or I could not find exactly what I was looking for, I would head over to #tomcat or #apache on and pose my question there. Usually, I received a response within minutes.

The following software was used for the purposes of this article. See the resources section at the end of this article for download locations:

  • J2sdk1.4.2_09

  • Tomcat 5.0.28

  • Apache 2.0.54

  • mod_jk 1.2.14

I am certain some of you are wondering why I used the Java software development kit (SDK) rather than the Java runtime environment (JRE). The answer is simple: Tomcat requires tools.jar to compile JSP pages, and tools.jar is provided in the SDK. If you do not wish to use the SDK, you need to place tools.jar in $CATALINA_HOME\common\lib.


For the purposes of this article, I assume that you already have Apache, Java and Tomcat installed. With all of the software listed above installed, except mod_jk, let's set up our environment.

In order for Tomcat to start, you need to set two environment variables, JAVA_HOME and CATALINA_HOME. JAVA_HOME should point to the J2sdk installation directory, and CATALINA_HOME should point to the installation directory for Tomcat. To make life easier, I have placed the following lines in /etc/bashrc:

export JAVA_HOME=/usr/java/j2sdk1.4.2_09
export CATALINA_HOME=/opt/tomcat 

Notice that I have set CATALINA_HOME to /opt/tomcat. Although this is the case, /opt/tomcat actually is a symlink to /opt/jakarta-tomcat-5.0.28. Although you can tell which version of Tomcat you have installed by running $CATALINA_HOME/bin/ version, I prefer to be able to note the version immediately by looking at the installation directory.

Before we dive into compiling mod_jk, I would like to dispel some confusion I came across while working on this project. Specifically, the confusion centers around the myth that bigger is better. In the world of Tomcat connectors, there exists mod_jk and mod_jk2. In my mind mod_jk2 was the logical choice, as it had a higher version number. After a bit of probing and inquiring, however, I discovered that mod_jk2 is deprecated--it is no longer being developed. Unfortunately for me, I had invested several hours in getting mod_jk2 to work when I discovered this fact. Hopefully, you will have saved yourself some time by reading this article.

Compiling, Installing and Configuring mod_jk

Open a terminal and change directories to the location where you have saved the mod_jk source. See the Resources section at the end of this article for the download link. In the terminal window, extract the source archive and install with the following four lines:

tar -xzvf jakarta-tomcat-connectors-
cd jakarta-tomcat-connectors-
./configure --with-axps=/usr/sbin/axps 
make && make install

The --with-axps=/usr/sbin/apxs configuration option allows us to build Apache modules without requiring the Apache source. If all goes well, you should see a message near the end informing you of the location of the libraries. On my distribution, it is /usr/lib/httpd/modules.

With mod_jk installed, we must now configure Apache to load the module by editing httpd.conf. httpd.conf is located in /etc/httpd/conf on my system. Configuring Apache to load mod_jk is a simple two-line step:

#Load the mod_jk connector LoadModule jk_module

A mistake I initially made was naming the module mod_jk, as in LoadModule mod_jk /usr/lib/httpd/modules/ The above command is certain to make Apache complain and refuse to start. With that said, it is a good idea to start or restart Apache now to verify that it can load the newly compiled module. If Apache starts without a problem, it is safe to continue.

Setting Up Multiple Tomcat Instances

Multiple Tomcat instances are possible to create with the use of the CATALINA_BASE environment variable. Each instance uses a common binary distribution but uses its own conf, webapps, temp, logs and work directories. Each instance also has its own JVM and, thereby, its own memory pool. If you have defined the maximum memory to be 512MB via JAVA_OPTS, each instance will attempt to allocate a maximum of 512MB.

Let's proceed now to set up these directories. As I mentioned before, Tomcat is installed in /opt/tomcat. To keep things somewhat organized, I created the following folders in /opt: /opt/tomcat_instance1, /opt/tomcat_instance2 and /opt/tomcat_instance3. It probably is more appropriate, however, to name these folders based on their purposes or applications. Remember that each of the three folders will contain conf, webapps, temp and work directories.

Configuring the First Instance

Tomcat uses a server.xml configuration file to determine the ports, connector engines and various other "server" configuration options. We are going to copy the installed server.xml from $CATALINA_HOME/conf/server.xml to /opt/tomcat_instance1/conf/server.xml. While we are at it, we might as well copy $CATALINA_HOME/con/server.xml to /opt/tomcat_instance2/conf/server.xml and /opt/tomcat_instance3conf/server.xml as well.

Tomcat also uses a global web.xml file. By global, I mean it is used for each instance. The web.xml file provides the default configuration for each Web application running under the given instance. If an option is not defined in the individual Web application, the default web.xml option is used. We can copy $CATALINA_HOME/conf/web.xml to /opt/tomcat_instance1/conf, /opt/tomcat_instance2/conf and /opt/tomcat_instance3/conf.

Now we must make some edits to server.xml. First, we need to disable the Coyote connector. To do this, we comment out the Coyote connector information. This is an XML file, so it uses the same comment syntax as HTML. After we are done commenting out the the connector, it should look something like this:

  <Connector port="8080"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               debug="0" connectionTimeout="20000"
               disableUploadTimeout="true" />

Because this is the first running instance, we do not need to modify any more of this file. For subsequent instances, we are required to change the shutdown port and the AJP connector port. The AJP connector port is the port that Apache uses to forward requests.

Next, copy the servlets-examples file provided with the installation of Tomcat from $CATALINA_HOME/webapps/servlets-examples to /opt/tomcat_instance1/webapps/servlets-examples. Again, copy the sample application to /opt/tomcat_instance2/webapps and /opt/tomcat_instance3/webapps as well. At this point, the set up of tomcat_instance1 is complete. We now need to set up the second and third instances before we pull it all together.

Configuring the Second Instance

We already copied server.xml from the installation directory. We now need to make the same edit to /opt/tomcat_instance2/conf/server.xml as we did for the first instance. That is, comment out the Coyote connector exactly as we did above.

Additional required edits are to change the SHUTDOWN port from 8005 to 8105. We must change the port from 8005 because the first instance already is using it. You can change the second instance's port to be any unused port above 1024, but for simplicity and organization's sake, let's use 8105. Here is the line as it should be in the file:

<Server port="8105" shutdown="SHUTDOWN" debug="0">

Now we must change the AJP connector from 8009 to 8109. Again, this is required because the first instance already is using 8009. Below is the line to change with the required edit:

    <Connector port="8109"
	enableLookups="false" redirectPort="8443" debug="0"
      protocol="AJP/1.3" />

If you are using SSL, you also should change the redirectPort to the appropriate SSL port that Apache is listening on, normally 443.

Configuring the Third Instance

We need to make the same edits to /opt/tomcat_instance3/conf/server.xml as we did for the second instance, except we substitute 8205 for 8005 and 8209 for 8009. In case this does not make sense, here are the respective sections of server.xml:

<Server port="8205" shutdown="SHUTDOWN" debug="0">

    <Connector port="8209"
	enableLookups="false" redirectPort="8443" debug="0"
      protocol="AJP/1.3" />

Configuring mod_jk

mod_jk uses a file named I recommend placing this file with the rest of your Apache configuration files. is used to define where Apache looks for the Tomcat instances. Here, I cover only the items we are going to use for the three instances we have set up. Below is the file we are going to use, followed by an explanation of the options:

# Set properties for worker1
# Set properties for worker2
# Set properties for worker3

worker.list is a comma-separated list of worker names. You could have Tomcat workers defined later in the file that will not be used. Any worker defined is not used unless the worker is listed in the worker.list value. Workers are defined in format of worker.NAMEOFWORKER.type, with the value being the type of connector. All of our workers are of type ajp13. In the above example, we have defined three workers: worker1, worker2 and worker3.

You may have noticed the host portion of the configuration. This can be used to configure Apache to forward to Tomcat instances on separate machines. In fact, this is an option that one might choose to employ in order to make a site more secure. Because Tomcat and Apache both reside on the same machine, we use localhost.

Each worker also needs to define the port on which the connector is configured to work. If you remember, earlier we configured instance1 to listen on port 8009, instance2 to listen on port 8109 and instance3 to listen on port 8209.

Configuring Apache with mod_jk

To get all of this started, we need to tell Apache where to find the file and where to log mod_jk requests. We also need to specify the format of the log files and the options specific to mod_jk. I did this by adding the following lines to httpd.conf; I placed all mod_jk configuration directives just before the virtual host declarations:

JkWorkersFile "/etc/httpd/conf/"
JkLogFile     "/var/logs/www/mod_jk.log"
JkLogLevel  info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkOptions     +ForwardKeySize +ForwardURICompat -ForwardDirectories
JkRequestLogFormat     "%w %V %T"

The above options tell Apache to use /etc/httpd/conf/ for the worker definitions and to use the /var/logs/www/mod_jk.log log file. If you are experiencing trouble with mod_jk, adjust the JkLogLevel to "debug" in order to get more verbose messages. JKLogStampFormat and JkRequestLogFormat define the logging formats. The option ForwardKeySize instructs mod_jk to forward the SSL key size along with the request. ForwardURICompat instructs mod_jk to forward the URL to Tomcat normally. -FowardDirectories instructs mod_jk not to return a directory listing from Tomcat.

Configuring Apache to Forward

We use domain1, domain2 and domain3 as our virtual hosts. To pull this off, we also have to edit /etc/hosts to ensure that domain1, domain2 and domain3 are resolved properly. To do this, we make three VirtualDirectory declarations, each corresponding to a worker defined in Below is the VirtualHosts section, followed by an explanation of the options.

<VirtualHost *:80>
    ServerName domain1
    JkMount  /servlets-examples/* worker1
<VirtualHost *:80>
    ServerName domain2
    JkMount  /servlets-examples/* worker2
<VirtualHost *:80>
    ServerName domain3
    JkMount  /servlets-examples/* worker3

Configuring the Instances to Start at Boot

Now that we have most of the configuration complete, it is time to set up the instances to start at boot. This partially is done by creating a bash script and placing it in /etc/init.d. I used the start-up script found here.

# tomcat        
# chkconfig: 
# description:  Start up the Tomcat servlet engine.

# Source function library.
. /etc/init.d/functions

export CATALINA_BASE="/opt/tomcat_instance1"
export CATALINA_HOME="/opt/tomcat"

case "$1" in
        if [ -f $CATALINA_HOME/bin/ ];
            echo $"Starting Tomcat"
            /bin/su tomcat $CATALINA_HOME/bin/
        if [ -f $CATALINA_HOME/bin/ ];
            echo $"Stopping Tomcat"
            /bin/su tomcat $CATALINA_HOME/bin/
        echo $"Usage: $0 {start|stop}"
        exit 1
exit $RETVAL

Copy the contents above and place them in /etc/init.d/tomcat_instance1, /etc/init.dtomcat_instance2 and /etc/init.d/tomcat_instance3. Be sure to change CATALINA_BASE to the appropriate directory for each script. Now, we need to link to these in /etc/rc5.d. To create the symlinks, issue the following as root:

cd /etc/rc5.d
ln -s /etc/init.d/tomcat_instance1  S71tomcat_service1
ln -s /etc/init.d/tomcat_instance2 S71tomcat_service2
ln -s /etc/init.d/tomcat_instance3 S71tomcat_service3

Testing the Setup

With all of our configuration complete, it now is time to test our setup. We begin by starting Apache or restarting if it already is running. Next, bring up the first instance:

/etc/init.d/httpd stop
/etc/init.d/httpd start
/etc/init.d/tomcat_service1 start

Now, open a browser window and go to http://domain1/servlets-examples/. If all goes well, you should see something similar to Figure 1.

Figure 1. Checking Your Setup

If you do not see a page similar to the above, look in the log files. Specifically, check /var/logs/httpd/mod_jk.log and /opt/tomcat_instance1/logs/catalina.out for any errors that may have occurred.

If everything looks correct, go ahead and start the remaining two contexts:

/etc/init.d/tomcat_instance2 start
/etc/init.d/tomcat_instance3 start

Point your browser to http://domain2/servlets-examples and http://domain3/servlets-examples. You should see the exact same page for all three instances.

To make things a bit more clear and to verify that we are hitting the correct instance, we can modify a line in /opt/tomcat_instance2/webapps/servlets-examples/index.html and /opt/tomcat_instance3/webapps/servlets-examples/index.html. The line to modify in both files is:

<b><font face="Arial, Helvetica, sans-serif"><font size=+2>Servlet
Examples with Code</font></font></b>

For the second instance, we want the line to read as follows:

<b><font face="Arial, Helvetica, sans-serif"><font size=+2>Domain 2 Servlet
Examples with Code</font></font></b>

Make a similar modification to the third instance:

<b><font face="Arial, Helvetica, sans-serif"><font size=+2>Domain 3 Servlet
Examples with Code</font></font></b>

If you now point your browser to http://domain2/servlets-examples and http://domain3/servlets-examples, you should see Domain 2 and Domain 3 at the beginning of the respective page.


Hopefully this HOWTO has given you a step-by-step understanding of what it takes to get multiple instances of Tomcat running when Apache is the front-end. Many more options are available that would produce similar setups. You could, for example, use Apache as a front-end and load balance between several servers running Tomcat. See the documentation for mod_jk for more information about the available options.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Hi, I'm doing this on Windows

Andy J's picture

I'm doing this on Windows XP. I had the 1st instance working and I then proceeded to set up other Tomcat instances. They didn't work so I backtracked and now I can't get a single instance to work.

The error is in the mod_jk log:

(worker1) connecting to backend failed. Tomcat is probably not started or is listening on the wrong port (errno=61)

worker1) connecting to tomcat failed.

The tomcat port in question is 8009, and I can telnet into that and it IS listening. Tomcat is running fine: I reenabled http port 8080 and can access the webapp that way, but just not through apache.

I've disabled Windows firewall. No difference.

And the frustrating thing is I did have it working (for a single instance) earlier on!

Can anyone suggest a way forward? I seem to have tried everything at this point. Thanks in advance.

thanks for the article, I am

Shriram's picture

thanks for the article, I am doing all the steps right but when I start tomcat_instance1 it gives me ClassNotFoundException.

Any help will much be appreciated.

Both tomcat using different JDK

Darshan Joshi's picture

Hi Daniel,
Excellent article indeed - very helpful.

I want to achieve same thing but configuration is little different.

My 1st tomcat (tomcat1) is version 3.x and 2nd tomcat (tomcat2) is version 6.x - no problem there. But tomcat1 needs jdk 1.4.2 whereas tomcat2 need jdk 1.5.

How do I configure this in - I mean to my understanding the directive workers.tomcat_home and workers.java_home can only be used once.

Please help!!

Does mod_jk handle faulty app running on any of the tomcat insta

Anonymous's picture

Does mod_jk handle faulty app running on any of the tomcat installations. Meaning while forwarding the requests from apache to tomcat does it take into consideration and not forward any requests to a faulty instance of tomcat?
Any comments are highly appreciated..!!

How can we handle request if we are using .htaccess file

Anonymous's picture

How can we handle request if we are using .htaccess file and most of the domain have same name
for domain1
RewriteRule ^([/]?)$ /
RewriteRule ^/student([/]?)$ /domain1/student/main_content/

for domain2
RewriteRule ^([/]?)$ /domain1.html
RewriteRule ^/student([/]?)$ /domain2/student/main_content/

if we type the url

which domain will we accessed?


Anonymous's picture

Thank you for the excellent article.I was trying to achieve the same thing with Apache and JBoss, and had almost given up when I came across your article.Now I am successfully able to run multiple instances of JBoss with Apache as front end.
Thanks again.


Great Article !!!

Map007's picture


I have done same thing and its working fine.But i have que.

I have single site i.e., and at a time 400-600 users are logged in. Now i want to setup 2 tomcat with single apache. and do load balancing with apache. If users will come more then 300 the other request will transfer to second tomcat. So please guide me how can i do this.

Thank you.

Multiple tomcat's in a shared environment

oliveirad's picture

Due the diferences from the 5.0 to the 5.5 tomcat version, this article as delivered a easy way to configure multiple tomcat servers in a shared environment, which saved loads of working hours.

Nice article.


Nice article

Anilkumar BVN's picture

I have been struggling for days to setup the multiple tomcat instances with apache jk mod. This article made it an hour's job for me. Thanks a lot Daniel for such a good article.

Anilkumar BVN

ajp port specified is in use

Sebas's picture


I have configured 2 tomcat instances in this way and using ajp13 to connect apache2 to tomcat5, but now i have the following problem. Tomcat 1 started in ajp port 8009 as ussual, since we are stopping and starting the tomcat every day, a few days ago Tomcat 1 started in 8010 instead of 8009, in the catalina.out appear a info saying that the 8009 is bussy and started in 8010. At the time of the restart any other service or Tomcat was using this port, so Im assuming that when was stopped the socket 8009 was not correctly free and when started again encountered the port in use. Now every day is starting in 8010 since 8009 appear always in use. The stop and Start is separated by arround 10 minutes of the delay (stop at 2.15 am and start 2:25 am every day)

This caused that the connector doesn’t work anymore since is configured to use 8009.

I would like to know if exist any chance to prevent this problem or force to free the socket initiated by ajp13 Tomcat config.

Many thanks

Apache and Tomcat running on different servers

TheSearcher's picture

I am looking at doing something similar, but want to run the Tomcat on different servers. Can anyone point me to the changes I would need to make to this example or refer me to some additional HOWTO's.


howto secure cross tomcat instance connections

beri's picture


I use a similar setup with multiple instances of Tomcat (5.5.25) on the same server.
In fact, I have a couple of Apache+ Tomcat instances running, each pair of Apache and Tomcat using another user account. Tomcat (5.5.25) is connected to its Apache (2.0.59) via mod_jk (1.2.25). Users have ssh-access to their own Apache + Tomcat configuration. The problem is, that users could access another Tomcat instance not owned by themselves by simply challenging the port-number tomcat is running on.

For this to avoid I tried to use the "secret"-directive in the files and the server.xml of tomcat:
request.useSecret="true" request.secret="12345678"

But I got the following error:
org.apache.jk.common.ChannelSocket processConnection
WARNING: processCallbacks status 2

Without secret, the connection works fine.

Do you have any hints on this?

Awesome tutorial

The Relentless's picture

I was able to use this tutorial to get tomcat 5.5 and 6 running on the same windows server. Thanks.

Simply Gr8 Explanation ....

Anonymous's picture

Simply Gr8 Explanation ....

Disable selinux first!!!

Lou's picture

Great tutorial. Old, but still very relevant today. I just did it today on Redhat enterprise 5. Dan T's comments helped too.

One word of warning:

Be sure to disable selinux before trying this... if it's in "enforcing" mode, you're in for a lot of wasted hours debugging and tearing your hair out (like I did today).

apache tomcat on different machines

Anonymous's picture

Although Im able to use the mod_jk when tomcat and apache webserver on the same machine (localhost) but when apache web server and tomcat are on different machines...i cannot access the jsp applications on the other machines..Im using apache 2.0.54 and tomcat 5.5.3 on fedora 4 and RHEL3 respectively. Could anyone point me to some good howtos

my email id is


Multiple tomcat instances in windows OS

Anonymous's picture

This article is nice, however I am using a windows xp, so i think there are something different. can anyone provide a guideline to create multiple tomcat instances on windows os?? thanx in advance.

Multiple instance using the same domain

Anonymous's picture

This article is well written and I could not locate the answer for the multiple instaces using the same or single domain as I want to do the same hee too. With once instance I have problem when the users grow more than 700. The tomcat hangs and throws error. I would appreciate the help. My box is DL385 dual core 2.4 GHz OPTERON with 16 GB RAM. This box contains apache 2.0.54, tomcat 5.5.9 and Mod_jk 1.2.15.

Muliple tomcat instances using the same domain

Shaun's picture

I am trying to get servlets-examples working on my two instances of tomcat.
I can get different apps working in each instance (quarantine rather than load balancing) and assign different application names using mod_jk without a problem.
I cannot get servlets-examples working in each one though even when I rename the app in the second instance to be different.
I need to ensure that running this config will not hurt me in the future before taking it into production.
Can anyone help me out with advice on ensuring servlets will work in all instanxces running in the same single host under apache connecting to multiple Tomcat instances set up as described in this article. Only difference is I am running on Windows2000 Server.


VirtualHosts problem

Dan T's picture

This is not so much a comment but a request for help. I did everything in the article and it all *almost* works. One thing that I did differently was I did NOT comment out the Coyote connector for each instance, I just made sure that it was on different ports for each. This allows you to access the page directly through tomcat to troubleshoot problems. This came in handy later as we shall see.

After I put in the VirtualHost directives and restarted Apache, I got this warning:
[warn] _default_ VirtualHost overlap on port 80, the first has precedence

And going to
http://domain1/servlets-examples/ and
shows the exact same page, even though I made them different.
(I am only working with two instances, not 3 as in the article).
However, going through tomcat (http://localhost:8881/servlets-examples and http://localhost:8882/servlets-examples) shows the differences.

So I thought perhaps that warning meant that one of my virtual host directives was being ignored. So I changed the syntax of the virtual host directives; instead of:

I changed them both to:

This time when restarting apache I did not get any warnings. However, I had the same problem--only the first declared virtual host content was being served, regardless of which domain name I used in the browser.

One other thing to bear in mind is that my domain names are just alias es for localhost ( in /etc/hosts. Could that bear on the problem at all?

If anyone can help out, please let me know. If the solution works I will post a comment here describing it.

My email is:
dan punctuation1 dandante punctuation2 com

solved it

Dan T's picture

The solution was to uncomment the NameVirtualHost line in httpd.conf, and change the virtual host lines back to:
<VirtualHost *:80>


Dan T's picture

My comment should read that I changed the VirtualHost line from:
<VirtualHost *:80>
<VirtualHost *>


Very good article indeed. I

Paralikar's picture

Very good article indeed. I gone through other article too, but this was the best one. Here I would like to know few more things.

1) How do we shut down each instance, if we are not using it in services. As such when I put the script in the /etc/init.d it gives me following error: "/bin/su: user tomcat does not exist".

2) Can we control all the instances using the same Tomcat Admin / Manager panel? If yes, how?

3) We have a single application which has to be served using multiple instances. How can it be done? As per your current setup guide, it will configured as one instance one application.

Appreciate your help in this regards.


Larry Morroni's picture

This article is a dead ringer for the problem I was having. I run a small ISP and need to be able to support multiple instances of Tomcat. Your article helped fill in the gaps I found in the tomcat documentation.

Starting tomcat as normal user

Gaël Lams's picture

Really interesting and usefule article.

I just wanted to add that I had to setup other instances those days and I wanted to start Tomcat with a normal "tomcat" user. In this case, you need to slightly modify the init scripts (and the folders permissions) with the following lines:
su - tomcat -c 'export CATALINA_BASE="/opt/jakarta/tomcat-test" && export CATALINA_HOME="/opt/jakarta/tomcat" && CATALINA_HOME/bin/'


someone's picture

To use 'apxs' you need to have the package 'httpd-devel'. My Fedora 3 did not come with this package, and I had problems compiling the mod_jk module.

I think you have 'axps' missp

Newbie's picture

I think you have 'axps' misspelled. It should be apxs.


Use a reverse proxy instead?

MarkM's picture

What is the advantage of doing this versus simply using a reverse proxy as implemented in Apache?

Because of worker.type=lb

Anonymous's picture

Because ProxyPass and ProxyPassReverse do not know about multiple tomcat instances that are in a load balancing environment, so that the hits on the same session are constantly sent to the same tomcat node.