You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by hg...@apache.org on 2002/08/29 10:25:40 UTC
cvs commit: jakarta-tomcat-connectors/jk/doc tomcat-workers-howto.html mod_jk-howto.html Tomcat-Workers-HowTo.html
hgomez 2002/08/29 01:25:39
Modified: jk/doc mod_jk-howto.html
Added: jk/doc tomcat-workers-howto.html
Removed: jk/doc Tomcat-Workers-HowTo.html
Log:
Updated mod_jk howto (configure, faq, apache2)
renamed Tomcat-Workers-HowTo.html to tomcat-workers-howto.html
Revision Changes Path
1.5 +1010 -946 jakarta-tomcat-connectors/jk/doc/mod_jk-howto.html
Index: mod_jk-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/doc/mod_jk-howto.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- mod_jk-howto.html 21 Apr 2002 22:57:11 -0000 1.4
+++ mod_jk-howto.html 29 Aug 2002 08:25:39 -0000 1.5
@@ -1,946 +1,1010 @@
-<html>
-<head>
- <!-- $Id $ -->
- <!-- Copyright 2001, Apache Software Foundation -->
-
- <meta http-equiv=Content-Type content="text/html">
- <link rel="stylesheet" href="style.css">
- <style type="text/css">
- .inlinetd {
- background-color: #E0E0E0;
- vertical-align: text-top;
- border-top: thick black;
- border-right: thick black;
- border-bottom: thick black;
- border-left: thick black;
- }
- .inlineth {
- background-color: #d0d0d0;
- border-top: thick black;
- border-right: thick black;
- border-bottom: thick black;
- border-left: thick black;
- }
- .inlinetable {
- width: 75%;
- border: thick;
- background-color: #000000;
- }
- .subsection { margin:20pt; }
- .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }
-
- </style>
-
-<title>Working with mod_jk</title>
-</head>
-
-<body>
-<!-- Banner element, all hail the Project! -->
-<table border="0" width="100%" cellspacing="0" cellpadding="0">
- <tr>
- <td width="50%" align="left">
- <a href="http://jakarta.apache.org/index.html">
- <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="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!">
- </td>
- </tr>
-</table>
-
-<h1>Working with mod_jk</h1>
-<p>By Gal Shachor <tt><<a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>></tt></p>
-
-<h2>Table of Contents</h2>
-<ul>
-<li><a href="#s2">What is mod_jk?</a></li>
-<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">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="#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>
-<li><a href="#s74">Configuring Apache to serve static web application files</a></li>
-</ul></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 plug-in that handles the communication between Tomcat and Apache.</p>
-<hr>
-<h2><a name=s3>Why mod_jk?</a></h2>
-
-<p>Several reasons: </p>
-
-<ul>
- <li><b>mod_jserv was too complex</b>. Because it was ported from Apache/JServ, it
- brought with it lots of JServ specific bits that aren't needed by Apache.
- <li><b>mod_jserv supported only Apache</b>. 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.</li>
- <li>The layered approach provided
- by the jk library makes it easier to support both <b>Apache1.3.x <i>and</i>
- Apache2.xx.</b></li>
- <li><b>Better support for SSL</b>. mod_jserv couldn't reliably identify whether a
- request was made via HTTP or HTTPS. mod_jk can, using the newer Ajpv13 protocol.</li>
-</ul>
-<hr>
-<h2><a name=s4>What does it mean to me?</a></h2>
-
-<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 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>
-
-<p>In this document I am going to use a few terms, so let's define them:</p>
-
-<table class=inlinetable>
- <tr>
- <th class=inlineth>
- <p>Term</p>
- </th>
- <th class=inlineth>
- <p>Meaning</p>
- </th>
- </tr>
- <tr>
- <td class=inlinetd>
- <p>Worker Process</p>
- </td>
- <td class=inlinetd>
- <p>A worker is a tomcat instance that is running to serve
- servlet requests coming from the web server. In most cases there is only a
- single worker (the one and only tomcat process) but sometimes you will run
- multiple workers to achieve load balancing or site partitioning. Each worker
- is identified to the web server by the host were it is located, the port
- where it listens and the communication protocol used to exchange messages.</p>
- </td>
- </tr>
- <tr>
- <td class=inlinetd>
- <p>In-Process Worker</p>
- </td>
- <td class=inlinetd>
- <p>This is a special worker. Instead of working with a Tomcat
- process residing on another process, the web server opens a JVM and executes
- Tomcat inside the web server process address space. Our discussion in this
- document is not going to get into this special worker.</p>
- </td>
- </tr>
- <tr>
- <td class=inlinetd>
- <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 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>Plug-in Configuration</p>
- </td>
- <td class=inlinetd>
- <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>
- </td>
- <td class=inlinetd>
- <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">Obtaining mod_jk</a></h2>
-
-<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>
-
-<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>
-
-<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><a name="s63">Building mod_jk for NT</a></h3>
-
-<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 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
- command:<br><br>
- <tt><span>MSDEV mod_jk.dsp /MAKE ALL</span></tt><br><br>
- If msdev is not in your path, enter the full path to msdev.exe. Also, ApacheCore.lib
- is expected to exist in the APACHE1_HOME\src\CoreD and APACHE1_HOME\src\CoreR
- directories before linking will succeed. You will need to build enough of the
- Apache source to create these libraries.</li>
- <li>Copy mod_jk.dll to Apache's modules directory.</li>
-</ol>
-
-<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><a name="s64">Building mod_jk for Unix</a></h3>
-
-<h4> Apache</h4>
-
-<ol>
- <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>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>
-
-<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>
- <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>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>
- <li>The directive <tt>JkRequestLogFormat</tt> will configure the format of mod_jk
- individual request logging. Request logging is configured and enabled on a per
- virtual host basis. To enable request logging for a virtual host just add
- a JkRequestLogFormat config.
- The syntax of the format string is similiar to the Apache LogFormat command,
- here is a list of the avaialbe request log format options:
- <ul>
- <li>%b - Bytes sent, excluding HTTP headers. In CLF format</li>
- <li>%B - Bytes sent, excluding HTTP headers.</li>
- <li>%H - The request protocol</li>
- <li>%m - The request method</li>
- <li>%p - The canonical Port of the server serving the request</li>
- <li>%q - The query string (prepended with a ? if a query string exists,
- otherwise an empty string)</li>
- <li>%r - First line of request</li>
- <li>%s - request HTTP status code</li>
- <li>%T - Requset duration, elapsed time to handle request in seconds '.'
- micro seconds</li>
- <li>%U - The URL path requested, not including any query string.</li>
- <li>%v - The canonical ServerName of the server serving the request.</li>
- <li>%V - The server name according to the UseCanonicalName setting.</li>
- <li>%w - Tomcat worker name</li>
- </ul>
- </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 info
-JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
-</pre></blockquote>
-</div>
-
-<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>
-
-<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 with <tt>/servlet</tt> as the second path componenet 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>
-
-<h3><a name="s74">Configuring Apache to serve static web application files</a></h3>
-<div class=subsection>
-<p>If the Tomcat Host appBase (webapps) directory is accessible by the Apache
-web server, Apache can be configured to serve web application context directory
-static files instead of passing the request to Tomcat.</p>
-
-<p><b>Caution:</b> If Apache is configured to serve static pages for a web
-application it bypasses any security contraints you may have configured in
-your web application web.xml config file.</p>
-
-<p>Use Apache's Alias directive to map a single web application context directory
-into Apache's document space for a VirtualHost:
-
-<pre>
-# Static files in the examples webapp are served by apache
-Alias /examples /export/home/web/host1/webapps/examples
-
-JkMount /*.jsp ajp13
-JkMount /*/servlet/ ajp13
-</pre>
-</p>
-
-<p>Use the mod_jk JkAutoAlias directive to map all web application context
-directories into Apache's document space. Attempts to access the <code>WEB-INF</code>
-or <code>META-INF</code> directories within a web application context or a
-Web Archive <code>*.war</code> within the Tomcat Host appBase (webapps) directory
-will fail with an HTTP 403, Access Forbidden.</p>
-<p>
-Example configuration for an Apache VirtualHost:
-
-<pre>
-# Static files in all Tomcat webapp context directories are served by apache
-JkAutoAlias /export/home/web/host2/webapps
-
-JkMount /*.jsp ajp13
-JkMount /*/servlet/ ajp13
-</pre>
-</p>
-</div>
-
-<hr>
-<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).
-<BR><BR>
-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.<BR><BR>
-The example are over-simplified and incomplete but should get you started. Also note the
-virtual host setup is new in Tomcat 3.2 - <i>this example won't work with Tomcat 3.1</i>.<BR><BR>
-
-<table class=inlinetable><tr><td class=inlinetd>
-<blockquote><pre>
-.
-.
-<Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
- <Parameter name="port" value="8007"/>
-</Connector>
-
-<Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
- <Parameter name="port" value="8009"/>
-</Connector>
-
-<Host name="host1.apache.org">
- <Context path="" docBase="/web/host1" debug="0"/>
-</Host>
-<Host name="host2.apache.org">
- <Context path="" docBase="/web/host2" debug="0"/>
-</Host>
-.
-.
-</pre></blockquote>
-</td></tr></table>
-<i>Table 1 - Excerpt from server.xml showing the Ajp13 Connector and two virtual
-hosts.</i>
-<BR><BR>
-<table class=inlinetable><tr><td class=inlinetd>
-<blockquote><pre>
-# Setup for Solaris system
-#
-workers.tomcat_home=/usr/local/jakarta-tomcat
-workers.java_home=/usr/java
-ps=/
-worker.list=ajp12, ajp13
-
-# Definition for Ajp13 worker (Ajp12 left to readers imagination)
-#
-worker.ajp13.port=8009
-worker.ajp13.host=localhost
-worker.ajp13.type=ajp13
-</pre></blockquote>
-</td></tr></table>
-<i>Table 2 - Excerpt from workers.properties showing the Ajp13 worker</i>
-<BR><BR>
-<table class=inlinetable><tr><td class=inlinetd>
-<blockquote><pre>
-# Load mod_jk
-#
-LoadModule jk_module libexec/mod_jk.so
-AddModule mod_jk.c
-
-# Configure mod_jk
-#
-JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
-JkLogFile /usr/local/apache/logs/mod_jk.log
-JkLogLevel info
-
-# First Virtual Host. Request logging is enabled.
-#
-<VirtualHost 10.0.0.1:80>
- DocumentRoot /web/host1
- ServerName host1.apache.org
- JkRequestLogFormat "%w \"%r\" %s %T"
- JkMount /*.jsp ajp13
- JkMount /*/servlet/ ajp13
-</VirtualHost>
-
-# Second Virtual Host. Also accessible via HTTPS
-#
-<VirtualHost 10.0.0.2:80>
- DocumentRoot /web/host2
- ServerName host2.apache.org
- JkMount /*.jsp ajp13
- JkMount /*/servlet/ ajp13
-</VirtualHost>
-
-<VirtualHost 10.0.0.2:443>
- DocumentRoot /web/host2
- ServerName host2.apache.org
- SSLEngine On
- JkMount /*.jsp ajp13
- JkMount /*/servlet/ ajp13
-</VirtualHost>
-
-</pre></blockquote>
-</td></tr></table>
-<i>Table 3 - Excerpt from Apaches httpd.conf showing JK directives.</i>
-
-<HR>
-<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. 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 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. 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.<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="s11">Credits</a></h2>
-<p>This document was originally created by
-<a href="mailto:shachor@il.ibm.com">Gal Shachor</a></p>
-
-<p>Revisions by (Alphabetical)</p>
-
-<p>Mike Braden <tt><<a href="mailto:mikeb@mwbinc.com">mikeb@mwbinc.com</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-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>
- </tr>
-</table>
-</body>
-</html>
-
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <!-- $Id $ --> <!-- Copyright 2001, Apache Software Foundation -->
+
+ <meta http-equiv="Content-Type" content="text/html">
+
+ <link rel="stylesheet" href="style.css">
+
+ <style type="text/css">
+
+ .inlinetd {
+
+ background-color: #E0E0E0;
+
+ vertical-align: text-top;
+
+ border-top: thick black;
+
+ border-right: thick black;
+
+ border-bottom: thick black;
+
+ border-left: thick black;
+
+ }
+
+ .inlineth {
+
+ background-color: #d0d0d0;
+
+ border-top: thick black;
+
+ border-right: thick black;
+
+ border-bottom: thick black;
+
+ border-left: thick black;
+
+ }
+
+ .inlinetable {
+
+ width: 75%;
+
+ border: thick;
+
+ background-color: #000000;
+
+ }
+
+ .subsection { margin:20pt; }
+
+ .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }
+
+
+
+ </style>
+ <title>Working with mod_jk</title>
+</head>
+ <body>
+ <!-- Banner element, all hail the Project! -->
+<table border="0" width="100%" cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr>
+ <td width="50%" align="left"> <a
+ href="http://jakarta.apache.org/index.html"> <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="images/tomcat.gif" width="100" height="71"
+ alt="The mighty Tomcat - Meow!">
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+
+<h1>Working with mod_jk</h1>
+
+<p>By Gal Shachor <tt><<a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>></tt></p>
+
+<h2>Table of Contents</h2>
+
+<ul>
+ <li><a href="#s2">What is mod_jk?</a></li>
+ <li><a href="#s3">Why mod_jk?</a></li>
+ <li><a href="#s4">What does it mean to me?</a></li>
+ <li><a href="#s4-1">mod_jk cvs</a><br>
+ </li>
+ <li><a href="#s5">Definitions and Terminology</a></li>
+ <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="#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>
+ <li><a href="#s74">Configuring Apache to serve static web application
+ files</a></li>
+
+ </ul>
+ </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 plug-in that handles the communication between Tomcat and
+Apache.</p>
+
+<hr>
+<h2><a name="s3">Why mod_jk?</a></h2>
+
+<p>Several reasons: </p>
+
+<ul>
+ <li><b>mod_jserv was too complex</b>. Because it was ported from Apache/JServ,
+ it brought with it lots of JServ specific bits that aren't needed by Apache.
+ </li>
+ <li><b>mod_jserv supported only Apache</b>. 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.</li>
+ <li>The layered approach provided by the jk library makes it easier
+ to support both <b>Apache1.3.x <i>and</i> Apache2.xx.</b></li>
+ <li><b>Better support for SSL</b>. mod_jserv couldn't reliably identify
+ whether a request was made via HTTP or HTTPS. mod_jk can, using the newer
+ Ajpv13 protocol.</li>
+
+</ul>
+
+<hr>
+<h2><a name="s4">What does it mean to me?</a></h2>
+
+<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 Apache and other web servers, such as Microsoft's
+ Internet Information Server (IIS) and the iPlanet Enterprise Web Server.</p>
+ <br>
+
+<hr>
+<h2><a name="s4-1">mod_jk CVS</a></h2>
+
+<p>Originaly mod_jk was included in Tomcat 3.2 and next in 3.3 CVS repository,
+ causing major headaches to maintain 2 set of identical code.<br>
+ In 2001, all the connectors works was moved outside Tomcat 3.2/3.3 (for
+ mod_jk) and Tomcat 4.0 (for mod_webapp) in a new repository called jakarta-tomcat-connectors,
+ where all connector oriented development is now conducted.<br>
+ </p>
+
+<p>In this repository you'll find native and java code, various native connectors
+like mod_jk (jk/native), mod_jk2 (jk/native2), mod_webapp, you'll find also
+the java side of these connectors (jk/java and webapp/java).<br>
+ </p>
+
+<p>As such mod_jk could be used today by all of the ASF Tomcat Engine, 3.2.x,
+ 3.3.x, 4.0.x, 4.1.x and 5.x.<br>
+ </p>
+ <br>
+
+<hr>
+<h2><a name="s5">Definitions and Terminology</a></h2>
+
+<p>In this document I am going to use a few terms, so let's define them:</p>
+ <br>
+ <br>
+
+<hr>
+<h2><a name="s6">Obtaining mod_jk</a></h2>
+
+<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>The binaries for mod_jk are now available, for several platforms, in a
+ separate 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>
+
+<p>For example mod_jk 1.2.0 located at <a
+ href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/">http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/</a>
+ contains the following: </p>
+
+<table border="1" cellspacing="0" bordercolor="#000000" cellpadding="2"
+ width="600">
+ <tbody>
+ <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 valign="top">rpms/<br>
+ </td>
+ <td valign="top">Contains the rpms (including sources and i386
+architectures)<br>
+ </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>
+
+ </tbody>
+</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 mod_jk 1.2.0 distribution will function correctly with Tomcat 3.2 up
+ to Tomcat 5.</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 live next to the Binary Distribution
+ :</p>
+
+<p><a
+ href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/src/">http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/src/</a>
+ </p>
+
+<p>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.<br>
+ </p>
+
+<h3><a name="s63">Building mod_jk for NT</a></h3>
+
+<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 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 command:<br>
+ <br>
+ <tt><span>MSDEV mod_jk.dsp /MAKE ALL</span></tt><br>
+ <br>
+ If msdev is not in your path, enter the full path to msdev.exe.
+Also, ApacheCore.lib is expected to exist in the APACHE1_HOME\src\CoreD
+and APACHE1_HOME\src\CoreR directories before linking will succeed.
+You will need to build enough of the Apache source to create these libraries.</li>
+ <li>Copy mod_jk.dll to Apache's modules directory.</li>
+
+</ol>
+
+<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><a name="s64">Building mod_jk for Unix</a></h3>
+
+<h4>Building using configure</h4>
+ It is possible to use autoconf for configuration and installation.<br>
+ To create jakarta-tomcat-connectors's autoconf script, you will need libtool
+ 1.3.3 or higher, and autoconf 2.13 or newer.<br>
+ Those tools will not be required if you are just using a package downloaded
+ from apache.org, they are only required for<br>
+ developers.<br>
+ <br>
+ To configure jakarta-tomcat-connectors run the following commands.<br>
+ <br>
+
+<pre> ./buildconf.sh (not required if there is allready the configure script)<br> ./configure [autoconf arguments] [jakarta-tomcat-connectors arguments]<br> make</pre>
+ <br>
+ It is possible to set <tt>CFLAGS</tt> and <tt>LDFLAGS </tt>to add
+ some platform specifics:<br>
+
+<pre> LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs</pre>
+
+<h4> Building for both Apache 1.3 and 2.0 using configure</h4>
+ If you want to build mod_jk for Apache 1.3 and 2.0, you should
+:<br>
+ <br>
+ use configure and indicate Apache 1.3 apxs location (--with-apxs)<br>
+ use make<br>
+ copy the mod_jk binary to the apache modules location<br>
+ <br>
+ make clean (to remove all previously compiled modules)<br>
+ use configure and indicate Apache 2.0 apxs location,<br>
+ then make.<br>
+ <br>
+ <tt>./configure --with-apxs=/usr/sbin/apxs<br>
+ make<br>
+ cp ./apache-1.3/mod_jk.so /usr/lib/apache<br>
+ make clean<br>
+ ./configure --with-apxs=/usr/sbin/apxs2<br>
+ make <br>
+ cp ./apache-2.0/mod_jk.so /usr/lib/apache2</tt><br>
+ <br>
+
+<h4> Examples using configure</h4>
+ Apache2.0, JNI support:<br>
+
+<pre> ./configure --with-apxs=/opt/apache2/bin/apxs --with-java-home=${JAVA_HOME} --with-java-platform=2 --enable-jni</pre>
+ Apache 1.3, no JNI support:<br>
+
+<pre> ./configure --with-apxs=/usr/sbin/apxs </pre>
+
+<h4> Configure arguments</h4>
+
+<table class="inlinetable">
+ <tbody>
+ <tr>
+ <th class="inlineth">
+ <p>Apache related parameters</p>
+ </th>
+ <th class="inlineth">
+ <p><br>
+ </p>
+ <br>
+ </th>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-apxs[=FILE]</p>
+ </td>
+ <td class="inlinetd">
+ <p>FILE is the location of the apxs tool. Default is finding apxs in
+ PATH.<br>
+ It builds a shared Apache module. It detects automaticly the Apache version.<br>
+ (2.0 and 1.3)</p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-apache=DIR </p>
+ </td>
+ <td class="inlinetd">
+ <p>DIR is the path where apache sources are located.<br>
+ The apache sources should have been configured before configuring mod_jk.<br>
+ DIR is something like: /home/apache/apache_1.3.19<br>
+ It builds a static Apache module.</p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--enable-EAPI</p>
+ </td>
+ <td class="inlinetd">
+ <p>This parameter is needed when using Apache-1.3 and mod_ssl, otherwise
+ you will get the error message: <br>
+ "this module might crash under EAPI!" when loading mod_jk.so in httpd.<br>
+ Not needed when --with-apxs has been used </p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-java-platform=VAL </p>
+ </td>
+ <td class="inlinetd">
+ <p>VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 anf higher,
+ should be guessed correctly. </p>
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+ <br>
+ <br>
+
+<table class="inlinetable">
+ <tbody>
+ <tr>
+ <th class="inlineth">
+ <p>JNI related parameters</p>
+ </th>
+ <th class="inlineth">
+ <p><br>
+ </p>
+ <br>
+ </th>
+ </tr>
+ <tr>
+ <td class="inlinetd">--enable-jni<br>
+ </td>
+ <td class="inlinetd">Build the JNI worker and so the build process
+will require some informations about your Java Environment<br>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-java-home=DIR</p>
+ </td>
+ <td class="inlinetd">
+ <p>DIR is the patch to the JDK root directory. Something like:
+ /opt/java/jdk12</p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-os-type[=SUBDIR] </p>
+ </td>
+ <td class="inlinetd">
+ <p>SUBDIR is the os-type subdirectory, normaly configure should guess
+ it correctly.</p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-arch-type[=SUBDIR]</p>
+ </td>
+ <td class="inlinetd">
+ <p>SUBDIR is the arch subdirectory, normaly configure should guess
+it correctly. </p>
+ </td>
+ </tr>
+ <tr>
+ <td class="inlinetd">
+ <p>--with-java-platform=VAL </p>
+ </td>
+ <td class="inlinetd">
+ <p>VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 anf higher,
+ should be guessed correctly. </p>
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+ <br>
+
+<h4> Notes</h4>
+
+<ul>
+ <li>Configure will locate your java environnement by looking at the JAVA_HOME
+env var if you didn't specify it with the parameter --with-java-home.</li>
+ <li>You should have perl 5 installed to make use of Apache apxs build
+script</li>
+ <li>After a successfull compilation you'll find the Apache 1.3 module in
+ <tt>apache-1.3/mod_jk.so</tt>, the Apache 2.0 in <tt>apache-2.0/mod_jk.so</tt>,
+the jni module will be <tt>in jni/jk_jnicb.so.</tt></li>
+ <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>If you compile mod_jk statically, you should determnie if Apache
+has EAPI support, and add the --enable-eapi flag to configure. When building
+with APXS, using DSO, apxs will set the compilation flags for 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>
+ <li>If apxs fails with <code>apxs:Break: Command failed with rc=255</code>,
+ it may have been damaged by mod_ssl. :<br>
+ <br>
+ <pre>Search for:
+
+my $CFG_LD_SHLIB = q(); # substituted via Makefile.tmpl<br>my $CFG_LDFLAGS_SHLIB = q(); # substituted via Makefile.tmpl
+ </pre>
+and change to: <br>
+ <pre>my $CFG_LD_SHLIB = q(ld); # substituted via Makefile.tmpl<br>my $CFG_LDFLAGS_SHLIB = q(-G); # substituted via Makefile.tmpl
+ </pre>
+ </li>
+</ul>
+<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>
+
+<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>
+ <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>info</i>, <i>error</i>, and <i>emerg</i>, but
+ <i>info</i> should be your default selection.</li>
+ <li>The directive <tt>JkOptions </tt>allow you to set many forwarding
+ options :</li>
+
+ <ul>
+ <li>With <tt>ForwardKeySize</tt>, <tt> </tt>you ask mod_jk,
+when using ajp13, to forward also the SSL Key Size as required by
+Servlet API 2.3. <br>
+ This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by
+default).</li>
+ <li>With <tt>ForwardURICompat</tt>, you told mod_jk to send the URI
+ to Tomcat normally, which is less spec compliant but mod_rewrite compatible,
+ use it for compatibility with Tomcat 3.2.x engines (on by default).</li>
+ <li>With <tt>ForwardURICompatUnparsed</tt>, the forwarded URI is
+unparsed, it's spec compliant but broke mod_rewrite.</li>
+ <li>With <tt>ForwardURIEscaped, </tt>the forwarded URI is escaped
+and Tomcat (till 3.3 rc2) will do the decoding part.</li>
+ <li>With <tt>ForwardDirectories</tt>, all directory requests with
+no index files are forwarded to Tomcat.</li>
+
+ </ul>
+ <li>The directive <tt>JkEnvVar </tt>allow you to forward an environment
+ vars from Apache server to Tomcat engine.<br>
+ </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>
+ <li>The directive <tt>JkRequestLogFormat</tt> will configure the format
+ of mod_jk individual request logging. Request logging is configured
+ and enabled on a per virtual host basis. To enable request logging
+for a virtual host just add a JkRequestLogFormat config. The syntax
+ of the format string is similiar to the Apache LogFormat command,
+here is a list of the avaialbe request log format options:
+
+ <ul>
+ <li>%b - Bytes sent, excluding HTTP headers. In CLF format</li>
+ <li>%B - Bytes sent, excluding HTTP headers.</li>
+ <li>%H - The request protocol</li>
+ <li>%m - The request method</li>
+ <li>%p - The canonical Port of the server serving the request</li>
+ <li>%q - The query string (prepended with a ? if a query string
+ exists, otherwise an empty string)</li>
+ <li>%r - First line of request</li>
+ <li>%s - request HTTP status code</li>
+ <li>%T - Requset duration, elapsed time to handle request in
+seconds '.' micro seconds</li>
+ <li>%U - The URL path requested, not including any query string.</li>
+ <li>%v - The canonical ServerName of the server serving the request.</li>
+ <li>%V - The server name according to the UseCanonicalName setting.</li>
+ <li>%w - Tomcat worker name</li>
+
+ </ul>
+ <br>
+ </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<br>AddModule mod_jk.c<br>JkWorkersFile /usr/local/jakarta-tomcat/conf/workers.properties<br>JkLogFile /usr/local/apache/logs/mod_jk.log<br>JkLogLevel info<br>JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "<br>JkOptions +<tt>ForwardKeySize</tt> +<tt>ForwardURICompat</tt> -<tt>ForwardDirectories</tt><br></pre>
+ </blockquote>
+ </div>
+
+<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>
+
+<pre>JkMount <i><URL prefix></i> <i><Worker name></i><br></pre>
+
+<p>For example the following directives will send all requests ending in <tt>.jsp</tt>
+or with <tt>/servlet</tt> as the second path componenet to the "<tt>ajp13</tt>"
+worker, but jsp requests to files located in /otherworker will go to "<tt>remoteworker</tt>".
+ </p>
+
+<blockquote>
+ <pre>JkMount /*.jsp ajp13<br>JkMount /*/servlet/ ajp13<br>JkMount /otherworker/*.jsp remoteworker<br></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>
+
+<h3><a name="s74">Configuring Apache to serve static web application files</a></h3>
+
+<div class="subsection">
+<p>If the Tomcat Host appBase (webapps) directory is accessible by the Apache
+ web server, Apache can be configured to serve web application context directory
+ static files instead of passing the request to Tomcat.</p>
+
+<p><b>Caution:</b> If Apache is configured to serve static pages for a web
+ application it bypasses any security contraints you may have configured
+in your web application web.xml config file.</p>
+
+<p>Use Apache's Alias directive to map a single web application context directory
+ into Apache's document space for a VirtualHost: </p>
+
+<pre># Static files in the examples webapp are served by apache<br>Alias /examples /export/home/web/host1/webapps/examples<br><br>JkMount /*.jsp ajp13<br>JkMount /*/servlet/ ajp13<br></pre>
+
+<p>Use the mod_jk JkAutoAlias directive to map all web application context
+ directories into Apache's document space. Attempts to access the <code>WEB-INF</code>
+ or <code>META-INF</code> directories within a web application context or
+ a Web Archive <code>*.war</code> within the Tomcat Host appBase (webapps)
+ directory will fail with an HTTP 403, Access Forbidden.</p>
+
+<p> Example configuration for an Apache VirtualHost: </p>
+
+<pre># Static files in all Tomcat webapp context directories are served by apache<br>JkAutoAlias /export/home/web/host2/webapps<br><br>JkMount /*.jsp ajp13<br>JkMount /*/servlet/ ajp13<br></pre>
+ </div>
+
+<hr>
+<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 /><br></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 ... ><br> ...<br> <ApacheConfig <i>options</i> /><br> ...<br>< /ContextManager ><br></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>
+ <li><b>jservconfig</b> - path to write apache jserv conf file to. If
+ not set, defaults to "conf/jserv/tomcat-apache.conf". </li>
+ <li><b>jkconfig</b> - path to write apacke mod_jk conf file to. If
+not set, defaults to "conf/jk/mod_jk.conf". </li>
+ <li><b>workersconfig</b> - path to workers.properties file used by
+mod_jk. If not set, defaults to "conf/jk/workers.properties". </li>
+ <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>
+ <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>
+ <li><b>jklog</b> - path to log file to be used by mod_jk.</li>
+
+</ul>
+
+<p> Example: </p>
+
+<blockquote>
+ <pre>...<br><br><AutoWebApp dir="webapps" host="DEFAULT" /><br><br><ApacheConfig confighome="/home/mydir" /><br><br>...</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<br> className="org.apache.tomcat.modules.server.Ajp13Interceptor"<br> port="8009"/><br></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).
+ <br>
+ <br>
+ 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.<br>
+ <br>
+ The example are over-simplified and incomplete but should get you started.
+ Also note the virtual host setup is new in Tomcat 3.2 - <i>this example
+won't work with Tomcat 3.1</i>.<br>
+ <br>
+
+<table class="inlinetable">
+ <tbody>
+ <tr>
+ <td class="inlinetd">
+ <blockquote>
+ <pre>.<br>.<br><Connector className="org.apache.tomcat.service.PoolTcpConnector"><br> <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/><br> <Parameter name="port" value="8007"/><br></Connector><br><br><Connector className="org.apache.tomcat.service.PoolTcpConnector"><br> <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/><br> <Parameter name="port" value="8009"/><br></Connector><br><br><Host name="host1.apache.org"><br> <Context path="" docBase="/web/host1" debug="0"/><br></Host><br><Host name="host2.apache.org"><br> <Context path="" docBase="/web/host2" debug="0"/><br></Host><br>.<br>.<br></pre>
+ </blockquote>
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+ <i>Table 1 - Excerpt from server.xml showing the Ajp13 Connector and
+two virtual hosts.</i> <br>
+ <br>
+
+<table class="inlinetable">
+ <tbody>
+ <tr>
+ <td class="inlinetd">
+ <blockquote>
+ <pre># Setup for Solaris system<br>#<br>workers.tomcat_home=/usr/local/jakarta-tomcat<br>workers.java_home=/usr/java<br>ps=/<br>worker.list=ajp12, ajp13<br><br># Definition for Ajp13 worker (Ajp12 left to readers imagination)<br>#<br>worker.ajp13.port=8009<br>worker.ajp13.host=localhost<br>worker.ajp13.type=ajp13<br></pre>
+ </blockquote>
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+ <i>Table 2 - Excerpt from workers.properties showing the Ajp13 worker</i>
+ <br>
+ <br>
+
+<table class="inlinetable">
+ <tbody>
+ <tr>
+ <td class="inlinetd">
+ <blockquote>
+ <pre># Load mod_jk<br>#<br>LoadModule jk_module libexec/mod_jk.so<br>AddModule mod_jk.c<br><br># Configure mod_jk<br>#<br>JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties<br>JkLogFile /usr/local/apache/logs/mod_jk.log<br>JkLogLevel info<br><br># First Virtual Host. Request logging is enabled.<br>#<br><VirtualHost 10.0.0.1:80><br> DocumentRoot /web/host1<br> ServerName host1.apache.org<br> JkRequestLogFormat "%w \"%r\" %s %T"<br> JkMount /*.jsp ajp13<br> JkMount /*/servlet/ ajp13<br></VirtualHost><br><br># Second Virtual Host. Also accessible via HTTPS<br>#<br><VirtualHost 10.0.0.2:80><br> DocumentRoot /web/host2<br> ServerName host2.apache.org<br> JkMount /*.jsp ajp13<br> JkMount /*/servlet/ ajp13<br></VirtualHost><br><br><VirtualHost 10.0.0.2:443><br> DocumentRoot /web/host2<br> ServerName host2.apache.org<br> SSLEngine On<br> JkMount /*.jsp ajp13<br> JkMount /*/servlet/ ajp13<br></VirtualHost><br><br></pre>
+ </blockquote>
+ </td>
+ </tr>
+
+ </tbody>
+</table>
+ <i>Table 3 - Excerpt from Apaches httpd.conf showing JK directives.</i>
+
+<hr>
+<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 mod_jk Documentation
+ included in the doc directory. Documentation is also available on
+the Apache Jakarta web site for Tomcat at <a
+ href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/doc/index.html">http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/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. Now that mod_jk moved to jakarta-tomcat-connectors repository, the
+source and binaries for mod_jk are present in the jakarta-tomcat-connectors
+directory at jakarta.apache.org. You'll find jk release at : <a
+ href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/">
+http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/ </a> .
+
+<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 it. There is more information in
+the <a href="tomcat-workers-howto.html">workers.properties howto</a> document,
+ajp12 is now deprecated. Also ajp13 is supported by all Apache Tomcat
+including 3.2.x , 3.3.x, 4.0.x, 4.1.x and the new tomcat 5. Also others Servlet
+engine like jetty have support for Ajp13.
+<h3>Q. Whenever I restart Tomcat, Apache locks up!</h3>
+ 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.
+<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<br># gzip -dc apache_1.3.19.tar.gz|tar xvf -<br># cd apache_1.3.19<br># ./configure --prefix=/usr/local/apache \<br> --enable-module=most \<br> --enable-shared=max<br># make<br># 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.<br>
+</p>
+<h3>Q. Apache 2.0 complains about incorrect module version</h3>
+ A. Since Apache 2.0 API still change often, the Apache 2.0 teams decide
+to put in headers of compiled modules the Apache 2.0 version used to compile
+the module. At start time Apache 2.0 check that version in modules headers
+and stop if it detect that a module was compiled for another Apache 2.0 version.
+As such you should allways use modules compiled for the same Apache 2.0 version.
+This check may be removed if the future.<br>
+<h3>Q. JNI didn't works with Apache 1.3</h3>
+ A. JNI support require a multi-threaded environment which is not the
+case for Apache 1.3. You should verify if Apache 1.3 has been build with
+thread support and if not you could add the LoadModule "/usr/lib/libpthreads.so"
+in your httpd.conf. Also keep in mind that JNI is suited for multi-threaded
+servers and you should consider upgrading to Apache 2.0 to support JNI.<br>
+<h3>Q. JNI report that JVM couldn't be started under Linux</h3>
+ A. Under Linux, you should set some environment variables BEFORE launching
+your Apache server :<br>
+<pre>export LD_LIBRARY_PATH=$jre/bin:$jre/bin/classic:$LD_LIBRARY_PATH</pre>
+Also some Linux distributions have enabled a GLIBC feature called 'floating
+stacks' which may not works with kernel less than 2.4.10 on SMP machines.
+You should disable floating stacks by exporting an environment variable :<br>
+<pre>export LD_ASSUME_KERNEL=2.2.5<br></pre>
+You could have to update your service scripts, ie <tt>/etc/rc.d/init.d/httpd</tt>,
+to set these env vars before your httpd server starts.<br>
+
+<h3>Q. I've got a firewall between my WebServer and Tomcat who drop ajp13
+connections after some times</h3>
+ A. Ajp13 use persistant connections where the traffic could be null
+if there is no request to be sent to Tomcat. Firewall used to drop inactive
+connections and will make your WebServer and Tomcat think the connection
+is valid. In mod_jk 1.2.0 a <tt>socket_keepalive</tt><tt></tt> property
+as been added to ajp13 settings, and you should take a look at it in <a
+ href="file:///D:/jakarta-tomcat-connectors/jk/doc/tomcat-workers-howto.html">workers.properties
+howto</a><br>
+
+<h3>Q. Under heavy load, I've got many threads in Tomcat even if my Apache
+Web Server handle much of the load</h3>
+ A. Under heavy load, Apache WebServer create many childs to handle
+the load, which will in turn create many connections to Tomcat to forward
+the requests they should handle. Apache WebServer will normally kill the
+childs/threads when the load decrease. But if the load is still there and
+even if only Apache handle the requests, ie static contents, the childs are
+kept and with them the ajp13 connections, even if they are no more used.
+In mod_jk 1.2.0 <tt>cache_timeout </tt>and <tt>socket_timeout </tt>properties
+as been added to close connections after some time, for more informations
+refer to <a
+ href="file:///D:/jakarta-tomcat-connectors/jk/doc/tomcat-workers-howto.html">workers.properties
+howto</a><br>
+ <br>
+<br>
+
+<hr>
+<h2><a name="s11">Credits</a></h2>
+
+<p>This document was originally created by <a
+ href="mailto:shachor@il.ibm.com">Gal Shachor</a></p>
+
+<p>Revisions by (Alphabetical)</p>
+
+<p>Mike Braden <tt><<a href="mailto:mikeb@mwbinc.com">mikeb@mwbinc.com</a>></tt><br>
+ Mike Bremford<br>
+ Henri Gomez <tt><<a href="mailto:hgomez@apache.org">hgomez@apache.org</a>></tt><br>
+ Glenn Nielsen<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">
+ <tbody>
+ <tr>
+ <td>
+ <p class="fineprint"> 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>
+ </tr>
+
+ </tbody>
+</table>
+ <br>
+ <br>
+ <br>
+ <br>
+</body>
+</html>
1.1 jakarta-tomcat-connectors/jk/doc/tomcat-workers-howto.html
Index: tomcat-workers-howto.html
===================================================================
<html>
<head>
<!-- $Id: tomcat-workers-howto.html,v 1.1 2002/08/29 08:25:39 hgomez Exp $ -->
<!-- Copyright 1999, Apache Software Foundation -->
<meta http-equiv=Content-Type content="text/html">
<link rel="stylesheet" href=style.css>
<style type="text/css">
td {
background-color: #E0E0E0;
vertical-align: text-top;
border-top: thick black;
border-right: thick black;
border-bottom: thick black;
border-left: thick black;
}
th {
background-color: #d0d0d0;
border-top: thick black;
border-right: thick black;
border-bottom: thick black;
border-left: thick black;
}
table {
width: 75%;
border: thick;
background-color: #000000;
}
</style>
<title>Tomcat Workers HowTo</title>
</head>
<body>
<h1>Tomcat workers.properties</h1>
<p>By Gal Shachor <tt><<a href="mailto:shachor@il.ibm.com">
shachor@il.ibm.com</a>></tt></p>
<p>A Tomcat worker is a Tomcat instance that is waiting to
execute servlets on behalf of some web server. For example, we can have a web
server such as Apache forwarding servlet requests to a Tomcat process (the
worker) running behind it. </p>
<p>The scenario described above is a very simple one; in fact
one can configure multiple Tomcat workers to serve servlets on behalf of a
certain web server. The reasons for such configuration can be:</p>
<ul>
<li>We
want different contexts to be served by different Tomcat workers to
provide a development environment where all the developers share the same
web server but own a Tomcat worker of their own.</li>
<li>We
want different virtual hosts served by different Tomcat processes to
provide a clear separation between sites belonging to different companies.</li>
<li>We
want to provide load balancing, meaning run multiple Tomcat workers each
on a machine of its own and distribute the requests between them.</li>
</ul>
<p>There are probably more reasons for having multiple workers
but I guess that this list is enough... </p>
<p>Tomcat workers are defined in a properties file dubbed
workers.properties and this tutorial explains how to work with it.</p>
<h2>Defining Workers</h2>
<p>Defining workers to the Tomcat web server plugin can be done
using a properties file (a sample file named workers.properties is available in
the conf/ directory); the file contains entries of the following form:</p>
<p>worker.list=<a comma separated list of worker names></p>
<p>For example, <tt>worker.list= ajp12, ajp13</tt></p>
<p>And </p>
<p>worker.<worker name>.<property>=<property
value></p>
<p>For example, <tt>worker.local.port=8007</tt></p>
<p>When starting up, the web server plugin will instantiate the
workers whose name appears in the worker.list property, these are also the
workers to whom you can map requests. </p>
<p>Each named worker should also have a few entries to provide
additional information on his behalf; this information includes the worker's
type and other related worker information. Currently the following worker types
that exists are (Tomcat 3.2-dev): </p>
<table>
<tr>
<th>
<p>Worker type</p>
</th>
<th>
<p>Description</p>
</th>
</tr>
<tr>
<td bgcolor="#FeFeFe">ajp12</p>
</td>
<td bgcolor="#FeFeFe">
<p>This worker knows how to forward requests to
out-of-process Tomcat workers using the ajpv12 protocol.</p>
</td>
</tr>
<tr>
<td>
<p>ajp13</p>
</td>
<td>
<p>This worker knows how to forward requests to
out-of-process Tomcat workers using the ajpv13 protocol.</p>
</td>
</tr>
<tr>
<td>
<p>jni</p>
</td>
<td>
<p>This worker knows how to forward requests to in-process
Tomcat workers using JNI.</p>
</td>
</tr>
<tr>
<td>
<p>lb</p>
</td>
<td>
<p>This is a load-balancing worker; it knows how to provide
round-robin based sticky load balancing with a certain level of
fault-tolerance.</p>
</td>
</tr>
</table>
<p>Defining workers of a certain type should be done with the
following property format:</p>
<p>worker.<worker name>.type=<worker type></p>
<p>Where worker name is the name assigned to the worker and the
worker type is one of the four types defined in the table (a worker name may
not contain any space (a good naming convention for queue named should follow
the Java variable naming rules).</p>
<p>For example:</p>
<table>
<tr>
<th>
<p>Worker definition</p>
</th>
<th>
<p>Meaning</p>
</th>
</tr>
<tr>
<td>
<p>worker.local.type=ajp12</p>
</td>
<td>
<p>Defines a worker named "local" that uses the ajpv12 protocol
to forward requests to a Tomcat process.</p>
</td>
</tr>
<tr>
<td>
<p>worker.remote.type=ajp13</p>
</td>
<td>
<p>Defines a worker named "remote" that uses the ajpv13 protocol
to forward requests to a Tomcat process.</p>
</td>
</tr>
<tr>
<td>
<p>worker.fast.type=jni</p>
</td>
<td>
<p>Defines a worker named "fast" that uses JNI
to forward requests to a Tomcat process.</p>
</td>
</tr>
<tr>
<td>
<p>worker.loadbalancer.type=lb</p>
</td>
<td>
<p>Defines a worker named "loadbalancer" that
loadbalances several Tomcat processes transparently.</p>
</td>
</tr>
</table>
<h2>Setting Worker Properties</h2>
<p>After defining the workers you can also specify properties
for them. Properties can be specified in the following manner:</p>
<p>worker.<worker name>.<property>=<property
value></p>
<p>Each worker has a set of properties that you can set as
specified in the following subsections:</p>
<h3>ajp12 Worker properties</h3>
<p>The ajp12 typed workers forward requests to out-of-process
Tomcat workers using the ajpv12 protocol over TCP/IP sockets. The following
table specifies properties that the ajp12 worker can accept:</p>
<table>
<tr>
<th>
<p>Property name</p>
</th>
<th>
<p>Meaning</p>
</th>
<th>
<p>Example</p>
</th>
</tr>
<tr>
<td>
<p>port</p>
</td>
<td>
<p>The port where the Tomcat worker is listening for ajp12
requests.</p>
</td>
<td>
<p>worker.local.port=8007</p>
</td>
</tr>
<tr>
<td>
<p>host</p>
</td>
<td>
<p>The host where the Tomcat worker is listening for ajp12
requests.</p>
</td>
<td>
<p>worker.local.host=www.x.com</p>
</td>
</tr>
<tr>
<td>
<p>lbfactor</p>
</td>
<td>
<p>When working with a load balancer worker, this is the
load-balancing factor for the worker. (More on this in the lb worker section).</p>
</td>
<td>
<p>worker.local.lbfactor=2.5</p>
</td>
</tr>
</table>
<h3>ajp13 Worker properties</h3>
<p>The ajp13 typed workers forward requests to out-of-process
Tomcat workers using the ajpv13 protocol over TCP/IP sockets. The main
difference between ajpv12 and ajpv13 are that:</p>
<ol>
<li>ajpv13
is a more binary protocol and it try to compress some of the request data
by coding frequently used strings as small integers.</li>
<li>ajpv13
reuse open sockets and leaves them open for future requests.</li>
<li>ajpv13
has special treatment for SSL information so that the container can
implement SSL related methods such as isSecure().</li>
</ol>
<p>The following table specifies properties that the ajp13
worker can accept:</p>
<table>
<tr>
<th>
<p>Property name</p>
</th>
<th>
<p>Meaning</p>
</th>
<th>
<p>Example</p>
</th>
</tr>
<tr>
<td>
<p>port</p>
</td>
<td>
<p>The port where the Tomcat worker is listening for ajp13
requests.</p>
</td>
<td>
<p>worker.local13.port=8007</p>
</td>
</tr>
<tr>
<td>
<p>host</p>
</td>
<td>
<p>The host where the Tomcat worker is listening for ajp13
requests.</p>
</td>
<td>
<p>worker.local13.host=www.x.com</p>
</td>
</tr>
<tr>
<td>
<p>lbfactor</p>
</td>
<td>
<p>When working with a load balancer worker, this is the
load-balancing factor for the worker. (More on this in the lb worker
section).</p>
</td>
<td>
<p>worker.local13.lbfactor=2.5</p>
</td>
</tr>
<tr>
<td>
<p>cachesize</p>
</td>
<td>
<p>Specifies the number of open socket connections that the
worker will keep. By default this value is 1, but multithreaded web servers
such as Apach2.xx, IIS and Netscape will benefit the most by setting this
value to a higher level (such as the estimated average concurrent users for
Tomcat)</p>
</td>
<td>
<p>worker.local13.cachesize=30</p>
</td>
</tr>
</table>
<h3>lb Worker properties</h3>
<p>The load-balancing worker does not really communicate with
Tomcat workers; instead it is responsible for the management of several
"real" workers. This management includes:</p>
<ul>
<li>Instantiating
the workers in the web server.</li>
<li>Using
the worker's load-balancing factor, perform weighed-round-robin load
balancing where high lbfactor means stronger machine (that is going to
handle more requests)</li>
<li>Keeping
requests belonging to the same session executing on the same Tomcat
worker.</li>
<li>Identifying
failed Tomcat workers, suspending requests to them and instead
fall-backing on other workers managed by the lb worker.</li>
</ul>
<p>The overall result is that workers managed by the same lb
worker are load-balanced (based on their lbfactor and current user session) and
also fall-backed so a single Tomcat process death will not "kill" the
entire site.</p>
<p>The following table specifies properties that the lb worker
can accept:</p>
<table>
<tr>
<th>
<p>Property name</p>
</th>
<th>
<p>Meaning</p>
</th>
<th>
<p>Example</p>
</th>
</tr>
<tr>
<td>
<p>balanced_workers</p>
</td>
<td>
<p>A comma separated list of workers that the load balancer
need to manage. These workers should not appear in the worker.list
property.</p>
</td>
<td>
<p>worker.loadbalancer.balanced_workers= local13, local12</p>
</td>
</tr>
</table>
<h3>jni Worker properties</h3>
<p>The jni worker opens a JVM inside the web server process and
executes Tomcat within it (that is in-process). Following that, messages to and
from the JVM are passed using JNI method calls, this makes the jni worker
faster then the out-of-process workers that need to communicate to the Tomcat
workers by writing AJP messages over TCP/IP sockets.</p>
<p>Note: Since the JVM is multithreaded; the jni worker should
be used only within multithreaded servers such as AOLServer, IIS, Netscape and
Apache2.0. You should also make sure that the threading scheme used by the web
servers match the one used to build the jk web server plugin.</p>
<p>Since the jni worker opens a JVM it can accept many
properties that it forward to the JVM such as the classpath etc. as we can see
in the following table.</p>
<table>
<tr>
<th>
<p>Property name</p>
</th>
<th>
<p>Meaning</p>
</th>
<th>
<p>Example</p>
</th>
</tr>
<tr>
<td>
<p>class_path</p>
</td>
<td>
<p>The classpath as used by the in-process JVM. This should
point to all Tomcats' jar/file files as well as any class or other jar file
that you want to add to the JVM.</p>
<p>You should remember to also add Javac to the classpath.
This can be done in Java2 by adding tools.jar to the classpath. In JDK1.xx
you should just add classes.zip.</p>
<p>The class_path property can be given in multiple lines. In
this case the jk environment will concatenate all the classpath entries
together by putting path delimiter (":"/";") between the
entries.</p>
</td>
<td>
<p>worker.localjni.class_path=path-to-some-jarfile</p>
<p>worker.localjni.class_path=path-to-class-directory</p>
</td>
</tr>
<tr>
<td>
<p>cmd_line</p>
</td>
<td>
<p>The command line that is handed over to Tomcats' startup
code. </p>
<p>The cmd_line property can be given in multiple lines. In
this case the jk environment will concatenate all the cmd_line entries
together by putting spaces between the entries.</p>
</td>
<td>
<p>worker.localjni.cmd_line=-config</p>
<p>worker.localjni.cmd_line=path-to-tomcats-server.xml-file</p>
<p>worker.localjni.cmd_line=-home</p>
<p>worker.localjni.cmd_line=-path-to-tomcat-home</p>
</td>
</tr>
<tr>
<td>
<p>jvm_lib</p>
</td>
<td>
<p>Full path to the JVM implementation library. The jni
worker will use this path to load the JVM dynamically.</p>
</td>
<td>
<p>worker.localjni.jvm_lib=full-path-to-jvm.dll</p>
</td>
</tr>
<tr>
<td>
<p>stdout</p>
</td>
<td>
<p>Full path to where the JVM write its System.out</p>
</td>
<td>
<p>worker.localjni.stdout=full-path-to-stdout-file</p>
</td>
</tr>
<tr>
<td>
<p>stderr</p>
</td>
<td>
<p>Full path to where the JVM write its System.err</p>
</td>
<td>
<p>worker.localjni.stderr=full-path-to-stderr-file</p>
</td>
</tr>
<tr>
<td>
<p>sysprops</p>
</td>
<td>
<p>Java system properties for the JVM</p>
</td>
<td>
<p>worker.localjni.sysprops=some-property</p>
</td>
</tr>
<tr>
<td>
<p>ld_path</p>
</td>
<td>
<p>Additional dynamic libraries path (similar in nature to
LD_LIBRARY_PATH)</p>
</td>
<td>
<p>worker.localjni.ld_path=some-extra-dynamic-library-path</p>
</td>
</tr>
</table>
<h2>Property file macros</h2>
<p>Starting with Tomcat3.2 you can define "macros" in
the property files. These macros let you define properties and later on use
them while constructing other properties. For example the following fragment:</p>
<pre>
workers.tomcat_home=d:\tomcat
workers.java_home=d:\sdk\jdk1.2.2
ps=\
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes
worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar
</pre>
<p>Will end up with the following values for the
worker.inprocess.class_path properties</p>
<pre>
worker.inprocess.class_path= d:\tomcat\classes
worker.inprocess.class_path=d:\sdk\jdk1.2.2\lib\tools.jar
</pre>
<h2>The sample worker.properties</h2>
<p>Since coping with worker.properties on your own is not an
easy thing to do, a sample worker.properties file is bundled along with
Tomcat3.2-dev (and above). The file is meant to be as <b>generic</b> as
possible and it uses the property macros extensively.</p>
<p>The sample worker.properties contains the following high
level definitions:</p>
<ol>
<li>An
ajp12 worker that used the host localhost and the port 8007</li>
<li>An
ajp13 worker that used the host localhost and the port 8008</li>
<li>A jni
worker</li>
<li>A lb
worker that load balance the ajp12 and ajp13 workers</li>
</ol>
<p>The ajp12, ajp13 and lb worker definitions can work without
modifying the file. However to make the jni worker come into life you should
set the following properties in the file:</p>
<ul>
<li>workers.tomcat_home
- Have it point to your tomcat_home. E.g. wrkers.tomcat_home=d:\tomcat</li>
<li>workers.java_home
- Have it point to where you placed your JDK. E.g.
workers.java_home=c:\jdk1.2.2</li>
<li>ps - Have it point to the file system
separator of your OS. E.g. ps=\</li>
</ul>
<p>When you are done, the default jni worker <b>should</b>
work.</p>
</body>
</html>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>