Intro

Jk2 uses an architecture and configuration mechanism modeled after JMX. It consist of "jk_bean" components, with a registry and API that attempts to mirror JMX.

As in JMX, multiple config formats and stores are possible. The default is a neutral .INI-style file, and Apache2 also supports configuration in httpd.conf. Other formats and repositories can be easily implemented, but the general concept is the same.

Each component has a name, a type and a set of attributes. Reasonable defaults are provided, and some components are created automatically using the defaults if not explicitely configured. You need to specify the config only where you want to override the defaults.

Config file format

The config file is named "workers2.properties", located by default in ${serverRoot}/conf, where ${serverRoot} is the web server dir, like /usr/local/apache. It is possible to modify the location of the file using server-specific directives.

Settings are grouped in sections - one section for each object. The section head is the component name, and must include the type and local name of the component, separated by ":". Inside each section you must define the attributes of the component. The attribute name is a simple string, with no '.' or special characters. The value is a string - no quoting is currently supported. It should be noted that the component name is processed to compute default for the component attributes - for example [channel.socket:localhost:8009] name will create a socket channel object with host=locahost and port=8009. You don't need to provide this information twice. It is highly recommended to use this naming scheme for consistency, even if you could use any name and then specify the properties explicitely.

The general syntax is:

                [TYPE:NAME]
                PROPERTY=VALUE
            

It is also possible to use an alternate format, mostly for backward compatibility:

                TYPE:NAME.PROPERTY=VALUE 
            

Runtime reconfiguration

The main purpose of this reconfiguration is to implement "graceful" shutdown and to allow adding or disabling of more tomcat instances in the load balancing mode

Each component has a "ver" attribute - it is initially set to the value in the config file or 0 if this is not specified. Every time the config file is read, jk will check the version number in the component, and reconfigure if it is different.

If Jk2 reloads the config file, it detect modified components using "ver" and reconfigures them. To avoid performance hits, the check is done only when the /jkstatus page is accessed - or if the scoreboard signature changes. An access to /jkstatus will check the timestamp of the config file and if a change is detected it'll reload the config file. In apache and multiprocess servers - this can only affect the current process, so /jkstatus will increment the scoreboard mark. All other processes in a multiprocess server will see the modified byte and reload before serving the next request.

Changing the file and forcing a reload is currently the easiest way to reconfigure. A JMX proxy is in experimental stage and will allow the user to perform all configuration in JMX - using same tools that he uses for tomcat, and completely transparent. The internal implementation will also save the file - it is the cleanest way to sync multi-process web servers.

Changing 'graceful' stop state

Each tomcat instance corresponds to a "channel" jk component that defines the host and port. The channel can be set in a special "graceful" mode or back to active by setting the corresponding attribute. This mode disables sending any new requests to that tomcat instance - only requests for an existing session are permitted.

When you want to disable a tomcat instance, you should first set the channel in "graceful" mode, then wait until all existing sessions expire or are completed. If the sessions are serializable and tomcat is configured in clustering mode - you can also migrate the sessions to a different instance.

1. Edit workers2.properties. Find the channel. Change "graceful" to "1" to disable or "0" to reactivate". Increment "ver".
2. Access /jkstatus page. You should see the value changed in the channel and worker info.

When a worker is in this state, no new requests will be sent to that worker - only requests that have an explicit session ID for that particular worker. It is recommended you wait for all sessions to expire before stopping the tomcat instance, or you use a session migration mechanism.

Adding a new tomcat instance

1. Edit workers2.properties. Add a new channel. If you want, also add a worker.ajp entry - but this is optional

2. Access the /jkstatus page or triger reloading with a program. You should see the new channel displayed in the status page, and requests should start going to the new tomcat instance

Advanced: reconfiguration using JMX

This is very experimental. On tomcat side, you must enable the JMX proxy. This is done by setting "modjk.webServerHost" and "modjk.webServerPort" in jk2.properties to point to the web server port that contains /jkstatus. ( recent versions of jk and mod_jk are required ). You can also add mx4j-tools.jar to server/lib and set "mx.port=PORT" in jk2.properties to enable the console, or use your favorite JMX console or tools.

When tomcat starts up, it'll connect to the web server and create JMX mbean proxies for each mod_jk component. The data will be refreshed when JMX operations are performed - a set or invoke will allways refresh, while get will use cached values and refresh only periodically ( 5 sec default ).

Every time a change is made, the config file will be written ( for persistence and to allow other processes to get the same change ). The scoreboard will be changed, and then all other server processes will act just like in the case of a file change. All comments will be lost - you should use "info" attributes in components and set "disabled" to 1 if you want to temporary disable some components.

Native server configuration

For Apache2 you can also use httpd.conf instead or in addition to workers2.properties. Other servers may support similar configuration - for example using registry or their native formats. This configuration mode is less tested - but provides some unique advantages (and disadvantages )

I'll describe the apache2 specifics, since this is the only one implemented. We use 2 directives - JkSet is a top-level directive is used to set global config options, and JkUriSet is used to set options for Location sections

JkSet takes 2 parameters, the property name ( including component name ) and the value. (Note: probably we should change it to 3 params, and separate the component name from property )

Each Location that has a JkUriSet will automatically create a jk2 [uri] object, using the Location path and the vhost. All JkUriSet directives will set attributes in this [uri] object, exactly like properties in a ini file section

You can mix workers2.properties and JkUriSet - for example workers and global options can be set in worker2.properties, but all uri properties in httpd.conf. Some people might preffer to have only one config file and use httpd.conf for all configuration.

The biggest benefit is that Apache2 mapping is used instead of jk2 to detect the requests that need to be sent to tomcat. Apache2 has been optimized and tuned to server huge number of servers and uris - if you have only few the diference may be hard to notice. Some people preffer to use the httpd.conf format and some tools could be better used in this mode.

One major problem is that reconfiguration is not supported if httpd.conf is used. You can still enable/disable/add workers if you use workers2.properties, and you could add or change uri properties in that file.

Config generators

There is work in progress to support automatic generation of the config file. The code is included in org.apache.jk.config and consist of a number of ant tasks ( that work from CLI as well) that process web.xml files and generate worker2.properties or server-specific config files