JSP Quick-Start Guide for Linux

Linking Apache and Tomcat with mod_jk

Now that you've got Apache and Tomcat running side by side, you need to link them together so that Apache can process JSP requests by handing them off to Tomcat. There are actually several ways to do this, and all involve installing an Apache module. The first option is to use mod_jk, which was designed specifically for Tomcat 3.x to work with various servers and uses a fairly efficient protocol for communication with Tomcat.

As of Tomcat 4.0, a new mechanism for linking Apache and Tomcat is available: mod_webapp. This Apache module provides efficient communication between Apache and Tomcat, and is exceedingly easy to configure. Unfortunately, the developer in charge of mod_webapp has some pretty strong feelings against Windows, so mod_webapp does not work reliably on that platform. Rather than use a different module for each platform, I prefer to stick with mod_jk on both Windows and Linux. That way I know I've got a solution that works, whatever platform I need for a particular job.

A revamped implementation of mod_jk called mod_jk2 is available as of Tomcat 4.1. It was written to be more modular, offer better performance, and improve the ease of configuration. Unfortunately, documentation on mod_jk2 is still a little sketchy; therefore, mod_jk is the module we'll install in this article.

The Elusive mod_jk

mod_jk comes in two parts: a connector plug-in for Tomcat and an Apache module. The connector plug-in is included with every copy of Tomcat 4.1. The other half of the equation, the Apache module, is a different story.

Because Apache 2.0 is in a constant state of flux, older versions of the mod_jk module will usually not be compatible with newer versions of Apache 2.0. In general, you need a copy of mod_jk that was compiled after the Apache 2.0 release you want to use it with. The Jakarta team always tries to maintain a downloadable copy of mod_jk that is compatible with the latest Apache 2.0 release on their Web site.

At this time, the latest release of mod_jk is available from http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.2/bin/linux/i386/. The file is called mod_jk-2.0.43.so to signify that it was compiled to work with Apache 2.0.43 (it will also work with 2.0.44). Download the file, rename it to mod_jk.so, and copy it to the modules subdirectory of your Apache 2.0 installation (/usr/local/apache2/modules).

With the Apache module installed and the Tomcat plug-in built into the server, we must now configure both Apache and Tomcat to use mod_jk to communicate with each other.

Configuring Tomcat

Now we need to configure Tomcat to use mod_jk. Locate the server.xml file in the conf subdirectory of your Tomcat directory and open it in a text editor of your choice.

Immediately following the <Server port="8005" ...> tag near the top of the file, add the following:

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig"    
 modJk="/usr/local/apache2/modules/mod_jk.so" jkDebug="info"    
 workersConfig="/usr/local/tomcat/conf/jk/workers.properties"    
 jkLog="/usr/local/tomcat/logs/mod_jk.log" />

Be sure to replace the paths in bold with those on your system if they differ.

About halfway through the file, find the <Host name="localhost" ...> tag and add the following immediately after it:

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig"    
 append="true" />

Close server.xml, then create a new directory called jk in that same directory (conf). This directory is where we'll create the workers.properties file mentioned in the first <Listener> tag above. Open up your text editor again and type (or copy) in the following:

workers.tomcat_home=/usr/local/tomcat    
workers.java_home=$(JAVA_HOME)    
workers.th=$(workers.tomcat_home)    
ps=\    
worker.list=ajp13, ajp14    
worker.ajp13.port=8009    
worker.ajp13.host=localhost    
worker.ajp13.type=ajp13    
worker.ajp13.lbfactor=1    
worker.ajp14.port=8010    
worker.ajp14.host=localhost    
worker.ajp14.type=ajp14    
worker.ajp14.secretkey=secret    
worker.ajp14.credentials=myveryrandomentropy    
worker.ajp14.lbfactor=1    
worker.loadbalancer.type=lb    
worker.loadbalancer.balanced_workers=ajp13    
worker.inprocess.type=jni    
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)tomcat.jar    
worker.inprocess.cmd_line=start    
worker.inprocess.jvm_lib=$(workers.th)$(ps)jre$(ps)bin$(ps)classic$(ps)jvm.dll    
worker.inprocess.stdout=$(workers.th)$(ps)logs$(ps)inprocess.stdout    
worker.inprocess.stderr=$(workers.th)$(ps)logs$(ps)inprocess.stderr

Be sure to adjust the tomcat_home line (shown in bold) to match your system. Save the file as workers.properties in your newly-created jk directory.

Restart Tomcat. If you haven't missed any steps, it should automatically create another directory in its conf directory called auto with a file called mod_jk.conf inside it. This file contains everything that Apache needs to know to use Tomcat to process JSPs.

Configuring Apache

Because Tomcat generates all the configuration information for Apache automatically as mod_jk.conf, all we need to do is point Apache at that file! Open your Apache 2.0 configuration file (/usr/local/apache2/conf/httpd.conf) in a text editor. Scroll down about 1/4 of the way through the file to find the section entitled Dynamic Shared Object (DSO) Support. After the LoadModule lines that appear below this heading, add the following line (adjusted to match your Tomcat directory):

Include "/usr/local/tomcat/conf/auto/mod_jk.conf"

With that line added to httpd.conf, save your changes and restart Apache (apachectl graceful). You should now get the same page whether you load http://localhost:8080/examples/jsp/ (from Tomcat), or http://localhost/examples/jsp/ (from Apache).