<?xml version="1.0"?>
<document>
<copyright>
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
</copyright>
<properties>
<title>Configuration file</title>
<author email="cmanolache@yahoo.com">Costin Manolache</author>
<author email="jfrederic.clere@fujitsu-siemens.com">Jean-Frederic Clere</author>
<date>$Date$</date>
</properties>
    <section name="Intro">

        <p>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.</p>

        <p>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.</p>

        <p>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.</p>

    </section>

    <section name="Config file format">

        <p>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.</p>

        <p>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.</p>

        <p>The general syntax is:
            <source>
                [TYPE:NAME]
                PROPERTY=VALUE
            </source>
        </p>

        <p>It is also possible to use an alternate format, mostly for backward compatibility:
            <source>
                TYPE:NAME.PROPERTY=VALUE 
            </source>
        </p>
    </section>

    <section name="Runtime reconfiguration">

      <p>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</p>

      <p>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.</p>

   <p>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.</p>

<p>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.
</p>


    </section>

    <section name="Changing 'graceful' stop state">

      <p>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.</p>

      <p>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.</p>

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

     <p>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.
</p> 

</section>
    <section name="Adding a new tomcat instance">

     <p>1. Edit workers2.properties. Add a new channel. If you want, also add a worker.ajp entry - 
but this is optional</p>
     <p>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</p>

</section>
    <section name="Advanced: reconfiguration using JMX">

        <p>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.enable=true" in jk2.properties to enable the console, or use your favorite JMX
console or tools. You could also select http and/or jrmp protocol, with mx.httpPort, mx.httpHost, mxjrmpPort
and mx.jrmpPort</p>
   
         <p>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 ).</p>

<p>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.</p>   


</section>
    <section name="Native server configuration">

<p>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 )</p>

<p>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</p>

<p>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 )</p>

<p>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</p>

<p>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.</p>

<p>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.</p>

<p>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. </p>

</section>
    <section name="Config generators">
 
<p>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</p>

</section>


</document>