Apache Software Foundation | Jakarta Project | Apache Tomcat
Intro

Jk2 uses a config file ( workers2.properties ) in the style of a .properties or ini file. It can be configured to use any other backend that provides similar capabilities.

This document describes the format of this configuration file. Its default name is ${serverRoot}/conf/workers2.properties, where ${serverRoot} is something like /opt/apache.


Config file

The default config file is user editable, but mod_jk will persist the changes requested by protocol( not implemented). If you manually change the file while jk2 is working, your changes will be lost.

The default configuration format . . Each setting consists of an object name and a property, with the associated value. The property name is a simple string, with no '.' in it. The name can be anything, but it must have a known 'type' as prefix.

2 formats are supported:

                TYPE:NAME.PROPERTY=VALUE 
            

and

                [TYPE:NAME]
                PROPERTY=VALUE
            


Components

Each component instance has a name, that is used for configuration and at runtime. Each component has a number of configurable properties. The following rules are used:

  • The name is composed from the type and a local part, separated with a ':' ( example: channel.unixsocket:/tmp/jk.socket )
  • The 'type' consist of '.' and ascii characters. It is mapped to a JMX 'domain'.
  • The local part consists of ascii characters and .:/;
  • The property is a simple name, with no dots.
  • A simple form of substitution is used in values, where $(property) will be replaced with a previously defined setting. If the property has ':' in it, it'll take the value from the object, if not it'll take the value from a global map.

Common properties

Common properties for all components

Property name Default Description
disabled 0 (false) "disabled" state for the component, 1=true 0=false
debug 0 (false) "debug" state for the component, 1=true 0=false


workerEnv

This component represent the core jk2, it has the default logger for all other components. Is the central controller, it controls global properties and provides access to all other objects

Property name Default Description
logger logger Default loger used by jk2 components, can be changed in the config file, normally it defaults to "logger" the Alias for the default logger for the Server/platform.
timing 0 Will jk2 get request timing (needs APR?)


config

The config component, hold the detail of the conifg system, such config file name, create global defines

Property name Default Description
debugEnv 0 Set the debug level of the hidden env component


uriMap

shm

Shared memory descriptor

Property name Default Description
file No default value Name of the file that will be mmapped to use as shared memory.
size No default value Size of the file.


uri

A uri stores a pattern that is used to match requests to workers, and asociated properties

Property name Default Description
worker lb:0 (The default loadbalancer) Name of the worker that process the request corresponding to the uri
context the context that will be served by this uri component (webapp style)
reverse 0 If set to 1 all satisfied matches will be rejected. This is usefull for the situations when you wish to map the entire application, but still wish that paticular context is not served through Tomcat.


vm

Represents the JVM when used as inprocess container

Property name Default Description
JVM (Autoguess) JVM to use for this vm
OPT Option to pass to this vm, this is a multivalued property


channels

A channel represents a transport protocol, connecting 2 sides for RPC communication. The most common and standard is the tcp socket. Other important channels are unix socket and jni

channel.un

AF_UNIX socket. Only on UNIX like platform. These sockets are faster than "normal" sockets but they are limited to the machine.

Property name Default Description
file Name of socket Name of the socket file (It is created by the Tomcat ChannelUn)


channel.socket

A communication transport to a remote Engine Magic: The local part of the name will be the Engine name, to use when defining the uri mappings. For example channel.socket.local_9009 will automatically define an engine named local_9009, and if no other setting is set ajp13 will be used for communication. Magic: If no channel is defined in the config, a default channel will be constructed with port=8009, engine=DEFAULT, worker=ajp13 - named 'channel.socket.DEFAULT'

Property name Default Description
port 8009 Port where Tomcat is listening
host localhost Remote host
keepalive 0 ?
lbfactor 1 Load balancing factor to use. At this moment, it'll be set on the worker, but in future it should be possible to use lb on a channel level.
group lb:0 loadbalanced groups to which this channel and the associated worker will be added, multivalued
tomcatId ? ?


channel.jni

The jni channel, used if tomcat is started inprocess



workers

For the moment 4 worker types are supported: worker.jni,ajp13,status,lb.

worker.jni

worker used in inprocess, holds the details of the Tomcat class to startup, and paramters to pass

Property name Default Description
class org/apache/jk/apr/TomcatStarter class that holds the main method called to start tomcat
ARG Arguments to pass to main method when called
stdout NULL file to redirect Standard output from the java process
stderr NULL file to redirect Standard output from the java process


ajp13

Default worker

Property name Default Description
secretkey NULL Magic: The secret key will be set automatically on the associated worker.
tomcatId
route
group
level
channel


status

Worker that outputs a page with usefull information to monitor JK2

To use it add a uri component assigned to this worker


lb

Loadbalanced worker

Property name Default Description
worker
noWorkerMsg
noWorkerCode 503
hwBalanceErr



loggers

Any connector based on jk2, at least has a default logger, that can be reached using the "logger" alias, the logger used is the more appropiate for the plataform/server combination, Apache2 under in any platform has logger.apache2 as default, IIS on his only platform uses logger.win32, and Any apache 1 install uses logger.file as default.., the config file lets you change that defaults, you can end using logger.file in IIs i.e

The properties shared by all loggers are:

Property name Default Description
level INFO Log level. Supported: EMERG, ERROR, INFO, DEBUG

logger.file

Property name Default Description
file ${serverRoot}/logs/jk2.log Log file. XXX you may be able to change this at runtime, to implement rolling.


logger.win32

logger used in the IIS server by default, it ends at native Application Event Log.


logger.apache2

Logger used in Apache2 servers, it normally in ends in error.log




Examples

The examples below are working when the Tomcat is configured according the examples described in the configtc file.

/example using normal socket

Map /examples to the Tomcat /examples context using a normal socket. Note the IP instead localhost (The JVM listens on the IPV4 address not no the IPV6).

[shm]
file=${serverRoot}/logs/shm.file
size=1048576

# Example socket channel, override port and host.
[channel.socket:localhost:8019]
port=8019
host=127.0.0.1

# define the worker
[ajp13:localhost:8019]
channel=channel.socket:localhost:8019

# Uri mapping
[uri:/examples/*]
worker=ajp13:localhost:8019


/jkstatus

Map /jkstatus to the status worker.

[shm]
file=${serverRoot}/logs/shm.file
size=1048576

# define the worker
[status:status]

# Uri mapping
[uri:/jkstatus/*]
worker=status:status


/example using AF_UNIX socket

Map /examples to the Tomcat /examples context using a AF_UNIX socket. Socket file is create by the Tomcat becarefull when the Web Server runs in a different user than the Tomcat with the permission of the socket file:

apache20@jfcexpert:~/apache> ls -l /home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket
srw-rw----    1 jakarta  jakarta         0 Jun 20 08:27 /home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket
Here the Tomcat user and the Web Server user must be in the same group.

[shm]
file=${serverRoot}/logs/shm.file
size=1048576

# Example unixsocket channel.
[channel.un:unixsocket]
file=/home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket

# define the worker
[ajp13:unixsocket]
channel=channel.un:unixsocket

# Uri mapping
[uri:/examples/*]
worker=ajp13:unixsocket