2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Copyright 2004-2005 The Apache Software Foundation or its licensors, as
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_proxy_balancer.xml.meta">
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>
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
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>
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
49 <seealso><module>mod_proxy</module></seealso>
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
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>
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
73 <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
74 to fulfill its quota of work</em>.</p>
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>
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
86 <p>If some workers are disabled, the others will
87 still be scheduled correctly.</p>
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
95 candidate lbstatus -= total factor</code></pre>
98 <p>If a balancer is configured as follows:</p>
106 <tr><th>lbfactor</th>
111 <tr><th>lbstatus</th>
118 <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
126 <tr><th>lbstatus</th>
127 <td><em>-50</em></td>
131 <tr><th>lbstatus</th>
134 <td><em>-25</em></td>
136 <tr><th>lbstatus</th>
140 <td><em>0</em></td></tr>
141 <tr><td colspan="5">(repeat)</td></tr>
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>
154 <tr><th>lbfactor</th>
161 <p>Has the exact same behavior as:</p>
169 <tr><th>lbfactor</th>
176 <p>This is because all values of <dfn>lbfactor</dfn> are normalized
177 with respect to the others. For:</p>
184 <tr><th>lbfactor</th>
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>
193 <p>The following asymmetric configuration works as one would expect:</p>
199 <tr><th>lbfactor</th>
202 <tr><td colspan="2"> </td></tr>
203 <tr><th>lbstatus</th>
204 <td><em>-30</em></td>
206 <tr><th>lbstatus</th>
208 <td><em>-40</em></td></tr>
209 <tr><th>lbstatus</th>
212 <tr><th>lbstatus</th>
213 <td><em>-20</em></td>
215 <tr><th>lbstatus</th>
216 <td><em>-50</em></td>
218 <tr><th>lbstatus</th>
220 <td><em>-20</em></td></tr>
221 <tr><th>lbstatus</th>
222 <td><em>-10</em></td>
224 <tr><th>lbstatus</th>
225 <td><em>-40</em></td>
227 <tr><th>lbstatus</th>
229 <td><em>-30</em></td></tr>
230 <tr><th>lbstatus</th>
233 <tr><td colspan="3">(repeat)</td></tr>
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>
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>
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>
252 <p>If a balancer is configured as follows:</p>
259 <tr><th>lbfactor</th>
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>
274 <section id="enable">
275 <title>Enabling Balancer Manager Support</title>
276 <p>This module <em>requires</em> the service of
277 <module>mod_status</module>.
278 Balancer manager enables dynamic update of balancer
279 members. You can use balancer manager to change the balance
280 factor or a particular member, or put it in the off line
284 <p>Thus, in order to get the ability of load balancer management,
285 <module>mod_status</module> and <module>mod_proxy_balancer</module>
286 have to be present in the server.</p>
288 <p>To enable load balancer management for browsers from the foo.com
289 domain add this code to your <code>httpd.conf</code>
290 configuration file</p>
292 <Location /balancer-manager><br />
293 SetHandler balancer-manager<br />
295 Order Deny,Allow<br />
297 Allow from .foo.com<br />
301 <p>You can now access load balancer manager by using a Web browser
303 <code>http://your.server.name/balancer-manager</code></p>