The Apache Tomcat Connector - Generic HowToWorkers HowTo |  |
| Introduction |
-
-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 Apache forwarding servlet requests to a
-Tomcat process (the worker) running behind it.
-
-
-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:
-
-
--
-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.
-
--
-We want different virtual hosts served by different Tomcat processes to provide a
-clear separation between sites belonging to different companies.
-
--
-We want to provide load balancing, meaning run multiple Tomcat workers each on a
-machine of its own and distribute the requests between them.
-
-
-
-
-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.
-
-
-
-This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor,
-but has been split off for organisational reasons.
-
- |
| Defining Workers |
-
-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).
-
-
-
-the file contains entries of the following form:
-
-
-
-worker.list=<a comma separated list of worker names>
-
-
-
- # the list of workers
- worker.list= worker1, worker2
-
-When starting up, the web server plugin will instantiate the workers whose name appears in the
-worker.list property, these are also the workers to whom you can map requests. The directive can be used multiple times.
-
-
-| Workers Type |
-
-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):
-
-
-
- | Type | Description |
|---|
- | ajp12 | This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol. |
- | ajp13 | This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol. |
- | jni | DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI. |
- | lb | This is a load-balancing worker; it knows how to provide round-robin based sticky load balancing with a certain level of fault-tolerance. |
- | status | This is a status worker for managing load balancers. |
-
-
-
-Defining workers of a certain type should be done with the following property format:
-
-
-
-worker.worker name.type=<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\-_]).
-
-
-
- # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
- worker.local.type=ajp12
- # Defines a worker named "remote" that uses the ajpv13 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
- |
-
- |
| Setting Worker Properties |
-
-After defining the workers you can also specify properties for them.
-Properties can be specified in the following manner:
-
-
-
-worker.<worker name>.<property>=<property value>
-
-
-Each worker has a set of properties that you can set as specified in the following subsections:
-
-| ajp12 Worker properties |
-
-The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead
-ajp13 which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6.
-
-
-The ajp12 typed workers forward requests to out-of-process Tomcat workers
-using the ajpv12 protocol over TCP/IP sockets.
-
-
-
-the ajp12 worker properties are :
-
-
-
-host property sets the host where the Tomcat worker is listening for ajp12 requests.
-
-
-
-port property sets the port where the Tomcat worker is listening for ajp12 requests
-
-
-
-lbfactor 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 lb worker section.
-
-
-
- # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
- worker.worker1.host=www.x.com
- worker.worker1.port=8007
- worker.worker1.lbfactor=2
-
-Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
-The default port for ajp12 is 8007
-
-
- |
-
-| ajp13 Worker properties |
-
-The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
-The main difference between ajpv12 and ajpv13 are that:
-
--
-ajpv13 is a more binary protocol and it tries to compress some of the request data by coding
-frequently used strings as small integers.
-
--
-ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
-web server and Tomcat).
-
--
-ajpv13 has special treatment for SSL information so that the container can implement
-SSL related methods such as isSecure().
-
-
-
-
-
-
-You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6.
-
-
-
-
- # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
- 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/*
-
-Notes: In the ajpv13 protocol, the default port is 8009
-
-
- |
-
-| lb Worker properties |
-
-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:
-
-
-
--
-Instantiating the workers in the web server.
-
--
-Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
-high lbfactor means stronger machine (that is going to handle more requests)
-
--
-Keeping requests belonging to the same session executing on the same Tomcat worker.
-
--
-Identifying failed Tomcat workers, suspending requests to them and instead falling-back on
-other workers managed by the lb worker.
-
-
-
-
-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 fall-backed so a single Tomcat process death will not "kill" the entire site.
-The following table specifies some properties that the lb worker can accept:
-
-- balance_workers 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.
-- sticky_session specifies whether requests with SESSION ID's should be routed back to the same
-Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which
-can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.
-
-
-
-
- # The worker balance1 while use "real" workers worker1 and worker2
- worker.balance1.balance_workers=worker1, worker2
- |
-
-| Status Worker properties |
-
-The status worker does not communicate with Tomcat.
-Instead it is responsible for the load balancer management.
-
-
- # Add the status worker to the worker list
- worker.list=jkstatus
- # Define a 'jkstatus' worker using status
- worker.jkstatus.type=status
- Next thing is to mount the requests to the jkstatus worker. For Apache
-web servers use the:
-
- # Add the jkstatus mount point
- JkMount /jkmanager/* jkstatus
- To obtain a higher level of security use the:
-
- # Enable the JK manager access from localhost only
- <Location /jkmanager/>
- JkMount jkstatus
- Order deny,allow
- Deny from all
- Allow from 127.0.0.1
- </Location>
- |
-
-| Property file macros |
-
-You can define "macros" in the property files.
-These macros let you define properties and later on use them while
-constructing other properties.
-
-
-
- # 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
- |
-
-| Hierarchical property configuration |
-
-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".
-
-
-
- # 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
-
-Please note, that the reference contains
-the full prefix to the referenced configuration attributes,
-not only the name of the referenced worker.
-
-
-
-References can be nested. Be careful to avoid loops!
-
-
-
-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.
-
-
-
-References are especially useful, when configuring load balancers.
-Try to understand the following two stage references:
-
-
-
- # 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
- |
-
- |
| A sample worker.properties |
-
-Since coping with worker.properties on your own is not an easy thing to do,
-a sample worker.properties file is bundled along JK.
-
-
-
-You could also find here a sample workers.properties defining :
-
-
-
--
-An ajp12 worker that used the host localhost and the port 8007
-
--
-An ajp13 worker that used the host localhost and the port 8008
-
--
-An lb worker that load balance the ajp12 and ajp13 workers
-
-
-
-
- # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker
- worker.list=worker1, worker2, worker3
- # Set properties for worker1 (ajp12)
- worker.worker1.type=ajp12
- worker.worker1.host=localhost
- worker.worker1.port=8007
- worker.worker1.lbfactor=1
- # Set properties for worker2 (ajp13)
- worker.worker2.type=ajp13
- worker.worker2.host=localhost
- worker.worker2.port=8009
- worker.worker2.lbfactor=1
- worker.worker2.connection_pool_timeout=600
- worker.worker2.socket_keepalive=1
- worker.worker2.socket_timeout=60
- # Set properties for worker3 (lb) which use worker1 and worker2
- worker.worker3.balance_workers=worker1,worker2
- |
|
