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 7 --> 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<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.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_proxy_balancer</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_proxy_balancer.html" title="English"> en </a> | 28<a href="/fr/mod/mod_proxy_balancer.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 29<a href="/ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 30</div> 31<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> 32<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 33<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>proxy_balancer_module</td></tr> 34<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_proxy_balancer.c</td></tr> 35<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.1 and later</td></tr></table> 36<h3>Summary</h3> 37 38 <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 39 <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols 40 </p> 41 42 <p>Load balancing scheduler algorithm is provided by not this 43 module but other modules such as: 44 <code class="module"><a href="/mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code>, 45 <code class="module"><a href="/mod/mod_lbmethod_bytraffic.html">mod_lbmethod_bytraffic</a></code>, 46 <code class="module"><a href="/mod/mod_lbmethod_bybusyness.html">mod_lbmethod_bybusyness</a></code> and 47 <code class="module"><a href="/mod/mod_lbmethod_heartbeat.html">mod_lbmethod_heartbeat</a></code>. 48 </p> 49 50 <p>Thus, in order to get the ability of load balancing, 51 <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> 52 and at least one of load balancing scheduler algorithm modules have 53 to be present in the server.</p> 54 55 <div class="warning"><h3>Warning</h3> 56 <p>Do not enable proxying until you have <a href="mod_proxy.html#access">secured your server</a>. Open proxy 57 servers are dangerous both to your network and to the Internet at 58 large.</p> 59 </div> 60</div> 61<div id="quickview"><h3 class="directives">Directives</h3> 62<p>This module provides no 63 directives.</p> 64<h3>Topics</h3> 65<ul id="topics"> 66<li><img alt="" src="/images/down.gif" /> <a href="#scheduler">Load balancer scheduler algorithm</a></li> 67<li><img alt="" src="/images/down.gif" /> <a href="#stickyness">Load balancer stickyness</a></li> 68<li><img alt="" src="/images/down.gif" /> <a href="#example">Examples of a balancer configuration</a></li> 69<li><img alt="" src="/images/down.gif" /> <a href="#environment">Exported Environment Variables</a></li> 70<li><img alt="" src="/images/down.gif" /> <a href="#balancer_manager">Enabling Balancer Manager Support</a></li> 71<li><img alt="" src="/images/down.gif" /> <a href="#stickyness_implementation">Details on load balancer stickyness</a></li> 72<li><img alt="" src="/images/down.gif" /> <a href="#stickyness_troubleshooting">Troubleshooting load balancer stickyness</a></li> 73</ul><h3>See also</h3> 74<ul class="seealso"> 75<li><code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code></li> 76</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 77<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 78<div class="section"> 79<h2><a name="scheduler" id="scheduler">Load balancer scheduler algorithm</a></h2> 80 81 <p>At present, there are 3 load balancer scheduler algorithms available 82 for use: Request Counting, Weighted Traffic Counting and Pending Request 83 Counting. These are controlled via the <code>lbmethod</code> value of 84 the Balancer definition. See the <code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code> 85 directive for more information, especially regarding how to 86 configure the Balancer and BalancerMembers.</p> 87</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 88<div class="section"> 89<h2><a name="stickyness" id="stickyness">Load balancer stickyness</a></h2> 90 91 <p>The balancer supports stickyness. When a request is proxied 92 to some back-end, then all following requests from the same user 93 should be proxied to the same back-end. Many load balancers implement 94 this feature via a table that maps client IP addresses to back-ends. 95 This approach is transparent to clients and back-ends, but suffers 96 from some problems: unequal load distribution if clients are themselves 97 hidden behind proxies, stickyness errors when a client uses a dynamic 98 IP address that changes during a session and loss of stickyness, if the 99 mapping table overflows.</p> 100 <p>The module <code class="module"><a href="/mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> implements stickyness 101 on top of two alternative means: cookies and URL encoding. Providing the 102 cookie can be either done by the back-end or by the Apache web server 103 itself. The URL encoding is usually done on the back-end.</p> 104</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 105<div class="section"> 106<h2><a name="example" id="example">Examples of a balancer configuration</a></h2> 107 108 <p>Before we dive into the technical details, here's an example of 109 how you might use <code class="module"><a href="/mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> to provide 110 load balancing between two back-end servers: 111 </p> 112 113 <pre class="prettyprint lang-config"><Proxy balancer://mycluster> 114 BalancerMember http://192.168.1.50:80 115 BalancerMember http://192.168.1.51:80 116</Proxy> 117ProxyPass /test balancer://mycluster 118ProxyPassReverse /test balancer://mycluster</pre> 119 120 121 <p>Another example of how to provide load balancing with stickyness 122 using <code class="module"><a href="/mod/mod_headers.html">mod_headers</a></code>, even if the back-end server does 123 not set a suitable session cookie: 124 </p> 125 126 <pre class="prettyprint lang-config">Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED 127<Proxy balancer://mycluster> 128 BalancerMember http://192.168.1.50:80 route=1 129 BalancerMember http://192.168.1.51:80 route=2 130 ProxySet stickysession=ROUTEID 131</Proxy> 132ProxyPass /test balancer://mycluster 133ProxyPassReverse /test balancer://mycluster</pre> 134 135</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 136<div class="section"> 137<h2><a name="environment" id="environment">Exported Environment Variables</a></h2> 138 139 <p>At present there are 6 environment variables exported:</p> 140 141 <dl> 142 143 <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt> 144 <dd> 145 <p>This is assigned the <var>stickysession</var> value used for the current 146 request. It is the name of the cookie or request parameter used for sticky sessions</p> 147 </dd> 148 149 150 <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt> 151 <dd> 152 <p>This is assigned the <var>route</var> parsed from the current 153 request.</p> 154 </dd> 155 156 157 <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt> 158 <dd> 159 <p>This is assigned the name of the balancer used for the current 160 request. The value is something like <code>balancer://foo</code>.</p> 161 </dd> 162 163 164 <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt> 165 <dd> 166 <p>This is assigned the name of the worker used for the current request. 167 The value is something like <code>http://hostA:1234</code>.</p> 168 </dd> 169 170 171 <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt> 172 <dd> 173 <p>This is assigned the <var>route</var> of the worker that will be 174 used for the current request.</p> 175 </dd> 176 177 178 <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt> 179 <dd> 180 <p>This is set to 1 if the session route does not match the 181 worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the 182 session does not yet have an established route. This can be used to 183 determine when/if the client needs to be sent an updated route 184 when sticky sessions are used.</p> 185 </dd> 186 </dl> 187 188</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 189<div class="section"> 190<h2><a name="balancer_manager" id="balancer_manager">Enabling Balancer Manager Support</a></h2> 191 192 <p>This module <em>requires</em> the service of 193 <code class="module"><a href="/mod/mod_status.html">mod_status</a></code>. 194 Balancer manager enables dynamic update of balancer 195 members. You can use balancer manager to change the balance 196 factor or a particular member, or put it in the off line 197 mode. 198 </p> 199 200 <p>Thus, in order to get the ability of load balancer management, 201 <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> 202 have to be present in the server.</p> 203 204 <p>To enable load balancer management for browsers from the example.com 205 domain add this code to your <code>httpd.conf</code> 206 configuration file</p> 207<pre class="prettyprint lang-config"><Location /balancer-manager> 208 SetHandler balancer-manager 209 Require host example.com 210</Location></pre> 211 212 213 <p>You can now access load balancer manager by using a Web browser 214 to access the page 215 <code>http://your.server.name/balancer-manager</code>. Please note 216 that only Balancers defined outside of <code><Location ...></code> 217 containers can be dynamically controlled by the Manager.</p> 218</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 219<div class="section"> 220<h2><a name="stickyness_implementation" id="stickyness_implementation">Details on load balancer stickyness</a></h2> 221 222 <p>When using cookie based stickyness, you need to configure the 223 name of the cookie that contains the information about which back-end 224 to use. This is done via the <var>stickysession</var> attribute added 225 to either <code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code> or 226 <code class="directive"><a href="/mod/mod_proxy.html#proxyset">ProxySet</a></code>. The name of 227 the cookie is case-sensitive. The balancer extracts the value of the 228 cookie and looks for a member worker with <var>route</var> equal 229 to that value. The <var>route</var> must also be set in either 230 <code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code> or 231 <code class="directive"><a href="/mod/mod_proxy.html#proxyset">ProxySet</a></code>. The cookie can either 232 be set by the back-end, or as shown in the above 233 <a href="#example">example</a> by the Apache web server itself.</p> 234 <p>Some back-ends use a slightly different form of stickyness cookie, 235 for instance Apache Tomcat. Tomcat adds the name of the Tomcat instance 236 to the end of its session id cookie, separated with a dot (<code>.</code>) 237 from the session id. Thus if the Apache web server finds a dot in the value 238 of the stickyness cookie, it only uses the part behind the dot to search 239 for the route. In order to let Tomcat know about its instance name, you 240 need to set the attribute <code>jvmRoute</code> inside the Tomcat 241 configuration file <code>conf/server.xml</code> to the value of the 242 <var>route</var> of the worker that connects to the respective Tomcat. 243 The name of the session cookie used by Tomcat (and more generally by Java 244 web applications based on servlets) is <code>JSESSIONID</code> 245 (upper case) but can be configured to something else.</p> 246 <p>The second way of implementing stickyness is URL encoding. 247 The web server searches for a query parameter in the URL of the request. 248 The name of the parameter is specified again using <var>stickysession</var>. 249 The value of the parameter is used to lookup a member worker with <var>route</var> 250 equal to that value. Since it is not easy to extract and manipulate all 251 URL links contained in responses, generally the work of adding the parameters 252 to each link is done by the back-end generating the content. 253 In some cases it might be feasible doing 254 this via the web server using <code class="module"><a href="/mod/mod_substitute.html">mod_substitute</a></code> or 255 <code class="module"><a href="/mod/mod_sed.html">mod_sed</a></code>. This can have negative impact on performance though.</p> 256 <p>The Java standards implement URL encoding slightly different. They use 257 a path info appended to the URL using a semicolon (<code>;</code>) 258 as the separator and add the session id behind. As in the cookie case, 259 Apache Tomcat can include the configured <code>jvmRoute</code> in this path 260 info. To let Apache find this sort of path info, you neet to set 261 <code>scolonpathdelim</code> to <code>On</code> in 262 <code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code> or 263 <code class="directive"><a href="/mod/mod_proxy.html#proxyset">ProxySet</a></code>.</p> 264 <p>Finally you can support cookies and URL encoding at the same time, by 265 configuring the name of the cookie and the name of the URL parameter 266 separated by a vertical bar (<code>|</code>) as in the following example:</p> 267 <pre class="prettyprint lang-config">ProxyPass /test balancer://mycluster stickysession=JSESSIONID|jsessionid scolonpathdelim=On 268<Proxy balancer://mycluster> 269 BalancerMember http://192.168.1.50:80 route=node1 270 BalancerMember http://192.168.1.51:80 route=node2 271</Proxy></pre> 272 273 <p>If the cookie and the request parameter both provide routing information 274 for the same request, the information from the request parameter is used.</p> 275</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 276<div class="section"> 277<h2><a name="stickyness_troubleshooting" id="stickyness_troubleshooting">Troubleshooting load balancer stickyness</a></h2> 278 279 <p>If you experience stickyness errors, e.g. users lose their 280 application sessions and need to login again, you first want to 281 check whether this is because the back-ends are sometimes unavailable 282 or whether your configuration is wrong. To find out about possible 283 stability problems with the back-ends, check your Apache error log 284 for proxy error messages.</p> 285 <p>To verify your configuration, first check, whether the stickyness 286 is based on a cookie or on URL encoding. Next step would be logging 287 the appropriate data in the access log by using an enhanced 288 <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code>. 289 The following fields are useful:</p> 290 <dl> 291 <dt><code>%{MYCOOKIE}C</code></dt> 292 <dd>The value contained in the cookie with name <code>MYCOOKIE</code>. 293 The name should be the same given in the <var>stickysession</var> 294 attribute.</dd> 295 <dt><code>%{Set-Cookie}o</code></dt> 296 <dd>This logs any cookie set by the back-end. You can track, 297 whether the back-end sets the session cookie you expect, and 298 to which value it is set.</dd> 299 <dt><code>%{BALANCER_SESSION_STICKY}e</code></dt> 300 <dd>The name of the cookie or request parameter used 301 to lookup the routing information.</dd> 302 <dt><code>%{BALANCER_SESSION_ROUTE}e</code></dt> 303 <dd>The route information found in the request.</dd> 304 <dt><code>%{BALANCER_WORKER_ROUTE}e</code></dt> 305 <dd>The route of the worker chosen.</dd> 306 <dt><code>%{BALANCER_ROUTE_CHANGED}e</code></dt> 307 <dd>Set to <code>1</code> if the route in the request 308 is different from the route of the worker, i.e. 309 the request couldn't be handled sticky.</dd> 310 </dl> 311 <p>Common reasons for loss of session are session timeouts, 312 which are usually configurable on the back-end server.</p> 313 <p>The balancer also logs detailed information about handling 314 stickyness to the error log, if the log level is set to 315 <code>debug</code> or higher. This is an easy way to 316 troubleshoot stickyness problems, but the log volume might 317 be to high for production servers under high load.</p> 318</div> 319</div> 320<div class="bottomlang"> 321<p><span>Available Languages: </span><a href="/en/mod/mod_proxy_balancer.html" title="English"> en </a> | 322<a href="/fr/mod/mod_proxy_balancer.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 323<a href="/ja/mod/mod_proxy_balancer.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 324</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 325<script type="text/javascript"><!--//--><![CDATA[//><!-- 326var comments_shortname = 'httpd'; 327var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_proxy_balancer.html'; 328(function(w, d) { 329 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 330 d.write('<div id="comments_thread"><\/div>'); 331 var s = d.createElement('script'); 332 s.type = 'text/javascript'; 333 s.async = true; 334 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 335 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 336 } 337 else { 338 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 339 } 340})(window, document); 341//--><!]]></script></div><div id="footer"> 342<p class="apache">Copyright 2014 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> 343<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 344if (typeof(prettyPrint) !== 'undefined') { 345 prettyPrint(); 346} 347//--><!]]></script> 348</body></html>
