rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/loadbalancers.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic 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 Logo" 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>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>Generic HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the impatient</a></li><li><a href="../generic_howto/workers.html">All about workers</a></li><li><a href="../generic_howto/timeouts.html">Timeouts</a></li><li><a href="../generic_howto/loadbalancers.html">Load Balancing</a></li><li><a href="../generic_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>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&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;product=Tomcat+Connectors&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;emailassigned_to1=1&amp;emailtype1=substring&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailcc2=1&amp;emailtype2=substring&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;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/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 Connector - Generic 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
   2                     </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>
   3 <br>
   4 <p>A load balancer is a worker that does not directly communicate with Tomcat.
   5 Instead it is responsible for the management of several "real" workers,
   6 called members or sub workers of the load balancer.</p>
   7 <p>
   8 This management includes:
   9 </p>
  10 <ul>
  11 <li>
  12 Instantiating the workers in the web server.
  13 </li>
  14 <li>
  15 Using the worker's load-balancing factor, perform weighted load balancing
  16 (distributing load according to defined strengths of the targets).
  17 </li>
  18 <li>
  19 Keeping requests belonging to the same session executing on the same Tomcat
  20 (session stickyness).
  21 </li>
  22 <li>
  23 Identifying failed Tomcat workers, suspending requests to them and instead
  24 falling-back on other workers managed by the load balancer.
  25 </li>
  26 <li>
  27 Providing status and load metrics for the load balancer itself and all
  28 members via the status worker interface.
  29 </li>
  30 <li>
  31 Allowing to dynamically reconfigure load-balancing via the status worker
  32 interface.
  33 </li>
  34 </ul>
  35 <p>
  36 Workers managed by the same load balancer worker are load-balanced
  37 (based on their configured balancing factors and current request or session load)
  38 and also secured against failure by providing failover to other members of the same
  39 load balancer. So a single Tomcat process death will not "kill" the entire site.
  40 </p>
  41 <p>Some of the features provided by a load balancer are even interesting, when
  42 only working with a single member worker (where load balancing is not possible).</p>
  43
  44 <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>
  45 <p>A worker is configured as a load balancer by setting its worker <b class="code">type</b>
  46 to <b>lb</b>.
  47 </p>
  48 <p>
  49 The following table specifies some properties used to configure a load balancer worker:
  50 </p>
  51 <ul>
  52 <li><b>balance_workers</b> is a comma separated list of names of the member workers of the
  53 load balancer. These workers are typically of type <b>ajp13</b>. The member workers do
  54 not need to appear in the <b class="code">worker.list</b> property themselves, adding the
  55 load balancer to it suffices.</li>
  56 <li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed
  57 back to the same Tomcat instance that created the session. You can set sticky_session to
  58 <b>False</b> when Tomcat is using a session manager which can share session data across
  59 multiple instances of Tomcat - or if your application is stateless.
  60 By default sticky_session is set to <b>True</b>.</li>
  61 <li><b>lbfactor</b> can be added to each member worker to configure individual
  62 strengths for the members. A higher <b class="code">lbfactor</b> will lead to more
  63 requests being balanced to that worker. The factors must be given by integers and the
  64 load will be distributed proportional to the factors given. Higher factors lead to
  65 more requests.</li>
  66 </ul>
  67
  68 <div class="example"><pre>
  69   # The load balancer worker balance1 will distribute
  70   # load to the members worker1 and worker2
  71   worker.balance1.type=lb
  72   worker.balance1.balance_workers=worker1, worker2
  73   worker.worker1.type=ajp13
  74   worker.worker1.host=myhost1
  75   worker.worker1.port=8009
  76   worker.worker2.type=ajp13
  77   worker.worker1.host=myhost2
  78   worker.worker1.port=8009
  79 </pre></div>
  80
  81 <p><font color="#ff0000">
  82 Session stickyness is not implemented using a tracking table for sessions.
  83 Instead each Tomcat instance gets an individual name and adds its name at
  84 the end of the session id. When the load balancer sees a session id, it
  85 finds the name of the Tomcat instance and sends the request via the correct
  86 member worker. For this to work you must set the name of the Tomcat instances
  87 as the value of the <b class="code">jvmRoute</b> attribute in the Engine element of
  88 each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name
  89 of the corresponding load balancer member. In the above example, Tomcat on host
  90 "myhost1" needs <b class="code">jvmRoute="worker1"</b>, Tomcat on host "myhost2"
  91 needs <b class="code">jvmRoute="worker2"</b>.
  92 </font></p>
  93
  94 <p>For a complete reference of all load balancer configuration
  95 attributes, please consult the worker <a href="../reference/workers.html">reference</a>.
  96 </p>
  97 </blockquote></td></tr></table>
  98
  99 <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>
 100 <p>The load balancer supports complex topologies and failover configurations.
 101 Using the member attribute <b class="code">distance</b> you can group members.
 102 The load balancer will always send a request to a member of lowest distance.
 103 Only when all of those are broken, it will balance to the members of the
 104 next higher configured distance. This allows to define priorities between
 105 Tomcat instances in different data center locations.
 106 </p>
 107 <p>When working with shared sessions, either by using session replication
 108 or a persisting session manager (e.g. via a database), one often splits
 109 up the Tomcat farm into replication groups. In case of failure of a member,
 110 the load balancer needs to know, which other members share the session.
 111 This is configured using the <b class="code">domain</b> attribute. All workers
 112 with the same domain are assumed to share the sessions.</p>
 113 <p>For maintenance purposes you can tell the load balancer to not
 114 allow any new sessions on some members, or even not use them at all.
 115 This is controlled by the member attribute <b class="code">activation</b>.
 116 The value <b>Active</b> allows normal use of a member, <b>disabled</b>
 117 will not create new sessions on it, but still allow sticky requests,
 118 and <b>stopped</b> will no longer send any requests to the member.
 119 Switching the activation from "active" to "disabled" some time before
 120 maintenance will drain the sessions on the worker and minimize disruption.
 121 Depending on the usage pattern of the application, draining will take from
 122 minutes to hours. Switching the worker to stopped immediately before
 123 maintenance will reduce logging of false errors by mod_jk.</p>
 124 <p>Finally you can also configure hot spare workers by using
 125 <b class="code">activation</b> set to <b>disabled</b> in combination with
 126 the attribute <b class="code">redirect</b> added to the other workers:</p>
 127
 128 <div class="example"><pre>
 129   # The advanced router LB worker
 130   worker.list=router
 131   worker.router.type=lb
 132   worker.router.balance_workers=worker1,worker2
 133
 134   # Define the first member worker
 135   worker.worker1.type=ajp13
 136   worker.worker1.host=myhost1
 137   worker.worker1.port=8009
 138   # Define preferred failover node for worker1
 139   worker.worker1.redirect=worker2
 140
 141   # Define the second member worker
 142   worker.worker2.type=ajp13
 143   worker.worker2.host=myhost2
 144   worker.worker2.port=8009
 145   # Disable worker2 for all requests except failover
 146   worker.worker2.activation=disabled
 147 </pre></div>
 148
 149 <p>
 150 The <b class="code">redirect</b> flag on worker1 tells the load balancer
 151 to redirect the requests to worker2 in case that worker1 has a problem.
 152 In all other cases worker2 will not receive any requests, thus acting
 153 like a hot standby.
 154 </p>
 155
 156 <p>A final note about setting <b class="code">activation</b> to <b>disabled</b>:
 157 The session id coming with a request is send either
 158 as part of the request URL (<b class="code">;jsessionid=...</b>) or via a cookie.
 159 When using bookmarks or browsers that are running since a long time,
 160 it is possible to send a request carrying an old and invalid session id
 161 pointing at a disabled member.
 162 Since the load balancer does not have a list of valid sessions, it will
 163 forward the request to the disabled member. Thus draining takes longer than
 164 expected. To handle such cases, you can add a Servlet filter to your web
 165 application, which checks the request attribute <b class="code">JK_LB_ACTIVATION</b>.
 166 This attribute contains one of the strings "ACT", "DIS" or "STP". If you
 167 detect "DIS" and the session for the request is no longer active, delete the
 168 session cookie and redirect using a self-referential URL. The redirected
 169 request will then no longer carry session information and thus the load
 170 balancer will not send it to the disabled worker. The request attribute
 171 <b class="code">JK_LB_ACTIVATION</b> has been added in version 1.2.32.</p>
 172 </blockquote></td></tr></table>
 173
 174 <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>
 175 <p>
 176 The status worker does not communicate with Tomcat.
 177 Instead it is responsible for the worker management. It is
 178 especially useful when combined with load balancer workers.
 179 </p>
 180 <div class="example"><pre>
 181   # Add the status worker to the worker list
 182   worker.list=jkstatus
 183   # Define a 'jkstatus' worker using status
 184   worker.jkstatus.type=status
 185 </pre></div>
 186 <p>Next thing is to mount the requests to the jkstatus worker. For Apache
 187 web servers use the:</p>
 188 <div class="example"><pre>
 189   # Add the jkstatus mount point
 190   JkMount /jkmanager/* jkstatus
 191 </pre></div>
 192 <p>To obtain a higher level of security use the:</p>
 193 <div class="example"><pre>
 194   # Enable the JK manager access from localhost only
 195  &lt;Location /jkmanager/&gt;
 196     JkMount jkstatus
 197     Order deny,allow
 198     Deny from all
 199     Allow from 127.0.0.1
 200  &lt;/Location&gt;
 201 </pre></div>
 202
 203 </blockquote></td></tr></table>
 204
 205 </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>
 206         Copyright &copy; 1999-2011, Apache Software Foundation
 207         </em></font></div></td></tr></table></body></html>