mturk 2002/10/03 08:34:10
Modified: jk/xdocs/jk2 configweb.xml configtc.xml
Log:
Add new splitted documents
Revision Changes Path
1.12 +1 -592 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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- configweb.xml 3 Oct 2002 10:52:16 -0000 1.11
+++ configweb.xml 3 Oct 2002 15:34:10 -0000 1.12
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<document>
<properties>
-<title>Configuration in the Web Server</title>
+<title>Configuration file</title>
<author email="[EMAIL PROTECTED]">Costin Manolache</author>
<author email="[EMAIL PROTECTED]">Jean-Frederic Clere</author>
<date>$Date$</date>
@@ -37,596 +37,5 @@
PROPERTY=VALUE
</source>
</p>
- </section>
- <section name="Components"><p>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:
-<ul><li>The name is composed from the type and a local part, separated with a ':' (
example: channel.unixsocket:/tmp/jk.socket ) </li>
-<li>The 'type' consist of '.' and ascii characters. It is mapped to a JMX
'domain'. </li>
-<li>The local part consists of ascii characters and .:/;
-<p>Note that '=,' are not currently allowed - a future version may support the jmx
syntax by using quotes to separate the local part from the property and value ( in
.properties mode we must use '=' to separate the value from type, local name and
property name ). </p></li>
-<li>The property is a simple name, with no dots. </li>
-<li>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.</li></ul></p>
- <subsection name="Common properties">
- <p>Common properties for all components</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>disabled</td>
- <td>0 (false)</td>
- <td>"disabled" state for the component, 1=true 0=false</td>
- </tr>
- <tr>
- <td>debug</td>
- <td>0 (false)</td>
- <td>"debug" state for the component, 1=true 0=false</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="workerEnv">
- <p>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</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>logger</td>
- <td>logger</td>
- <td>Default loger used by jk2 components, can be changed in
the config file, normally it defaults to "logger" the Alias for the default logger for
the Server/platform.</td>
- </tr>
- <tr>
- <td>timing</td>
- <td>0</td>
- <td>Will jk2 get request timing (needs APR?)</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="config">
- <p>The config component, hold the detail of the conifg system, such
config file name, create global defines</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>file</td>
- <td>${serverRoot}/conf/workers2.properties</td>
- <td>Location of the workers2.properties file</td>
- </tr>
- <tr>
- <td>debug</td>
- <td>0</td>
- <td>Set the debug level of the config component</td>
- </tr>
- <tr>
- <td>debugEnv</td>
- <td>0</td>
- <td>Set the debug level of the hidden env component </td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="uriMap"/>
- <subsection name="shm">
- <p>Shared memory descriptor</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>file</td>
- <td>No default value</td>
- <td>Name of the file that will be mmapped to use as shared
memory.</td>
- </tr>
- <tr>
- <td>size</td>
- <td>No default value</td>
- <td>Size of the file.</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="uri">
- <p>A uri stores a pattern that is used
- to match requests to workers, and asociated properties</p>
- <p>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 <b>hostname</b> or <b>hostname:port</b> 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.</p>
- <p>
- Special case is a default server named as <b>[uri:*]</b> 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.
- </p>
- <p>
- Addition wild char scheme id <b>[uri:*:port]</b> 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.
- </p>
- <p>
- The order how the host names are resolved is :
- <ul>
- <li>Exact host name and optional non default port number</li>
- <li>Alias matching host name and port number</li>
- <li>*:port if the port is other then default</li>
- <li>Default server</li>
- </ul>
- </p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>worker</td>
- <td>lb:0 (The default loadbalancer)</td>
- <td>Name of the worker that process the request
corresponding to the uri</td>
- </tr>
- <tr>
- <td>context</td>
- <td/>
- <td>the context that will be served by this uri component
(webapp style)</td>
- </tr>
- <tr>
- <td>alias</td>
- <td/>
- <td>server name alias</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="vm">
- <p>Represents the JVM when used as inprocess container
- </p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>JVM</td>
- <td>(Autoguess)</td>
- <td>JVM to use for this vm</td>
- </tr>
- <tr>
- <td>OPT</td>
- <td/>
- <td>Option to pass to this vm, this is a multivalued
property</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="channels">
- <p>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</p>
- <subsection name="channel.un">
- <p>
- AF_UNIX socket. Only on UNIX like platform. These sockets are faster
- than "normal" sockets but they are limited to the machine.
-</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>file</td>
- <td>Name of socket</td>
- <td>Name of the socket file (It is created by the
Tomcat ChannelUn)</td>
- </tr>
- </table>
- </p>
- </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'
-</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>port</td>
- <td>8009</td>
- <td>Port where Tomcat is listening</td>
- </tr>
- <tr>
- <td>host</td>
- <td>localhost</td>
- <td>Remote host</td>
- </tr>
- <tr>
- <td>keepalive</td>
- <td>0</td>
- <td>? </td>
- </tr>
- <tr>
- <td>lbfactor</td>
- <td>1</td>
- <td>
- Load balancing factor to use. At this moment, it'll be set on the worker,
- but in future it should be possible to use lb on a channel level.
- </td>
- </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>
- </tr>
- <tr>
- <td>tomcatId</td>
- <td>?</td>
- <td>?</td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="channel.apr">
- <p>
- A communication transport to a remote Engine using APR library
- <b>Magic:</b> The local part of the name will be the Engine name,
- to use when defining the uri mappings. For example
- channel.apr.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.apr.DEFAULT'
-</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>port</td>
- <td>8009</td>
- <td>Port where Tomcat is listening</td>
- </tr>
- <tr>
- <td>host</td>
- <td>localhost</td>
- <td>Remote host</td>
- </tr>
- <tr>
- <td>keepalive</td>
- <td>0 (disabled)</td>
- <td>If set to 1 then it enables the use of keep-alive
packets on TCP connection </td>
- </tr>
- <tr>
- <td>timeout</td>
- <td>0 (infinite)</td>
- <td>Socket timeout for sending and receiving</td>
- </tr>
- <tr>
- <td>ndelay</td>
- <td>0</td>
- <td>If set to 1 Disables the Nagle algorithm for send
coalescing</td>
- </tr>
- <tr>
- <td>lbfactor</td>
- <td>1</td>
- <td>
- Load balancing factor to use. At this moment, it'll be set on the worker,
- but in future it should be possible to use lb on a channel level.
- </td>
- </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>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="channel.jni">
- <p>The jni channel, used if tomcat is started inprocess</p>
- </subsection>
- </subsection>
- <subsection name="workers">
- <p>
- For the moment 4 worker types are supported:
worker.jni,ajp13,status,lb.
- </p>
- <subsection name="worker.jni">
- <p>worker used in inprocess, holds the details of the Tomcat class
to startup, and parameters to pass</p>
- <p>There are two predefined jni workers <b>onStartup</b> and
<b>onShutdown</b>. 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.
- </p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>class</td>
- <td>org/apache/jk/apr/TomcatStarter</td>
- <td>class that holds the main method called to start
tomcat</td>
- </tr>
- <tr>
- <td>ARG</td>
- <td/>
- <td>Arguments to pass to main method when called</td>
- </tr>
- <tr>
- <td>stdout</td>
- <td>NULL</td>
- <td>file to redirect Standard output from the java
process</td>
- </tr>
- <tr>
- <td>stderr</td>
- <td>NULL</td>
- <td>file to redirect Standard output from the java
process </td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="ajp13">
- <p>Default worker</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>secretkey</td>
- <td>NULL</td>
- <td>
- <b>Magic:</b> The secret key will be set
automatically on the associated
- worker.
- </td>
- </tr>
- <tr>
- <td>tomcatId</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>route</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>group</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>level</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>channel</td>
- <td/>
- <td/>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="status">
- <p>Worker that outputs a page with usefull information to monitor
JK2</p>
- <p>To use it add a uri component assigned to this worker</p>
- </subsection>
- <subsection name="lb">
- <p>Loadbalanced worker</p>
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>worker</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>noWorkerMsg</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>noWorkerCode</td>
- <td>503</td>
- <td/>
- </tr>
- <tr>
- <td>hwBalanceErr</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td>timeout</td>
- <td>0 (disabled)</td>
- <td>If all the workers are in the error state, probably
by Tomcat
-refusing any new connections due to the overload, you can set the timeout forcing
lb to wait that some
-worker becomes available, instead of immediately returning error to the client.
This is very useful in
-situations with high peek load. The timeout should be set to the maximum
application call time, but
-not less then 1 second.
- </td>
- </tr>
- <tr>
- <td>attempts</td>
- <td>3</td>
- <td>Number of attempts that lb will try on each worker
before
- giving up.
- </td>
- </tr>
- <tr>
- <td>recovery</td>
- <td>60 (seconds)</td>
- <td>Time to wait before retrying to see if the worker
came out
- of the error state.
- </td>
- </tr>
- </table>
- </p>
- </subsection>
- </subsection>
- <subsection name="loggers">
- <p>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</p>
- <p>The properties shared by all loggers are:
-<table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>level</td>
- <td>INFO</td>
- <td>Log level. Supported: EMERG, ERROR, INFO, DEBUG</td>
- </tr>
- </table>
- </p>
- <subsection name="logger.file">
- <p>
- <table>
- <tr>
- <th>Property name</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>file</td>
- <td>${serverRoot}/logs/jk2.log</td>
- <td>
- Log file. XXX you may be able to change this at runtime,
- to implement rolling.
- </td>
- </tr>
- </table>
- </p>
- </subsection>
- <subsection name="logger.win32">
- <p>logger used in the IIS server by default, it ends at native
Application Event Log.</p>
- </subsection>
- <subsection name="logger.apache2">
- <p>Logger used in Apache2 servers, it normally in ends in error.log
</p>
- </subsection>
- </subsection>
- </section>
- <section name="Examples">
- <p>
-The examples below are working when the Tomcat is configured according the
-examples described in the configtc file.
-</p>
- <subsection name="/example using normal socket">
- <p>
-Map /examples to the Tomcat /examples context using a normal socket. Note the
-IP instead localhost (The JVM listens on the IPV4 address not no the IPV6).
-</p>
- <p>
- <source>
-[shm]
-file=${serverRoot}/logs/shm.file
-size=1048576
-
-# Example socket channel, override port and host.
-[channel.socket:localhost:8019]
-port=8019
-host=127.0.0.1
-
-# define the worker
-[ajp13:localhost:8019]
-channel=channel.socket:localhost:8019
-
-# Uri mapping
-[uri:/examples/*]
-worker=ajp13:localhost:8019
-</source>
- </p>
- </subsection>
- <subsection name="/jkstatus">
- <p>
-Map /jkstatus to the status worker.
-</p>
- <p>
- <source>
-[shm]
-file=${serverRoot}/logs/shm.file
-size=1048576
-
-# define the worker
-[status:status]
-
-# Uri mapping
-[uri:/jkstatus/*]
-worker=status:status
-</source>
- </p>
- </subsection>
- <subsection name="/example using AF_UNIX socket">
- <p>
-Map /examples to the Tomcat /examples context using a AF_UNIX socket.
-Socket file is create by the Tomcat becarefull when the Web Server runs in
-a different user than the Tomcat with the permission of the socket file:
-<source>
-apache20@jfcexpert:~/apache> ls -l
/home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket
-srw-rw---- 1 jakarta jakarta 0 Jun 20 08:27
/home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket
-</source>
-Here the Tomcat user and the Web Server user must be in the same group.
-</p>
- <p>
- <source>
-[shm]
-file=${serverRoot}/logs/shm.file
-size=1048576
-
-# Example unixsocket channel.
-[channel.un:unixsocket]
-file=/home1/jakarta/jakarta-tomcat-4.1/dist/work/jk2.socket
-
-# define the worker
-[ajp13:unixsocket]
-channel=channel.un:unixsocket
-
-# Uri mapping
-[uri:/examples/*]
-worker=ajp13:unixsocket
-</source>
- </p>
- </subsection>
</section>
</document>
1.4 +3 -100 jakarta-tomcat-connectors/jk/xdocs/jk2/configtc.xml
Index: configtc.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk2/configtc.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- configtc.xml 20 Sep 2002 21:35:31 -0000 1.3
+++ configtc.xml 3 Oct 2002 15:34:10 -0000 1.4
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<document>
<properties>
-<title>Configuration in the Tomcat</title>
+<title>Configuration options</title>
<author email="[EMAIL PROTECTED]">Jean-Frederic Clere</author>
<date>$Date$</date>
</properties>
@@ -17,7 +17,7 @@
<section name="Config options">
<p>
<table>
-
+
<tr>
<th>Property name</th>
<th>Default</th>
@@ -142,102 +142,5 @@
</table>
</p>
-</section>
-
-<section name="Examples">
-<p>
-The examples below are working when the Web Server is configured according the
-examples described in the configweb file.
-</p>
-<subsection name="using normal socket">
-<p>
-There is no need to use the jkjni logic to use normal socket, so that just for
-Fun.
-</p>
-
-<p>
-<source>
-# list of needed handlers.
-handler.list=apr,channelSocket,request
-
-# Override the default port for the channelSocket
-channelSocket.port=8019
-
-# Dynamic library
-apr.NativeSo=/home1/jakarta/jakarta-tomcat-connectors/jk/build/jk2/apache2/jkjni.so
-</source>
-</p>
-</subsection>
-
-<subsection name="using AF_UNIX socket">
-<p>
-Create and listen on a AF_UNIX socket. The location of the socket must be the
-same in the Web Server configuration file.
-</p>
-
-<p>
-<source>
-# list of needed handlers.
-handler.list=apr,channelUnix,request
-
-# Location of the socket.
-channelUnix.file=${jkHome}/work/jk2.socket
-
-# Dynamic library
-jtc=/home1/jakarta/jakarta-tomcat-connectors
-apr.NativeSo=${jtc}/jk/build/jk2/apache2/jkjni.so
-</source>
-</p>
-</subsection>
-
-<subsection name="using user defined class for communication">
-<p>
-It is possible to have a user defined class for the communication.
-Here we have used the ChannelUn as example.
-</p>
-
-<p>
-<source>
-# Define our own handler.
-class.mychannel=org.apache.jk.common.ChannelUn
-# list of needed handlers.
-handler.list=apr,mychannel,request
-
-# Location of the socket.
-channelUnix.file=${jkHome}/work/jk2.socket
-
-# Dynamic library
-jtc=/home1/jakarta/jakarta-tomcat-connectors
-apr.NativeSo=${jtc}/jk/build/jk2/apache2/jkjni.so
-</source>
-</p>
-</subsection>
-
-<subsection name="using jni channel class for communication">
-<p>
-Here we have the minimum configuration needed for the jni communication.
-</p>
-
-<p>
-<source>
-# list of needed handlers.
-handler.list=apr,request,channelJni
-
-# Dynamic library needs to be defined only if Tomcat is used
-# out of process
-jtc=/home1/jakarta/jakarta-tomcat-connectors
-apr.NativeSo=${jtc}/jk/build/jk2/apache2/jkjni.so
-# Or you can use the mod_jk2 directly
-apr.jniModeSo=/opt/apache2/modules/mod_jk2.so
-
-# If you wish to start the Tomcat from inside web server then
-# you don't need any above directive. Here is shown the default
-# value for the apr that you can ommit
-apr.jniModeSo=inprocess
-
-</source>
-</p>
-</subsection>
-
</section>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
