Tomcat Connector

Configuring Apache

Here are the all directives supported by Apache:

Directive Description
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.
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
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:

Options Description
%b Bytes sent, excluding HTTP headers (CLF format)
%B Bytes sent, excluding HTTP headers
%H The request protocol
%m The request method
%p The canonical Port of the server serving the request
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Request HTTP status code
%T Request duration, elapsed time to handle request in seconds '.' micro seconds
%U The URL path requested, not including any query string.
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%w Tomcat worker name
  JkRequestLogFormat     "%w %V %T"
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 told mod_jk to send the URI to Tomcat normally, which is less spec compliant but mod_rewrite compatible, use it for compatibility with Tomcat 3.2.x engines (on by default).
  
  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 told 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 told mod_jk to make a flush after each AJP packet received from Tomcat.
  
  JkOptions     +FlushPackets
The directive JkEnvVar allow you to forward an environment vars from Apache server to Tomcat engine.
  
  JkEnvVar     SSL_CLIENT_V_START
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.