costin 2003/03/06 11:45:27
Modified: jk/xdocs/jk2 configweb.xml configwebcom.xml
Log:
Updated the documentations.
Revision Changes Path
1.17 +119 -68 jakarta-tomcat-connectors/jk/xdocs/jk2/configweb.xml
Index: configweb.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk2/configweb.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- configweb.xml 11 Dec 2002 20:56:42 -0000 1.16
+++ configweb.xml 6 Mar 2003 19:45:27 -0000 1.17
@@ -7,94 +7,145 @@
<date>$Date$</date>
</properties>
<section name="Intro">
- <p>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.
- </p>
- <p>
- This document describes the format of this configuration file. Its default name
is ${serverRoot}/conf/workers2.properties,
- where ${serverRoot} is something like /opt/apache.
-</p>
+
+ <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">
- <p> 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.
- </p>
-
-<p>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. </p>
-
- <p>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.
- </p>
- <p>2 formats are supported:
+
+ <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
+ [TYPE:NAME]
+ PROPERTY=VALUE
</source>
</p>
- <p>and
+
+ <p>It is also possible to use an alternate format, mostly for backward
compatibility:
<source>
- [TYPE:NAME]
- PROPERTY=VALUE
+ TYPE:NAME.PROPERTY=VALUE
</source>
</p>
</section>
- <section name="Advanced: reconfiguration">
- <p>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. </p>
-
-<p>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.</p>
-
-<p>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. </p>
-
-<p>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.
+ <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>
-<p>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 </p>
-
-<p>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.</p>
-
-<p>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. </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="Server-specific configuration">
+ <section name="Adding a new tomcat instance">
-<p>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
+ <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.port=PORT" in jk2.properties to enable the console, or use
your favorite JMX
+console or tools.</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. 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</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>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>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
1.7 +23 -18 jakarta-tomcat-connectors/jk/xdocs/jk2/configwebcom.xml
Index: configwebcom.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk2/configwebcom.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- configwebcom.xml 3 Jan 2003 13:52:38 -0000 1.6
+++ configwebcom.xml 6 Mar 2003 19:45:27 -0000 1.7
@@ -231,15 +231,15 @@
</subsection>
<subsection name="channel.socket">
<p>
- A communication transport to a remote Engine
- <b>Magic:</b> 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.
- <b>Magic:</b> 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'
+ Defines a communication transport to a remote Servlet Engine. </p>
+
+<p>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.
+</p>
+<p>
+Tomcat Engine must be set with jvmRoute="HOST:PORT", to match the default tomcatId
of the channel.
</p>
<p>
<table>
@@ -250,13 +250,18 @@
</tr>
<tr>
<td>port</td>
- <td>8009</td>
- <td>Port where Tomcat is listening</td>
+ <td>extracted from the component name</td>
+ <td>Port where Tomcat is listening. It is automatically
extracted from the name - you shouldn't have to specify it explicitely.</td>
</tr>
<tr>
<td>host</td>
- <td>localhost</td>
- <td>Remote host</td>
+ <td>extracted from the component name</td>
+ <td>Remote host. You should use the name, no need to
override it</td>
+ </tr>
+ <tr>
+ <td>graceful</td>
+ <td>0</td>
+ <td>If 1, only requests for existing sessions will be
forwarded</td>
</tr>
<tr>
<td>keepalive</td>
@@ -273,13 +278,13 @@
</tr>
<tr>
<td>group</td>
- <td>lb:0</td>
- <td>loadbalanced groups to which this channel and the
associated worker will be added, multivalued</td>
+ <td>lb</td>
+ <td>loadbalanced groups to which this channel and the
associated worker will be added, multivalued. You need to set it only if you have an
advanced setup with multiple clusters.</td>
</tr>
<tr>
<td>tomcatId</td>
- <td>?</td>
- <td>?</td>
+ <td>Automatically set to the localname ( host:port
)</td>
+ <td>Must match the JVM route on tomcat Engine, for load
balancing</td>
</tr>
</table>
</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
