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 may persist changes requested by protocol. If you manually change the file while jk2 is working and make changes using jkstatus or a jmx proxy, your changes will be lost. Jk2 is modeled after JMX. It consist of a number of named components, each having certain management attributes. In order to configure jk2 you need to create the components and set the desired attributes. The format of the default config file. 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 has 2 parts, separated by ":". The first part is the component type, and the second is the local part of the name. 2 formats are supported:
                    TYPE:NAME.PROPERTY=VALUE
and
                    [TYPE:NAME]
                    PROPERTY=VALUE
Advanced: reconfiguration
One of the features ok jk2 is support for (partial) reconfiguration at runtime, without a restart. The main use is to add/remove/change workers and uris. This allows smooth updates, without server restarts, where each worker is upgraded while the other workers server content. The jk2 architecture is modeled after JMX, and in future it'll have a JMX proxy that will make most reconfiguration transparent. This section describes the mechanisms used for reconfiguration. Each Jk2 component has a name and a number of attributes. The config is abstracted - but for simplicity we'll discuss the default ( ini-file ) format. Some of the attributes and components support run time changes. The most important is "disabled", that allows a component to be included or excluded from the runtime. The easiest way to reconfigure jk2 is by making modifications to the config file. Jk will process the file again and call the setters for attributes - including disabled, etc. Only components and attributes that include support for reloading will be affected. The reconfig is enabled by using a flag in the scoreboard. The flag can be set programmatically, or it'll be set automatically every time the jk_status page is displayed if a change is detected in the config file A more advanced ( and less tested ) reconfiguration mechanism uses the jk_config API, called programmatically using messages from server or using jk_status web interfaces. 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. A typical user will just edit the config file, add more workers or URIs or change disabled flag of existing workers/uris. Then it'll access the jk_status page, which will detect the config file changes and reload the config in the current server process, and use the scoreboard to inform other server processes of the change.
Server-specific configuration
Since the config is abstracted, some servers ( Apache2 only at this moment ) may support a server-specific configuration mode. 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. In this mode the config will be included in httpd.conf. The JkSet top-level directive is used to set global config options, and JkUriSet is used to set options for Location sections 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. 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 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