Working with mod_jk

Binaries are available for Linux and Win32 under the bin directory where you obtained the Tomcat distribution file. For Linux, mod_jk is available as mod_jk.so. For Win32, mod_jk is available as mod_jk.dll. If there isn't a prebuilt mod_jk available or you wish to build your own copy, you can build it yourself from the source. First, download the Source Distribution for Tomcat. There are a large number of files in the download directory, but the only one you need is jakarta-tomcat.

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:

1. Change directory to the apache1.3/apache2.0 source directory.
2. Set an APACHE1_HOME environment variable which points to where your Apache is installed.
3. Execute the following command:
   
   MSDEV mod_jk.dsp /MAKE ALL
   
   If msdev is not in your path, enter the full path to msdev.exe. Also, ApacheCore.lib is expected to exist in the APACHE1_HOME\src\CoreD and APACHE1_HOME\src\CoreR directories before linking will succeed. You will need to build enough of the Apache source to create these libraries.
4. 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 Apache

1. Make sure you have Perl 5 installed. The apxs script used to build the module is written in Perl.
2. Change directory to jakarta-tomcat/src/native/apache1.3 (or apache2.0).
3. Run the apxs command that came with your apache distribution (hint: look in /usr/local/apache/bin, /usr/sbin, or wherever you intalled apache). Type the command all on one line.
   
   For Solaris:
   

   apxs -o mod_jk.so -DSOLARIS -I../jk -I/usr/java/include -I/usr/java/include/solaris -c *.c ../jk/*.c

   On some systems, this will build the module correctly, but will fail at runtime with a "symbol "fdatasync" not found". To fix, add -lposix4 just before the -c in the above command.
   
   For Linux:

   apxs -o mod_jk.so -I../jk -I/usr/local/jdk/include -I/usr/local/jdk/include/linux -c *.c ../jk/*.c

   Your build may fail because the object files from the ../jk directory have been compiled to the current directory, rather than their source directory. Running gcc -shared -o mod_jk.so *.o should finish the build.
   
   (If you've installed Java in another directory, adjust accordingly). For other *nixes you should be able to work it out, but remember that the order of the arguments to apxs is important!.
4. Copy mod_jk.so to Apache's libexec directory

For other Webservers

There are several Makefiles in the other directories under the jakarta-tomcat/src/native directory.

mod_jk can use either the original Ajpv12 protocol or the newer Ajpv13 protocol. If you choose the latter, you need to activate the "Ajp13" Connection Handler in Tomcat. This will give you the benefit of a faster protocol and the ability to identify requests made via HTTPS.

Add the following block to your TOMCAT_HOME/conf/server.xml file.

<Connector className="org.apache.tomcat.service.PoolTcpConnector">
  <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
  <Parameter name="port" value="8009"/>
</Connector>

The servlet.xml file already has a block similar to this for Ajp12 connections on port 8007 (as delivered by mod_jserv). Even if you think you're only using Ajp13, you probably don't want to delete this connector - it's required to shut down Tomcat.

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 in TOMCAT_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 Tomcat 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.

Workers are configured using the file TOMCAT_HOME/conf/workers.properties. There is a great deal of information in the workers.properties howto document, and you should really look at that first. If you're in a hurry however, you can probably get away with editing the file workers.properties and setting the workers.tomcat_home, workers.java_home and ps variables to the correct values for your system.

Configuring Apache to use mod_jk is done using the Apache server configuration directives; to get you started, look at 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 and AddModule configuration directives.
• 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.

A simple example would be to include the following lines in your httpd.conf file:

LoadModule    jk_module  libexec/mod_jk.so
AddModule     mod_jk.c
JkWorkersFile /usr/local/jakarta-tomcat/conf/workers.properties
JkLogFile     /usr/local/apache/logs/mod_jk.log
JkLogLevel    warn

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 requests ending in .jsp or beginning with /servlet to the "ajp13" worker, but jsp requests to files located in /otherworker will go to "remoteworker".

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

You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file.