The Apache Tomcat Connectors - Reference Guide

JkWorkersFile specify the location where mod_jk will find the workers definitions. Take a look at Workers documentation for detailed description.

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 contain standard mod_jk activity (default).
• warn log will contain non fatal error reports.
• error log will contain also error reports.
• debug log will contain all information on mod_jk activity
• trace log will contain all tracing 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 log file. See above 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.

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. To enable request logging for a virtual host just add a JkRequestLogFormat config. The syntax of the format string is similar to the Apache LogFormat command, here is a list of the available request log format options:

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 remote client address. This can be used by the 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 (on 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.

JkUnMount directive acts as an opposite to JkMount and blocks access to a particular URL. The purpose is to be able to filter out the particular content types from mounted context. The following example mounts /servlet/* context, but all .gif files that belongs to that context are not served.

# send all requests ending with /servlet to worker1
JkMount /servlet/* worker1
# do not send requests ending with .gif to worker1
JkUnMount /servlet/*.gif worker1

JkUnMount takes precedence over JkMount directives, meaning that the JK will first try to mount and then checks, if there is an exclusion defined by a JkUnMount. A JkUnMount overrides a JkMount only, if the worker names in the JkMount and in the JkUnMount are the same.

The following example will block all .gif files although there is a JkMount for them:

# do not send requests ending with .gif to worker1
JkUnMount /*.gif worker1
# The .gif files will not be mounted cause JkUnMount takes
# precedence over JkMount directive
JkMount /servlet/*.gif worker1

Starting with version 1.2.26 of JK you can apply a JkUnMount to any worker, by using the star character '*' as the worker name in the JkUnMount. More complex patterns in JkUnMount worker names are not allowed.

# Mapping the webapps myapp1 and myapp2:
/myapp1/*=worker1
/myapp2/*=worker2
# Exclude the all subdirectories static for all workers:
!/*/static/*=*
# Exclude some suffixes for all workers:
!*.html=*

JkAutoAlias directive automatically Alias webapp context directories into the Apache document space. It enables Apache to serve a static context while Tomcat serving dynamic context. This directive is used for convenience so that you don't have to put an Apache Alias directive for each application directory inside Tomcat's webapp directory. 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. The directive only works in the simple case of contexts with a single path element and no version marker. It does not support:

• the ROOT context (i.e. .../webapps/ROOT)
• multi-level contexts (e.g. .../webapps/foo#bar)
• parallel deployment (e.g. .../webapps/foo##v00.05.12)

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

The following example shows how to serve a dynamic context by Tomcat and static using Apache. The webapps directory has to be accessible by Apache.

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

# Mount 'examples' directory. It's physical location
# is assumed to be in the /opt/tomcat/webapps/examples
# ajp13w is a worker defined in the workers.properties
JkMount /examples/* ajp13w

# Unmount desired static content from examples webapp.
# This content will be served by the Apache directly.
JkUnMount /*.gif ajp13w

Note that you can have a single JkAutoAlias directive per virtual host inside your httpd.conf

JkWorkerProperty is a new directive available from JK 1.2.7 version. It is a convenient method for setting directives that are usually set inside workers.propeties file. The parameter for that directive is raw line from workers.properties file.

# Just like workers.properties but exact line is prefixed
# with JkWorkerProperty

# Minimal jk configuration
JkWorkerProperty worker.list=ajp13w
JkWorkerProperty worker.ajp13w.type=ajp13
JkWorkerProperty worker.ajp13w.host=localhost
JkWorkerProperty worker.ajp13w.port=8009   

JkMountFile is a new directive available from JK 1.2.9 version. It is used for dynamic updates of mount points at runtime. When the mount file is changed, JK will reload it's content.

# Load mount points

JkMountFile conf/uriworkermap.properties

If the mount point uri starts with an exclamation mark '!' it defines an exclusion in the same way JkUnMount does. If the mount point uri starts with minus sign '-' the mount point will only be disabled. A disabled mount can be reenabled by deleting the minus sign and waiting for the JkMountFile to reload. An exclusion can be disabled by prefixing it with a minus sign.

# Sample uriworkermap.properties file

/examples/*=ajp13w
# Do not map .gif files
!/*.gif=ajp13w
# Make jsp examples initially disabled  
-/examples/jsp/*=ajp13w

At run time you can change the content of this file. For example removing minus signs will enable the previously disabled uri mappings. You can add any number of new entries at runtime that reflects the newly deployed applications. Apache will reload the file and update the mount points within 60 second interval.

There is no way to delete entries by dynamic reloading, but you can disable or exclude mappings.

Alternatively to the mod_jk specific directives, you can also use SetHandler and environment variables to control, which requests are being forwarded via which worker. This gives you more flexibility, but the results might be more difficult to understand. If you mix both ways of defining the forwards, in general to mod_jk directives will win.

SetHandler jakarta-servlet forces requests to be handled by mod_jk. If you neither specify any workers via JkMount and the related directives, not via the environment variable described below, the first worker in the list of all worker will be chosen. You can use SetHandler for example in Location blocks or with Apache 2.2 and later also in RewriteRule.

In order to control the worker using SetEnvIf or RewriteRule for more complex rules, you can set the environment variable JK_WORKER_NAME to the name of your chosen target worker. This enables you to decide on the chosen worker in a more flexible way, including dependencies on cookie values. This feature has been added in version 1.2.19 of mod_jk. Furthermore you might append rule extensions to the worker name. The extensions are separated from the worker name by a semicolon ";" using the same syntax as in the uriworkermap.properties file. Supporting rule extensions in the worker name has been added in version 1.2.33.

In order to use another variable than JK_WORKER_NAME, you can set the name of this variable via the JkWorkerIndicator directive.

You can also define exclusions from mod_jk forwards by setting the environment variable no-jk.

# Automatically map all encoded urls
<Location *;jsessionid=>
  SetHandler jakarta-servlet
  SetEnv JK_WORKER_NAME my_worker
</Location>

# Map all subdirs to workers via naming rule
# and exclude static content.
<Location /apps/>
  SetHandler jakarta-servlet
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk
</Location>

Environment variables allow to overwrite the default behaviour of mod_jk depending on request properties like e.g. the request URI, header values or cookie. This can be done using the SetEnvIf or RewriteRule directives.

The environment variable JK_ROUTE can be set to explicitely choose a member of a load balancer worker. The value must be equal to the route attribute of the member, or if that attribute is not used, equal to the member name. Note that this is only needed if session IDs and routes are encoded in a non standard way in the request. Stickyness using the Java Servlet compliant way of encoding the IDs is supported by default. This is available since version 1.2.33.

The environment variable JK_REPLY_TIMEOUT can be set to dynamically define a reply timeout. The value must be given in milliseconds. This is available since version 1.2.27.

The environment variable JK_STICKY_IGNORE can be set to disable session stickyness for individual requests. If the variable is set to an empty string or a nonzero number, session stickyness will be disabled. Setting it to 0 will reset to the behaviour defined by the worker configuration. This is available since version 1.2.33.

This feature can be useful to optimize load balancing when using cookie based session stickyness. In this case, as long as she keeps her browser open, any request by a user who started a session will be send to the same Tomcat instance, even if he left the part of the application which uses the session. You can for instance set this environment variable when a user requests a login form to ensure, that this initial session request is balanced non-sticky.

The environment variable JK_STATELESS can be used to improve load balancing for the session based balancing methods Session and Next. In this case normally any request which does not come with a session id counts as a new session. This can be problematic, if for instance static content is retrieved without a session id. If you set the environment variable JK_STATELESS for a request, then the request will not count as a new session, even if it does not come with a session id. This is available since version 1.2.33.

The environment variable JK_IGNORE_CL can be set to force ignoring the request Content-Length header (if it exists). mod_jk will then stream the request body until the web server indicates that the full body was read. No Content-Length header will be send to the backend. This is available since version 1.2.41.

This feature can be used to make mod_jk compatible with filters which change the size of the request body. One such filter is mod_deflate when used to inflate the body of a request with gzip encoded body. In this case mod_jk will by default forward a truncated body, because it gets the wrong body size from the web server. Telling mod_jk to ignore the Content-Length header will result in streaming all request body data it can read from the web server to the backend.

You should only set the JK_IGNORE_CL environment variables for requests that actually need it. Unfortunately there's no way for mod_jk to detect the need automatically.