larryi 01/03/15 08:23:18
Modified: src/doc mod_jk-howto.html
Log:
Reogranized to group Apache configs together and Tomcat configs together.
Updates to the <ApacheConfig ... /> documentation.
Info added for Solaris and hp-ux scripts.
Links added to FAQ.
Includes changes submitted by: Chris Pepper
Submitted by: Mike Braden
Revision Changes Path
1.6 +462 -186 jakarta-tomcat/src/doc/mod_jk-howto.html
Index: mod_jk-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/mod_jk-howto.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- mod_jk-howto.html 2001/03/14 07:31:42 1.5
+++ mod_jk-howto.html 2001/03/15 16:23:12 1.6
@@ -1,7 +1,7 @@
<html>
<head>
<!-- $Id $ -->
- <!-- Copyright 1999, Apache Software Foundation -->
+ <!-- Copyright 2001, Apache Software Foundation -->
<meta http-equiv=Content-Type content="text/html">
<link rel="stylesheet" href="style.css">
@@ -58,24 +58,39 @@
<li><a href="#s3">Why mod_jk?</a></li>
<li><a href="#s4">What does it mean to me?</a></li>
<li><a href="#s5">Definitions and Terminology</a></li>
-<li><a href="#s6">Configuring Apache to use mod_jk</a>
+<li><a href="#s6">Obtaining mod_jk</a>
+ <ul>
+ <li><a href="#s61">mod_jk Binaries</a></li>
+ <li><a href="#s62">Building mod_jk</a></li>
+ <li><a href="#s63">Building mod_jk
+ for NT</a></li>
+ <li><a href="#s64">Building mod_jk
+ for Unix</a></li>
+ </ul>
+</li>
+<li><a href="#s7">Configuring Apache</a>
<ul>
-<li><a href="#s61">Removing the mod_jserv directives</a></li>
-<li><a href="#s62">Obtaining mod_jk</a></li>
-<li><a href="#s63">Configuring Tomcat to use the Ajpv13 protocol</a></li>
-<li><a href="#s64">Defining workers for mod_jk</a></li>
-<li><a href="#s65">Configuring Apache to use mod_jk</a></li>
-<li><a href="#s66">Assigning URLs to be redirected to Tomcat</a></li>
+<li><a href="#s71">Removing mod_jserv directives</a></li>
+<li><a href="#s72">Configuring Apache to use mod_jk</a></li>
+<li><a href="#s73">Assigning URLs to be redirected to Tomcat</a></li>
</ul></li>
-<li><a href="#s7">An example configuration</a></li>
-<li><a href="#s8">Troubleshooting and F.A.Q's</a></li>
-<li><a href="#s9">Credits</a></li>
+<li><a href="#s8">Configuring Tomcat</a>
+ <ul>
+ <li><a href="#s81">Enabling Tomcat's Apache Auto-Config</a></li>
+ <li><a href="#s82">Configuring Tomcat to use the
+ AJPv13 Protocol</a></li>
+ <li><a href="#s83">Defining Workers</a></li>
+ </ul>
+</li>
+<li><a href="#s9">Example Configuration</a></li>
+<li><a href="#s10">Troubleshooting and F.A.Q's</a></li>
+<li><a href="#s11">Credits</a></li>
</ul>
<hr>
<h2><a name=s2>What is mod_jk?</a></h2>
<p>mod_jk is a replacement to the elderly mod_jserv. It is a completely new
-Tomcat-Apache plugin that handles the communication between Tomcat and Apache</p>
+Tomcat-Apache plug-in that handles the communication between Tomcat and Apache.</p>
<hr>
<h2><a name=s3>Why mod_jk?</a></h2>
@@ -99,13 +114,13 @@
<p>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).</p>
+want to deploy Tomcat on Apache and other web servers, such as Microsoft's
+Internet Information Server (IIS) and the iPlanet Enterprise Web Server.</p>
<hr>
-<h2><a name=s5>Definitions and terminology</a></h2>
+<h2><a name=s5>Definitions and Terminology</a></h2>
-<p>During this document I am going to use a few terms, so lets define them:</p>
+<p>In this document I am going to use a few terms, so let's define them:</p>
<table class=inlinetable>
<tr>
@@ -118,7 +133,7 @@
</tr>
<tr>
<td class=inlinetd>
- <p>Worker process</p>
+ <p>Worker Process</p>
</td>
<td class=inlinetd>
<p>A worker is a tomcat instance that is running to serve
@@ -131,7 +146,7 @@
</tr>
<tr>
<td class=inlinetd>
- <p>In process worker</p>
+ <p>In-Process Worker</p>
</td>
<td class=inlinetd>
<p>This is a special worker. Instead of working with a Tomcat
@@ -142,81 +157,98 @@
</tr>
<tr>
<td class=inlinetd>
- <p>Web server plugin/tomcat redirector</p>
+ <p>Web Server Plug-in/Tomcat Redirector</p>
</td>
<td class=inlinetd>
<p>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.</p>
+ 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.</p>
</td>
</tr>
<tr>
<td class=inlinetd>
- <p>Plugin configuration</p>
+ <p>Plug-in Configuration</p>
</td>
<td class=inlinetd>
- <p>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. </p>
+ <p>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. </p>
</td>
</tr>
<tr>
<td class=inlinetd>
- <p>Web server configuration</p>
+ <p>Web Server Configuration</p>
</td>
<td class=inlinetd>
- <p>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.</p>
+ <p>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.</p>
</td>
</tr>
</table>
<hr>
-<h2><a name=s6>Configuring Apache to use mod_jk</a></h2>
+<h2><a name="s6">Obtaining mod_jk</a></h2>
-<p>The configuration includes the following steps: </p>
+<p>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. </p>
+
+<h3><a name="s61">mod_jk Binaries</a></h3>
+
+<p>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. </p>
-<ol>
- <li>Remove your old mod_jserv configuration. mod_jk and mod_jserv cannot coexist
!!</li>
- <li>Obtaining or building mod_jk</li>
- <li><i>(optional)</i> Configuring Tomcat to use the Ajpv13 protocol</li>
- <li>Defining workers for mod_jk (or selecting the quick start option)</li>
- <li>Configuring Apache to use mod_jk and configure mod_jk internals (or selecting
the quick start option)</li>
- <li>Assigning URLs to be redirected to Tomcat (or selecting the quick start
option)</li>
-</ol>
-
-<h3><a name=s61>1. Removing the mod_jserv directives</a></h3>
-<p class=subsection>
-If you've already configured Apache to use mod_jserv, remove any
<tt>ApJServMount</tt> directives from your httpd.conf. If you're including
<tt>tomcat-apache.conf</tt> or <tt>tomcat.conf</tt>, you'll want to remove them as
well - they are specific to mod_jserv.
-</p>
+<p>For example, the Tomcat 3.3 M1 Release at <a
href="http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3-m1/bin/">http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3-m1/bin/</a>
+ contains the following: </p>
-<h3><a name=s62>2. Obtaining and building mod_jk</a></h3>
-<div class=subsection>
-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.
-
-<p> 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 <b><a
href="http://jakarta.apache.org/downloads/sourceindex.html">Source
Distribution</a></b> for Tomcat. There are a large number
-of files in the download directory, but the only one you need is
-<tt>jakarta-tomcat[.zip|.tar.Z|.tar.gz]</tt>.
+<table border="1" cellspacing="0" bordercolor="#000000" cellpadding="2" width="600">
+ <tr>
+ <td width="15%">linux/i386/</td>
+ <td width="85%">Contains mod_jk.so for Apache 1.3 for the standard API as
+ well as EAPI and mod_jk.so for Apache 2.0</td>
+ </tr>
+ <tr>
+ <td width="15%">netware/</td>
+ <td width="85%">Contains the mod_jk.nlm and nsapi.nlm</td>
+ </tr>
+ <tr>
+ <td width="15%">win32/</td>
+ <td width="85%">Contains the mod_jk.dll for Windows as well as other useful
+ binaries.</td>
+ </tr>
+</table>
+<p>Check the site for the latest binaries.</p>
+<p>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.</p>
+<h3><a name="s62">Building mod_jk</a></h3>
+
+<p>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. </p>
-<h3>On NT</h3>
+<h3><a name="s63">Building mod_jk for NT</a></h3>
-<p>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.</p>
+<p>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.</p>
<p>The steps that you need to take are: </p>
<ol>
- <li>Change directory to the
- apache1.3/apache2.0 source directory. </li>
+ <li>Change directory to the apache1.3 or apache2.0 source directory depending
+ on your version of Apache. </li>
<li>Set an APACHE1_HOME environment variable which points to where your Apache is
installed.</li>
<li>Execute the following
@@ -229,94 +261,308 @@
<li>Copy mod_jk.dll to Apache's modules directory.</li>
</ol>
-<p>This will build both release and debug versions of the redirector plugin
-(mod_jk). </p>
+<p>This will build both release and debug versions of the redirector plug-in
(mod_jk). </p>
<p>An alternative will be to open <tt>mod_jk.dsp</tt> in msdev and build it using
the build
menu.</p>
-<h3>On UNIX</h3>
+<h3><a name="s64">Building mod_jk for Unix</a></h3>
-<h4>For Apache</h4>
+<h4> Apache</h4>
<ol>
- <li>Make sure you have Perl 5 installed. The <tt>apxs</tt> script
- used to build the module is written in Perl.
-
- <li>Change directory to
- <tt>jakarta-tomcat/src/native/apache1.3</tt> (or <tt>apache2.0</tt>).
-
- <li>Build mod_jk.so. <br /><br />
+ <li>Make sure your Apache has DSO support. You can check this
+ with <tt>$APACHE_HOME/bin/httpd -l</tt>. 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.</li>
+
+ <li>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,
+ <tt>$APACHE_HOME/bin/apachectl configtest</tt> will warn
+ you.</li>
+
+ <li>Make sure you have Perl 5 installed. The <tt>apxs</tt>
+ script used to build the module is written in Perl.
+
+ <li>Change directory to <tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt> (or
+ <tt>apache2.0</tt>).
+
+ <li>
+ <p>Build mod_jk.so. Following are three techniques you can try,
+ in order of simplicity:</p>
+
+ <ol>
+ <li>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
<tt>./build-unix.sh</tt>. This script will set some variables, call
+ <tt>apxs</tt> as below, and try to copy mod_jk.so to
+ $APACHE_HOME/libexec. If it fails, you need to do
+ the following manually:
- Following are three alternate techniques you can try, in order of
- simplicity.
-
- <ul>
- <li><b>Option 1</b>: Run <tt>./build-unix.sh</tt> . This script will set some
- variables, call <tt>apxs</tt> as below, and try to copy mod_jk.so to
- $APACHE_HOME/libexec. If it fails, you may need to do the following:
<ul>
- <li>set JAVA_HOME in your shell, e.g. "<tt>set JAVA_HOME=/usr/local/jdk1.2.2;
export JAVA_HOME</tt>"</li>
- <li>set APACHE_HOME in your shell, e.g. "<tt>set APACHE_HOME=/usr/local/apache;
export APACHE_HOME</tt>"</li>
- <li>uncomment the following line in the <tt>build-unix.sh</tt> file,
- replacing "linux" with the name of your platform as specified in the
+ <li>set JAVA_HOME in your shell, e.g. "<tt>set
+ JAVA_HOME=/usr/local/jdk1.2.2; export
+ JAVA_HOME</tt>"</li>
+ <li>set APACHE_HOME in your shell, e.g.
+ "<tt>set APACHE_HOME=/usr/local/apache;
+ export APACHE_HOME</tt>"</li>
+ <li>uncomment the following line in the
+ <tt>build-unix.sh</tt> file,
+ replacing "linux" with the name of your
+ platform as specified in the
Java include directory for your installation
-<blockquote><tt>
-# JAVA_INCLUDE="-I ${JAVA_HOME}/include -I ${JAVA_HOME}/include/linux"
-</tt></blockquote>
- </ul></li>
- <li> <b>Option 2</b>: If build-unix.sh fails, you may have better luck with the
- Makefiles in the same directory. E.g. "<tt>make -f Makefile.linux mod_jk.so</tt>"
+
+ <blockquote><tt># JAVA_INCLUDE="-I
+ ${JAVA_HOME}/include -I
+ ${JAVA_HOME}/include/linux"</tt></blockquote>
</li>
- <li> <b>Option 3</b>: Finally, you can try to build it manually. Run the
<tt>apxs</tt> 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.<BR><BR>
- For Solaris:<BR>
- <blockquote><tt>apxs -o mod_jk.so -DSOLARIS -I../jk -I/usr/java/include
-I/usr/java/include/solaris -c *.c ../jk/*.c</tt></blockquote>
- <i>On some systems, this will build the module correctly, but will fail at
runtime with a </i>"<tt>symbol "fdatasync" not found</tt>"<i>. To fix, add
</i><tt>-lposix4</tt><i> just before the </i><tt>-c</tt><i> in the above
command.</i><BR><BR>
- For Linux:
- <blockquote><tt>apxs -o mod_jk.so -I../jk -I/usr/local/jdk/include
-I/usr/local/jdk/include/linux -c *.c ../jk/*.c</tt></blockquote>
- <i>Your build may fail because the object files from the <tt>../jk</tt> directory
have been compiled to the current directory, rather than their source directory.
Running </i><tt>gcc -shared -o mod_jk.so *.o</tt><i> should finish the
build.</i><BR><BR>
- (If you've installed Java in another directory, adjust accordingly). For other
*nixes you should be able to work it out, but remember that <b>the order of the
arguments to <tt>apxs</tt> is important!</b>.
- <br /><br />
+
+ </ul>
</li>
- </ul></li>
- <li>Copy mod_jk.so to Apache's libexec directory. (Note that
- build-unix.sh attempts to do this, but you may have to "su root"
- first.) </li>
+
+ <li>If build-unix.sh fails, you may have better luck
+ with the Makefiles in the same directory, e.g.
+ "<tt>make -f Makefile.linux mod_jk.so</tt>"
+ </li>
+
+ <li>
+ <p>Finally, you can try to build it manually. Run the
+ <tt>apxs</tt> 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.</p>
+
+ <hr>
+
+ <p>For Linux:</p>
+
+ <blockquote><tt>apxs -o mod_jk.so -I../jk
+ -I/usr/local/jdk/include -I/usr/local/jdk/include/linux
+ -c *.c ../jk/*.c</tt></blockquote>
+
+ <p>Your build may fail because the object files from
+ the <tt>../jk</tt> directory have been compiled to the
+ current directory, rather than their source directory.
+ Running <tt>gcc -shared -o mod_jk.so *.o</tt>
+ should finish the build.</p>
+
+ <hr>
+
+ <p>For Solaris:</p>
+
+ <p>Use the <tt>build-solaris.sh</tt> script as follows:</p>
+
+ <blockquote><tt># sh build-solaris.sh</tt></blockquote>
+
+ <p>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 <tt>JAVA_HOME=/usr/java</tt>
and
+ <tt>APACHE_HOME=/usr/local/apache</tt>. If your installation is
different,
+ you will need to edit the <tt>build-solaris.sh</tt> script and change these
+ values appropriately.</p>
+
+ <p>See <tt>README.solaris</tt> located in
<tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt>
+ for more information.</p>
+
+ <p>If the build script does not work, you can also build mod_jk as
+ follows:</p>
+
+ <blockquote><tt>$APACHE_HOME/bin/apxs -o mod_jk.so -DSOLARIS -I../jk
-I/usr/java/include
+ -I/usr/java/include/solaris -c *.c ../jk/*.c</tt></blockquote>
+
+ <p>On some systems, this will build the module
+ correctly, but will fail at runtime with a
+ "<tt>symbol "fdatasync" not found</tt>". To
+ fix, add <tt>-lposix4</tt> just before the
+ <tt>-c</tt> in the above command.</p>
+
+ <hr>
+
+ <p>For HP-UX 11.00:</p>
+
+ <p>Use the <tt>build-hpux.sh</tt> script as follows:</p>
+
+ <blockquote><tt># sh build-hpux.sh</tt></blockquote>
+
+ <p>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
<tt>JAVA_HOME=/opt/java1.3</tt> and
+ <tt>APACHE_HOME=/usr/local/apache</tt>. If your installation is
different,
+ you will need to edit the <tt>build-hpux.sh</tt> script and change these
+ values appropriately.</p>
+
+ <p>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.</p>
+
+ <p>The <tt>build-hpux.sh</tt> script should also work for HP-UX 10.00.</p>
+
+ <p>See <tt>README.hpux</tt> located in
<tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt>
+ for more information.</p>
+
+ <hr>
+
+ <p>For other Unixes (including FreeBSD):</p>
+
+ <p>You may need to replace fdatasync() with fsync() in jk_util.c.</p>
+
+ <p>The <tt>build-hpux-cc.sh</tt> script should be modifiable for IRIX and
AIX.
+ Edit the script and change the APACHE_HOME and JAVA_HOME locations as
+ required.</p>
+
+ <hr>
+
+ <p>If you are using EAPI, try adding
+ <tt>-DEAPI</tt> to the apxs command after
+ <tt>mod_jk.so</tt>.</p>
+
+ <p>If apxs fails with <code>apxs:Break: Command failed
+ with rc=255</code>, it may have been damaged by
+ mod_ssl. Search for:</p>
+
+<pre>my $CFG_LD_SHLIB = q(); # substituted via Makefile.tmpl
+my $CFG_LDFLAGS_SHLIB = q(); # substituted via Makefile.tmpl
+</pre>
+
+ <p>and change to:</p>
+
+<pre>my $CFG_LD_SHLIB = q(ld); # substituted via Makefile.tmpl
+my $CFG_LDFLAGS_SHLIB = q(-G); # substituted via Makefile.tmpl
+</pre>
+
+ <p>If you've installed Java in another directory,
+ adjust accordingly.</p>
+
+ <p>For other Unixes you should be able to work it out,
+ but remember that <strong>the order of the arguments to
+ <tt>apxs</tt> is important!</strong>.</p>
+ </li>
+
+ </ol>
+ </li>
+
+ <li>Now, copy the mod_jk library. <tt># cp mod_jk.so
$APACHE_HOME/libexec</tt>. (Note that
+ the build scripts attempt to do this, but you may have to
+ <tt>su</tt> first.)</li>
</ol>
+
+<h4>Other Webservers</h4>
+
+<p>There are several Makefiles in the other directories under the
<tt>TOMCAT_HOME/native/mod_jk/</tt>
+directory. You should also check the Tomcat documentation for specific
+information related to other web servers.</p>
+
+<hr>
+<h2><a name="s7">Configuring Apache</a></h2>
+
+<p>This section details the configuration that is required for the Apache Web
+Server to support mod_jk.</p>
+
+<h3><a name="s71">Removing mod_jserv directives</a></h3>
+<p class=subsection>
+If you've previously configured Apache to use mod_jserv, remove any
<tt>ApJServMount</tt> directives from your httpd.conf. If you're including
<tt>tomcat-apache.conf</tt> or <tt>tomcat.conf</tt>, 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!
+</p>
+
+<h3><a name="s72">Configure Apache to use mod_jk</a></h3>
+<div class=subsection>
+<p>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:</p>
+
+<p><tt>Include TOMCAT_HOME/conf/jk/mod_jk.conf-auto</tt></p>
+
+<p>Example:</p>
+
+<p><tt>Include /usr/local/jakarta-tomcat/conf/jk/mod_jk.conf-auto</tt></p>
+
+<p>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 [<a
href="#s8">Configuring
+Tomcat</a>].</p>
+
+<p><b>NOTE: If you plan to use the Tomcat-Apache auto-configuration, skip
+the rest of this section and continue with the <a href="#s8">Configuring Tomcat</a>
+section.</b></p>
+
+<p>Custom configurations can be created by enabling the auto-configuration and
+copying the <tt>TOMCAT_HOME/conf/jk/mod_jk.conf-auto</tt> file to your own
+configuration file, such as <tt>TOMCAT_HOME/conf/jk/mod_jk.conf-local</tt>.</p>
-<h4>For other Webservers</h4>
+<p>The basic configuration is as follows:</p>
-There are several Makefiles in the other directories under the
<tt>jakarta-tomcat/src/native</tt> directory.
+<ul>
+ <li>You will need to instruct Apache to load Tomcat. This can be done with
+ Apache's <tt>LoadModule</tt> and <tt>AddModule</tt> configuration directives.</li>
+ <li>You must inform mod_jk the location of your <tt>workers.properties</tt> file.
+ Use mod_jk's <tt>JkWorkersFile</tt> configuration directive.</li>
+ <li>You should specify a location where mod_jk is going to place its log file
+ and a log level to be used. Use the <tt>JkLogFile</tt> and <tt>JkLogLevel</tt>
+ configuration directives. Possible log levels are <i>debug</i>, <i>warn</i>,
+ <i>error</i> and <i>emerg</i>, but <i>warn</i> should be your default
+ selection.</li>
+</ul>
+A simple example would be to include the following lines in your
<tt>httpd.conf</tt> file:
+<blockquote><pre>
+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
+</pre></blockquote>
</div>
-<h3><a name=s63>3. (optional) Configuring Tomcat to use the Ajpv13 protocol</a></h3>
+<h3><a name="s73">Assigning URLs to Tomcat</a></h3>
<div class=subsection>
-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.<BR><BR>
-Add the following block to your <tt>TOMCAT_HOME/conf/server.xml</tt> file.
+<p>If you have created a custom or local version of <tt>mod_jk.conf-local</tt>
+ as noted above, you can change settings such as the workers or URL prefix.</p>
+
+<p>Use mod_jk's JkMount directive to assign specific URLs to Tomcat. In general
+the structure of a JkMount directive is:</p>
+
+<pre>
+JkMount <i><URL prefix></i> <i><Worker name></i>
+</pre>
+
+<p>For example the following directives will send all requests ending in
+<tt>.jsp</tt> or beginning with <tt>/servlet</tt> to the "<tt>ajp13</tt>"
worker,
+but jsp requests to files located in /otherworker will go to
"<tt>remoteworker</tt>".
+
<blockquote><pre>
-<Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter name="handler"
value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
- <Parameter name="port" value="8009"/>
-</Connector>
+JkMount /*.jsp ajp13
+JkMount /servlet/* ajp13
+JkMount /otherworker/*.jsp remoteworker
</pre></blockquote>
-The <tt>server.xml</tt> 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.
+You can use the <tt>JkMount</tt> directive at the top level or inside
<tt><VirtualHost></tt>
+sections of your httpd.conf file.
</div>
-<h3><a name=s64>4. Defining "workers"</a></h3>
+
+<hr>
+<h2><a name="s8">Configuring Tomcat</a></h2>
-<h4>Quick start?</h4>
+<h3><a name="s81">Enabling Tomcat's Apache Auto-Config</a></h3>
<div class=subsection>
<p>
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.
+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 <tt>"Include
TOMCAT_HOME/conf/jk/mod_jk.conf-auto"</tt>)
-in your httpd.conf. To configure Tomcat to generate the Apache
-auto-configuration:</p>
-<p>
-Add the following block to your <tt>TOMCAT_HOME/conf/server.xml</tt> file after
<AutoWebApp ... />.
+in your httpd.conf, as shown in the previous section (<a href="#s7">Configuring
+Apache</a>).
+</p>
+<p>To configure Tomcat to generate the Apache auto-configuration add the following
block to your <tt>TOMCAT_HOME/conf/server.xml</tt> file after <tt><AutoWebApp ...
/></tt>.
</p>
<blockquote><pre>
<ApacheConfig />
@@ -325,6 +571,12 @@
That's it, you can
now start Tomcat and Apache and access Tomcat from the Apache server.
</p>
+<p>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.
+</p>
<p>
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
@@ -337,7 +589,7 @@
the file <tt>TOMCAT_HOME/conf/jk/mod_jk.conf-auto</tt> is generated when
tomcat starts, so you'll need to start Tomcat before Apache. Tomcat will
overwrite <tt>TOMCAT_HOME/conf/jk/mod_jk.conf-auto</tt> each startup so
-a customized configuration should be kept elsewhere. For example, copy
+customized configuration should be kept elsewhere. For example, copy
<tt>TOMCAT_HOME/conf/jk/mod_jk.conf-auto</tt> to
<tt>TOMCAT_HOME/conf/jk/mod_jk.conf-local
</tt>before making changes. You'll need to startup Tomcat once to generate
this file with your configuration for the first time.
@@ -375,8 +627,39 @@
netware, and "libexec/mod_jk.so" everywhere else.
<li><b>jklog</b> - path to log file to be used by mod_jk.</li>
</ul>
+<p>
+ Example:
+</p>
+<blockquote><pre>...
+
+<AutoWebApp dir="webapps" host="DEFAULT" />
+
+<ApacheConfig confighome="/home/mydir" />
+
+...</pre></blockquote>
</div>
+<h3><a name="s82">(Optional) Configuring Tomcat to use the Ajpv13 protocol</a></h3>
+<div class=subsection>
+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.<BR><BR>
+Add the following block to your <tt>TOMCAT_HOME/conf/server.xml</tt> file.
+<blockquote><pre>
+<Connector className="org.apache.tomcat.service.PoolTcpConnector">
+ <Parameter name="handler"
value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
+ <Parameter name="port" value="8009"/>
+</Connector>
+</pre></blockquote>
+
+<p>The <tt>server.xml</tt> 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.</p>
+
+</div>
+<h3><a name="s83">(Optional) Defining "workers"</a></h3>
+
<h4>Configuring workers manually.</h4>
<div class=subsection>
<p>
@@ -388,59 +671,8 @@
</p>
</div>
-<h3><a name=s65>5. Configure Apache to use mod_jk</a></h3>
-<div class=subsection>
-<p>Configuring Apache to use mod_jk is done using the Apache server
-configuration directives; to get you started, look at the auto-generated
-<tt>mod_jk.conf-auto</tt> available in Tomcat's <tt>conf</tt> directory.</p>
-
-<ul>
- <li>You will need to instruct Apache to load Tomcat. This can be done with
- Apache's <tt>LoadModule</tt> and <tt>AddModule</tt> configuration directives.</li>
- <li>You must inform mod_jk the location of your <tt>workers.properties</tt> file.
- Use mod_jk's <tt>JkWorkersFile</tt> configuration directive.</li>
- <li>You should specify a location where mod_jk is going to place its log file
- and a log level to be used. Use the <tt>JkLogFile</tt> and <tt>JkLogLevel</tt>
- configuration directives. Possible log levels are <i>debug</i>, <i>warn</i>,
- <i>error</i> and <i>emerg</i>, but <i>warn</i> should be your default
- selection.</li>
-</ul>
-A simple example would be to include the following lines in your
<tt>httpd.conf</tt> file:
-<blockquote><pre>
-LoadModule jk_module libexec/mod_jk.so
-AddModule mod_jk.c
-JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
-JkLogFile /usr/local/apache/logs/mod_jk.log
-JkLogLevel warn
-</pre></blockquote>
-</div>
-
-<h3><a name=s66>6. Assigning URLs to Tomcat</a></h3>
-<div class=subsection>
-<p>Use mod_jk's JkMount directive to assign specific URLs to Tomcat. In general
-the structure of a JkMount directive is:</p>
-
-<pre>
-JkMount <i><URL prefix></i> <i><Worker name></i>
-</pre>
-
-<p>For example the following directives will send all requests ending in
-<tt>.jsp</tt> or beginning with <tt>/servlet</tt> to the "<tt>ajp13</tt>"
worker,
-but jsp requests to files located in /otherworker will go to
"<tt>remoteworker</tt>".
-
-<blockquote><pre>
-JkMount /*.jsp ajp13
-JkMount /servlet/* ajp13
-JkMount /otherworker/*.jsp remoteworker
-</pre></blockquote>
-You can use the <tt>JkMount</tt> directive at the top level or inside
<tt><VirtualHost></tt>
-sections of your httpd.conf file.
-</div>
-
-You're done! You should now be able to start Tomcat and apache and have them
cooperate
-to serve servlets and JSP files.
<hr>
-<h2><a name=s7>An example configuration</a></h2>
+<h2><a name="s9">Example Configuration</a></h2>
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).
@@ -540,16 +772,33 @@
<i>Table 3 - Excerpt from Apaches httpd.conf showing JK directives.</i>
<HR>
-<h2><a name=s8>Troubleshooting and F.A.Q.s</a></h2>
+<h2><a name="s10">Troubleshooting and F.A.Q.s</a></h2>
+<h3>Q. Where can I get help/support for mod_jk?</h3>
+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 <a
href="http://localhost:8080/doc/index.html">http://localhost:8080/doc/index.html</a>.
+Documentation is also available on the Apache Jakarta web site for Tomcat at <a
href="http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/index.html">http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/index.html</a>.
+<p>For additional help, the best resource is the Tomcat Users Discussion
+list. You should start by searching the mail list archives located at <a
href="http://">http://mikal.org/interests/java/tomcat/index.html</a>
+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. <a href="http://">http://jakarta.apache.org/site/mail.html</a></p>
+
<h3>Q. I can't find mod_jk anywhere. Where is it?</h3>
-A. You need to download the <b>Source Distribution</b> of Tomcat and build it
yourself.
-See <a href="#s62">this section</a> for more information.
+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.
<h3>Q. Which protocol should I use? Ajp12 or Ajp13?</h3>
A. Ajp13 is a newer protocol, it's faster, and it works better with SSL. You almost
-certainly want to use that. There is more information in the
-<a href="Tomcat-Workers-HowTo.html">workers.properties howto</a> document
+certainly want to use it. There is more information in the
+<a href="Tomcat-Workers-HowTo.html">workers.properties howto</a> document.
<h3>Q. Whenever I restart Tomcat, Apache locks up!</h3>
A. The Ajp13 protocol keeps an open socket between Tomcat and Apache. When you
restart
@@ -558,19 +807,46 @@
<h3>Q. Where can I get more information?</h3>
A. The <a href="Tomcat-Workers-HowTo.html">workers.properties howto</a> 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.
+also try searching the mailing list archives for "mod_jk" or look at the
source.<h3>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?</h3>
+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 <a
href="http://httpd.apache.org">http://httpd.apache.org</a>
+and build it yourself. Use the following for a basic build (read the
+Apache docs for other options):
+<blockquote><pre># 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</pre></blockquote>
+
+<p>Note: The above steps assume that you downloaded the Apache source and placed
+it in your /usr/local/src directory.</p>
<hr>
-<h2><a name=s9>Credits</a></h2>
-<p>This document was created by
-<a href="mailto:[EMAIL PROTECTED]">Gal Shachor</a>, and was revised by Mike
Bremford with help from the countless many on the tomcat-dev and tomcat-user lists!</p>
+<h2><a name="s11">Credits</a></h2>
+<p>This document was originally created by
+<a href="mailto:[EMAIL PROTECTED]">Gal Shachor</a></p>
+
+<p>Revisions by (Alphabetical)</p>
+
+<p>Mike Braden <tt><<a
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>></tt><br>
+Mike Bremford<br>
+Chris Pepper</p>
+
+<p>With help from countless others on the tomcat-dev and tomcat-user lists!</p>
<table width="100%" border="0" cellpadding="10" cellspacing="0">
<tr>
<td>
<p class="fineprint">
- Copyright ©1999-2000 The Apache Software Foundation<br>
+ Copyright ©1999-2001 The Apache Software Foundation<br>
<a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us
Say</a><br>
<a href="http://jakarta.apache.org/contact.html">Contact Information</a>
</p>
</td>
