Components

Intro

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

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

Only one of the forwardURI option could be used it replaces the default value.

config

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

uriMap

shm

Shared memory descriptor

uri

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

If the uri name doesn't have a slash then it is considered as a virtual host directive. Uri name can have a virtual host name and(or) port associated with. Format of such a name is hostname or hostname:port where hostname is virtual server name and the port is vitual server port number. The port number is used only for the non default server ports.

Special case is a default server named as [uri:*] that is used when the virtual host cannot be found inside the configuration. All the uri directives not containing host name belongs to this default server making global mappings.

Addition wild char scheme id [uri:*:port] that is used when you wish to match any virtual host having specified (non-default) port number, like [uri:*:443]. This will map all the virtual hosts no mather what is their name but that have port number 443.

The order how the host names are resolved is :

• Exact host name and optional non default port number
• Alias matching host name and port number
• *:port if the port is other then default
• Default server

vm

Represents the JVM when used as inprocess container

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.

channel.socket

Defines a communication transport to a remote Servlet Engine.

The name of the channels should be: channel.socket:HOST:PORT, where HOST and PORT are the tomcat Ajp location. You could use other names and explicitely set HOST and PORT, but this is discouraged. In most cases, you don't need to set any other config - just add a line like [channel.socket:localhost:8009] and all other things will have good defaults.

NB: Starting with JK2 2.0.4, APR is mandatory and the channel.socket use APR (previously called channel.apr).

Tomcat Engine must be set with jvmRoute="HOST:PORT", to match the default tomcatId of the channel.

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 parameters to pass

There are two predefined jni workers onStartup and onShutdown . Those two workers are executed during startup and shutdown phase of the connector. Both must exists in the configuration to be able to start and shutdown Tomcat.

ajp13

Default worker. If a property is in both the worker and the channel, you only need to define it in one place. The channel passes down the properties to its worker. (at least in the ajp13-channel.socket linkage)

status

An optional worker that outputs (HTML) pages with useful information to monitor JK2.

To create the worker, add a [status:] or [status:'a name'] section.

The status worker needs no 'local' name, although one can be used if desired.

To access the worker, add a [uri] section with the group= assigned to this worker.

The status worker has the following additional properties:

The syleMode setting accepts the following values:

If the stylePath has not been set, styleMode=2 and 3 are ignored.

The sylePath setting accepts the following values:

If the Style file cannot be found, Mode 2 and 3 record Apache log entries.

For styleMode=2 and 3, changes in the Style Sheet are effective on the next access to the status worker.

lb

Loadbalanced worker

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:

logger.file

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

How Load Balancing Works

The lb_factor and level properties combine to deliver a flexible static load balancing solution. The level property is used to create up to four pools over workers in descending priority and lb_factor is used to weight the workers within a pool. The lower the level the more likely the worker is to be used and the lower the lb_factor the more likely the worker is to be used. Here is how the algorithm is currently implemented:

(Assume that every worker's lb_value is set to their lb_factor)

if (loadbalancer has a route) and (stickysession=1){
    worker= loadbanlancer.getWorkerForRoute(route)
    if worker.hasRedirect
        redirect=worker.redirect
    else if !worker.hasError
        return worker
    }

selectedWorker=null
foreach lb_level {
    foreach worker in the level {
        if worker.isNotWorking
            continue
        if selectedWorker == null
            selectedWorker = worker
            continue
        if worker.lb_value < selectedWorker.lb_value
            selectedWorker = worker
            continue
    }
    if selectedWorker !=null
        break
}

Reenable workers in error state if the timeout has passed()

if selectedWorker !=null {
    selectedWorker.lb_value += selectedWorker.lb_factor
    if selectedWorker.lb_value > 255 {
        foreach worker in load_balancer.workers[selectedWorker.level]
            worker.lb_value=worker.lb_factor
        }
    }
    return selectedWorker
}