<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="apache.html">

  &project;
<copyright>
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
</copyright>
<properties>
<title>Apache HTTP Server HowTo</title>
<author email="hgomez@apache.org">Henri Gomez</author>
<author email="shachor@il.ibm.com">Gal Shachor</author>
</properties>
<body>
<section name="Introduction">
<p>
This document explains how to connect Tomcat to the popular open source web server, Apache HTTP Server.
You can use the connection module mod_jk with any version of Apache starting with 1.3 and any version
of Tomcat starting with (at least) 3.2.
</p>

<p>
It is recommended that you also read the
<a href="../common_howto/workers.html">Workers HowTo</a> document
to learn how to setup the working entities between your web server and Tomcat Engines.
For more detailed configuration information consult the Reference Guide for
<a href="../reference/workers.html">workers.properties</a>,
<a href="../reference/uriworkermap.html">uriworkermap</a>
and <a href="../reference/apache.html">Apache</a>.
</p>

<p><b>Warning: If Apache and Tomcat are configured to serve content from
the same file system location then care must be taken to ensure that Apache is
not able to serve inappropriate content such as the contents of the WEB-INF
directory or JSP source code.</b> This could occur if the Apache DocumentRoot
overlaps with a Tomcat Host's appBase or the docBase of any Context. It could
also occur when using the Apache Alias directive with a Tomcat Host's appBase or
the docBase of any Context.
</p>

<p>
This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
but has been split off for organisational reasons.
</p>

<subsection name="Document Conventions and Assumptions">
<p>
${tomcat_home} is the root directory of tomcat.
Your Tomcat installation should have the following subdirectories:

<ul>
<li>
${tomcat_home}\conf - Where you can place various configuration files
</li>
<li>
${tomcat_home}\webapps - Containing example applications
</li>
<li>
${tomcat_home}\bin - Where you place web server plugins
</li>
</ul>
</p>
<p>
In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>.
A <a href="../common_howto/workers.html">worker</a> is defined to be a tomcat process that accepts work from the Apache server.
</p>
</subsection>

<subsection name="Supported Configuration">
<p>
The mod_jk module was developed and tested on:
<ul>
<li>
Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should work on major Unixes platforms
supporting Apache 1.3 and/or 2.x
</li>
<li>
WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98
</li>
<li>
Cygwin (until you have an Apache server and autoconf/automake support tools)
</li>
<li>
i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed.
</li>
<li>
Tomcat 3.2 to Tomcat 8.
</li>
</ul>
</p>

<p>
The mod_jk module uses the AJP protocol to send requests to the Tomcat containers.
The AJP version typically used is <b>ajp13</b>.
</p>
</subsection>

<subsection name="Who supports AJP protocols?">
<p>
Tomcat supports ajp13 since Tomcat 3.2.
Others servlet engines such as <b>Jetty</b> or <b>JBoss</b> also support the ajp13 protocol
</p>

<p>
The <b>ajp12</b> protocol has been <b>deprecated</b> and you should no longer use it.
The <b>ajp14</b> protocol is considered experimental.
</p>

</subsection>

<subsection name="How does it work ?">
<p>
In a nutshell a web server is waiting for client HTTP requests.
When these requests arrive the server does whatever is needed to serve the
requests by providing the necessary content.
</p>

<p>
Adding a servlet container may somewhat change this behaviour.
Now the web server needs also to perform the following:
</p>

<ul>
<li>
Load the servlet container adaptor library and initialise it (prior to serving requests).
</li>
<li>
When a request arrives, it needs to check and see if a certain request belongs to a servlet,
if so it needs to let the adaptor take the request and handle it.
</li>
</ul>

<p>
The adaptor on the other hand needs to know what requests it is going to serve,
usually based on some pattern in the request URL, and to where to direct these requests.
</p>

<p>
Things are even more complex when the user wants to set a configuration that uses virtual hosts,
or when they want multiple developers to work on the same web server
but on different servlet container JVMs.
We will cover these two cases in the advanced sections.
</p>

</subsection>

</section>

<section name="Obtaining mod_jk">
<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.
</p>

<p>
It is recommended to use the binary version if one is available.
If the binary is not available, follow the instructions
given in the below &quot;Building mod_jk&quot; sections for building mod_jk from source.
The mod_jk source can be downloaded from a mirror
<a href="http://tomcat.apache.org/download-connectors.cgi">
here</a>
</p>

<p>
The binaries for mod_jk are now available for several platforms.
The binaries are located in subdirectories by platform.
</p>

<p>
For some platforms, such as Windows, this is the typical way of obtaining mod_jk
since most Windows systems do not have C compilers.
</p>

<p>
For others, the binary distribution of mod_jk offers simpler installation.
</p>

<p>
For example JK 1.2.x can be downloaded from a mirror
<a href="http://tomcat.apache.org/download-connectors.cgi">
here</a> (look for JK 1.2 Binary Releases). The "JK 1.2 Binary Releases" link contains binary version for a variety of
operating systems for both Apache 1.3 and Apache 2.x.
</p>

</section>

<section name="Installation">
<p>
mod_jk requires two entities:

<ul>
<li>
<b>mod_jk.xxx</b> - The Apache HTTP Server module, depending on your operating system, it will be mod_jk.so, mod_jk.nlm
or MOD_JK.SRVPGM (see the build section).
</li>
<li>
<b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes).
A sample workers.properties can be found under the conf directory in the source download.
</li>
</ul>
</p>

<p>
Also as with other Apache modules, mod_jk should be first installed on the modules directory of your
Apache HTTP Server, ie: /usr/lib/apache and you should update your <b>httpd.conf</b> file.
</p>


<subsection name="Disabling old mod_jserv">
<p>
If you've previously configured Apache to use <b>mod_jserv</b>, remove any <b>ApJServMount</b> directives
from your httpd.conf.
</p>

<p>If you're including <b>tomcat-apache.conf</b> or <b>tomcat.conf</b>, you'll want to remove them as well -
they are specific to <b>mod_jserv</b>.
</p>

<p>
The mod_jserv configuration directives are not compatible with mod_jk !
</p>
</subsection>

<subsection name="Using Tomcat auto-configure">
<warn>Tomcat auto-configure is deprecated and has been removed in Tomcat 7 and later.</warn>
<p>
The auto-configure works only for a single Tomcat running on the same machine where the Apache HTTP Server is running.
The simplest way to configure Apache HTTP Server to use mod_jk is to turn on the Apache HTTP Server 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>

<source># To be added at the end of your httpd.conf
Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto
</source>

<p>
Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf
</p>

<p>
This will tell the Apache HTTP Server to use directives in the <b>mod_jk.conf-auto</b> file in
the Apache configuration. This file is created by enabling the Apache
auto-configuration by creating your workers.properties file at
$TOMCAT_HOME/conf/jk/workers.properties and adding the listener to the Engine
element in the server.xml file as per the following example.
<b>Please note that this example is specific to Tomcat 5.x, unlike other sections of this document
   which also apply to previous Tomcat branches.</b>
</p>
<source>...
&lt;Engine ...&gt;
  ...
    &lt;Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" /&gt;
  ...
&lt;/Engine&gt;
...
</source>

<p>
Then restart Tomcat and mod_jk.conf should be generated. For more information on
this topic, please refer to the API documentation at the
<a href="http://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/jk/config/ApacheConfig.html">
Tomcat docs website</a>.
</p>

</subsection>

<subsection name="Custom mod_jk configuration">
<p>
You should use custom configuration when:
</p>
<ul>
<li>
You couldn't use <b>mod_jk.conf-auto</b> since Tomcat engine isn't on the same machine that your Apache web server,
ie when you have an Apache in front of a Tomcat Farm.
</li>
<li>
Another case for custom configuration is when your Apache is in front of many different Tomcat engines,
each one having it's own configuration, a general case in ISP hosting
</li>
<li>
Also most Apache web masters will retain custom configuration to be able to tune the settings
to their real needs.
</li>
</ul>

</subsection>

<subsection name="Simple configuration example">
<p>
Here is a simple configuration:
</p>

<source># Load mod_jk module
LoadModule    jk_module  modules/mod_jk.so
# Add the module (activate this lne for Apache 1.3)
# AddModule     mod_jk.c
# Where to find workers.properties
JkWorkersFile /etc/httpd/conf/workers.properties
# Where to put jk shared memory
JkShmFile     /var/log/httpd/mod_jk.shm
# Where to put jk logs
JkLogFile     /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel    info
# Send requests for context /examples to worker named worker1
JkMount  /examples/* worker1
</source>

</subsection>
</section>

<section name="mod_jk Directives">
<p>
We'll discuss here the mod_jk directives and details behind them
</p>

<subsection name="Define workers">
<p>
<b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions.

<source>JkWorkersFile     /etc/httpd/conf/workers.properties
</source>

</p>
</subsection>

<subsection name="Logging">
<p>
<b>JkLogFile</b> specify the location where mod_jk is going to place its log file.
</p>

<source>JkLogFile     /var/log/httpd/mod_jk.log
</source>

<p>
Since JK 1.2.3 for Apache 2.x and JK 1.2.16 for Apache 1.3 this can also
be used for piped logging:
</p>

<source>JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
</source>

<p>
<b>JkLogLevel</b>
set the log level between:
</p>

<ul>
<li>
<b>info</b> log will contains standard mod_jk activity (default).
</li>
<li>
<b>error</b> log will contains also error reports.
</li>
<li>
<b>debug</b> log will contains all information on mod_jk activity
</li>
</ul>

<source>JkLogLevel    info
</source>

<p>
<code>info</code> should be your default selection for normal operations.
</p>

<p>
<b>JkLogStampFormat</b> will configure the date/time format found on mod_jk logfile.
See the mod_jk <a href="../reference/apache.html">Apache HTTP Server reference</a> for details.
</p>

<source>JkLogStampFormat "[%y-%m-%d %H:%M:%S.%Q] "
</source>

<p>
You can log mod_jk information using the Apache standard module <b>mod_log_config</b>.
The module sets several notes in the Apache notes table.
Most of them are are only useful in combination with a load balancer worker.
See the mod_jk <a href="../reference/apache.html">Apache HTTP Server reference</a> for details.
</p>

<source>LogFormat     "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \
              %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log
CustomLog     logs/access_log     mod_jk_log
</source>

<p>
You can also log a request protocol in the mod_jk log file instead of
the access log. This is not recommended and mostly a backward compatibility
feature. The directive <b>JkRequestLogFormat</b> will configure the format
of this protocol. It gets configured and enabled on a per virtual host basis.
See the mod_jk <a href="../reference/apache.html">Apache HTTP Server reference</a> for details.
</p>

<source>JkRequestLogFormat     "%w %V %T"
</source>

</subsection>

<subsection name="Forwarding">
<p>
The directive JkOptions allow you to set many forwarding options which will enable (+)
or disable (-) following option. Without any leading signs, options will be enabled.
</p>

<p>
The four following options <b>+ForwardURIxxx</b> are mutually exclusive.
Exactly one of them is required, a negative sign prefix is not allowed with them.
The default value is "ForwardURIProxy" since version 1.2.24.
It was "ForwardURICompatUnparsed" in version 1.2.23 and
"ForwardURICompat" until version 1.2.22.
You can turn the default off by switching on one of the other two options.
You should leave this at it's default value, unless you have a very good
reason to change it.
</p>

<p>
All options are inherited from the global server to virtual hosts.
Options that support enabling (plus options) and disabling (minus options),
are inherited in the following way:
<br/>
options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)
<br/>
</p>

<p>
Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI
will be partially reencoded after processing inside Apache and
before forwarding to Tomcat. This will be compatible with local
URL manipulation by mod_rewrite and with URL encoded session ids.

<source>JkOptions     +ForwardURIProxy
</source>

</p>

<p>
Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI
will be unparsed. It's spec compliant and secure.
It will always forward the original request URI, so rewriting
URIs with mod_rewrite and then forwarding the rewritten URI
will not work.

<source>JkOptions     +ForwardURICompatUnparsed
</source>

</p>
<p>
Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will
be decoded by Apache. Encoded characters will be decoded and
explicit path components like ".." will already be resolved.
This is less spec compliant and is <b>not safe</b> if you are using
prefix JkMount. This option will allow to rewrite URIs with
mod_rewrite before forwarding.

<source>JkOptions     +ForwardURICompat
</source>

</p>
<p>
Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will
be the encoded form of the URI used by ForwardURICompat.
Explicit path components like ".." will already be resolved.
This will not work in combination with URL encoded session IDs,
but it will allow to rewrite URIs with mod_rewrite before forwarding.

<source>JkOptions     +ForwardURIEscaped
</source>

</p>

<p>
JkOptions <b>RejectUnsafeURI</b> will block all
URLs, which contain percent signs '%' or backslashes '\'
after decoding.
</p>
<p>
Most web apps do not use such URLs. Using the option RejectUnsafeURI, you
can block several well known URL encoding attacks. By default, this option
is not set.
</p>
<p>
You can also realise such a check with mod_rewrite, which is more powerful
but also slightly more complicated.

<source>JkOptions     +RejectUnsafeURI
</source>

</p>

<p>
JkOptions <b>CollapseSlashesAll</b> is deprecated as of 1.2.44 and will be
ignored if used.
</p>

<p>
JkOptions <b>CollapseSlashesUnmount</b> is deprecated as of 1.2.44 and will be
ignored if used.
</p>

<p>
JkOptions <b>CollapseSlashesNone</b> is deprecated as of 1.2.44 and will be
ignored if used.
</p>

<p>
JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b>
directive of Apache. As such mod_dir should be available to Apache,
statically or dynamically (DSO)
</p>

<p>
When DirectoryIndex is configured, Apache will create sub-requests for
each of the local-url's specified in the directive, to determine if there is a
local file that matches (this is done by stat-ing the file).
</p>

<p>
If ForwardDirectories is set to <b>false</b> (default) and Apache doesn't find any
files that match, Apache will serve the content of the directory (if directive
Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if
directive Options doesn't specify Indexes for that directory).
</p>

<p>
If ForwardDirectories is set to <b>true</b> and Apache doesn't find any files that
match, the request will be forwarded to Tomcat for resolution. This is used in
cases when Apache cannot see the index files on the file system for various
reasons: Tomcat is running on a different machine, the JSP file has been
precompiled etc.
</p>

<p>Note that locally visible files will take precedence over the
ones visible only to Tomcat (i.e. if Apache can see the file, that's the one
that's going to get served). This is important if there is more then one type of
file that Tomcat normally serves - for instance Velocity pages and JSP pages.

<source>JkOptions     +ForwardDirectories
</source>
</p>

<p>
Setting JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address
of the Apache HTTP Server instead of remote client address. This can be used by
Tomcat remote address valve for allowing connections only from configured Apache
servers.

<source>JkOptions     +ForwardLocalAddress
</source>
</p>

<p>
Setting JkOptions <b>ForwardPhysicalAddress</b>, you ask mod_jk to send the
physical peer TCP IP address as the client address. By default mod_jk
uses the logical address as provided by the web server. For example the module
mod_remoteip sets the logical IP address to the client IP forwarded by proxies
in the <code>X-Forwarded-For</code> header.

<source>JkOptions     +ForwardPhysicalAddress
</source>
</p>

<p>
JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection
buffer after each AJP packet chunk received from Tomcat. This option can have
a strong performance penalty for Apache and Tomcat as writes are performed
more often than would normally be required (ie: at the end of each
response).

<source>JkOptions     +FlushPackets
</source>

</p>

<p>
JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection
buffer after the response headers have been  received from Tomcat.

<source>JkOptions     +FlushHeader
</source>

</p>

<p>
JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately
after their use. Normally mod_jk uses persistent connections and pools idle
connections to reuse them, when new requests have to be sent to Tomcat.
</p>

<p>
Using this option will have a strong performance penalty for Apache and Tomcat.
Use this only as a last resort in case of unfixable network problems.
If a firewall between Apache and Tomcat silently kills idle connections,
try to use the worker attribute socket_keepalive in combination with an appropriate
TCP keepalive value in your OS.

<source>JkOptions     +DisableReuse
</source>

</p>

<p>
JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as
required by Servlet API 2.3.
This flag shouldn't be set when servlet engine is Tomcat 3.2.x (off by default).

<source>JkOptions     +ForwardKeySize
</source>

</p>

<p>
JkOptions <b>ForwardSSLCertChain</b>, you ask mod_jk, when using ajp13,
to forward SSL certificate chain (off by default).
Mod_jk only passes the <code>SSL_CLIENT_CERT</code> to the AJP connector. This is not a
problem with self-signed certificates or certificates directly signed by the
root CA certificate. However, there's a large number of certificates signed by
an intermediate CA certificate, where this is a significant problem: A servlet
will not have the possibility to validate the client certificate on its own. The
bug would be fixed by passing on the <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector.
<br/>
This directive exists only since version 1.2.22.
<source>JkOptions     +ForwardSSLCertChain
</source>

</p>

<p>
The directive <b>JkEnvVar</b> allows you to forward environment variables
from Apache server to Tomcat engine.
You can add a default value as a second parameter to the directive.
If the default value is not given explicitly, the variable
will only be send, if it is set during runtime.
<br/>
The variables can be retrieved on the Tomcat side as request attributes
via request.getAttribute(attributeName).
Note that the variables send via JkEnvVar will not be listed
in request.getAttributeNames().
<br/>
The variables are inherited from the global server to virtual hosts.

<source>JkEnvVar     SSL_CLIENT_V_START     undefined
</source>
</p>

</subsection>

<subsection name="Assigning URLs to Tomcat">
<p>
If you have created a custom or local version of mod_jk.conf-local as noted above,
you can change settings such as the workers or URL prefix.
</p>

<p>
<b>JkMount</b> directive assign specific URLs to Tomcat.
In general the structure of a JkMount directive is:
</p>

<source>JkMount [URL prefix] [Worker name]</source>

<source># send all requests ending in .jsp to worker1
JkMount /*.jsp worker1
# send all requests ending /servlet to worker1
JkMount /*/servlet/ worker1
# send all requests jsp requests to files located in /otherworker will go worker2
JkMount /otherworker/*.jsp worker2
</source>

<p>
You can use the JkMount directive at the top level or inside &lt;VirtualHost&gt; sections of your httpd.conf file.
</p>
</subsection>

<subsection name="Configuring Apache to serve static web application files">
<p>
If the Tomcat Host appBase (webapps) directory is accessible by the Apache HTTP Server,
Apache can be configured to serve web application context directory static files instead
of passing the request to Tomcat.
</p>

<p>
Caution: For security reasons it is strongly recommended that JkMount is used to
pass all requests to Tomcat by default and JkUnMount is used to explicitly
exclude static content to be served by Apache. It should also be noted that
content served by Apache will bypass any security constraints defined in the
application's web.xml.
</p>

<p>Use Apache's <b>Alias</b> directive to map a single web application context directory into Apache's
document space for a VirtualHost:
</p>

<source># Static files in the examples webapp are served by Apache
Alias /examples /vat/tomcat3/webapps/examples
# All requests go to worker1 by default
JkMount /* worker1
# Serve html, jpg and gif using Apache
JkUnMount /*.html worker1
JkUnMount /*.jpg  worker1
JkUnMount /*.gif  worker1
</source>

<p>
Starting with mod_jk 1.2.6 for Apache 2.x and 1.2.19 for Apache 1.3, it's possible to exclude some URL/URI from
jk processing by setting the env var <b>no-jk</b>, for example with the SetEnvIf Directive.
</p>

<p>
You could use <b>no-jk</b> env var to fix problem with mod_alias or mod_userdir
directive when jk and alias/userdir URLs matches.
</p>

<source># All URL goes to tomcat except the one containing /home
&lt;VirtualHost *:80&gt;
    ServerName testxxx.mysys
    DocumentRoot /www/testxxx/htdocs

# Use SetEnvIf to set no-jk when /home/ is encountered
    SetEnvIf Request_URI "/home/*" no-jk

# Now /home will goes to /home/dataxxx/
    Alias /home /home/dataxxx/

    &lt;Directory "/home/dataxxx"&gt;
        Options Indexes MultiViews
        AllowOverride None
        Require all granted
    &lt;/Directory&gt;

    JkMount /* myssys-xxx

&lt;/VirtualHost&gt;
</source>


<p>
Use the mod_jk <b>JkAutoAlias</b> directive to map all web application context directories
into Apache's document space.
</p>

<p>
Attempts to access the WEB-INF or META-INF directories within a web application context
or a Web Archive *.war within the Tomcat Host appBase (webapps) directory will fail with an
<code>HTTP 403, Access Forbidden</code>
</p>

<source># Static files in all Tomcat webapp context directories are served by Apache
JkAutoAlias /var/tomcat3/webapps

# All requests go to worker1 by default
JkMount /* ajp13
# Serve html, jpg and gif using Apache
JkUnMount /*.html ajp13
JkUnMount /*.jpg  ajp13
JkUnMount /*.gif  ajp13
</source>

<p>
If you encoded all your URLs to contain the session id
(<code>;jsessionid=...</code>), and you later decide, you want to
move part of the content to Apache, you can tell
mod_jk to strip off all session ids from URLs for
those requests, that do not get forwarded via mod_jk.
</p>

<p>
You enable this feature by setting JkStripSession to On.
It can be enabled individually for virtual servers. The default
value is Off.
</p>

</subsection>
</section>

<section name="Building mod_jk on Unix">
<p>
The mod_jk build use the widely used configure system.
</p>
<subsection name="Prepare your mod_jk configure from subversion">
In case you get source from subversion, ie without an existing configure script,
you should have autoconf for configuration and installation.
<p>
To create the mod_jk autoconf script, you will need libtool
1.5.2, automake 1.10 and autoconf 2.59 or newer. The use of more recent
versions is encouraged, e.g. for reliable detection of the features of
recent version of operating systems.
</p><p>
Those tools will not be required if you are just using a package downloaded from apache.org,
they are only required for developers.
</p>
<p>
To create the configure script just type:

<screen>
<type>./buildconf.sh</type>
</screen>
</p>
</subsection>

<subsection name="Using configure to build mod_jk">
<p>Here's how to use configure to prepare mod_jk for building, just type:
<source>./configure [autoconf arguments] [mod_jk arguments]
</source>
</p>

<p>
You could set <b>CFLAGS</b> and <b>LDFLAGS</b> to add some platform specifics:
</p>

<screen>
<type>LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs</type>
</screen>

<p>
If you want to build mod_jk for different versions of the Apache HTTP Server, like 1.3 or 2.x,
you need to go through the full build process for each of them.
Please note, that Apache 2.0, 2.2 or 2.4 modules are <b>not</b> binary compatible.
You have to compile the module using the Apache version you plan to run it in.
The mod_jk build directory used is "apache-2.0" for all 2.x builds. The source code
is compatible with Apache HTTP Server 2.0, 2.2 and 2.4.
<ul>
<li>
use configure and indicate the correct Apache HTTP Server apxs location (--with-apxs)
</li>
<li>
use make
</li>
<li>
copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory
to the Apache HTTP Server modules location.
</li>
<li>
make clean (to remove all previously compiled object files)
</li>
<li>
Start over with the apxs location for your next Apache HTTP Server version.
</li>
</ul>

</p>
</subsection>

<subsection name="configure arguments">
<p>
<table>
  <tr valign="top"><th>Apache related parameters</th><th></th></tr>
  <tr valign="top">
  <td>--with-apxs[=FILE]</td>
  <td>FILE is the location of the apxs tool. Default is finding apxs in PATH.
It builds a shared Apache module. It detects automatically the Apache version.
(2.x and 1.3)</td>
  </tr>
  <tr valign="top"><td>--with-apache=DIR</td>
  <td>DIR is the path where Apache sources are located.
The Apache sources should have been configured before configuring mod_jk.
DIR is something like: /home/apache/apache_1.3.19
It builds a static Apache module.</td>
  </tr>
  <tr valign="top"><td>--enable-EAPI</td>
  <td>This parameter is needed when using Apache-1.3 and mod_ssl, otherwise you will get the error message:
"this module might crash under EAPI!" when loading mod_jk.so in Apache.
Not needed when --with-apxs has been used</td>
</tr>
  <tr valign="top"><td>--enable-prefork</td>
  <td>
In case you build mod_jk for a multi-threaded Apache HTTP Server 2.x MPM (Multi-Processing Module),
some areas of mod_jk code need to be synchronised to make it thread-safe.
Because configure can not easily detect, whether your are using a multi-threaded MPM,
mod_jk by default is always build thread-safe for Apache HTTP Server 2.x.
If you are sure, that your MPM is not multi-threaded, you can use "--enable-prefork"
to force the removal of the synchronisation code (thus increasing performance a bit).
For instance, the prefork MPM is not multi-threaded. For Apache HTTP Server 1.3
this flag will be set automatically.</td>
</tr>
  <tr valign="top"><td>--disable-trace</td>
  <td>
When using log level "trace", mod_jk traces a lot of function calls with
"enter" and "exit" log messages. Even if the log level is not "trace",
comparing the log levels to decide about logging has some performance
impact.<br/>
If you use "--disable-trace", then the trace log code doesn't get compiled
into the module binary and you might save some cycles during execution.<br/>
Even with "--disable-trace" logging debug messages with debug log level
will still be possible.</td>
</tr>
  <tr valign="top"><td>--enable-api-compatibility</td>
  <td>
Only use Apache API functions available in all Apache production releases
of the chosen major Apache release branch. This improves binary
compatibility of module builds with Apache releases older than the release
against mod_jk is build (only between minor Apache versions).</td>
</tr>
  <tr valign="top"><td>--enable-flock</td>
  <td>
In case the operating system supports flock system call use this flag to enable this
faster locks that are implemented as system call instead emulated by GNU C library.<br/>
However those locks does not work on NFS mounted volumes, so you can use
"--enable-flock" during compile time to force the flocks() calls.</td>
</tr>

</table>
</p>
</subsection>

<subsection name="Examples of configure use">

<screen>
<note>Apache 1.3 and 2.x build</note>
<type>./configure --with-apxs=/usr/sbin/apxs</type><br/>
<type>make</type><br/>
<type>cp ./apache-1.3/mod_jk.so /usr/lib/apache</type><br/>
<type>make clean</type><br/>
<type>./configure --with-apxs=/usr/sbin/apxs2</type><br/>
<type>make</type><br/>
<type>cp ./apache-2.0/mod_jk.so /usr/lib/apache2</type><br/>
</screen>

</subsection>

</section>

<section name="Building mod_jk for Apache on Windows">
<p>
The module was developed using Microsoft Visual C++, so having Visual Studio installed
is a prerequisite if you want to perform your own build.</p>
<p>
You can build the source using the IDE GUI, or using a pure
commandline build based on nmake. The IDE build currently only
supports building 32 Bit binaries. The nmake builds are available
for 32 Bit and 64 Bit binaries.
</p>
<p>
The common steps for all build procedures are:
<ul>
<li>
Set up your build environment for 32 Bits or 64 Bits.
The IDE build only supports 32 Bits.
</li>
<li>
Download the sources as a zip file and unpack it.
</li>
<li>
Change directory to the ISAPI redirector source directory.
</li>
<li>
Set your path to the Apache web server directory in your
environment.
</li>
</ul>
<screen>
<note>Set up 32 or 64 Bit build environment</note>
<typedos>setenv /Release /X86</typedos>
<note>or (not available for IDE build)</note>
<typedos>setenv /Release /X64</typedos>
<note>Download tomcat-connectors-xxx-src.zip from</note>
<note>https://tomcat.apache.org/download-connectors.cgi</note>
<note>and unpack it</note>
<typedos>unzip tomcat-connectors-xxx-src.zip</typedos>
<note>Change directory to the mod_jk source directory.</note>
<note>To build mod_jk for the Apache HTTP server 2.0, 2.2 or 2.4,</note>
<note>use the "apache-2.0" directory, for the old</note>
<note>Apache HTTP server 1.3, the "apache-1.3" directory.</note>
<typedos>cd tomcat-connectors-xxx-src\native\apache-2.0</typedos>
<note>Set the environment variable "APACHE1_HOME" resp.</note>
<note>"APACHE2_HOME" resp. "APACHE22_HOME" resp. "APACHE24_HOME"</note>
<note>to the installation path of your Apache web server.</note>
<typedos>set APACHE24_HOME=D:\software\Apache\httpd-2.4.16</typedos>
</screen>
</p>
<p>
The steps for an IDE build are then:
<ul>
<li>
Start Visual Studio using "start mod_jk.dsp"
</li>
<li>
During IDE startup choose "Yes" in all conversion popups.
</li>
<li>
Next choose a Configuration form the dropdown. There are pre-defined
configurations for debug and release builds and in the
"apache-2.0" directory each of them is available as a configuration
to build against the web server versions 2.0, 2.2 and 2.4.
</li>
<li>
Finally choose "Build Solution" in the "Build" menu.
</li>
</ul>
The resulting file mod_jk.so (and the debug symbol file
mod_jk.pdb) is located in the "Debug" resp. "Release" sub
directory depending on the build Configuration chosen. For
the "apache-2.0" module the directories are named "Debug_20",
"Release_20", "Debug_22", "Release_22", "Debug_24" and "Release_24"
depending on the chosen build configuration.
</p>
<p>
Alternatively the steps for an nmake commandline build are:
<ul>
<li>
Set your target architecture to X86 or X64 by editing the "ARCH="
line in the file Makefile.vc.
</li>
<li>
Issue "nmake -f Makefile.vc"
</li>
</ul>
The resulting file mod_jk.so (and the debug symbol file
mod_jk.pdb) is located in the "Debug" resp. "Release" sub
directory depending on the build Configuration chosen. For
the "apache-2.0" module the directories are named "Debug_20",
"Release_20", "Debug_22", "Release_22", "Debug_24" and "Release_24"
depending on the chosen build configuration.
</p>
<p>
Finally you need to copy the file mod_jk.so to the modules directory
of your Apache HTTP server (resp. the libexec directory for the old Apache 1.3).
</p>
<p>
For Apache HTTP Server 1.3, ApacheCore.lib is expected to exist before
linking mod_jk will succeed.
</p>
</section>

<section name="Building mod_jk for Apache on System I - i5/OS (OS400)">
<p>
Since OS400 V4R5, System I (AS/400) has used Apache 2.0 as their primary web server,
replacing the old IBM web server.
It's now possible to build mod_jk on System I thanks to the help of the IBM
Rochester Labs which has provided information and patches to adapt mod_jk to i5/OS.
</p>
<p>
You should have at least Apache 2.0.58 (product 5722DG1), a C Compiler and IFS.
Apache 2.0.58 is provided with the most recent set of PTFs for the iSeries Apache
server, which can be found at <a href="http://www.ibm.com/servers/eserver/iseries/software/http/">
http://www.ibm.com/servers/eserver/iseries/software/http/</a>
</p>
<p>
The all latest Apache 2 for i5/OS V5R3 (or V5R4) is now 2.0.58 (as of 2007/04/17).
Be sure to have the latest PTFs loaded if you want to make use of jk 1.2.15 and higher.
NB: The latest mod_jk known to work on i5/OS V5R3 was 1.2.19.
</p>
<p>
New in i5/OS V5R4, UTF is required, also for Apache modules, as such Apache modules do not require
translations to/from EBCDIC but works should be done to port mod_jk 1.2.23 (and higher) to V5R4.

From the V5R4 Infocenter:

As of i5/OS(tm) V5R4, modules must be recompiled with a UTF locale. This creates an environment where locale-dependent C runtime functions assume
that string data is encoded in UTF-8. Any hardcoded constants can be encoded in UTF-8 by adding a #pragma convert(1208) statement in the module.
Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is.
Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required.
APR and HTTP APIs as of V5R4, expect data in UTF-8. Note that several APIs have additional functions that allow a CCSID to be set to
indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added.
Be sure to review APIs used by your module to be aware of current changes.

</p>
<p>
To configure mod_jk on System I use the CL source provided with the mod_jk source.
</p>
<ul>
<li>
Get the latest mod_jk source and untar it on a Windows or Unix boxes
</li>
<li>
Create a directory in IFS, ie /home/apache
</li>
<li>
Send the whole jk source directory to System I directory via FTP.
</li>
<li>
Then go to the System I command line:
</li>
</ul>
<screen>
<note>Create mod_jk library</note>
<type5250>CRTLIB MOD_JK TEXT(‘Apache mod'jk tomcat connector module')</type5250>
<note>Create service program source file</note>
<type5250>CRTSRCPF MOD_JK/QSRVSRC TEXT(‘Service program source file’)</type5250>
<note>Create the CL build program source file</note>
<type5250>CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(‘Build program source file’)</type5250>
<note>Edit the service program source file</note>
<type5250>STRSEU MOD_JK/QSRVSRC MOD_JK</type5250>
</screen>
<p>
In the edited file, specify that only jk_module should be exported:
<screen>
<note> Columns   . . :    1  71     Edit                               MOD_JK/QSRVSRC </note>
<note> SEU==>                                                                  MOD_JK </note>
<note>        *************** Beginning of data ************************************* </note>
<note>0001.00 STRPGMEXP PGMLVL(*CURRENT)                                              </note>
<note>0002.00 EXPORT SYMBOL("jk_module")                                              </note>
<note>0003.00 ENDPGMEXP                                                               </note>
<note>        ****************** End of data **************************************** </note>
</screen>
</p>
<p>
You could start to build all the modules of mod_jk (cases for V5R4 or previous releases):
</p>
<screen>
<note>Copy the CL build program source for i5/OS before V5R4 from IFS</note>
<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +</type5250>
<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)</note>
<note>Build the CL build program</note>
<type5250>CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')</type5250>
<note>Launch the build</note>
<type5250>CALL MOD_JK/BLDJK</type5250><br/>
<note>If the build if successfull, copy the new mod_jk module</note>
<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250>
</screen>
<screen>
<note>Copy the CL build program source for i5/OS V5R4 from IFS</note>
<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +</type5250>
<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)</note>
<note>Build the CL build program for i5/OS V5R4</note>
<type5250>CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)</type5250>
<note>Launch the build for i5/OS V5R4</note>
<type5250>CALL MOD_JK/BLDJK54</type5250><br/>
<note>If the build if successfull, copy the new mod_jk module</note>
<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250>
</screen>
<p>
Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I.
</p>
<screen>
<note>ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note>
<note>STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note>
</screen>
</section>

<section name="Building mod_jk for Apache on MacOS/X">
<p>
Mac OS X (10.2.x) build notes:
</p>
<p>
Assuming that you are root:
</p>
<screen>
<note>For Apache 1.3:</note>
<type>./configure --with-apxs=/usr/sbin/apxs</type>
<type>cd apache-1.3</type>
<type>make -f Makefile.apxs</type>
<type>cp mod_jk.so /etc/libexec/httpd</type>

<note>For Apache 2.x:</note>
<type>./configure --with-apxs=/usr/local/apache2/bin/apxs</type>
<note>(you should point to the directory where you installed Apache 2.x)</note>
<type>cd apache-2.0</type>
<type>make -f Makefile.apxs install</type>
</screen>
</section>

<section name="Getting mod_jk linked statically with Apache">
<p>
mod_jk allows to install mod_jk in the Apache source tree to get a statically
linked mod_jk. Having mod_jk in the Apache executable brings some small performance
improvements. The configure option --with-apache prepare mod_jk to install it
in the Apache source tree.
The option --with-apache works both for Apache 1.3 and Apache 2.x.
The examples below show how to get mod_jk in the Apache process.
</p>

<subsection name="Installation for Apache-2.x">
<screen>
<note> /home/apache24/httpd-2.4.12 is the directory where the Apache HTTP Server sources
are located. </note>
<type>./configure --with-apache=/home/apache24/httpd-2.4.12</type><br/>
<type>make</type><br/>
<note>Install the mod_jk library and other files in
/home/apache24/httpd-2.4.12/modules: </note>
<type>make install</type><br/>
<note> It is not possible to configure Apache directly because the config.m4 of mod_jk must
be added to the configure of httpd-2.x. </note>
<type>cd /home/apache24/httpd-2.4.12</type>
<type>sh buildconf</type>
<type>configure ... --with-mod_jk</type>
<type>make</type>
<type>make install</type><br/>
</screen>
<p>
The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only
allow static linking of mod_jk.
</p>
</subsection>

<subsection name="Installation for Apache-1.3">
<screen>
<note> /home/apache/apache_1.3.27 is the directory where the apache-1.3 sources
are located. </note>
<type>./configure --with-apache=/home/apache/apache_1.3.27</type><br/>
<type>make</type><br/>
<note>Install the libjk library, mod_jk.c, includes and other files in
/home/apache/apache_1.3.27/src/modules/jk: </note>
<type>make install</type><br/>
<note> Configure in the Apache sources: </note>
<type>cd /home/apache/apache_1.3.27</type>
<type>configure ... --enable-module=dir --disable-shared=dir \</type>
<typenext>              --activate-module=src/modules/jk/libjk.a \</typenext>
<typenext>              --disable-shared=jk</typenext>
<type>make</type>
<type>make install</type><br/>
</screen>
<p>
The --enable-shared=jk is also working and builds a dso file.
</p>
<screen>
<note> Just change the configure in the Apache sources: </note>
<type>configure ... --enable-module=dir --enable-shared=dir \</type>
<typenext>              --activate-module=src/modules/jk/libjk.a \</typenext>
<typenext>              --enable-shared=jk</typenext>
</screen>
</subsection>

</section>
</body>
</document>
