The Apache Tomcat Connectors - Web Server HowTo

${tomcat_home} is the root directory of tomcat. Your Tomcat installation should have the following subdirectories:

• ${tomcat_home}\conf - Where you can place various configuration files
• ${tomcat_home}\webapps - Containing example applications
• ${tomcat_home}\bin - Where you place web server plugins

In all the examples in this document ${tomcat_home} will be /var/tomcat3. A worker is defined to be a tomcat process that accepts work from the Apache server.

The mod_jk module was developed and tested on:

• Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should work on major Unixes platforms supporting Apache 1.3 and/or 2.x
• WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98
• Cygwin (until you have an Apache server and autoconf/automake support tools)
• i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed.
• Tomcat 3.2 to Tomcat 8.

The mod_jk module uses the AJP protocol to send requests to the Tomcat containers. The AJP version typically used is ajp13.

Tomcat supports ajp13 since Tomcat 3.2. Others servlet engines such as Jetty or JBoss also support the ajp13 protocol

The ajp12 protocol has been deprecated and you should no longer use it. The ajp14 protocol is considered experimental.

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.

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

• Load the servlet container adaptor library and initialise it (prior to serving requests).
• 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.

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.

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.

If you've previously configured Apache to use mod_jserv, remove any ApJServMount directives from your httpd.conf.

If you're including tomcat-apache.conf or tomcat.conf, 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 !

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:

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

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

This will tell the Apache HTTP Server to use directives in the mod_jk.conf-auto 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. Please note that this example is specific to Tomcat 5.x, unlike other sections of this document which also apply to previous Tomcat branches.

...
<Engine ...>
  ...
    <Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" />
  ...
</Engine>
...

Then restart Tomcat and mod_jk.conf should be generated. For more information on this topic, please refer to the API documentation at the Tomcat docs website.

You should use custom configuration when:

• You couldn't use mod_jk.conf-auto 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.
• 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
• Also most Apache web masters will retain custom configuration to be able to tune the settings to their real needs.

Here is a simple configuration:

# 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

JkWorkersFile specify the location where mod_jk will find the workers definitions.

JkWorkersFile     /etc/httpd/conf/workers.properties

JkLogFile specify the location where mod_jk is going to place its log file.

JkLogFile     /var/log/httpd/mod_jk.log

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:

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

JkLogLevel set the log level between:

• info log will contains standard mod_jk activity (default).
• error log will contains also error reports.
• debug log will contains all information on mod_jk activity

JkLogLevel    info

info should be your default selection for normal operations.

JkLogStampFormat will configure the date/time format found on mod_jk logfile. See the mod_jk Apache HTTP Server reference for details.

JkLogStampFormat "[%y-%m-%d %H:%M:%S.%Q] "

You can log mod_jk information using the Apache standard module mod_log_config. 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 Apache HTTP Server reference for details.

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

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 JkRequestLogFormat will configure the format of this protocol. It gets configured and enabled on a per virtual host basis. See the mod_jk Apache HTTP Server reference for details.

JkRequestLogFormat     "%w %V %T"

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.

The four following options +ForwardURIxxx 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.

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:
options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)

Using JkOptions ForwardURIProxy, 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.

JkOptions     +ForwardURIProxy

Using JkOptions ForwardURICompatUnparsed, 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.

JkOptions     +ForwardURICompatUnparsed

Using JkOptions ForwardURICompat, 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 not safe if you are using prefix JkMount. This option will allow to rewrite URIs with mod_rewrite before forwarding.

JkOptions     +ForwardURICompat

Using JkOptions ForwardURIEscaped, 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.

JkOptions     +ForwardURIEscaped

JkOptions RejectUnsafeURI will block all URLs, which contain percent signs '%' or backslashes '\' after decoding.

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.

You can also realise such a check with mod_rewrite, which is more powerful but also slightly more complicated.

JkOptions     +RejectUnsafeURI

JkOptions CollapseSlashesAll is deprecated as of 1.2.44 and will be ignored if used.

JkOptions CollapseSlashesUnmount is deprecated as of 1.2.44 and will be ignored if used.

JkOptions CollapseSlashesNone is deprecated as of 1.2.44 and will be ignored if used.

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

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

If ForwardDirectories is set to false (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 403 Forbidden response (if directive Options doesn't specify Indexes for that directory).

If ForwardDirectories is set to true 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.

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.

JkOptions     +ForwardDirectories

Setting JkOptions ForwardLocalAddress, 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.

JkOptions     +ForwardLocalAddress

Setting JkOptions ForwardPhysicalAddress, 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 X-Forwarded-For header.

JkOptions     +ForwardPhysicalAddress

JkOptions FlushPackets, 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).

JkOptions     +FlushPackets

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

JkOptions     +FlushHeader

JkOptions DisableReuse, 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.

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.

JkOptions     +DisableReuse

JkOptions ForwardKeySize, 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).

JkOptions     +ForwardKeySize

JkOptions ForwardSSLCertChain, you ask mod_jk, when using ajp13, to forward SSL certificate chain (off by default). Mod_jk only passes the SSL_CLIENT_CERT 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 SSL_CLIENT_CERT_CHAIN to Tomcat via the AJP connector.
This directive exists only since version 1.2.22.

JkOptions     +ForwardSSLCertChain

The directive JkEnvVar 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.
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().
The variables are inherited from the global server to virtual hosts.

JkEnvVar     SSL_CLIENT_V_START     undefined

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.

JkMount directive assign specific URLs to Tomcat. In general the structure of a JkMount directive is:

JkMount [URL prefix] [Worker name]

# 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

You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file.

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.

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.

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

# 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

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 no-jk, for example with the SetEnvIf Directive.

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

# All URL goes to tomcat except the one containing /home
<VirtualHost *:80>
    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/

    <Directory "/home/dataxxx">
        Options Indexes MultiViews
        AllowOverride None
        Require all granted
    </Directory>

    JkMount /* myssys-xxx

</VirtualHost>

Use the mod_jk JkAutoAlias directive to map all web application context directories into Apache's document space.

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 HTTP 403, Access Forbidden

# 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

If you encoded all your URLs to contain the session id (;jsessionid=...), 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.

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

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.

Those tools will not be required if you are just using a package downloaded from apache.org, they are only required for developers.

To create the configure script just type: ./buildconf.sh

Here's how to use configure to prepare mod_jk for building, just type:

./configure [autoconf arguments] [mod_jk arguments]

You could set CFLAGS and LDFLAGS to add some platform specifics:

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

• use configure and indicate the correct Apache HTTP Server apxs location (--with-apxs)
• use make
• copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory to the Apache HTTP Server modules location.
• make clean (to remove all previously compiled object files)
• Start over with the apxs location for your next Apache HTTP Server version.

The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only allow static linking of mod_jk.

The --enable-shared=jk is also working and builds a dso file.