1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>mod_proxy_balancer - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.3</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_proxy_balancer</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_balancer.html" title="English"> en </a> |
25 <a href="../ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> extension for load balancing </td></tr>
28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_balancer_module</td></tr>
30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy_balancer.c</td></tr>
31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.1 and later</td></tr></table>
34 <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. It provides load balancing support for
35 <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols
38 <p>Load balancing scheduler algorithm is provided by not this
39 module but other modules such as:
40 <code class="module"><a href="../mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code>,
41 <code class="module"><a href="../mod/mod_lbmethod_bytraffic.html">mod_lbmethod_bytraffic</a></code> and
42 <code class="module"><a href="../mod/mod_lbmethod_bybusyness.html">mod_lbmethod_bybusyness</a></code>.
45 <p>Thus, in order to get the ability of load balancing,
46 <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
47 and at least one of load balancing scheduler algorithm modules have
48 to be present in the server.</p>
50 <div class="warning"><h3>Warning</h3>
51 <p>Do not enable proxying until you have <a href="mod_proxy.html#access">secured your server</a>. Open proxy
52 servers are dangerous both to your network and to the Internet at
56 <div id="quickview"><h3 class="directives">Directives</h3>
58 <li><img alt="" src="../images/down.gif" /> <a href="#balancernonce">BalancerNonce</a></li>
62 <li><img alt="" src="../images/down.gif" /> <a href="#scheduler">Load balancer scheduler algorithm</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#stickyness">Load balancer stickyness</a></li>
64 <li><img alt="" src="../images/down.gif" /> <a href="#example">Examples of a balancer configuration</a></li>
65 <li><img alt="" src="../images/down.gif" /> <a href="#environment">Exported Environment Variables</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#balancer_manager">Enabling Balancer Manager Support</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#stickyness_implementation">Details on load balancer stickyness</a></li>
68 <li><img alt="" src="../images/down.gif" /> <a href="#stickyness_troubleshooting">Troubleshooting load balancer stickyness</a></li>
69 </ul><h3>See also</h3>
71 <li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
73 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
75 <h2><a name="scheduler" id="scheduler">Load balancer scheduler algorithm</a></h2>
77 <p>At present, there are 3 load balancer scheduler algorithms available
78 for use: Request Counting, Weighted Traffic Counting and Pending Request
79 Counting. These are controlled via the <code>lbmethod</code> value of
80 the Balancer definition. See the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>
81 directive for more information.</p>
82 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
84 <h2><a name="stickyness" id="stickyness">Load balancer stickyness</a></h2>
86 <p>The balancer supports stickyness. When a request is proxied
87 to some back-end, then all following requests from the same user
88 should be proxied to the same back-end. Many load balancers implement
89 this feature via a table that maps client IP addresses to back-ends.
90 This approach is transparent to clients and back-ends, but suffers
91 from some problems: unequal load distribution if clients are themselves
92 hidden behind proxies, stickyness errors when a client uses a dynamic
93 IP address that changes during a session and loss of stickyness, if the
94 mapping table overflows.</p>
95 <p>The module <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> implements stickyness
96 on top of two alternative means: cookies and URL encoding. Providing the
97 cookie can be either done by the back-end or by the Apache web server
98 itself. The URL encoding is usually done on the back-end.</p>
99 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
100 <div class="section">
101 <h2><a name="example" id="example">Examples of a balancer configuration</a></h2>
103 <p>Before we dive into the technical details, here's an example of
104 how you might use <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> to provide
105 load balancing between two back-end servers:
108 <div class="example"><p><code>
109 <Proxy balancer://mycluster><br />
110 BalancerMember http://192.168.1.50:80<br />
111 BalancerMember http://192.168.1.51:80<br />
113 ProxyPass /test balancer://mycluster
116 <p>Another example of how to provide load balancing with stickyness
117 using <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code>, even if the back-end server does
118 not set a suitable session cookie:
121 <div class="example"><p><code>
122 Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/"
123 env=BALANCER_ROUTE_CHANGED<br />
124 <Proxy balancer://mycluster><br />
125 BalancerMember http://192.168.1.50:80 route=1<br />
126 BalancerMember http://192.168.1.51:80 route=2<br />
127 ProxySet stickysession=ROUTEID<br />
129 ProxyPass /test balancer://mycluster
131 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
132 <div class="section">
133 <h2><a name="environment" id="environment">Exported Environment Variables</a></h2>
135 <p>At present there are 6 environment variables exported:</p>
139 <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
141 <p>This is assigned the <var>stickysession</var> value used for the current
142 request. It is the name of the cookie or request parameter used for sticky sessions</p>
146 <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
148 <p>This is assigned the <var>route</var> parsed from the current
153 <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
155 <p>This is assigned the name of the balancer used for the current
156 request. The value is something like <code>balancer://foo</code>.</p>
160 <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
162 <p>This is assigned the name of the worker used for the current request.
163 The value is something like <code>http://hostA:1234</code>.</p>
167 <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
169 <p>This is assigned the <var>route</var> of the worker that will be
170 used for the current request.</p>
174 <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
176 <p>This is set to 1 if the session route does not match the
177 worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
178 session does not yet have an established route. This can be used to
179 determine when/if the client needs to be sent an updated route
180 when sticky sessions are used.</p>
184 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
185 <div class="section">
186 <h2><a name="balancer_manager" id="balancer_manager">Enabling Balancer Manager Support</a></h2>
188 <p>This module <em>requires</em> the service of
189 <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.
190 Balancer manager enables dynamic update of balancer
191 members. You can use balancer manager to change the balance
192 factor or a particular member, or put it in the off line
196 <p>Thus, in order to get the ability of load balancer management,
197 <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> and <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
198 have to be present in the server.</p>
200 <p>To enable load balancer management for browsers from the example.com
201 domain add this code to your <code>httpd.conf</code>
202 configuration file</p>
203 <div class="example"><p><code>
204 <Location /balancer-manager><br />
205 SetHandler balancer-manager<br />
207 Require host example.com<br />
211 <p>You can now access load balancer manager by using a Web browser
213 <code>http://your.server.name/balancer-manager</code></p>
214 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
215 <div class="section">
216 <h2><a name="stickyness_implementation" id="stickyness_implementation">Details on load balancer stickyness</a></h2>
218 <p>When using cookie based stickyness, you need to configure the
219 name of the cookie that contains the information about which back-end
220 to use. This is done via the <var>stickysession</var> attribute added
221 to either <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or
222 <code class="directive"><a href="../mod/mod_proxy.html#proxyset">ProxySet</a></code>. The name of
223 the cookie is case-sensitive. The balancer extracts the value of the
224 cookie and looks for a member worker with <var>route</var> equal
225 to that value. The <var>route</var> must also be set in either
226 <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or
227 <code class="directive"><a href="../mod/mod_proxy.html#proxyset">ProxySet</a></code>. The cookie can either
228 be set by the back-end, or as shown in the above
229 <a href="#example">example</a> by the Apache web server itself.</p>
230 <p>Some back-ends use a slightly different form of stickyness cookie,
231 for instance Apache Tomcat. Tomcat adds the name of the Tomcat instance
232 to the end of its session id cookie, separated with a dot (<code>.</code>)
233 from the session id. Thus if the Apache web server finds a dot in the value
234 of the stickyness cookie, it only uses the part behind the dot to search
235 for the route. In order to let Tomcat know about its instance name, you
236 need to set the attribute <code>jvmRoute</code> inside the Tomcat
237 configuration file <code>conf/server.xml</code> to the value of the
238 <var>route</var> of the worker that connects to the respective Tomcat.
239 The name of the session cookie used by Tomcat (and more generally by Java
240 web applications based on servlets) is <code>JSESSIONID</code>
241 (upper case) but can be configured to something else.</p>
242 <p>The second way of implementing stickyness is URL encoding.
243 The web server searches for a query parameter in the URL of the request.
244 The name of the parameter is specified again using <var>stickysession</var>.
245 The value of the parameter is used to lookup a member worker with <var>route</var>
246 equal to that value. Since it is not easy to extract and manipulate all
247 URL links contained in responses, generally the work of adding the parameters
248 to each link is done by the back-end generating the content.
249 In some cases it might be feasible doing
250 this via the web server using <code class="module"><a href="../mod/mod_substitute.html">mod_substitute</a></code> or
251 <code class="module"><a href="../mod/mod_sed.html">mod_sed</a></code>. This can have negative impact on performance though.</p>
252 <p>The Java standards implement URL encoding slightly different. They use
253 a path info appended to the URL using a semicolon (<code>;</code>)
254 as the separator and add the session id behind. As in the cookie case,
255 Apache Tomcat can include the configured <code>jvmRoute</code> in this path
256 info. To let Apache find this sort of path info, you neet to set
257 <code>scolonpathdelim</code> to <code>On</code> in
258 <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or
259 <code class="directive"><a href="../mod/mod_proxy.html#proxyset">ProxySet</a></code>.</p>
260 <p>Finally you can support cookies and URL encoding at the same time, by
261 configuring the name of the cookie and the name of the URL parameter
262 separated by a vertical bar (<code>|</code>) as in the following example:</p>
263 <div class="example"><p><code>
264 ProxyPass /test balancer://mycluster stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
265 <Proxy balancer://mycluster><br />
266 BalancerMember http://192.168.1.50:80 route=node1<br />
267 BalancerMember http://192.168.1.51:80 route=node2<br />
270 <p>If the cookie and the request parameter both provide routing information
271 for the same request, the information from the request parameter is used.</p>
272 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
273 <div class="section">
274 <h2><a name="stickyness_troubleshooting" id="stickyness_troubleshooting">Troubleshooting load balancer stickyness</a></h2>
276 <p>If you experience stickyness errors, e.g. users loose their
277 application sessions and need to login again, you first want to
278 check whether this is because the back-ends are sometimes unavailable
279 or whether your configuration is wrong. To find out about possible
280 stability problems with the back-ends, check your Apache error log
281 for proxy error messages.</p>
282 <p>To verify your configuration, first check, whether the stickyness
283 is based on a cookie or on URL encoding. Next step would be logging
284 the appropriate data in the access log by using an enhanced
285 <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code>.
286 The following fields are useful:</p>
288 <dt><code>%{MYCOOKIE}C</code></dt>
289 <dd>The value contained in the cookie with name <code>MYCOOKIE</code>.
290 The name should be the same given in the <var>stickysession</var>
292 <dt><code>%{Set-Cookie}o</code></dt>
293 <dd>This logs any cookie set by the back-end. You can track,
294 whether the back-end sets the session cookie you expect, and
295 to which value it is set.</dd>
296 <dt><code>%{BALANCER_SESSION_STICKY}e</code></dt>
297 <dd>The name of the cookie or request parameter used
298 to lookup the routing information.</dd>
299 <dt><code>%{BALANCER_SESSION_ROUTE}e</code></dt>
300 <dd>The route information found in the request.</dd>
301 <dt><code>%{BALANCER_WORKER_ROUTE}e</code></dt>
302 <dd>The route of the worker chosen.</dd>
303 <dt><code>%{BALANCER_ROUTE_CHANGED}e</code></dt>
304 <dd>Set to <code>1</code> if the route in the request
305 is different from the route of the worker, i.e.
306 the request couldn't be handled sticky.</dd>
308 <p>Common reasons for loss of session are session timeouts,
309 which are usually configurable on the back-end server.</p>
310 <p>The balancer also logs detailed information about handling
311 stickyness to the error log, if the log level is set to
312 <code>debug</code> or higher. This is an easy way to
313 troubleshoot stickyness problems, but the log volume might
314 be to high for production servers under high load.</p>
316 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
317 <div class="directive-section"><h2><a name="BalancerNonce" id="BalancerNonce">BalancerNonce</a> <a name="balancernonce" id="balancernonce">Directive</a></h2>
318 <table class="directive">
319 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the nonce used in the balancer-manager application</td></tr>
320 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerNonce Default|None|Set "value"</code></td></tr>
321 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyStatus Default</code></td></tr>
322 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
323 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
324 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_balancer</td></tr>
325 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4 and later</td></tr>
327 <p>This directive specifies the protective nonce used in the
328 <code>balancer-manager</code> application page.</p>
329 <p>The default is to use an automatically determined UUID-based
330 nonce, to provide for further protection for the page. If set
331 to <code>Set</code>, then the next argument sets the nonce to that
332 value. A setting of <code>None</code> disables all nonce checking.</p>
334 <div class="example"><p><code>
335 BalancerNonce Set "RealGudSharedSecret"
338 <div class="note"><h3>Note</h3>
339 <p>In addition to the nonce, the <code>balancer-manager</code> page
340 should be protected via an ACL.</p>
346 <div class="bottomlang">
347 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_balancer.html" title="English"> en </a> |
348 <a href="../ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
349 </div><div id="footer">
350 <p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
351 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>