Working with mod_jk

By Gal Shachor < shachor@il.ibm.com>

What is mod_jk

mod_jk is a replacement to the elderly mod_jeserv. It is a completely new Tomcat-Apache plugin that passed adaptation to Tomcat. With some luck working with it is going to be simpler for everyone.

Why mod_jk?

Several reasons:

mod_jserv was too complex because it supported Jserv specific requirements that Tomcat does not pose.
mod_jserv supported only Apache; on the other hand Tomcat supports many web servers through a compatibility layer named the jk library. Supporting two different modes of work became problematic in terms of support, documentation and bug fixes. mod_jk should fix that.
The layered approach provided by the jk library makes it easier to support both Apache1.3.x and Apache2.xx.

What does it means to me?

You will need to get to know a new simplified configuration mechanism. The advantage is that learning this mechanism will give you a head start if you want to deploy Tomcat on other web servers such as IIS and Netscape (oops, iPlanet).

Configuring Apache to use mod_jk

The configuration includes the following steps:

Remove your old mod_jserv configuration. mod_jk and mod_jserv cannot coexist !!
Obtaining mod_jk
Defining workers for mod_jk (or selecting the quick start option)
Configuring Apache to use mod_jk and configure mod_jk internals (or selecting the quick start option)
Assigning URLs to be redirected to Tomcat (or selecting the quick start option)

Obtaining mod_jk

There are no prebuilt mod_jk distribution for now, so you will need to build it yourself.

On NT

The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want to perform a custom build.

The steps that you need to take are:

Change directory to the apache1.3/apache2.0 source directory.
Execute the following command:
MSDEV mod_jk.dsp /MAKE ALL
If msdev is not in your path, enter the full path to msdev.exe
Copy mod_jk.dll to Apache's modules directory.

This will build both release and debug versions of the redirector plugin (mod_jk).

An alternative will be to open mod_jk.dsp in msdev and build it using the build menu.

On UNIX

For apache1.3

Change directory to the apache1.3/ apache2.0 source directory.
Use apxs in the following manner:
apxs -o mod_jk.so -c *.c ../jk/ *.c -I ../jk/
Copy mod_jk.so to Apache's libexec directory

Quick start?

In most of simple cases Tomcat can generate the needed Apache configuration. When Tomcat starts up it will automatically generate a configuration file for Apache inTOMCAT_HOME/conf/mod_jk.conf-auto. Most of the time you don't need to do anything but include this file (appending "Include TOMCAT_HOME/conf/mod_jk.conf-auto") in your httpd.conf. That’s it, you can now start Tomact and Apache and access Tomcat from the Apache server.

If you have special needs, for example mounting URL prefixes that are not the default, you can use this file as a base for your customized configuration and save the results in another file. If you manage the Apache configuration yourself you'll need to update it whenever you add a new context.

Tomcat 3.2: you must restart tomcat and apache after adding a new context; Apache doesn't support configuration changes without a restart. Also the file TOMCAT_HOME/conf/mod_jk.conf-auto is generated when tomcat starts, so you'll need to start Tomcat before Apache. Tomcat will overwrite TOMCAT_HOME/conf/mod_jk.conf-auto each startup so customized configuration should be kept elsewhere.

Definitions and terminology

During this document I am going to use a few terms, so lets define them:

Term	Meaning
Worker process	A worker is a tomcat instance that is running to serve servlet requests coming from the web server. In most cases there is only a single worker (the one and only tomcat process) but sometimes you will run multiple workers to achieve load balancing or site partitioning. Each worker is identified to the web server by the host were it is located, the port where it listens and the communication protocol used to exchange messages.
In process worker	This is a special worker. Instead of working with a Tomcat process residing on another process, the web server opens a JVM and executes Tomcat inside the web server process address space. Our discussion in this document is not going to get into this special worker.
Web server plugin/tomcat redirector	For Tomcat to cooperate with any web server it needs an "agent" to reside in the web server and send him servlet requests. This is the web server plugin, and in our case the web server plugin is mod_jk. The redirector usually comes in the shape of a DLL/shared object module that you should plug into the web server.
Plugin configuration	We need to configure the web server plugin so that it will know where are the different Tomcat workers and to which of them it should forward requests. This information accompanied with some internal parameter such as the log level comprises the plugin configuration.
Web server configuration	Each web server has some configuration that defines how behave, e.g. on which port to listen, what files to serve, what web server plugins to load, etc. You will need to modify your web server configuration to instruct it to load the tomcat redirector.

Configuring workers

Workers are configured using the file workers.properties, look into the workers.properties howto document for further documentation.

Configure Apache to use mod_jk

Configuring Apache to use mod_jk is done using the Apache server configuration directives; to assist you in your first steps, please take a look into the auto-generated mod_jk.conf-auto available in Tomcat's conf directory.

You will need to instruct Apache to load Tomcat. This can be done with Apache's LoadModule configuration directive.
You must inform mod_jk the location of your workers.properties file. Use mod_jk's JkWorkersFile configuration directive.
You should specify a location where mod_jk is going to place its log file and a log level to be used. Use the JkLogFile and JkLogLevel configuration directives. Possible log levels are debug, warn, error and emerg, but warn should be your default selection.

That's it. Now you should assign URLs to be redirected to Tomcat.

Assigning URLs to Tomcat

Use mod_jk's JkMount directive to assign specific URLs to Tomcat. In general the structure of a JkMount directive is:

JkMount <URL prefix> <Worker name>

For example the following directives will send all the .jsp suffixed requests to localworker, but jsp requests to files located in /otherworker will go to remoteworker. Additionally any requests prefixed by /servlet/ will go to localworker

JkMount /*.jsp localworker
JkMount /otherworker/*.jsp remoteworker
JkMount /servlet/* localworker

You should of course adjust the mounts points to reflect your own topology.

Running Apache with Tomcat

That's it; you are done. You should now be able to start Tomcat and apache and have tomcat and apache cooperate to serve servlets and JSP files.