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