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>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>Examples 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
  84     <p>Another example of how to provide load balancing with stickyness
  85     using <module>mod_headers</module>, even if the backend server does
  86     not set a suitable session cookie:
  87     </p>
  88
  89     <example>
  90     Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/"
  91            env=BALANCER_ROUTE_CHANGED<br />
  92     &lt;Proxy balancer://mycluster&gt;<br />
  93     BalancerMember http://192.168.1.50:80 route=1<br />
  94     BalancerMember http://192.168.1.51:80 route=2<br />
  95     ProxySet stickysession=ROUTEID<br />
  96     &lt;/Proxy&gt;<br />
  97     ProxyPass /test balancer://mycluster
  98     </example>
  99 </section>
 100
 101 <section id="environment">
 102     <title>Exported Environment Variables</title>
 103     <p>At present there are 6 environment variables exported:</p>
 104
 105     <dl>
 106     <!-- ============= BALANCER_SESSION_STICKY =============== -->
 107     <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
 108     <dd>
 109     <p>This is assigned the <var>stickysession</var> value used in the current
 110     request.  It is the cookie or parameter name used for sticky sessions</p>
 111     </dd>
 112
 113     <!-- ============= BALANCER_SESSION_ROUTE ================ -->
 114     <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
 115     <dd>
 116     <p>This is assigned the <var>route</var> parsed from the current
 117     request.</p>
 118     </dd>
 119
 120     <!-- ============= BALANCER_NAME ========================= -->
 121     <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
 122     <dd>
 123     <p>This is assigned the name of the balancer used for the current
 124     request. The value is something like <code>balancer://foo</code>.</p>
 125     </dd>
 126
 127     <!-- ============= BALANCER_WORKER_NAME ================== -->
 128     <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
 129     <dd>
 130     <p>This is assigned the name of the worker used for the current request.
 131     The value is something like <code>http://hostA:1234</code>.</p>
 132     </dd>
 133
 134     <!-- ============= BALANCER_WORKER_ROUTE ================= -->
 135     <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
 136     <dd>
 137     <p>This is assigned the <var>route</var> of the worker that will be
 138     used for the current request.</p>
 139     </dd>
 140
 141     <!-- ============= BALANCER_ROUTE_CHANGED ================= -->
 142     <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
 143     <dd>
 144     <p>This is set to 1 if the session route does not match the
 145     worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
 146     session does not yet have an established route.  This can be used to
 147     determine when/if the client needs to be sent an updated route
 148     when sticky sessions are used.</p>
 149     </dd>
 150     </dl>
 151
 152 </section>
 153
 154 <section id="enable">
 155     <title>Enabling Balancer Manager Support</title>
 156     <p>This module <em>requires</em> the service of
 157     <module>mod_status</module>.
 158     Balancer manager enables dynamic update of balancer
 159     members. You can use balancer manager to change the balance
 160     factor or a particular member, or put it in the off line
 161     mode.
 162     </p>
 163
 164     <p>Thus, in order to get the ability of load balancer management,
 165     <module>mod_status</module> and <module>mod_proxy_balancer</module>
 166     have to be present in the server.</p>
 167
 168     <p>To enable load balancer management for browsers from the example.com
 169     domain add this code to your <code>httpd.conf</code>
 170     configuration file</p>
 171 <example>
 172     &lt;Location /balancer-manager&gt;<br />
 173     SetHandler balancer-manager<br />
 174 <br />
 175     Order Deny,Allow<br />
 176     Deny from all<br />
 177     Allow from .example.com<br />
 178     &lt;/Location&gt;
 179 </example>
 180
 181     <p>You can now access load balancer manager by using a Web browser
 182     to access the page
 183     <code>http://your.server.name/balancer-manager</code></p>
 184 </section>
 185
 186 <directivesynopsis>
 187 <name>BalancerNonce</name>
 188 <description>Set the nonce used in the balancer-manager application</description>
 189 <syntax>BalancerNonce Default|None|Set "value"</syntax>
 190 <default>ProxyStatus Default</default>
 191 <contextlist><context>server config</context>
 192 <context>virtual host</context>
 193 </contextlist>
 194 <compatibility>Available in version 2.4 and later</compatibility>
 195
 196 <usage>
 197     <p>This directive specifies the protective nonce used in the
 198     <code>balancer-manager</code> application page.</p>
 199     <p>The default is to use an automatically determined UUID-based
 200     nonce, to provide for further protection for the page. If set
 201     to <code>Set</code>, then the next argument sets the nonce to that
 202     value. A setting of <code>None</code> disables all nonce checking.</p>
 203
 204     <example>
 205     BalancerNonce Set "RealGudSharedSecret"
 206     </example>
 207
 208     <note><title>Note</title>
 209       <p>In addition to the nonce, the <code>balancer-manager</code> page
 210       should be protected via an ACL.</p>
 211     </note>
 212
 213 </usage>
 214 </directivesynopsis>
 215
 216 </modulesynopsis>