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

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