mod_proxy_balancer.xml revision ad9438d62e51f5785e0175c2d3e5308df5968a6c
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl<!-- $LastChangedRevision$ -->
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl Licensed to the Apache Software Foundation (ASF) under one or more
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl contributor license agreements. See the NOTICE file distributed with
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl this work for additional information regarding copyright ownership.
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl The ASF licenses this file to You under the Apache License, Version 2.0
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl (the "License"); you may not use this file except in compliance with
a530dde7009b0a808300c420def741354a4d13d2Martin Kühl the License. You may obtain a copy of the License at
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Unless required by applicable law or agreed to in writing, software
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco distributed under the License is distributed on an "AS IS" BASIS,
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco See the License for the specific language governing permissions and
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco limitations under the License.
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<modulesynopsis metafile="mod_proxy_balancer.xml.meta">
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<description><module>mod_proxy</module> extension for load balancing </description>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<compatibility>Available in version 2.1 and later</compatibility>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <p>This module <em>requires</em> the service of <module
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco >mod_proxy</module>. It provides load balancing support for
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <p>Thus, in order to get the ability of load balancing,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <module>mod_proxy</module> and <module>mod_proxy_balancer</module>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco have to be present in the server.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco href="mod_proxy.html#access">secured your server</a>. Open proxy
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco servers are dangerous both to your network and to the Internet at
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <title>Load balancer scheduler algorithm</title>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>At present, there are 3 load balancer scheduler algorithms available
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco for use: Request Counting, Weighted Traffic Counting and Pending Request
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Counting. These are controlled via the <code>lbmethod</code> value of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco the Balancer definition. See the <directive module="mod_proxy">ProxyPass</directive>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco directive for more information.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <title>Example of a balancer configuration</title>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Before we dive into the technical details, here's an example of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco how you might use <module>mod_proxy_balancer</module> to provide
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco load balancing between two back-end servers:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <Proxy balancer://mycluster><br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco </Proxy><br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco ProxyPass /test balancer://mycluster/
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco scheduler is that we distribute the requests among the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco various workers to ensure that each gets their configured share
7474965b2e6323002c96c0b39a59843cde201870Adrián Riesco of the number of requests. It works as follows:</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p><dfn>lbfactor</dfn> is <em>how much we expect this worker
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco to work</em>, or <em>the workers's work quota</em>. This is
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco a normalized value representing their "share" of the amount of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco work to be done.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>The <dfn>worker</dfn> is a member of the load balancer,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco usually a remote host serving one of the supported protocols.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>We distribute each worker's work quota to the worker, and then look
7474965b2e6323002c96c0b39a59843cde201870Adrián Riesco which of them needs to work most urgently (biggest lbstatus). This
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco worker is then selected for work, and its lbstatus reduced by the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco total work quota we distributed to all workers. Thus the sum of all
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco lbstatus does not change(*) and we distribute the requests
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco as desired.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>If some workers are disabled, the others will
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco still be scheduled correctly.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <example><pre><code>for each worker in workers
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco worker lbstatus += worker lbfactor
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco total factor += worker lbfactor
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco if worker lbstatus > candidate lbstatus
7474965b2e6323002c96c0b39a59843cde201870Adrián Riesco candidate = worker
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescocandidate lbstatus -= total factor</code></pre>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>If a balancer is configured as follows:</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>This is because all values of <dfn>lbfactor</dfn> are normalized
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco with respect to the others. For:</p>
7fc57d0f02d0fec1192376ccebe2be0224cb9a55Adrián Riesco <p>worker <var>b</var> will, on average, get 4 times the requests
b9840e4ee6fda6e42fa4ee9f337482ccc4839a39Adrián Riesco <p>The following asymmetric configuration works as one would expect:</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco are selected with 3 <var>b</var> interspersed.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <title>Weighted Traffic Counting Algorithm</title>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco scheduler is very similar to the Request Counting method, with
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco the following changes:</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want
7fc57d0f02d0fec1192376ccebe2be0224cb9a55Adrián Riesco this worker to handle</em>. This is also a normalized value
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco representing their "share" of the amount of work to be done,
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco but instead of simply counting the number of requests, we take
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco into account the amount of traffic this worker has seen.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>If a balancer is configured as follows:</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>Then we mean that we want <var>b</var> to process twice the
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco amount of bytes than <var>a</var> or <var>c</var> should. It does
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco not necessarily mean that <var>b</var> would handle twice as
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco many requests, but it would process twice the I/O. Thus, the
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco size of the request and response are applied to the weighting
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco and selection algorithm.</p>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco <title>Pending Request Counting Algorithm</title>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco <p>Enabled via <code>lbmethod=bybusyness</code>, this scheduler keeps
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco track of how many requests each worker is assigned at present. A new
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco request is automatically assigned to the worker with the lowest
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco number of active requests. This is useful in the case of workers
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco that queue incoming requests independently of Apache, to ensure that
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco queue length stays even and a request is always given to the worker
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco most likely to service it fastest.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>In the case of multiple least-busy workers, the statistics (and
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco weightings) used by the Request Counting method are used to break the
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco tie. Over time, the distribution of work will come to resemble that
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco characteristic of <code>byrequests</code>.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>At present there are 6 environment variables exported:</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <!-- ============= BALANCER_SESSION_STICKY =============== -->
7fc57d0f02d0fec1192376ccebe2be0224cb9a55Adrián Riesco <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco <p>This is assigned the <var>stickysession</var> value used in the current
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco request. It is the cookie or parameter name used for sticky sessions</p>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco <!-- ============= BALANCER_SESSION_ROUTE ================ -->
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>This is assigned the <var>route</var> parsed from the current
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <!-- ============= BALANCER_NAME ========================= -->
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>This is assigned the name of the balancer used for the current
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco request. The value is something like <code>balancer://foo</code>.</p>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco <!-- ============= BALANCER_WORKER_NAME ================== -->
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco <p>This is assigned the name of the worker used for the current request.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco The value is something like <code>http://hostA:1234</code>.</p>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco <!-- ============= BALANCER_WORKER_ROUTE ================= -->
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>This is assigned the <var>route</var> of the worker that will be
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco used for the current request.</p>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco <!-- ============= BALANCER_ROUTE_CHANGED ================= -->
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco <p>This is set to 1 if the session route does not match the
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco session does not yet have an established route. This can be used to
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco determine when/if the client needs to be sent an updated route
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco when sticky sessions are used.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <title>Enabling Balancer Manager Support</title>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>This module <em>requires</em> the service of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Balancer manager enables dynamic update of balancer
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco members. You can use balancer manager to change the balance
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco factor or a particular member, or put it in the off line
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Thus, in order to get the ability of load balancer management,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <module>mod_status</module> and <module>mod_proxy_balancer</module>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco have to be present in the server.</p>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco <p>To enable load balancer management for browsers from the example.com
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco domain add this code to your <code>httpd.conf</code>
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco configuration file</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <Location /balancer-manager><br />
27aad79faa0eec8d0e7dda32bca710db95bd2d0aAdrián Riesco SetHandler balancer-manager<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Order Deny,Allow<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Deny from all<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco </Location>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>You can now access load balancer manager by using a Web browser
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco to access the page
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <code>http://your.server.name/balancer-manager</code></p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco</modulesynopsis>