apache/docs/manual/mod/mod_proxy_balancer.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_proxy_balancer.xml.meta">

<name>mod_proxy_balancer</name>
<description><module>mod_proxy</module> extension for load balancing </description>
<status>Extension</status>
<sourcefile>mod_proxy_balancer.c</sourcefile>
<identifier>proxy_balancer_module</identifier>
<compatibility>Available in version 2.1 and later</compatibility>

<summary>
    <p>This module <em>requires</em> the service of <module
    >mod_proxy</module>. It provides load balancing support for
    <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols
    </p>

    <p>Load balancing scheduler algorithm is provided by not this
    module but other modules such as:
    <module>mod_lbmethod_byrequests</module>,
    <module>mod_lbmethod_bytraffic</module> and
    <module>mod_lbmethod_bybusyness</module>.
    </p>

    <p>Thus, in order to get the ability of load balancing,
    <module>mod_proxy</module>, <module>mod_proxy_balancer</module>
    and at least one of load balancing scheduler algorithm modules have
    to be present in the server.</p>

    <note type="warning"><title>Warning</title>
      <p>Do not enable proxying until you have <a
      href="mod_proxy.html#access">secured your server</a>. Open proxy
      servers are dangerous both to your network and to the Internet at
      large.</p>
    </note>
</summary>
<seealso><module>mod_proxy</module></seealso>

<section id="scheduler">
    <title>Load balancer scheduler algorithm</title>
    <p>At present, there are 3 load balancer scheduler algorithms available
    for use: Request Counting, Weighted Traffic Counting and Pending Request 
    Counting. These are controlled via the <code>lbmethod</code> value of
    the Balancer definition. See the <directive module="mod_proxy">ProxyPass</directive> 
    directive for more information.</p>

</section>

<section id="example">
    <title>Examples of a balancer configuration</title>
    <p>Before we dive into the technical details, here's an example of
    how you might use <module>mod_proxy_balancer</module> to provide
    load balancing between two back-end servers:
    </p>

    <example>
    &lt;Proxy balancer://mycluster&gt;<br />
        BalancerMember http://192.168.1.50:80<br />
        BalancerMember http://192.168.1.51:80<br />
    &lt;/Proxy&gt;<br />
    ProxyPass /test balancer://mycluster
    </example>

    <p>Another example of how to provide load balancing with stickyness
    using <module>mod_headers</module>, even if the backend server does
    not set a suitable session cookie:
    </p>

    <example>
    Header add Set-Cookie: "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/"
           env=BALANCER_ROUTE_CHANGED<br />
    &lt;Proxy balancer://mycluster&gt;<br />
    BalancerMember http://192.168.1.50:80 route=1<br />
    BalancerMember http://192.168.1.51:80 route=2<br />
    ProxySet stickysession=ROUTEID<br />
    &lt;/Proxy&gt;<br />
    ProxyPass /test balancer://mycluster
    </example>
</section>

<section id="environment">
    <title>Exported Environment Variables</title>
    <p>At present there are 6 environment variables exported:</p>

    <dl>
    <!-- ============= BALANCER_SESSION_STICKY =============== -->
    <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
    <dd>
    <p>This is assigned the <var>stickysession</var> value used in the current
    request.  It is the cookie or parameter name used for sticky sessions</p>
    </dd>

    <!-- ============= BALANCER_SESSION_ROUTE ================ -->
    <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
    <dd>
    <p>This is assigned the <var>route</var> parsed from the current 
    request.</p>
    </dd>

    <!-- ============= BALANCER_NAME ========================= -->
    <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
    <dd>
    <p>This is assigned the name of the balancer used for the current 
    request. The value is something like <code>balancer://foo</code>.</p>
    </dd>

    <!-- ============= BALANCER_WORKER_NAME ================== -->
    <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
    <dd>
    <p>This is assigned the name of the worker used for the current request.
    The value is something like <code>http://hostA:1234</code>.</p>
    </dd>

    <!-- ============= BALANCER_WORKER_ROUTE ================= -->
    <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
    <dd>
    <p>This is assigned the <var>route</var> of the worker that will be 
    used for the current request.</p>
    </dd>

    <!-- ============= BALANCER_ROUTE_CHANGED ================= -->
    <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
    <dd>
    <p>This is set to 1 if the session route does not match the
    worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
    session does not yet have an established route.  This can be used to
    determine when/if the client needs to be sent an updated route
    when sticky sessions are used.</p>
    </dd>
    </dl>

</section>

<section id="enable">
    <title>Enabling Balancer Manager Support</title>
    <p>This module <em>requires</em> the service of 
    <module>mod_status</module>.
    Balancer manager enables dynamic update of balancer
    members. You can use balancer manager to change the balance
    factor or a particular member, or put it in the off line
    mode.
    </p>

    <p>Thus, in order to get the ability of load balancer management,
    <module>mod_status</module> and <module>mod_proxy_balancer</module>
    have to be present in the server.</p>

    <p>To enable load balancer management for browsers from the example.com
    domain add this code to your <code>httpd.conf</code>
    configuration file</p>
<example>
    &lt;Location /balancer-manager&gt;<br />
    SetHandler balancer-manager<br />
<br />
    Order Deny,Allow<br />
    Deny from all<br />
    Allow from .example.com<br />
    &lt;/Location&gt;
</example>

    <p>You can now access load balancer manager by using a Web browser
    to access the page
    <code>http://your.server.name/balancer-manager</code></p>
</section>

</modulesynopsis>