Working with mod_jk

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

Table of Contents

• What is mod_jk?
• Why mod_jk?
• What does it mean to me?
• Definitions and Terminology
• Obtaining mod_jk
  • mod_jk Binaries
  • Building mod_jk
  • Building mod_jk for NT
  • Building mod_jk for Unix
• Configuring Apache
  • Removing mod_jserv directives
  • Configuring Apache to use mod_jk
  • Assigning URLs to be redirected to Tomcat
• Configuring Tomcat
  • Enabling Tomcat's Apache Auto-Config
  • Configuring Tomcat to use the AJPv13 Protocol
  • Defining Workers
• Example Configuration
• Troubleshooting and F.A.Q's
• Credits

What is mod_jk?

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.

Why mod_jk?

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.

What does it mean 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 Apache and other web servers, such as Microsoft's Internet Information Server (IIS) and the iPlanet Enterprise Web Server.

Definitions and Terminology

In this document I am going to use a few terms, so let's define them:
 

Obtaining 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.

mod_jk Binaries

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 Release at http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3/bin/ contains the following:
 

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.

Building mod_jk

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.

Building mod_jk for NT

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:

1. Change directory to the apache1.3 or apache2.0 source directory depending on your version of Apache.
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\Debug or APACHE1_HOME\src\Release (or the older APACHE1_HOME\src\CoreD or APACHE1_HOME\src\CoreR) directories before linking will succeed. You will need to build enough of the Apache source to create the required librarie(s).

4. 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.

Building mod_jk for Unix

Apache

1. 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.
2. 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.
3. Make sure you have Perl 5 installed. The apxs script used to build the module is written in Perl.
4. 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:

   1. 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.3.1; 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"

   2. 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

      ---

      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):

      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!.

5. 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.

Configuring Apache

This section details the configuration that is required for the Apache Web Server to support mod_jk.

Removing mod_jserv directives

Configure Apache to use mod_jk

Assigning URLs to Tomcat

JkMount <URL prefix><Worker name>

Configuring Tomcat

Enabling Tomcat's Apache Auto-Config

(Optional) Configuring Tomcat to use the Ajpv13 protocol

(Optional) Defining "workers"

Configuring workers manually.

Example Configuration

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, this form virtual host setup is new in Tomcat 3.3 and later - this example won't work with Tomcat 3.2 and earlier..
 

Troubleshooting and F.A.Q.s

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/tomcat-3.3-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://www.mail-archive.com/tomcat-user@jakarta.apache.org/ or http://mikal.org/interests/java/tomcat/index.jsp 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 with the binary distribution, 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 do two mod_jk.so files exist (-eapi ad -noeapi) in download dir for Linux ?

A. Many versions of Apache use a modified API, known at Extended API. For example, Apache using mod_ssl and the Apache present in certain recent Linux distributions. So if you have an 'Extended Apache', you need to use mod_jk.so-eapi, and use mod_jk.so-noeapi for standard Apache. It's wise to avoid using EAPI modules on standard API Apache and standard API modules on EAPI Apache. Always 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, such as Apache-mod_ssl or Apache from Redhat distro 6.2/7.0. However, your system is using the standard Apache with the 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 are trying 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.

Q. Why doesn't my form authentication work? I'm getting similar error messages from Apache:

Credits

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!
 

相关资料：

jkmount不转发php等

<VirtualHost *:80> 
    DocumentRoot "/webapps/WZBIZ_V10"  
    ServerName www.****.com  
    ServerAlias ****.com  
    ErrorLog "logs/****.com-error_log"  
   <Directory "/webapps/WZBIZ_V10"> 
        Options FollowSymLinks  
        AllowOverride None  
        Order deny,allow  
        Allow from all  
    </Directory> 
    JkMount /dwr/* tomcat01  
    JkMount /* tomcat01  
    DirectoryIndex index.html  
</VirtualHost> 

相关连接：

tomcat.apache.org/connectors-doc/