<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Apache Tomcat Connectors - Common HowTo - LoadBalancer HowTo</title><meta name="author" value="Mladen Turk"><meta name="email" value="mturk@apache.org"><link href="../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt=" :: Apache Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Common HowTo</strong></p><ul><li><a href="../common_howto/quick.html">For the impatient</a></li><li><a href="../common_howto/workers.html">All about workers</a></li><li><a href="../common_howto/timeouts.html">Timeouts</a></li><li><a href="../common_howto/loadbalancers.html">Load Balancing</a></li><li><a href="../common_howto/proxy.html">Reverse Proxy</a></li></ul><p><strong>Webserver HowTo</strong></p><ul><li><a href="../webserver_howto/apache.html">Apache HTTP Server</a></li><li><a href="../webserver_howto/iis.html">IIS</a></li><li><a href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>Reference Guide</strong></p><ul><li><a href="../reference/workers.html">workers.properties</a></li><li><a href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a href="../reference/status.html">Status Worker</a></li><li><a href="../reference/apache.html">Apache HTTP Server</a></li><li><a href="../reference/iis.html">IIS</a></li></ul><p><strong>AJP Protocol Reference</strong></p><ul><li><a href="../ajp/ajpv13a.html">AJPv13</a></li><li><a href="../ajp/ajpv13ext.html">AJPv13 Extension Proposal</a></li></ul><p><strong>Miscellaneous Documentation</strong></p><ul><li><a href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a href="../miscellaneous/changelog.html">Changelog</a></li><li><a href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=">Current Tomcat Connectors bugs</a></li><li><a href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html">Old JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a href="../news/20140201.html">2014</a></li><li><a href="../news/20120301.html">2012</a></li><li><a href="../news/20110701.html">2011</a></li><li><a href="../news/20100101.html">2010</a></li><li><a href="../news/20090301.html">2009</a></li><li><a href="../news/20081001.html">2008</a></li><li><a href="../news/20070301.html">2007</a></li><li><a href="../news/20060101.html">2006</a></li><li><a href="../news/20050101.html">2005</a></li><li><a href="../news/20041100.html">2004</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connectors - Common HowTo</h1><h2>LoadBalancer HowTo</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/loadbalancers.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
</a></small></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
<br>
<p>A load balancer is a worker that does not directly communicate with Tomcat.
Instead it is responsible for the management of several "real" workers,
called members or sub workers of the load balancer.</p>
<p>
This management includes:
</p>
<ul>
<li>
Instantiating the workers in the web server.
</li>
<li>
Using the worker's load-balancing factor, perform weighted load balancing
(distributing load according to defined strengths of the targets).
</li>
<li>
Keeping requests belonging to the same session executing on the same Tomcat
(session stickyness).
</li>
<li>
Identifying failed Tomcat workers, suspending requests to them and instead
falling-back on other workers managed by the load balancer.
</li>
<li>
Providing status and load metrics for the load balancer itself and all
members via the status worker interface.
</li>
<li>
Allowing to dynamically reconfigure load-balancing via the status worker
interface.
</li>
</ul>
<p>
Workers managed by the same load balancer worker are load-balanced
(based on their configured balancing factors and current request or session load)
and also secured against failure by providing failover to other members of the same
load balancer. So a single Tomcat process death will not "kill" the entire site.
</p>
<p>Some of the features provided by a load balancer are even interesting, when
only working with a single member worker (where load balancing is not possible).</p>
<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Basic Load Balancer Properties"><strong>Basic Load Balancer Properties</strong></a></font></td></tr><tr><td><blockquote>
<p>A worker is configured as a load balancer by setting its worker <b class="code">type</b>
to <b>lb</b>.
</p>
<p>
The following table specifies some properties used to configure a load balancer worker:
</p>
<ul>
<li><b>balance_workers</b> is a comma separated list of names of the member workers of the
load balancer. These workers are typically of type <b>ajp13</b>. The member workers do
not need to appear in the <b class="code">worker.list</b> property themselves, adding the
load balancer to it suffices.</li>
<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed
back to the same Tomcat instance that created the session. You can set sticky_session to
<b>false</b> when Tomcat is using a session manager which can share session data across
multiple instances of Tomcat - or if your application is stateless.
By default sticky_session is set to <b>true</b>.</li>
<li><b>lbfactor</b> can be added to each member worker to configure individual
strengths for the members. A higher <b class="code">lbfactor</b> will lead to more
requests being balanced to that worker. The factors must be given by integers and the
load will be distributed proportional to the factors given. Higher factors lead to
more requests.</li>
</ul>
<div class="example"><pre>
# The load balancer worker balance1 will distribute
# load to the members worker1 and worker2
worker.balance1.type=lb
worker.balance1.balance_workers=worker1, worker2
worker.worker1.type=ajp13
worker.worker1.host=myhost1
worker.worker1.port=8009
worker.worker2.type=ajp13
worker.worker1.host=myhost2
worker.worker1.port=8009
</pre></div>
<p><font color="#ff0000">
Session stickyness is not implemented using a tracking table for sessions.
Instead each Tomcat instance gets an individual name and adds its name at
the end of the session id. When the load balancer sees a session id, it
finds the name of the Tomcat instance and sends the request via the correct
member worker. For this to work you must set the name of the Tomcat instances
as the value of the <b class="code">jvmRoute</b> attribute in the Engine element of
each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name
of the corresponding load balancer member. In the above example, Tomcat on host
"myhost1" needs <b class="code">jvmRoute="worker1"</b>, Tomcat on host "myhost2"
needs <b class="code">jvmRoute="worker2"</b>.
</font></p>
<p>For a complete reference of all load balancer configuration
attributes, please consult the worker <a href="../reference/workers.html">reference</a>.
</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Advanced Load Balancer Worker Properties"><strong>Advanced Load Balancer Worker Properties</strong></a></font></td></tr><tr><td><blockquote>
<p>The load balancer supports complex topologies and failover configurations.
Using the member attribute <b class="code">distance</b> you can group members.
The load balancer will always send a request to a member of lowest distance.
Only when all of those are broken, it will balance to the members of the
next higher configured distance. This allows to define priorities between
Tomcat instances in different data center locations.
</p>
<p>When working with shared sessions, either by using session replication
or a persisting session manager (e.g. via a database), one often splits
up the Tomcat farm into replication groups. In case of failure of a member,
the load balancer needs to know, which other members share the session.
This is configured using the <b class="code">domain</b> attribute. All workers
with the same domain are assumed to share the sessions.</p>
<p>For maintenance purposes you can tell the load balancer to not
allow any new sessions on some members, or even not use them at all.
This is controlled by the member attribute <b class="code">activation</b>.
The value <b>Active</b> allows normal use of a member, <b>disabled</b>
will not create new sessions on it, but still allow sticky requests,
and <b>stopped</b> will no longer send any requests to the member.
Switching the activation from "active" to "disabled" some time before
maintenance will drain the sessions on the worker and minimize disruption.
Depending on the usage pattern of the application, draining will take from
minutes to hours. Switching the worker to stopped immediately before
maintenance will reduce logging of false errors by mod_jk.</p>
<p>Finally you can also configure hot spare workers by using
<b class="code">activation</b> set to <b>disabled</b> in combination with
the attribute <b class="code">redirect</b> added to the other workers:</p>
<div class="example"><pre>
# The advanced router LB worker
worker.list=router
worker.router.type=lb
worker.router.balance_workers=worker1,worker2
# Define the first member worker
worker.worker1.type=ajp13
worker.worker1.host=myhost1
worker.worker1.port=8009
# Define preferred failover node for worker1
worker.worker1.redirect=worker2
# Define the second member worker
worker.worker2.type=ajp13
worker.worker2.host=myhost2
worker.worker2.port=8009
# Disable worker2 for all requests except failover
worker.worker2.activation=disabled
</pre></div>
<p>
The <b class="code">redirect</b> flag on worker1 tells the load balancer
to redirect the requests to worker2 in case that worker1 has a problem.
In all other cases worker2 will not receive any requests, thus acting
like a hot standby.
</p>
<p>A final note about setting <b class="code">activation</b> to <b>disabled</b>:
The session id coming with a request is send either
as part of the request URL (<b class="code">;jsessionid=...</b>) or via a cookie.
When using bookmarks or browsers that are running since a long time,
it is possible to send a request carrying an old and invalid session id
pointing at a disabled member.
Since the load balancer does not have a list of valid sessions, it will
forward the request to the disabled member. Thus draining takes longer than
expected. To handle such cases, you can add a Servlet filter to your web
application, which checks the request attribute <b class="code">JK_LB_ACTIVATION</b>.
This attribute contains one of the strings "ACT", "DIS" or "STP". If you
detect "DIS" and the session for the request is no longer active, delete the
session cookie and redirect using a self-referential URL. The redirected
request will then no longer carry session information and thus the load
balancer will not send it to the disabled worker. The request attribute
<b class="code">JK_LB_ACTIVATION</b> has been added in version 1.2.32.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Status Worker properties"><strong>Status Worker properties</strong></a></font></td></tr><tr><td><blockquote>
<p>
The status worker does not communicate with Tomcat.
Instead it is responsible for the worker management. It is
especially useful when combined with load balancer workers.
</p>
<div class="example"><pre>
# Add the status worker to the worker list
worker.list=jkstatus
# Define a 'jkstatus' worker using status
worker.jkstatus.type=status
</pre></div>
<p>Next thing is to mount the requests to the jkstatus worker. For Apache
web servers use the:</p>
<div class="example"><pre>
# Add the jkstatus mount point
JkMount /jkmanager/* jkstatus
</pre></div>
<p>To obtain a higher level of security use the:</p>
<div class="example"><pre>
# 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>
</pre></div>
</blockquote></td></tr></table>
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
Copyright © 1999-2015, Apache Software Foundation
</em></font></div></td></tr></table></body></html>
