Apache TomcatApache Logo

Tomcat Connector

Configuring Apache

Configuration Directives

Here are the all directives supported by Apache:

DirectiveDescription
JkWorkersFile

The name of a worker file for the Tomcat servlet containers

JkWorkerProperty

Enables setting workers.properties inside Apache configuration file. This directive is available in jk1.2.7 version and later.

JkMount

A mount point from a context to a Tomcat worker

JkMountFile

File containing multiple mappings from a context to a Tomcat worker

JkUnMount

A no mount point from a context to a Tomcat worker This directive is available in jk1.2.7 version and later.

JkMountCopy

Should the base server mounts be copied to the virtual server.

JkWorkerIndicator

Name of the Apache environment variable that can be used to set worker names.

JkLogFile

Full or server relative path to the Tomcat Connector module log file

JkLogLevel

The Tomcat Connector module log level, can be debug, info, warn error or trace

JkLogStampFormat

The Tomcat Connector module date log format, follow strftime syntax

JkRequestLogFormat

Request log format string. See detailed description below.

JkAutoAlias

Automatically Alias webapp context directories into the Apache document space.

JkHTTPSIndicator

Name of the Apache environment variable that contains SSL indication

JkCERTSIndicator

Name of the Apache environment variable that contains SSL client certificates

JkCIPHERIndicator

Name of the Apache environment variable that contains SSL client cipher

JkSESSIONIndicator

Name of the Apache environment variable that contains SSL session

JkKEYSIZEIndicator

Name of the Apache environment variable that contains SSL key size in use

JkExtractSSL

Turns on SSL processing and information gathering by mod_jk

JkOptions

Set one of more options to configure the mod_jk module. See below for details about this directive

JkEnvVar

Adds a name of environment variable that should be sent to servlet-engine as a request atribute

JkShmFile

Shared memory file name. Used only on unix platforms.

JkShmSize

Size of the shared memory file name. Default is 64 k.

Configuration Directives Types

We'll discuss here the mod_jk directive types.

Define workers

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


Logging

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.0 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. Using the strftime() format string it's set by
default to "[%a %b %d %H:%M:%S %Y]"

  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "



JkRequestLogFormat 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 similar to the Apache LogFormat command, here is a list of the available request log format options:

OptionsDescription
%bBytes sent, excluding HTTP headers (CLF format)
%BBytes sent, excluding HTTP headers
%HThe request protocol
%mThe request method
%pThe canonical Port of the server serving the request
%qThe query string (prepended with a ? if a query string exists, otherwise an empty string)
%rFirst line of request
%sRequest HTTP status code
%TRequest duration, elapsed time to handle request in seconds '.' micro seconds
%UThe URL path requested, not including any query string.
%vThe canonical ServerName of the server serving the request
%VThe server name according to the UseCanonicalName setting
%wTomcat worker name

  JkRequestLogFormat     "%w %V %T"


You can also log mod_jk information using the Apache standard module mod_log_config. The module sets several notes in the Apache httpd notes table. Most of them are are only useful in combination with a load balancer worker.

NoteDescription
JK_WORKER_NAMEName of the worker selected by the URI mapping
JK_WORKER_TYPEType of the worker selected by the URI mapping
JK_REQUEST_DURATIONRequest duration in seconds and microseconds. At the moment only available if JkRequestLogFormat is set.
JK_LB_FIRST_NAMELoad-Balancer: Name of the first worker tried
JK_LB_FIRST_TYPELoad-Balancer: Type of the first worker tried
JK_LB_FIRST_ACCESSEDLoad-Balancer: Access count for the first worker tried
JK_LB_FIRST_READLoad-Balancer: Bytes read for the first worker tried
JK_LB_FIRST_TRANSFERREDLoad-Balancer: Bytes transferred for the first worker tried
JK_LB_FIRST_ERRORSLoad-Balancer: Error count for the first worker tried
JK_LB_FIRST_BUSYLoad-Balancer: Busy count for the first worker tried
JK_LB_LAST_NAMELoad-Balancer: Name of the last worker tried
JK_LB_LAST_TYPELoad-Balancer: Type of the last worker tried
JK_LB_LAST_ACCESSEDLoad-Balancer: Access count for the last worker tried
JK_LB_LAST_READLoad-Balancer: Bytes read for the last worker tried
JK_LB_LAST_TRANSFERREDLoad-Balancer: Bytes transferred for the last worker tried
JK_LB_LAST_ERRORSLoad-Balancer: Error count for the last worker tried
JK_LB_LAST_BUSYLoad-Balancer: Busy count for the last worker tried

  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


Forwarding

The directive JkOptions allow you to set many forwarding options which will enable (+) or disable (-) following option.

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 ForwardURICompat, you ask 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).

  
  JkOptions     +ForwardURICompat


JkOptions ForwardURICompatUnparsed, the forwarded URI is unparsed, it's spec compliant but broke mod_rewrite.

  
  JkOptions     +ForwardURICompatUnparsed


JkOptions ForwardURIEscaped, the forwarded URI is escaped and Tomcat (since 3.3 rc2) will do the decoding part.

  
  JkOptions     +ForwardURIEscaped


JkOptions ForwardDirectories is used in conjunction with DirectoryIndex directive of Apache web server. 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 ForwarDirectories 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


JkOptions ForwardLocalAddress, you ask mod_jk to send the local address, of the Apache web server instead remote client address. This can be used by Tomcat remote address valve for allowing connections only from registered Apache web servers.

  
  JkOptions     +ForwardLocalAddress


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


The directive JkEnvVar allows you to forward an environment variable from Apache server to Tomcat engine. The variable can be retrieved on the Tomcat side as a request attribute. You must add a default value as a second parameter to the directive.

  
  JkEnvVar     SSL_CLIENT_V_START     undefined


Assigning URLs to Tomcat

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 look for unmount and then for mount directives. The following example will block all .gif files.

  # 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

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.

  # enter the full path to the tomcat webapps directory
  JkAutoAlias /opt/tomtact/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/tomtact/webapps

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

  # Unmount desired static content from servlets-examples webapp.
  # This content will be served by the httpd directly.
  JkUnMount /servlets-examples/*.gif ajp13w
  JkUnMount /servlets-examples/*.jpg 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.propetiesfile. 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 mount point uri starts with minus '-' char the mount point will be disabled.

  # Sample uriworkermap.properties file

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

At run time you can change the content of this file. For example removing minus char will enable the uri mapping. 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.

Using SetHandler and Environment Variables

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

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

Finally you can 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>

Copyright © 1999-2005, Apache Software Foundation