xdocs/common_howto/workers.xml - tomcat-connectors - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="workers.html">

   &project;
 <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>Workers HowTo</title>
 <author email="hgomez@apache.org">Henri Gomez</author>
 <author email="shachor@il.ibm.com">Gal Shachor</author>
 <author email="mturk@apache.org">Mladen Turk</author>
 <date>$Date$</date>
 </properties>
 <body>
 <section name="Introduction">
 <p>
 A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
 For example, we can have a web server such as the Apache HTTP Server forwarding servlet requests to a
 Tomcat process (the worker) running behind it.
 </p>
 <p>
 The scenario described above is a very simple one;
 in fact one can configure multiple Tomcat workers to serve servlets on
 behalf of a certain web server.
 The reasons for such configuration can be:
 </p>
 <ul>
 <li>
 We want different contexts to be served by different Tomcat workers to provide a
 development environment where all the developers share the same web server but own a Tomcat worker of their own.
 </li>
 <li>
 We want different virtual hosts served by different Tomcat processes to provide a
 clear separation between sites belonging to different companies.
 </li>
 <li>
 We want to provide load balancing, meaning run multiple Tomcat workers each on a
 machine of its own and distribute the requests between them.
 </li>
 </ul>

 <p>
 There are probably more reasons for having multiple workers but I guess that this list is enough...
 Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
 explains how to work with it.
 </p>

 <p>
 This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
 but has been split off for organisational reasons.
 </p>
 </section>

 <section name="Defining Workers">
 <p>
 Defining workers to the Tomcat web server plugin can be done using a properties file
 (a sample file named workers.properties is available in the conf/ directory).
 </p>

 <p>
 the file contains entries of the following form:
 </p>

 <p>
 <b>worker.list</b>=&lt;a comma separated list of worker names&gt;
 </p>

 <source>
   # the list of workers
   worker.list= worker1, worker2
 </source>

 <p>
 When starting up, the web server plugin will instantiate the workers whose name appears in the
 <b>worker.list</b> property, these are also the workers to whom you can map requests. The directive can be used multiple times.
 </p>

 <subsection name="Worker Types">
 <p>
 Each named worker should also have a few entries to provide additional information on his behalf.
 This information includes the worker's type and other related worker information.
 Currently the following worker types that exists are (JK 1.2.5):
 </p>

 <table>
   <tr><th>Type</th><th>Description</th></tr>
   <tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp13 protocol.</td></tr>
   <tr><td>lb</td><td>This is a load balancing worker; it knows how to provide flexible load balancing with a certain level of fault-tolerance.</td></tr>
   <tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
   <tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp12 protocol. It is deprecated</td></tr>
   <tr><td>ajp14</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp14 protocol. It is experimental</td></tr>
 </table>

 <p>
 Defining workers of a certain type should be done with the following property format:
 </p>

 <p>
 <b>worker</b>.<b>worker name</b>.<b>type</b>=&lt;worker type&gt;
 Where worker name is the name assigned to the worker and the worker type is one of the four types defined
 in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).
 </p>

 <source>
   # Defines a worker named "local" that uses the ajp12 protocol to forward requests to a Tomcat process.
   worker.local.type=ajp12
   # Defines a worker named "remote" that uses the ajp13 protocol to forward requests to a Tomcat process.
   worker.remote.type=ajp13
   # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
   worker.loadbalancer.type=lb
 </source>

 </subsection>

 </section>

 <section name="Setting Worker Properties">
 <p>
 After defining the workers you can also specify properties for them.
 Properties can be specified in the following manner:
 </p>

 <p>
 worker.&lt;worker name&gt;.&lt;property&gt;=&lt;property value&gt;
 </p>

 Each worker has a set of properties that you can set as specified in the following subsections:

 <subsection name="ajp12 Worker Properties">
 <p><warn>
 The worker type <b>ajp12</b> has been <b>deprecated</b> and you should use instead
 <b>ajp13</b> instead.
 </warn></p>
 <p>
 The ajp12 typed workers forward requests to out-of-process Tomcat workers
 using the ajp12 protocol over TCP/IP sockets. It does not use persistent connections.
 </p>

 <p>
 The ajp12 worker properties are:
 </p>

 <p>
 <b>host</b> property sets the host where the Tomcat worker is listening for ajp12 requests.
 </p>

 <p>
 <b>port</b> property sets the port where the Tomcat worker is listening for ajp12 requests
 </p>

 <p>
 <b>lbfactor</b> property is used when working with a load balancer worker, this is the load balancing factor for the worker.
 We'll see more on this in the <a href="../common_howto/loadbalancers.html">load balancer worker</a> section.
 </p>

 <source>
   # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
   worker.worker1.type=ajp12
   worker.worker1.host=www.x.com
   worker.worker1.port=8007
   worker.worker1.lbfactor=2
 </source>

 <p>
 Note: The default port for ajp12 is 8007
 </p>

 </subsection>

 <subsection name="ajp13 Worker Properties">
 <p>
 The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajp13 protocol over TCP/IP sockets.
 The main difference between ajp12 and ajp13 are that:
 <ul>
 <li>
 ajp13 is a more binary protocol and it tries to compress some of the request data by coding
 frequently used strings as small integers.
 </li>
 <li>
 ajp13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
 web server and Tomcat).
 </li>
 <li>
 ajp13 has special treatment for SSL information so that the container can implement
 SSL related methods such as isSecure().
 </li>
 </ul>

 </p>

 <p>
 You should note that ajp13 is the recommended protocol to connect to Tomcat.
 </p>


 <source>
   # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
   worker.worker2.type=ajp13
   worker.worker2.host=www2.x.com
   worker.worker2.port=8009
   worker.worker2.lbfactor=3
   # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
   worker.worker2.connection_pool_timeout=600
   # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
   worker.worker2.socket_keepalive=1
   # mount can be used as an alternative to the JkMount directive
   worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
 </source>

 <p>
 Notes: In the ajp13 protocol, the default port is 8009
 </p>

 </subsection>

 <subsection name="lb Worker Properties">
 <p>
 The load balancing worker does not really communicate with Tomcat workers.
 Instead it is responsible for the management of several "real" workers.
 This management includes:
 </p>

 <ul>
 <li>
 Instantiating the workers in the web server.
 </li>
 <li>
 Using the worker's load balancing factor, perform weighted round-robin load balancing where
 a higher lbfactor means stronger machine (that is going to handle proportionally more requests)
 </li>
 <li>
 Keeping requests belonging to the same session executing on the same Tomcat worker
 (session stickyness).
 </li>
 <li>
 Identifying failed Tomcat workers, suspending requests to them and instead failing over on
 other workers managed by the lb worker.
 </li>
 </ul>

 <p>
 The overall result is that workers managed by the same lb worker are load balanced
 (based on their lbfactor and current user session) and also fail over so a single
 Tomcat process death will not "kill" the entire site.
 The following table specifies some properties that the lb worker can accept:
 <ul>
 <li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
 As long as these workers should only be used via the load balancer worker,
 there is no need to also put them into the worker.list property.
 This directive can be used multiple times for the same load balancer.</li>
 <li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
 Tomcat worker. Set sticky_session to <b>false</b> when Tomcat is using a Session Manager which
 can persist session data across multiple instances of Tomcat. By default sticky_session is set to
 <b>true</b>.</li>
 </ul>
 </p>

 <source>
   # The worker balance1 while use "real" workers worker1 and worker2
   worker.balance1.balance_workers=worker1, worker2
 </source>

 </subsection>

 <subsection name="Status Worker properties">
 <p>
 The status worker does not communicate with Tomcat.
 Instead it is responsible for the load balancer management.
 </p>
 <source>
   # Add the status worker to the worker list
   worker.list=jkstatus
   # Define a 'jkstatus' worker using status
   worker.jkstatus.type=status
 </source>
 <p>Next thing is to mount the requests to the jkstatus worker. For Apache
 HTTP Servers use:</p>
 <source>
   # Add the jkstatus mount point
   JkMount /jkmanager/* jkstatus
 </source>
 <p>To obtain a higher level of security use the:</p>
 <source>
   # Enable the JK manager access from localhost only
  &lt;Location /jkmanager/&gt;
     JkMount jkstatus
     Require ip 127.0.0.1
  &lt;/Location&gt;
 </source>

 </subsection>

 <subsection name="Property file macros">
 <p>
 You can define "macros" in the property files.
 These macros let you define properties and later on use them while
 constructing other properties.
 </p>

 <source>
   # property example, like a network base address
   mynet=194.226.31
   # Using the above macro to simplify the address definitions
   # for a farm of workers.
   worker.node1.host=$(mynet).11
   worker.node2.host=$(mynet).12
   worker.node3.host=$(mynet).13
 </source>

 </subsection>

 <subsection name="Hierarchical property configuration">
 <p>
 Workers can reference configurations of other workers.
 If worker "x" references worker "y", then it inherits all
 configuration parameters from "y", except for the ones
 that have explicitly been set for "x".
 </p>

 <source>
   # worker toe defines some default settings
   worker.toe.type=ajp13
   worker.toe.socket_keepalive=true
   worker.toe.connect_timeout=10000
   worker.toe.recovery_options=7
   # workers tic and tac inherit those values
   worker.tic.reference=worker.toe
   worker.tac.reference=worker.toe
 </source>

 <p>
 Please note, that the reference contains
 the full prefix to the referenced configuration attributes,
 not only the name of the referenced worker.
 </p>

 <p>
 References can be nested with a maximum depth of 20.
 Be careful to avoid loops!
 </p>

 <p>
 Attributes which are allowed multiple times for a single worker
 can not be merged from a worker and a reference. An attribute
 is only inherited from a reference, if it is not already set
 for the referring worker.
 </p>

 <p>
 References are especially useful, when configuring load balancers.
 Try to understand the following two stage references:
 </p>

 <source>
   # We only use one load balancer
   worker.list=lb
   # Let's define some defaults
   worker.basic.port=8009
   worker.basic.type=ajp13
   worker.basic.socket_keepalive=true
   worker.basic.connect_timeout=10000
   worker.basic.recovery_options=7
   # And we use them in two groups
   worker.lb1.domain=dom1
   worker.lb1.distance=0
   worker.lb1.reference=worker.basic
   worker.lb2.domain=dom2
   worker.lb2.distance=1
   worker.lb2.reference=worker.basic
   # Now we configure the load balancer
   worker.lb.type=lb
   worker.lb.method=B
   worker.lb.balanced_workers=w11,w12,w21,w22
   worker.w11.host=myhost11
   worker.w11.reference=worker.lb1
   worker.w12.host=myhost12
   worker.w12.reference=worker.lb1
   worker.w21.host=myhost21
   worker.w21.reference=worker.lb2
   worker.w22.host=myhost22
   worker.w22.reference=worker.lb2
 </source>

 </subsection>

 </section>

 <section name="A sample worker.properties">
 <p>
 Since coping with worker.properties on your own is not an easy thing to do,
 a sample worker.properties file is bundled along JK.
 </p>

 <p>
 You could also find here a sample workers.properties defining:
 </p>

 <ul>
 <li>
 Two ajp13 workers that use the host localhost and the ports 8109 and 8209
 </li>
 <li>
 An lb worker that load balances over the two ajp13 workers
 </li>
 </ul>

 <source>
   # Define 3 workers, 2 real workers using ajp13, and one being a load balancing worker
   worker.list=node1, node2, lbworker
   # Set properties for node1 (ajp13)
   worker.node1.type=ajp13
   worker.node1.host=localhost
   worker.node1.port=8109
   worker.node1.connection_pool_timeout=600
   worker.node1.socket_keepalive=1
   # Set properties for node2 (ajp13)
   worker.node2.type=ajp13
   worker.node2.host=localhost
   worker.node2.port=8209
   worker.node2.connection_pool_timeout=600
   worker.node2.socket_keepalive=1
   # Set properties for lbworker which uses node1 and node2
   worker.lbworker.type=lb
   worker.lbworker.balance_workers=node1,node2
 </source>

 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="workers.html">

	&project;
	<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>Workers HowTo</title>
	<author email="hgomez@apache.org">Henri Gomez</author>
	<author email="shachor@il.ibm.com">Gal Shachor</author>
	<author email="mturk@apache.org">Mladen Turk</author>
	<date>$Date$</date>
	</properties>
	<body>
	<section name="Introduction">
	<p>
	A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
	For example, we can have a web server such as the Apache HTTP Server forwarding servlet requests to a
	Tomcat process (the worker) running behind it.
	</p>
	<p>
	The scenario described above is a very simple one;
	in fact one can configure multiple Tomcat workers to serve servlets on
	behalf of a certain web server.
	The reasons for such configuration can be:
	</p>
	<ul>
	<li>
	We want different contexts to be served by different Tomcat workers to provide a
	development environment where all the developers share the same web server but own a Tomcat worker of their own.
	</li>
	<li>
	We want different virtual hosts served by different Tomcat processes to provide a
	clear separation between sites belonging to different companies.
	</li>
	<li>
	We want to provide load balancing, meaning run multiple Tomcat workers each on a
	machine of its own and distribute the requests between them.
	</li>
	</ul>

	<p>
	There are probably more reasons for having multiple workers but I guess that this list is enough...
	Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
	explains how to work with it.
	</p>

	<p>
	This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
	but has been split off for organisational reasons.
	</p>
	</section>

	<section name="Defining Workers">
	<p>
	Defining workers to the Tomcat web server plugin can be done using a properties file
	(a sample file named workers.properties is available in the conf/ directory).
	</p>

	<p>
	the file contains entries of the following form:
	</p>

	<p>
	<b>worker.list</b>=<a comma separated list of worker names>
	</p>

	<source>
	# the list of workers
	worker.list= worker1, worker2
	</source>

	<p>
	When starting up, the web server plugin will instantiate the workers whose name appears in the
	<b>worker.list</b> property, these are also the workers to whom you can map requests. The directive can be used multiple times.
	</p>

	<subsection name="Worker Types">
	<p>
	Each named worker should also have a few entries to provide additional information on his behalf.
	This information includes the worker's type and other related worker information.
	Currently the following worker types that exists are (JK 1.2.5):
	</p>

	<table>
	<tr><th>Type</th><th>Description</th></tr>
	<tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp13 protocol.</td></tr>
	<tr><td>lb</td><td>This is a load balancing worker; it knows how to provide flexible load balancing with a certain level of fault-tolerance.</td></tr>
	<tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
	<tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp12 protocol. It is deprecated</td></tr>
	<tr><td>ajp14</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajp14 protocol. It is experimental</td></tr>
	</table>

	<p>
	Defining workers of a certain type should be done with the following property format:
	</p>

	<p>
	<b>worker</b>.<b>worker name</b>.<b>type</b>=<worker type>
	Where worker name is the name assigned to the worker and the worker type is one of the four types defined
	in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).
	</p>

	<source>
	# Defines a worker named "local" that uses the ajp12 protocol to forward requests to a Tomcat process.
	worker.local.type=ajp12
	# Defines a worker named "remote" that uses the ajp13 protocol to forward requests to a Tomcat process.
	worker.remote.type=ajp13
	# Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
	worker.loadbalancer.type=lb
	</source>

	</subsection>

	</section>

	<section name="Setting Worker Properties">
	<p>
	After defining the workers you can also specify properties for them.
	Properties can be specified in the following manner:
	</p>

	<p>
	worker.<worker name>.<property>=<property value>
	</p>

	Each worker has a set of properties that you can set as specified in the following subsections:

	<subsection name="ajp12 Worker Properties">
	<p><warn>
	The worker type <b>ajp12</b> has been <b>deprecated</b> and you should use instead
	<b>ajp13</b> instead.
	</warn></p>
	<p>
	The ajp12 typed workers forward requests to out-of-process Tomcat workers
	using the ajp12 protocol over TCP/IP sockets. It does not use persistent connections.
	</p>

	<p>
	The ajp12 worker properties are:
	</p>

	<p>
	<b>host</b> property sets the host where the Tomcat worker is listening for ajp12 requests.
	</p>

	<p>
	<b>port</b> property sets the port where the Tomcat worker is listening for ajp12 requests
	</p>

	<p>
	<b>lbfactor</b> property is used when working with a load balancer worker, this is the load balancing factor for the worker.
	We'll see more on this in the <a href="../common_howto/loadbalancers.html">load balancer worker</a> section.
	</p>

	<source>
	# worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
	worker.worker1.type=ajp12
	worker.worker1.host=www.x.com
	worker.worker1.port=8007
	worker.worker1.lbfactor=2
	</source>

	<p>
	Note: The default port for ajp12 is 8007
	</p>

	</subsection>

	<subsection name="ajp13 Worker Properties">
	<p>
	The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajp13 protocol over TCP/IP sockets.
	The main difference between ajp12 and ajp13 are that:
	<ul>
	<li>
	ajp13 is a more binary protocol and it tries to compress some of the request data by coding
	frequently used strings as small integers.
	</li>
	<li>
	ajp13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
	web server and Tomcat).
	</li>
	<li>
	ajp13 has special treatment for SSL information so that the container can implement
	SSL related methods such as isSecure().
	</li>
	</ul>

	</p>

	<p>
	You should note that ajp13 is the recommended protocol to connect to Tomcat.
	</p>


	<source>
	# worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
	worker.worker2.type=ajp13
	worker.worker2.host=www2.x.com
	worker.worker2.port=8009
	worker.worker2.lbfactor=3
	# worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
	worker.worker2.connection_pool_timeout=600
	# worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
	worker.worker2.socket_keepalive=1
	# mount can be used as an alternative to the JkMount directive
	worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
	</source>

	<p>
	Notes: In the ajp13 protocol, the default port is 8009
	</p>

	</subsection>

	<subsection name="lb Worker Properties">
	<p>
	The load balancing worker does not really communicate with Tomcat workers.
	Instead it is responsible for the management of several "real" workers.
	This management includes:
	</p>

	<ul>
	<li>
	Instantiating the workers in the web server.
	</li>
	<li>
	Using the worker's load balancing factor, perform weighted round-robin load balancing where
	a higher lbfactor means stronger machine (that is going to handle proportionally more requests)
	</li>
	<li>
	Keeping requests belonging to the same session executing on the same Tomcat worker
	(session stickyness).
	</li>
	<li>
	Identifying failed Tomcat workers, suspending requests to them and instead failing over on
	other workers managed by the lb worker.
	</li>
	</ul>

	<p>
	The overall result is that workers managed by the same lb worker are load balanced
	(based on their lbfactor and current user session) and also fail over so a single
	Tomcat process death will not "kill" the entire site.
	The following table specifies some properties that the lb worker can accept:
	<ul>
	<li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
	As long as these workers should only be used via the load balancer worker,
	there is no need to also put them into the worker.list property.
	This directive can be used multiple times for the same load balancer.</li>
	<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
	Tomcat worker. Set sticky_session to <b>false</b> when Tomcat is using a Session Manager which
	can persist session data across multiple instances of Tomcat. By default sticky_session is set to
	<b>true</b>.</li>
	</ul>
	</p>

	<source>
	# The worker balance1 while use "real" workers worker1 and worker2
	worker.balance1.balance_workers=worker1, worker2
	</source>

	</subsection>

	<subsection name="Status Worker properties">
	<p>
	The status worker does not communicate with Tomcat.
	Instead it is responsible for the load balancer management.
	</p>
	<source>
	# Add the status worker to the worker list
	worker.list=jkstatus
	# Define a 'jkstatus' worker using status
	worker.jkstatus.type=status
	</source>
	<p>Next thing is to mount the requests to the jkstatus worker. For Apache
	HTTP Servers use:</p>
	<source>
	# Add the jkstatus mount point
	JkMount /jkmanager/* jkstatus
	</source>
	<p>To obtain a higher level of security use the:</p>
	<source>
	# Enable the JK manager access from localhost only
	<Location /jkmanager/>
	JkMount jkstatus
	Require ip 127.0.0.1
	</Location>
	</source>

	</subsection>

	<subsection name="Property file macros">
	<p>
	You can define "macros" in the property files.
	These macros let you define properties and later on use them while
	constructing other properties.
	</p>

	<source>
	# property example, like a network base address
	mynet=194.226.31
	# Using the above macro to simplify the address definitions
	# for a farm of workers.
	worker.node1.host=$(mynet).11
	worker.node2.host=$(mynet).12
	worker.node3.host=$(mynet).13
	</source>

	</subsection>

	<subsection name="Hierarchical property configuration">
	<p>
	Workers can reference configurations of other workers.
	If worker "x" references worker "y", then it inherits all
	configuration parameters from "y", except for the ones
	that have explicitly been set for "x".
	</p>

	<source>
	# worker toe defines some default settings
	worker.toe.type=ajp13
	worker.toe.socket_keepalive=true
	worker.toe.connect_timeout=10000
	worker.toe.recovery_options=7
	# workers tic and tac inherit those values
	worker.tic.reference=worker.toe
	worker.tac.reference=worker.toe
	</source>

	<p>
	Please note, that the reference contains
	the full prefix to the referenced configuration attributes,
	not only the name of the referenced worker.
	</p>

	<p>
	References can be nested with a maximum depth of 20.
	Be careful to avoid loops!
	</p>

	<p>
	Attributes which are allowed multiple times for a single worker
	can not be merged from a worker and a reference. An attribute
	is only inherited from a reference, if it is not already set
	for the referring worker.
	</p>

	<p>
	References are especially useful, when configuring load balancers.
	Try to understand the following two stage references:
	</p>

	<source>
	# We only use one load balancer
	worker.list=lb
	# Let's define some defaults
	worker.basic.port=8009
	worker.basic.type=ajp13
	worker.basic.socket_keepalive=true
	worker.basic.connect_timeout=10000
	worker.basic.recovery_options=7
	# And we use them in two groups
	worker.lb1.domain=dom1
	worker.lb1.distance=0
	worker.lb1.reference=worker.basic
	worker.lb2.domain=dom2
	worker.lb2.distance=1
	worker.lb2.reference=worker.basic
	# Now we configure the load balancer
	worker.lb.type=lb
	worker.lb.method=B
	worker.lb.balanced_workers=w11,w12,w21,w22
	worker.w11.host=myhost11
	worker.w11.reference=worker.lb1
	worker.w12.host=myhost12
	worker.w12.reference=worker.lb1
	worker.w21.host=myhost21
	worker.w21.reference=worker.lb2
	worker.w22.host=myhost22
	worker.w22.reference=worker.lb2
	</source>

	</subsection>

	</section>

	<section name="A sample worker.properties">
	<p>
	Since coping with worker.properties on your own is not an easy thing to do,
	a sample worker.properties file is bundled along JK.
	</p>

	<p>
	You could also find here a sample workers.properties defining:
	</p>

	<ul>
	<li>
	Two ajp13 workers that use the host localhost and the ports 8109 and 8209
	</li>
	<li>
	An lb worker that load balances over the two ajp13 workers
	</li>
	</ul>

	<source>
	# Define 3 workers, 2 real workers using ajp13, and one being a load balancing worker
	worker.list=node1, node2, lbworker
	# Set properties for node1 (ajp13)
	worker.node1.type=ajp13
	worker.node1.host=localhost
	worker.node1.port=8109
	worker.node1.connection_pool_timeout=600
	worker.node1.socket_keepalive=1
	# Set properties for node2 (ajp13)
	worker.node2.type=ajp13
	worker.node2.host=localhost
	worker.node2.port=8209
	worker.node2.connection_pool_timeout=600
	worker.node2.socket_keepalive=1
	# Set properties for lbworker which uses node1 and node2
	worker.lbworker.type=lb
	worker.lbworker.balance_workers=node1,node2
	</source>

	</section>
	</body>
	</document>