hgomez 01/06/22 07:49:49
Modified: src/doc Tag: tomcat_32 mod_jk-howto.html
Log:
Updated mod_jk documentation. Add in FAQ the explanation
about EAPI/STD, garbled and might crash !
Revision Changes Path
No revision
No revision
1.1.2.4 +532 -155 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.1.2.3
retrieving revision 1.1.2.4
diff -u -r1.1.2.3 -r1.1.2.4
--- mod_jk-howto.html 2001/06/05 14:38:23 1.1.2.3
+++ mod_jk-howto.html 2001/06/22 14:49:47 1.1.2.4
@@ -1,10 +1,10 @@
<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="uguide/style.css">
+ <link rel="stylesheet" href="style.css">
<style type="text/css">
.inlinetd {
background-color: #E0E0E0;
@@ -40,11 +40,11 @@
<tr>
<td width="50%" align="left">
<a href="http://jakarta.apache.org/index.html";>
- <img src="uguide/images/banner.gif" width="350" height="100" alt="The
Jakarta Project" border="0">
+ <img src="images/banner.gif" width="350" height="100" alt="The Jakarta
Project" border="0">
</a>
</td>
<td width="50%" align="right">
- <img border="0" src="uguide/images/tomcat.gif" width="100" height="71"
alt="The mighty Tomcat - Meow!">
+ <img border="0" src="images/tomcat.gif" width="100" height="71" alt="The
mighty Tomcat - Meow!">
</td>
</tr>
</table>
@@ -58,24 +58,36 @@
<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 +111,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 +130,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 +143,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,78 +154,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 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. 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>Source Distribution</b> for Tomcat. There are a large number
-of files in the download directory, but the only one you need is
<tt>jakarta-tomcat</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
@@ -226,95 +258,247 @@
<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>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>.
+ <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:
+
+ <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
+ Java include directory for your installation
+
+ <blockquote><tt># JAVA_INCLUDE="-I
+ ${JAVA_HOME}/include -I
+ ${JAVA_HOME}/include/linux"</tt></blockquote>
+ </li>
+
+ </ul>
</li>
- <li>Copy mod_jk.so to Apache's libexec directory</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>For other Webservers</h4>
+<h4>Other Webservers</h4>
-There are several Makefiles in the other directories under the
<tt>jakarta-tomcat/src/native</tt> directory.
-</div>
+<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>
-<h3><a name=s63>3. (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>
-The <tt>servlet.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.
-</div>
-<h3><a name=s64>4. Defining "workers"</a></h3>
+<hr>
+<h2><a name="s7">Configuring Apache</a></h2>
-<h4>Quick start?</h4>
-<div class=subsection>
-<p>
-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 <tt>TOMCAT_HOME/conf/mod_jk.conf-auto</tt>.
-Most of the time you don't need to do anything but
-include this file (appending <tt>"Include
TOMCAT_HOME/conf/mod_jk.conf-auto"</tt>)
-in your httpd.conf. That's it, you can
-now start Tomcat and Apache and access Tomcat from the Apache server.
-</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
-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.
-</p>
-<p class=note><b>Tomcat 3.2:</b> you must restart tomcat and apache after adding a
new
-context; Apache doesn't support configuration changes without a restart. Also
-the file <tt>TOMCAT_HOME/conf/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/mod_jk.conf-auto</tt> each startup so
-customized configuration should be kept elsewhere.</p>
-</div>
+<p>This section details the configuration that is required for the Apache Web
+Server to support mod_jk.</p>
-<h4>Configuring workers manually.</h4>
-<div class=subsection>
-<p>
-Workers are configured using the file <tt>TOMCAT_HOME/conf/workers.properties</tt>.
-There is a great deal of information in the
-<a href="Tomcat-Workers-HowTo.html">workers.properties howto</a> 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 <tt>workers.properties</tt> and setting the
<tt>workers.tomcat_home</tt>, <tt>workers.java_home</tt> and <tt>ps</tt> variables to
the correct values for your system.
+<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>
-</div>
-<h3><a name=s65>5. Configure Apache to use mod_jk</a></h3>
+<h3><a name="s72">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>
+<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>
+
+<p>The basic configuration is as follows:</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>
@@ -322,9 +506,12 @@
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
+ configuration directives. Possible log levels are <i>debug</i>, <i>info</i>,
+ <i>error</i> and <i>emerg</i>, but <i>info</i> should be your default
selection.</li>
+ <li>The directive <tt>JkLogStampFormat</tt> will configure the date/time format
+ found on mod_jk logfile. Using <tt>strftime()</tt> format string it's set by
+ default to "[%a %b %d %H:%M:%S %Y] "</li>
</ul>
A simple example would be to include the following lines in your
<tt>httpd.conf</tt> file:
<blockquote><pre>
@@ -332,12 +519,16 @@
AddModule mod_jk.c
JkWorkersFile /usr/local/jakarta-tomcat/conf/workers.properties
JkLogFile /usr/local/apache/logs/mod_jk.log
-JkLogLevel warn
+JkLogLevel info
+JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
</pre></blockquote>
</div>
-<h3><a name=s66>6. Assigning URLs to Tomcat</a></h3>
+<h3><a name="s73">Assigning URLs to Tomcat</a></h3>
<div class=subsection>
+<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>
@@ -358,10 +549,130 @@
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="s8">Configuring Tomcat</a></h2>
+
+<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 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, 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 />
+</pre></blockquote>
+<p>
+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
+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.
+</p>
+<p>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 <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
+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.
+</p>
+<p>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:
+</p>
+<blockquote><pre>
+< ContextManager ... >
+ ...
+ <ApacheConfig <i>options</i> />
+ ...
+< /ContextManager >
+</pre></blockquote>
+<p>
+ where <i>options</i> can include any of the following attributes:
+</p>
+<ul>
+ <li><b>confighome</b> - default parent directory for the following paths. If
+ not set, this defaults to TOMCAT_HOME. Ignored whenever any of the following
+ paths is absolute.
+ <li><b>jservconfig</b> - path to write apache jserv conf file to. If not set,
+ defaults to "conf/jserv/tomcat-apache.conf".
+ <li><b>jkconfig</b> - path to write apacke mod_jk conf file to. If not set,
+ defaults to "conf/jk/mod_jk.conf".
+ <li><b>workersconfig</b> - path to workers.properties file used by mod_jk. If
+ not set, defaults to "conf/jk/workers.properties".
+ <li><b>modjserv</b> - 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.
+ <li><b>modjk</b> - 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.
+ <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.
+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.<BR><BR>
+The following block enables Ajpv13 in your <tt>TOMCAT_HOME/conf/server.xml</tt>
file.
+<blockquote><pre>
+<RequestInterceptor
+ className="org.apache.tomcat.modules.server.Ajp13Interceptor"
+ port="8009"/>
+</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>
+Workers are configured using the file
<tt>TOMCAT_HOME/conf/jk/workers.properties</tt>.
+There is a great deal of information in the
+<a href="Tomcat-Workers-HowTo.html">workers.properties howto</a> 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 <tt>workers.properties</tt> and setting the
<tt>workers.tomcat_home</tt>, <tt>workers.java_home</tt> and <tt>ps</tt> variables to
the correct values for your system.
+</p>
+</div>
+
+<hr>
+<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).
@@ -426,9 +737,9 @@
# Configure mod_jk
#
-JkWorkersFile /usr/local/jakarta-tomcat/conf/workers.properties
+JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
JkLogFile /usr/local/apache/logs/mod_jk.log
-JkLogLevel warn
+JkLogLevel info
# First Virtual Host.
#
@@ -461,37 +772,103 @@
<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.
+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)
<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
-Tomcat, you need to restart Apache as well.
+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.
+
+<h3>Q. Why did exist two files mod_jk.so (-eapi ad -noeapi) in download dir for
Linux ?</h3>
+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
+
+
+<h3>Q. What's that message about 'garbled DSO ?'</h3>
+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.
+
+<h3>Q. And the message about 'module might crash under EAPI! '</h3>
+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.
<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>
