granicus.if.org Git - apache/blob - docs/manual/mod/mod_proxy_balancer.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_proxy_balancer - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_proxy_balancer</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_balancer.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> extension for load balancing </td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_balancer_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>proxy_balancer.c</td></tr>
  31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.1 and later</td></tr></table>
  32 <h3>Summary</h3>
  33
  34     <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. It provides load balancing support for
  35     <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols
  36     </p>
  37
  38     <p>Thus, in order to get the ability of load balancing,
  39     <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
  40     have to be present in the server.</p>
  41
  42     <div class="warning"><h3>Warning</h3>
  43       <p>Do not enable proxying until you have <a href="mod_proxy.html#access">secured your server</a>. Open proxy
  44       servers are dangerous both to your network and to the Internet at
  45       large.</p>
  46     </div>
  47 </div>
  48 <div id="quickview"><h3 class="directives">Directives</h3>
  49 <p>This module provides no
  50             directives.</p>
  51 <h3>Topics</h3>
  52 <ul id="topics">
  53 <li><img alt="" src="../images/down.gif" /> <a href="#scheduler">Load balancer scheduler algorithm</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#requests">Request Counting Algorithm</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#traffic">Weighted Traffic Counting Algorithm</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#environment">Exported Environment Variables</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Balancer Manager Support</a></li>
  58 </ul><h3>See also</h3>
  59 <ul class="seealso">
  60 <li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
  61 </ul></div>
  62 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  63 <div class="section">
  64 <h2><a name="scheduler" id="scheduler">Load balancer scheduler algorithm</a></h2>
  65
  66     <p>At present, there are 2 load balancer scheduler algorithms available
  67     for use: Request Counting and Weighted Traffic Counting. These are controlled
  68     via the <code>lbmethod</code> value of the Balancer definition. See
  69     the <code class="directive"><a href="../mod/mod_proxy.html#proxy">Proxy</a></code> directive for
  70     more information.</p>
  71
  72 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  73 <div class="section">
  74 <h2><a name="requests" id="requests">Request Counting Algorithm</a></h2>
  75
  76     <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this
  77     scheduler is that we distribute the requests among the
  78     various workers to ensure that each gets their configured share
  79     of the number of requests. It works as follows:</p>
  80
  81     <p><dfn>lbfactor</dfn> is <em>how much we expect this worker
  82     to work</em>, or <em>the workers's work quota</em>. This is
  83     a normalized value representing their "share" of the amount of
  84     work to be done.</p>
  85
  86     <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
  87     to fulfill its quota of work</em>.</p>
  88
  89     <p>The <dfn>worker</dfn> is a member of the load balancer,
  90     usually a remote host serving one of the supported protocols.</p>
  91
  92     <p>We distribute each worker's work quota to the worker, and then look
  93     which of them needs to work most urgently (biggest lbstatus).  This
  94     worker is then selected for work, and its lbstatus reduced by the
  95     total work quota we distributed to all workers.  Thus the sum of all
  96     lbstatus does not change(*) and we distribute the requests
  97     as desired.</p>
  98
  99     <p>If some workers are disabled, the others will
 100     still be scheduled correctly.</p>
 101
 102     <div class="example"><pre><code>for each worker in workers
 103     worker lbstatus += worker lbfactor
 104     total factor    += worker lbfactor
 105     if worker lbstatus &gt; candidate lbstatus
 106         candidate = worker
 107
 108 candidate lbstatus -= total factor</code></pre></div>
 109
 110     <p>If a balancer is configured as follows:</p>
 111
 112     <table><tr><th>worker</th>
 113         <th class="data">a</th>
 114         <th class="data">b</th>
 115         <th class="data">c</th>
 116         <th class="data">d</th></tr>
 117 <tr><th>lbfactor</th>
 118         <td class="data">25</td>
 119         <td class="data">25</td>
 120         <td class="data">25</td>
 121         <td class="data">25</td></tr>
 122 <tr><th>lbstatus</th>
 123         <td class="data">0</td>
 124         <td class="data">0</td>
 125         <td class="data">0</td>
 126         <td class="data">0</td></tr>
 127 </table>
 128
 129     <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
 130
 131     <table><tr><th>worker</th>
 132         <th class="data">a</th>
 133         <th class="data">b</th>
 134         <th class="data">c</th>
 135         <th class="data">d</th></tr>
 136 <tr><th>lbstatus</th>
 137         <td class="data"><em>-50</em></td>
 138         <td class="data">0</td>
 139         <td class="data">25</td>
 140         <td class="data">25</td></tr>
 141 <tr><th>lbstatus</th>
 142         <td class="data">-25</td>
 143         <td class="data">0</td>
 144         <td class="data"><em>-25</em></td>
 145         <td class="data">50</td></tr>
 146 <tr><th>lbstatus</th>
 147         <td class="data">0</td>
 148         <td class="data">0</td>
 149         <td class="data">0</td>
 150         <td class="data"><em>0</em></td></tr>
 151 <tr><td class="data" colspan="5">(repeat)</td></tr>
 152 </table>
 153
 154     <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var>
 155     <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var>
 156     <var>d</var> ... Please note that:</p>
 157
 158     <table><tr><th>worker</th>
 159         <th class="data">a</th>
 160         <th class="data">b</th>
 161         <th class="data">c</th>
 162         <th class="data">d</th></tr>
 163 <tr><th>lbfactor</th>
 164         <td class="data">25</td>
 165         <td class="data">25</td>
 166         <td class="data">25</td>
 167         <td class="data">25</td></tr>
 168 </table>
 169
 170     <p>Has the exact same behavior as:</p>
 171
 172     <table><tr><th>worker</th>
 173         <th class="data">a</th>
 174         <th class="data">b</th>
 175         <th class="data">c</th>
 176         <th class="data">d</th></tr>
 177 <tr><th>lbfactor</th>
 178         <td class="data">1</td>
 179         <td class="data">1</td>
 180         <td class="data">1</td>
 181         <td class="data">1</td></tr>
 182 </table>
 183
 184     <p>This is because all values of <dfn>lbfactor</dfn> are normalized
 185     with respect to the others. For:</p>
 186
 187     <table><tr><th>worker</th>
 188         <th class="data">a</th>
 189         <th class="data">b</th>
 190         <th class="data">c</th></tr>
 191 <tr><th>lbfactor</th>
 192         <td class="data">1</td>
 193         <td class="data">4</td>
 194         <td class="data">1</td></tr>
 195 </table>
 196
 197     <p>worker <var>b</var> will, on average, get 4 times the requests
 198     that <var>a</var> and <var>c</var> will.</p>
 199
 200     <p>The following asymmetric configuration works as one would expect:</p>
 201
 202     <table><tr><th>worker</th>
 203         <th class="data">a</th>
 204         <th class="data">b</th></tr>
 205 <tr><th>lbfactor</th>
 206         <td class="data">70</td>
 207         <td class="data">30</td></tr>
 208 <tr><td class="data" colspan="2">&nbsp;</td></tr>
 209 <tr><th>lbstatus</th>
 210         <td class="data"><em>-30</em></td>
 211         <td class="data">30</td></tr>
 212 <tr><th>lbstatus</th>
 213         <td class="data">40</td>
 214         <td class="data"><em>-40</em></td></tr>
 215 <tr><th>lbstatus</th>
 216         <td class="data"><em>10</em></td>
 217         <td class="data">-10</td></tr>
 218 <tr><th>lbstatus</th>
 219         <td class="data"><em>-20</em></td>
 220         <td class="data">20</td></tr>
 221 <tr><th>lbstatus</th>
 222         <td class="data"><em>-50</em></td>
 223         <td class="data">50</td></tr>
 224 <tr><th>lbstatus</th>
 225         <td class="data">20</td>
 226         <td class="data"><em>-20</em></td></tr>
 227 <tr><th>lbstatus</th>
 228         <td class="data"><em>-10</em></td>
 229         <td class="data">10</td></tr>
 230 <tr><th>lbstatus</th>
 231         <td class="data"><em>-40</em></td>
 232         <td class="data">40</td></tr>
 233 <tr><th>lbstatus</th>
 234         <td class="data">30</td>
 235         <td class="data"><em>-30</em></td></tr>
 236 <tr><th>lbstatus</th>
 237         <td class="data"><em>0</em></td>
 238         <td class="data">0</td></tr>
 239 <tr><td class="data" colspan="3">(repeat)</td></tr>
 240 </table>
 241
 242     <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var>
 243     are selected with 3 <var>b</var> interspersed.</p>
 244 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 245 <div class="section">
 246 <h2><a name="traffic" id="traffic">Weighted Traffic Counting Algorithm</a></h2>
 247
 248     <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this
 249     scheduler is very similar to the Request Counting method, with
 250     the following changes:</p>
 251
 252     <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want
 253     this worker to handle</em>. This is also a normalized value
 254     representing their "share" of the amount of work to be done,
 255     but instead of simply counting the number of requests, we take
 256     into account the amount of traffic this worker has seen.</p>
 257
 258     <p>If a balancer is configured as follows:</p>
 259
 260     <table><tr><th>worker</th>
 261         <th class="data">a</th>
 262         <th class="data">b</th>
 263         <th class="data">c</th></tr>
 264 <tr><th>lbfactor</th>
 265         <td class="data">1</td>
 266         <td class="data">2</td>
 267         <td class="data">1</td></tr>
 268 </table>
 269
 270     <p>Then we mean that we want <var>b</var> to process twice the
 271     amount of bytes than <var>a</var> or <var>c</var> should. It does
 272     not necessarily mean that <var>b</var> would handle twice as
 273     many requests, but it would process twice the I/O. Thus, the
 274     size of the request and response are applied to the weighting
 275     and selection algorithm.</p>
 276
 277 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 278 <div class="section">
 279 <h2><a name="environment" id="environment">Exported Environment Variables</a></h2>
 280
 281     <p>At present there are 6 environment variables exported:</p>
 282
 283     <dl>
 284
 285     <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
 286     <dd>
 287     <p>This is assigned the <var>stickysession</var> value used in the current
 288     request.  It is the cookie or parameter name used for sticky sessions</p>
 289     </dd>
 290
 291
 292     <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
 293     <dd>
 294     <p>This is assigned the <var>route</var> parsed from the current
 295     request.</p>
 296     </dd>
 297
 298
 299     <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
 300     <dd>
 301     <p>This is assigned the name of the balancer used for the current
 302     request. The value is something like <code>balancer://foo</code>.</p>
 303     </dd>
 304
 305
 306     <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
 307     <dd>
 308     <p>This is assigned the name of the worker used for the current request.
 309     The value is something like <code>http://hostA:1234</code>.</p>
 310     </dd>
 311
 312
 313     <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
 314     <dd>
 315     <p>This is assigned the <var>route</var> of the worker that will be
 316     used for the current request.</p>
 317     </dd>
 318
 319
 320     <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
 321     <dd>
 322     <p>This is set to 1 if the session route does not match the
 323     worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
 324     session does not yet have an established route.  This can be used to
 325     determine when/if the client needs to be sent an updated route
 326     when sticky sessions are used.</p>
 327     </dd>
 328     </dl>
 329
 330 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 331 <div class="section">
 332 <h2><a name="enable" id="enable">Enabling Balancer Manager Support</a></h2>
 333
 334     <p>This module <em>requires</em> the service of
 335     <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.
 336     Balancer manager enables dynamic update of balancer
 337     members. You can use balancer manager to change the balance
 338     factor or a particular member, or put it in the off line
 339     mode.
 340     </p>
 341
 342     <p>Thus, in order to get the ability of load balancer management,
 343     <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> and <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
 344     have to be present in the server.</p>
 345
 346     <p>To enable load balancer management for browsers from the foo.com
 347     domain add this code to your <code>httpd.conf</code>
 348     configuration file</p>
 349 <div class="example"><p><code>
 350     &lt;Location /balancer-manager&gt;<br />
 351     SetHandler balancer-manager<br />
 352 <br />
 353     Order Deny,Allow<br />
 354     Deny from all<br />
 355     Allow from .foo.com<br />
 356     &lt;/Location&gt;
 357 </code></p></div>
 358
 359     <p>You can now access load balancer manager by using a Web browser
 360     to access the page
 361     <code>http://your.server.name/balancer-manager</code></p>
 362 </div>
 363 </div>
 364 <div class="bottomlang">
 365 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_balancer.html" title="English">&nbsp;en&nbsp;</a> |
 366 <a href="../ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
 367 </div><div id="footer">
 368 <p class="apache">Copyright 2006 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 369 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 370 </body></html>