apache/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>mod_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>Load balancing scheduler algorithm is provided by not this
  39     module but other modules such as:
  40     <module>mod_lbmethod_byrequests</module>,
  41     <module>mod_lbmethod_bytraffic</module> and
  42     <module>mod_lbmethod_bybusyness</module>.
  43     </p>
  44
  45     <p>Thus, in order to get the ability of load balancing,
  46     <module>mod_proxy</module>, <module>mod_proxy_balancer</module>
  47     and at least one of load balancing scheduler algorithm modules have
  48     to be present in the server.</p>
  49
  50     <note type="warning"><title>Warning</title>
  51       <p>Do not enable proxying until you have <a
  52       href="mod_proxy.html#access">secured your server</a>. Open proxy
  53       servers are dangerous both to your network and to the Internet at
  54       large.</p>
  55     </note>
  56 </summary>
  57 <seealso><module>mod_proxy</module></seealso>
  58
  59 <section id="scheduler">
  60     <title>Load balancer scheduler algorithm</title>
  61     <p>At present, there are 3 load balancer scheduler algorithms available
  62     for use: Request Counting, Weighted Traffic Counting and Pending Request
  63     Counting. These are controlled via the <code>lbmethod</code> value of
  64     the Balancer definition. See the <directive module="mod_proxy">ProxyPass</directive>
  65     directive for more information.</p>
  66
  67 </section>
  68
  69 <section id="example">
  70     <title>Example of a balancer configuration</title>
  71     <p>Before we dive into the technical details, here's an example of
  72     how you might use <module>mod_proxy_balancer</module> to provide
  73     load balancing between two back-end servers:
  74     </p>
  75
  76     <example>
  77     &lt;Proxy balancer://mycluster&gt;<br />
  78         BalancerMember http://192.168.1.50:80<br />
  79         BalancerMember http://192.168.1.51:80<br />
  80     &lt;/Proxy&gt;<br />
  81     ProxyPass /test balancer://mycluster/
  82     </example>
  83 </section>
  84
  85 <section id="environment">
  86     <title>Exported Environment Variables</title>
  87     <p>At present there are 6 environment variables exported:</p>
  88
  89     <dl>
  90     <!-- ============= BALANCER_SESSION_STICKY =============== -->
  91     <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
  92     <dd>
  93     <p>This is assigned the <var>stickysession</var> value used in the current
  94     request.  It is the cookie or parameter name used for sticky sessions</p>
  95     </dd>
  96
  97     <!-- ============= BALANCER_SESSION_ROUTE ================ -->
  98     <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
  99     <dd>
 100     <p>This is assigned the <var>route</var> parsed from the current
 101     request.</p>
 102     </dd>
 103
 104     <!-- ============= BALANCER_NAME ========================= -->
 105     <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
 106     <dd>
 107     <p>This is assigned the name of the balancer used for the current
 108     request. The value is something like <code>balancer://foo</code>.</p>
 109     </dd>
 110
 111     <!-- ============= BALANCER_WORKER_NAME ================== -->
 112     <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
 113     <dd>
 114     <p>This is assigned the name of the worker used for the current request.
 115     The value is something like <code>http://hostA:1234</code>.</p>
 116     </dd>
 117
 118     <!-- ============= BALANCER_WORKER_ROUTE ================= -->
 119     <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
 120     <dd>
 121     <p>This is assigned the <var>route</var> of the worker that will be
 122     used for the current request.</p>
 123     </dd>
 124
 125     <!-- ============= BALANCER_ROUTE_CHANGED ================= -->
 126     <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
 127     <dd>
 128     <p>This is set to 1 if the session route does not match the
 129     worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
 130     session does not yet have an established route.  This can be used to
 131     determine when/if the client needs to be sent an updated route
 132     when sticky sessions are used.</p>
 133     </dd>
 134     </dl>
 135
 136 </section>
 137
 138 <section id="enable">
 139     <title>Enabling Balancer Manager Support</title>
 140     <p>This module <em>requires</em> the service of
 141     <module>mod_status</module>.
 142     Balancer manager enables dynamic update of balancer
 143     members. You can use balancer manager to change the balance
 144     factor or a particular member, or put it in the off line
 145     mode.
 146     </p>
 147
 148     <p>Thus, in order to get the ability of load balancer management,
 149     <module>mod_status</module> and <module>mod_proxy_balancer</module>
 150     have to be present in the server.</p>
 151
 152     <p>To enable load balancer management for browsers from the example.com
 153     domain add this code to your <code>httpd.conf</code>
 154     configuration file</p>
 155 <example>
 156     &lt;Location /balancer-manager&gt;<br />
 157     SetHandler balancer-manager<br />
 158 <br />
 159     Order Deny,Allow<br />
 160     Deny from all<br />
 161     Allow from .example.com<br />
 162     &lt;/Location&gt;
 163 </example>
 164
 165     <p>You can now access load balancer manager by using a Web browser
 166     to access the page
 167     <code>http://your.server.name/balancer-manager</code></p>
 168 </section>
 169
 170 </modulesynopsis>