By Gal Shachor <shachor@il.ibm.com>
Table of Contents
mod_jk is a replacement to the elderly mod_jserv. It is a completely new
Tomcat-Apache plug-in that handles the communication between Tomcat and Apache.
Several reasons:
- mod_jserv was too complex. Because it was ported from Apache/JServ, it
brought with it lots of JServ specific bits that aren't needed by Apache.
- mod_jserv supported only Apache. 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.
- Better support for SSL. mod_jserv couldn't reliably identify whether a
request was made via HTTP or HTTPS. mod_jk can, using the newer Ajpv13 protocol.
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 Apache and other web servers, such as Microsoft's
Internet Information Server (IIS) and the iPlanet Enterprise Web Server.
In this document I am going to use a few terms, so let's 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 Plug-in/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 plug-in, and in our case the web server plug-in is
mod_jk. The redirector usually comes in the shape of a DLL or shared object
module that you plug into the web server.
|
Plug-in Configuration
|
We need to configure the web server plug-in so that it
knows where the different Tomcat workers are and to which of them it should
forward requests. This information, accompanied with some internal parameter,
such as the log level, comprises the plug-in configuration.
|
Web Server Configuration
|
Each
web server has some configuration that defines its behavior, e.g. on
which port to listen, what files to serve, what web server plug-ins to
load, etc. You will need to modify your web server configuration to
instruct it to load the Tomcat redirector mod_jk.
|
mod_jk can be obtained in two formats - binary and source. Depending on
the platform you are running your web server on, a binary version of mod_jk may
be available. It is recommended to use the binary version if one is
available. If the binary is not available, follow the instructions for
building mod_jk from source. Notes at the end of this section offer
recommendations for specific platforms.
Binaries for mod_jk are available for several platforms in the same area as
the Tomcat Binary Release. The binaries are located in subdirectories by platform. For some
platforms, such as Windows, this is the typical way of obtaining mod_jk since
most Windows systems do not have C compilers. For others, the binary
distribution of mod_jk offers simpler installation.
For example, the Tomcat 3.3 M1 Release at http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3-m1/bin/
contains the following:
linux/i386/ |
Contains mod_jk.so for Apache 1.3 for the standard API as
well as EAPI and mod_jk.so for Apache 2.0 |
netware/ |
Contains the mod_jk.nlm and nsapi.nlm |
win32/ |
Contains the mod_jk.dll for Windows as well as other useful
binaries. |
Check the site for the latest binaries.
Note: The version of mod_jk is not dependent on the version of Tomcat.
The Tomcat 3.3 distribution of mod_jk will function correctly with other 3.x
versions of Tomcat, such as Tomcat 3.2.1.
mod_jk is available in source distribution for all Windows and most Unix
platforms. The source for mod_jk is included in the Binary Distribution of
Tomcat in the TOMCAT_HOME/native/mod_jk/ directory. This directory is
organized by Web Server name and version. Each directory contains the
source as well as the appropriate build scripts, make files, or project files.
The redirector was developed using Visual C++ version 6.0, so having this
environment is a prerequisite if you want to perform a custom build.
The steps that you need to take are:
- Change directory to the apache1.3 or apache2.0 source directory depending
on your version of Apache.
- Set an APACHE1_HOME environment variable which points to where your Apache is
installed.
- 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.
- Copy mod_jk.dll to Apache's modules directory.
This will build both release and debug versions of the redirector plug-in (mod_jk).
An alternative will be to open mod_jk.dsp in msdev and build it using the build
menu.
Apache
- Make sure your Apache has DSO support. You can check this
with $APACHE_HOME/bin/httpd -l. If you see
"mod_so.c" in the output, DSO support is available. If it's
missing, you may have to recompile or reinstall Apache.
- Find out whether your Apache has EAPI support. If you
compiled it yourself from source, EAPI is probably not compiled
in, unless you added it yourself (perhaps with mod_ssl). You
need to build mod_jk.so with or without EAPI to match your
Apache configuration. If you install a mismatched mod_jk.so,
$APACHE_HOME/bin/apachectl configtest will warn
you.
- Make sure you have Perl 5 installed. The apxs
script used to build the module is written in Perl.
- Change directory to TOMCAT_HOME/native/mod_jk/apache1.3 (or
apache2.0).
-
Build mod_jk.so. Following are three techniques you can try,
in order of simplicity:
- Run the build script for your platform. If a build script is
not available for your platform, you may be able to build mod_jk using ./build-unix.sh. This script will set some variables, call
apxs as below, and try to copy mod_jk.so to
$APACHE_HOME/libexec. If it fails, you need to do
the following manually:
- set JAVA_HOME in your shell, e.g. "set
JAVA_HOME=/usr/local/jdk1.2.2; export
JAVA_HOME"
- set APACHE_HOME in your shell, e.g.
"set APACHE_HOME=/usr/local/apache;
export APACHE_HOME"
- uncomment the following line in the
build-unix.sh file,
replacing "linux" with the name of your
platform as specified in the
Java include directory for your installation
# JAVA_INCLUDE="-I
${JAVA_HOME}/include -I
${JAVA_HOME}/include/linux"
- If build-unix.sh fails, you may have better luck
with the Makefiles in the same directory, e.g.
"make -f Makefile.linux mod_jk.so"
-
Finally, you can try to build it manually. Run the
apxs command that came with your apache
distribution (hint: look in /usr/local/apache/bin,
/usr/sbin, or wherever you installed apache). Type the
command all on one line.
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.
For Solaris:
Use the build-solaris.sh script as follows:
# sh build-solaris.sh
This will build and install mod_jk.so in your apache/libexec
directory. This script contains settings for your Java and Apache
home locations. Make sure that these are set according to your
installation. The default settings are JAVA_HOME=/usr/java and
APACHE_HOME=/usr/local/apache. If your installation is different,
you will need to edit the build-solaris.sh script and change these
values appropriately.
See README.solaris located in TOMCAT_HOME/native/mod_jk/apache1.3
for more information.
If the build script does not work, you can also build mod_jk as
follows:
$APACHE_HOME/bin/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 HP-UX 11.00:
Use the build-hpux.sh script as follows:
# sh build-hpux.sh
This will build and install mod_jk.so in your apache/libexec
directory. This script contains settings for your Java and Apache
home locations. Make sure that these are set according to your
installation. The default settings are JAVA_HOME=/opt/java1.3 and
APACHE_HOME=/usr/local/apache. If your installation is different,
you will need to edit the build-hpux.sh script and change these
values appropriately.
Also note that there are two HP-UX build scripts. One script
was written to build mod_jk without JNI support using GNU GCC. The
other script builds mod_jk with JNI support, however, this script
requires the HP ANSI C Compiler (not the stripped down C compiler
included with HP-UX to rebuild the kernel). The HP Compiler is
required because the dlopen() and related shared libraries are only
available for 64-bit applications and reliable 64-bit compilation is not
available with the current version of GCC.
The build-hpux.sh script should also work for HP-UX 10.00.
See README.hpux located in TOMCAT_HOME/native/mod_jk/apache1.3
for more information.
For other Unixes (including FreeBSD):
You may need to replace fdatasync() with fsync() in jk_util.c.
The build-hpux-cc.sh script should be modifiable for IRIX and AIX.
Edit the script and change the APACHE_HOME and JAVA_HOME locations as
required.
If you are using EAPI, try adding
-DEAPI to the apxs command after
mod_jk.so.
If apxs fails with apxs:Break: Command failed
with rc=255
, it may have been damaged by
mod_ssl. Search for:
my $CFG_LD_SHLIB = q(); # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(); # substituted via Makefile.tmpl
and change to:
my $CFG_LD_SHLIB = q(ld); # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(-G); # substituted via Makefile.tmpl
If you've installed Java in another directory,
adjust accordingly.
For other Unixes you should be able to work it out,
but remember that the order of the arguments to
apxs is important!.
- Now, copy the mod_jk library. # cp mod_jk.so $APACHE_HOME/libexec. (Note that
the build scripts attempt to do this, but you may have to
su first.)
Other Webservers
There are several Makefiles in the other directories under the TOMCAT_HOME/native/mod_jk/
directory. You should also check the Tomcat documentation for specific
information related to other web servers.
This section details the configuration that is required for the Apache Web
Server to support mod_jk.
If you've previously configured Apache to use mod_jserv, remove any ApJServMount directives from your httpd.conf. If you're including tomcat-apache.conf or tomcat.conf, you'll want to remove them as well - they are specific to
mod_jserv. The mod_jserv configuration directives are not compatible with
mod_jk!
The simplest way to configure Apache to use mod_jk is to turn on the Apache
auto-configure setting in Tomcat and put the following include directive at the
end of your Apache httpd.conf file (make sure you replace TOMCAT_HOME with the
correct path for your Tomcat installation:
Include TOMCAT_HOME/conf/jk/mod_jk.conf-auto
Example:
Include /usr/local/jakarta-tomcat/conf/jk/mod_jk.conf-auto
This will tell Apache to use directives in the mod_jk.conf-auto file
in the Apache configuration. This file is created by enabling the Apache
auto-configuration as described in the configuring Tomcat section below [Configuring
Tomcat].
NOTE: If you plan to use the Tomcat-Apache auto-configuration, skip
the rest of this section and continue with the Configuring Tomcat
section.
Custom configurations can be created by enabling the auto-configuration and
copying the TOMCAT_HOME/conf/jk/mod_jk.conf-auto file to your own
configuration file, such as TOMCAT_HOME/conf/jk/mod_jk.conf-local.
The basic configuration is as follows:
- 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, info,
error and emerg, but info should be your default
selection.
- The directive JkLogStampFormat will configure the date/time format
found on mod_jk logfile. Using strftime() format string it's set by
default to "[%a %b %d %H:%M:%S %Y] "
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 info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
If you have created a custom or local version of mod_jk.conf-local
as noted above, you can change settings such as the workers or URL prefix.
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.
In most simple cases Tomcat can generate the needed Apache configuration. You
can configure Tomcat so that when it starts up it will automatically generate
a configuration file for Apache to use mod_jk.
Most of the time you don't need to do anything but
include this file (appending "Include TOMCAT_HOME/conf/jk/mod_jk.conf-auto")
in your httpd.conf, as shown in the previous section (Configuring
Apache).
To configure Tomcat to generate the Apache auto-configuration add the following block to your TOMCAT_HOME/conf/server.xml file after <AutoWebApp ... />.
<ApacheConfig />
That's it, you can
now start Tomcat and Apache and access Tomcat from the Apache server.
Note: Settings for mod_jk auto-configuration is new in Tomcat 3.3.
Older versions of Tomcat create the auto-config file without a directive in
server.xml. The new directive in Tomcat 3.3 allows for additional
configuration options as detailed later in this section. For older
versions of Tomcat, refere to the documentation that came with that version.
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.
Note that 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/jk/mod_jk.conf-auto is generated when
tomcat starts, so you'll need to start Tomcat before Apache. Tomcat will
overwrite TOMCAT_HOME/conf/jk/mod_jk.conf-auto each startup so
customized configuration should be kept elsewhere. For example, copy
TOMCAT_HOME/conf/jk/mod_jk.conf-auto to TOMCAT_HOME/conf/jk/mod_jk.conf-local
before making changes. You'll need to startup Tomcat once to generate
this file with your configuration for the first time.
It is also possible to specify the location of the auto generated files by
setting options in the <ApacheConfig /> block. The following details
the syntax:
< ContextManager ... >
...
<ApacheConfig options />
...
< /ContextManager >
where options can include any of the following attributes:
- confighome - default parent directory for the following paths. If
not set, this defaults to TOMCAT_HOME. Ignored whenever any of the following
paths is absolute.
- jservconfig - path to write apache jserv conf file to. If not set,
defaults to "conf/jserv/tomcat-apache.conf".
- jkconfig - path to write apacke mod_jk conf file to. If not set,
defaults to "conf/jk/mod_jk.conf".
- workersconfig - path to workers.properties file used by mod_jk. If
not set, defaults to "conf/jk/workers.properties".
- modjserv - path to Apache JServ plugin module file. If not set,
defaults to "modules/ApacheModuleJServ.dll" on windows,
"modules/Jserv.nlm" on netware, and "libexec/mod_jserv.so"
everywhere else.
- modjk - path to Apache mod_jk plugin file. If not set, defaults to
"modules/mod_jk.dll" on windows, "modules/mod_jk.nlm" on
netware, and "libexec/mod_jk.so" everywhere else.
- jklog - path to log file to be used by mod_jk.
Example:
...
<AutoWebApp dir="webapps" host="DEFAULT" />
<ApacheConfig confighome="/home/mydir" />
...
mod_jk can use either the original Ajpv12 protocol or the newer Ajpv13 protocol.
Both protocols are enabled by default. The "Ajp13" Connection Handler in Tomcat will
give you the benefit of a faster protocol and the ability to identify requests made via HTTPS.
The following block enables Ajpv13 in your
TOMCAT_HOME/conf/server.xml file.
<RequestInterceptor
className="org.apache.tomcat.modules.server.Ajp13Interceptor"
port="8009"/>
The server.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.
Configuring workers manually.
Workers are configured using the file TOMCAT_HOME/conf/jk/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.
Here's an example configuration which probably reflects many real-world setups. A site
is using Tomcat and Apache with two virtual hosts (one of them using HTTPS as well, which
we're assuming is being handled by mod_ssl).
URLs ending in .jsp and beginning with /servlet are handled by Tomcat, the rest are
handled by Apache. The files for each Host are server out of /web/host1 and /web/host2
respectively.
The example are over-simplified and incomplete but should get you started. Also note the
virtual host setup is new in Tomcat 3.2 -
this example won't work with Tomcat 3.1.
.
.
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port" value="8007"/>
</Connector>
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
<Parameter name="port" value="8009"/>
</Connector>
<Host name="host1.apache.org">
<Context path="" docBase="/web/host1" debug="0"/>
</Host>
<Host name="host2.apache.org">
<Context path="" docBase="/web/host2" debug="0"/>
</Host>
.
.
|
Table 1 - Excerpt from server.xml showing the Ajp13 Connector and two virtual
hosts.
# Setup for Solaris system
#
workers.tomcat_home=/usr/local/jakarta-tomcat
workers.java_home=/usr/java
ps=/
worker.list=ajp12, ajp13
# Definition for Ajp13 worker (Ajp12 left to readers imagination)
#
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
|
Table 2 - Excerpt from workers.properties showing the Ajp13 worker
# Load mod_jk
#
LoadModule jk_module libexec/mod_jk.so
AddModule mod_jk.c
# Configure mod_jk
#
JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
JkLogFile /usr/local/apache/logs/mod_jk.log
JkLogLevel info
# First Virtual Host.
#
<VirtualHost 10.0.0.1:80>
DocumentRoot /web/host1
ServerName host1.apache.org
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13
</VirtualHost>
# Second Virtual Host. Also accessible via HTTPS
#
<VirtualHost 10.0.0.2:80>
DocumentRoot /web/host2
ServerName host2.apache.org
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13
</VirtualHost>
<VirtualHost 10.0.0.2:443>
DocumentRoot /web/host2
ServerName host2.apache.org
SSLEngine On
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13
</VirtualHost>
|
Table 3 - Excerpt from Apaches httpd.conf showing JK directives.
Q. Where can I get help/support for mod_jk?
A. The primary mechanism for support is through the Tomcat Documentation
included in the TOMCAT_HOME/doc directory. These documents are viewable
via browser through Tomcat
http://localhost:8080/doc/index.html.
Documentation is also available on the Apache Jakarta web site for Tomcat at
http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/index.html.
For additional help, the best resource is the Tomcat Users Discussion
list. You should start by searching the mail list archives located at http://mikal.org/interests/java/tomcat/index.html
before you post questions to the list. If you are unable to locate the
answer to your question in the archive, you can post questions about Tomcat or
mod_jk to the user list for assistance. Make sure that you include the
version of Apache and Tomcat that you are using as well as the platform you are
running on. http://jakarta.apache.org/site/mail.html
Q. I can't find mod_jk anywhere. Where is it?
A. Starting with Tomcat 3.3, the source for mod_jk is included in the native/mod_jk
directory. You can also download the Source Distribution of Tomcat to
obtain the source for mod_jk, which is how it was obtained in versions prior to
Tomcat 3.3. The Binary Distributions of mod_jk are available at the same
location as the Binary Distribution of Tomcat. The mod_jk binaries are
located in subdirectories by platform.
But in May 2001, the jakarta-tomcat-connectors was started and you'll find here
up to date featured mod_jk (ie: new protocols AJP14/WARP)
Q. Which protocol should I use? Ajp12 or Ajp13?
A. Ajp13 is a newer protocol, it's faster, and it works better with SSL. You almost
certainly want to use it. There is more information in the
workers.properties howto document.
Q. Whenever I restart Tomcat, Apache locks up!
A. The Ajp13 protocol keeps an open socket between Tomcat and Apache. The latest
release of mod_jk (the one found since Tomcat 3.3-m2 and J-T-C) handle the network failure.
But with previous release of mod_jk, you may have to restart Apache as well.
Q. Why did exist two files mod_jk.so (-eapi ad -noeapi) in download dir for Linux ?
A. Many versions of Apache use of modified API, known at Extended API. For example,
Apache using mod_ssl or Apache present in certains recent Linux distributions.
So if you got such 'Extended Apache', you need to use mod_jk.so-eapi, or use
mod_jk.so-noeapi for standard Apache. It's wise to avoid using EAPI modules on STD API Apache or to use standard
API modules on EAPI Apache. Allways be sure to have the mod_jk.so for your version of Apache
Q. What's that message about 'garbled DSO ?'
A. It's related to Apache EAPI, the message 'mod_jk.so is garbled - perhaps this is not an Apache module DSO ?'
just told you are trying to install a mod_jk.so DSO module that was compiled on an Apache using EAPI,
like apache-mod_ssl or apache from Redhat distro 6.2/7.0 but your system use the standard apache
with normal API.
Q. And the message about 'module might crash under EAPI! '
A. Also related to EAPI, the message '[warn] Loaded DSO /usr/lib/apache/mod_jk.so uses plain Apache 1.3 API,
this module might crash under EAPI! (please recompile it with -DEAPI)', the mod_jk.so was compiled under normal
Apache with standard API and you try to install the module on an Apache using EAPI.
Q. Where can I get more information?
A. The
workers.properties howto document has
considerably more in-depth information than this one, and is worth a look. You could
also try searching the mailing list archives for "mod_jk" or look at the source.
Q.
APXS is getting an error during the build of mod_jk, like rc=0 or rc=255.
I tried all of the steps in the build section, what do I do now?
A. APXS is a Perl script that is created when you build the Apache web server
from source. Chances are that if you are getting these errors and you
obtained Apache as a binary distribution, that APXS is not configured correctly
for your system. Your best bet is to get the Apache source from
http://httpd.apache.org
and build it yourself. Use the following for a basic build (read the
Apache docs for other options):
# cd /usr/local/src
# gzip -dc apache_1.3.19.tar.gz|tar xvf -
# cd apache_1.3.19
# ./configure --prefix=/usr/local/apache "
--enable-module=most "
--enable-shared=max
# make
# make install
Note: The above steps assume that you downloaded the Apache source and placed
it in your /usr/local/src directory.
This document was originally created by
Gal Shachor
Revisions by (Alphabetical)
Mike Braden <mikeb@mwbinc.com>
Mike Bremford
Chris Pepper
With help from countless others on the tomcat-dev and tomcat-user lists!
Copyright ©1999-2001 The Apache Software Foundation
Legal Stuff They Make Us Say
Contact Information