Blame docs/manual/mod/mod_proxy_balancer.html.en

Packit 90a5c9
Packit 90a5c9
Packit 90a5c9
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
Packit 90a5c9
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
Packit 90a5c9
Packit 90a5c9
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Packit 90a5c9
              This file is generated from xml source: DO NOT EDIT
Packit 90a5c9
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Packit 90a5c9
      -->
Packit 90a5c9
<title>mod_proxy_balancer - Apache HTTP Server Version 2.4</title>
Packit 90a5c9
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
Packit 90a5c9
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
Packit 90a5c9
<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" />
Packit 90a5c9
<script src="../style/scripts/prettify.min.js" type="text/javascript">
Packit 90a5c9
</script>
Packit 90a5c9
Packit 90a5c9
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
Packit 90a5c9
<body>
Packit 90a5c9
Packit 90a5c9

Modules | Directives | FAQ | Glossary | Sitemap

Packit 90a5c9

Apache HTTP Server Version 2.4

Packit 90a5c9
Packit 90a5c9
<-
Packit 90a5c9
Packit 90a5c9
Apache > HTTP Server > Documentation > Version 2.4 > Modules
Packit 90a5c9
Packit 90a5c9

Apache Module mod_proxy_balancer

Packit 90a5c9
Packit 90a5c9

Available Languages:  en  |

Packit 90a5c9
 fr  |
Packit 90a5c9
 ja 

Packit 90a5c9
Packit 90a5c9
Description:mod_proxy extension for load balancing
Packit 90a5c9
Status:Extension
Packit 90a5c9
Module Identifier:proxy_balancer_module
Packit 90a5c9
Source File:mod_proxy_balancer.c
Packit 90a5c9
Compatibility:Available in version 2.1 and later
Packit 90a5c9

Summary

Packit 90a5c9
Packit 90a5c9
    

This module requires the service of mod_proxy and it provides load balancing for

Packit 90a5c9
    all the supported protocols. The most important ones are:

Packit 90a5c9
    
    Packit 90a5c9
            
  • HTTP, using mod_proxy_http
  • Packit 90a5c9
            
  • FTP, using mod_proxy_ftp
  • Packit 90a5c9
            
  • AJP13, using mod_proxy_ajp
  • Packit 90a5c9
            
  • WebSocket, using mod_proxy_wstunnel
  • Packit 90a5c9
        
    Packit 90a5c9
        
    Packit 90a5c9
        

    The Load balancing scheduler algorithm is not provided by this

    Packit 90a5c9
        module but from other ones such as:

    Packit 90a5c9
        
      Packit 90a5c9
              
    • mod_lbmethod_byrequests
    • Packit 90a5c9
              
    • mod_lbmethod_bytraffic
    • Packit 90a5c9
              
    • mod_lbmethod_bybusyness
    • Packit 90a5c9
              
    • mod_lbmethod_heartbeat
    • Packit 90a5c9
          
      Packit 90a5c9
      Packit 90a5c9
          

      Thus, in order to get the ability of load balancing,

      Packit 90a5c9
          mod_proxy, mod_proxy_balancer
      Packit 90a5c9
          and at least one of load balancing scheduler algorithm modules have
      Packit 90a5c9
          to be present in the server.

      Packit 90a5c9
      Packit 90a5c9
          

      Warning

      Packit 90a5c9
            

      Do not enable proxying until you have secured your server. Open proxy

      Packit 90a5c9
            servers are dangerous both to your network and to the Internet at
      Packit 90a5c9
            large.

      Packit 90a5c9
          
      Packit 90a5c9
      Packit 90a5c9
      Support Apache!

      Topics

      Packit 90a5c9
        Packit 90a5c9
      • Load balancer scheduler algorithm
      • Packit 90a5c9
      • Load balancer stickyness
      • Packit 90a5c9
      • Examples of a balancer configuration
      • Packit 90a5c9
      • Exported Environment Variables
      • Packit 90a5c9
      • Enabling Balancer Manager Support
      • Packit 90a5c9
      • Details on load balancer stickyness
      • Packit 90a5c9
      • Troubleshooting load balancer stickyness
      • Packit 90a5c9

        Directives

        Packit 90a5c9

        This module provides no

        Packit 90a5c9
                    directives.

        Packit 90a5c9

        Bugfix checklist

        See also

        Packit 90a5c9
          Packit 90a5c9
        • mod_proxy
        • Packit 90a5c9
        • BalancerMember
        • Packit 90a5c9
        • BalancerGrowth
        • Packit 90a5c9
        • BalancerPersist
        • Packit 90a5c9
        • BalancerInherit
        • Packit 90a5c9
        • Comments
        • Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Load balancer scheduler algorithm

          Packit 90a5c9
              
          Packit 90a5c9
              

          At present, there are 4 load balancer scheduler algorithms available

          Packit 90a5c9
              for use: Request Counting (mod_lbmethod_byrequests),
          Packit 90a5c9
              Weighted Traffic Counting (mod_lbmethod_bytraffic),
          Packit 90a5c9
              Pending Request Counting (mod_lbmethod_bybusyness) and
          Packit 90a5c9
              Heartbeat Traffic Counting (mod_lbmethod_heartbeat).
          Packit 90a5c9
              These are controlled via the lbmethod value of
          Packit 90a5c9
              the Balancer definition. See the ProxyPass
          Packit 90a5c9
              directive for more information, especially regarding how to
          Packit 90a5c9
              configure the Balancer and BalancerMembers.

          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Load balancer stickyness

          Packit 90a5c9
              
          Packit 90a5c9
              

          The balancer supports stickyness. When a request is proxied

          Packit 90a5c9
              to some back-end, then all following requests from the same user
          Packit 90a5c9
              should be proxied to the same back-end. Many load balancers implement
          Packit 90a5c9
              this feature via a table that maps client IP addresses to back-ends.
          Packit 90a5c9
              This approach is transparent to clients and back-ends, but suffers
          Packit 90a5c9
              from some problems: unequal load distribution if clients are themselves
          Packit 90a5c9
              hidden behind proxies, stickyness errors when a client uses a dynamic
          Packit 90a5c9
              IP address that changes during a session and loss of stickyness, if the
          Packit 90a5c9
              mapping table overflows.

          Packit 90a5c9
              

          The module mod_proxy_balancer implements stickyness

          Packit 90a5c9
              on top of two alternative means: cookies and URL encoding. Providing the
          Packit 90a5c9
              cookie can be either done by the back-end or by the Apache web server
          Packit 90a5c9
              itself. The URL encoding is usually done on the back-end.

          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Examples of a balancer configuration

          Packit 90a5c9
              
          Packit 90a5c9
              

          Before we dive into the technical details, here's an example of

          Packit 90a5c9
              how you might use mod_proxy_balancer to provide
          Packit 90a5c9
              load balancing between two back-end servers:
          Packit 90a5c9
              

          Packit 90a5c9
          Packit 90a5c9
              
          <Proxy "balancer://mycluster">
          Packit 90a5c9
              BalancerMember "http://192.168.1.50:80"
          Packit 90a5c9
              BalancerMember "http://192.168.1.51:80"
          Packit 90a5c9
          </Proxy>
          Packit 90a5c9
          ProxyPass        "/test" "balancer://mycluster"
          Packit 90a5c9
          ProxyPassReverse "/test" "balancer://mycluster"
          Packit 90a5c9
          Packit 90a5c9
          Packit 90a5c9
              

          Another example of how to provide load balancing with stickyness

          Packit 90a5c9
              using mod_headers, even if the back-end server does
          Packit 90a5c9
              not set a suitable session cookie:
          Packit 90a5c9
              

          Packit 90a5c9
          Packit 90a5c9
              
          Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
          Packit 90a5c9
          <Proxy "balancer://mycluster">
          Packit 90a5c9
              BalancerMember "http://192.168.1.50:80" route=1
          Packit 90a5c9
              BalancerMember "http://192.168.1.51:80" route=2
          Packit 90a5c9
              ProxySet stickysession=ROUTEID
          Packit 90a5c9
          </Proxy>
          Packit 90a5c9
          ProxyPass        "/test" "balancer://mycluster"
          Packit 90a5c9
          ProxyPassReverse "/test" "balancer://mycluster"
          Packit 90a5c9
          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Exported Environment Variables

          Packit 90a5c9
              
          Packit 90a5c9
              

          At present there are 6 environment variables exported:

          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_SESSION_STICKY
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is assigned the stickysession value used for the current

          Packit 90a5c9
              request.  It is the name of the cookie or request parameter used for sticky sessions

          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_SESSION_ROUTE
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is assigned the route parsed from the current

          Packit 90a5c9
              request.

          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_NAME
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is assigned the name of the balancer used for the current

          Packit 90a5c9
              request. The value is something like balancer://foo.

          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_WORKER_NAME
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is assigned the name of the worker used for the current request.

          Packit 90a5c9
              The value is something like http://hostA:1234.

          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_WORKER_ROUTE
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is assigned the route of the worker that will be

          Packit 90a5c9
              used for the current request.

          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
              
          Packit 90a5c9
              
          BALANCER_ROUTE_CHANGED
          Packit 90a5c9
              
          Packit 90a5c9
              

          This is set to 1 if the session route does not match the

          Packit 90a5c9
              worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the
          Packit 90a5c9
              session does not yet have an established route.  This can be used to
          Packit 90a5c9
              determine when/if the client needs to be sent an updated route
          Packit 90a5c9
              when sticky sessions are used.

          Packit 90a5c9
              
          Packit 90a5c9
              
          Packit 90a5c9
          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Enabling Balancer Manager Support

          Packit 90a5c9
              
          Packit 90a5c9
              

          This module requires the service of

          Packit 90a5c9
              mod_status.
          Packit 90a5c9
              Balancer manager enables dynamic update of balancer
          Packit 90a5c9
              members. You can use balancer manager to change the balance
          Packit 90a5c9
              factor of a particular member, or put it in the off line
          Packit 90a5c9
              mode.
          Packit 90a5c9
              

          Packit 90a5c9
          Packit 90a5c9
              

          Thus, in order to get the ability of load balancer management,

          Packit 90a5c9
              mod_status and mod_proxy_balancer
          Packit 90a5c9
              have to be present in the server.

          Packit 90a5c9
          Packit 90a5c9
              

          To enable load balancer management for browsers from the example.com

          Packit 90a5c9
              domain add this code to your httpd.conf
          Packit 90a5c9
              configuration file

          Packit 90a5c9
          <Location "/balancer-manager">
          Packit 90a5c9
              SetHandler balancer-manager
          Packit 90a5c9
              Require host example.com
          Packit 90a5c9
          </Location>
          Packit 90a5c9
          Packit 90a5c9
          Packit 90a5c9
              

          You can now access load balancer manager by using a Web browser

          Packit 90a5c9
              to access the page
          Packit 90a5c9
              http://your.server.name/balancer-manager. Please note
          Packit 90a5c9
              that only Balancers defined outside of <Location ...>
          Packit 90a5c9
              containers can be dynamically controlled by the Manager.

          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Details on load balancer stickyness

          Packit 90a5c9
              
          Packit 90a5c9
              

          When using cookie based stickyness, you need to configure the

          Packit 90a5c9
              name of the cookie that contains the information about which back-end
          Packit 90a5c9
              to use. This is done via the stickysession attribute added
          Packit 90a5c9
              to either ProxyPass or
          Packit 90a5c9
              ProxySet. The name of
          Packit 90a5c9
              the cookie is case-sensitive. The balancer extracts the value of the
          Packit 90a5c9
              cookie and looks for a member worker with route equal
          Packit 90a5c9
              to that value. The route must also be set in either
          Packit 90a5c9
              ProxyPass or
          Packit 90a5c9
              ProxySet. The cookie can either
          Packit 90a5c9
              be set by the back-end, or as shown in the above
          Packit 90a5c9
              example by the Apache web server itself.

          Packit 90a5c9
              

          Some back-ends use a slightly different form of stickyness cookie,

          Packit 90a5c9
              for instance Apache Tomcat. Tomcat adds the name of the Tomcat instance
          Packit 90a5c9
              to the end of its session id cookie, separated with a dot (.)
          Packit 90a5c9
              from the session id. Thus if the Apache web server finds a dot in the value
          Packit 90a5c9
              of the stickyness cookie, it only uses the part behind the dot to search
          Packit 90a5c9
              for the route. In order to let Tomcat know about its instance name, you
          Packit 90a5c9
              need to set the attribute jvmRoute inside the Tomcat
          Packit 90a5c9
              configuration file conf/server.xml to the value of the
          Packit 90a5c9
              route of the worker that connects to the respective Tomcat.
          Packit 90a5c9
              The name of the session cookie used by Tomcat (and more generally by Java
          Packit 90a5c9
              web applications based on servlets) is JSESSIONID
          Packit 90a5c9
              (upper case) but can be configured to something else.

          Packit 90a5c9
              

          The second way of implementing stickyness is URL encoding.

          Packit 90a5c9
              The web server searches for a query parameter in the URL of the request.
          Packit 90a5c9
              The name of the parameter is specified again using stickysession.
          Packit 90a5c9
              The value of the parameter is used to lookup a member worker with route
          Packit 90a5c9
              equal to that value. Since it is not easy to extract and manipulate all
          Packit 90a5c9
              URL links contained in responses, generally the work of adding the parameters
          Packit 90a5c9
              to each link is done by the back-end generating the content.
          Packit 90a5c9
              In some cases it might be feasible doing
          Packit 90a5c9
              this via the web server using mod_substitute or
          Packit 90a5c9
              mod_sed. This can have negative impact on performance though.

          Packit 90a5c9
              

          The Java standards implement URL encoding slightly different. They use

          Packit 90a5c9
              a path info appended to the URL using a semicolon (;)
          Packit 90a5c9
              as the separator and add the session id behind. As in the cookie case,
          Packit 90a5c9
              Apache Tomcat can include the configured jvmRoute in this path
          Packit 90a5c9
              info. To let Apache find this sort of path info, you neet to set
          Packit 90a5c9
              scolonpathdelim to On in
          Packit 90a5c9
              ProxyPass or
          Packit 90a5c9
              ProxySet.

          Packit 90a5c9
              

          Finally you can support cookies and URL encoding at the same time, by

          Packit 90a5c9
              configuring the name of the cookie and the name of the URL parameter
          Packit 90a5c9
              separated by a vertical bar (|) as in the following example:

          Packit 90a5c9
              
          ProxyPass "/test" "balancer://mycluster" stickysession=JSESSIONID|jsessionid scolonpathdelim=On
          Packit 90a5c9
          <Proxy "balancer://mycluster">
          Packit 90a5c9
              BalancerMember "http://192.168.1.50:80" route=node1
          Packit 90a5c9
              BalancerMember "http://192.168.1.51:80" route=node2
          Packit 90a5c9
          </Proxy>
          Packit 90a5c9
          Packit 90a5c9
              

          If the cookie and the request parameter both provide routing information

          Packit 90a5c9
              for the same request, the information from the request parameter is used.

          Packit 90a5c9
          top
          Packit 90a5c9
          Packit 90a5c9

          Troubleshooting load balancer stickyness

          Packit 90a5c9
              
          Packit 90a5c9
              

          If you experience stickyness errors, e.g. users lose their

          Packit 90a5c9
              application sessions and need to login again, you first want to
          Packit 90a5c9
              check whether this is because the back-ends are sometimes unavailable
          Packit 90a5c9
              or whether your configuration is wrong. To find out about possible
          Packit 90a5c9
              stability problems with the back-ends, check your Apache error log
          Packit 90a5c9
              for proxy error messages.

          Packit 90a5c9
              

          To verify your configuration, first check, whether the stickyness

          Packit 90a5c9
              is based on a cookie or on URL encoding. Next step would be logging
          Packit 90a5c9
              the appropriate data in the access log by using an enhanced
          Packit 90a5c9
              LogFormat.
          Packit 90a5c9
              The following fields are useful:

          Packit 90a5c9
              
          Packit 90a5c9
              
          %{MYCOOKIE}C
          Packit 90a5c9
              
          The value contained in the cookie with name MYCOOKIE.
          Packit 90a5c9
              The name should be the same given in the stickysession
          Packit 90a5c9
              attribute.
          Packit 90a5c9
              
          %{Set-Cookie}o
          Packit 90a5c9
              
          This logs any cookie set by the back-end. You can track,
          Packit 90a5c9
              whether the back-end sets the session cookie you expect, and
          Packit 90a5c9
              to which value it is set.
          Packit 90a5c9
              
          %{BALANCER_SESSION_STICKY}e
          Packit 90a5c9
              
          The name of the cookie or request parameter used
          Packit 90a5c9
              to lookup the routing information.
          Packit 90a5c9
              
          %{BALANCER_SESSION_ROUTE}e
          Packit 90a5c9
              
          The route information found in the request.
          Packit 90a5c9
              
          %{BALANCER_WORKER_ROUTE}e
          Packit 90a5c9
              
          The route of the worker chosen.
          Packit 90a5c9
              
          %{BALANCER_ROUTE_CHANGED}e
          Packit 90a5c9
              
          Set to 1 if the route in the request
          Packit 90a5c9
              is different from the route of the worker, i.e.
          Packit 90a5c9
              the request couldn't be handled sticky.
          Packit 90a5c9
              
          Packit 90a5c9
              

          Common reasons for loss of session are session timeouts,

          Packit 90a5c9
              which are usually configurable on the back-end server.

          Packit 90a5c9
              

          The balancer also logs detailed information about handling

          Packit 90a5c9
              stickyness to the error log, if the log level is set to
          Packit 90a5c9
              debug or higher. This is an easy way to
          Packit 90a5c9
              troubleshoot stickyness problems, but the log volume might
          Packit 90a5c9
              be to high for production servers under high load.

          Packit 90a5c9
          Packit 90a5c9
          Packit 90a5c9
          Packit 90a5c9

          Available Languages:  en  |

          Packit 90a5c9
           fr  |
          Packit 90a5c9
           ja 

          Packit 90a5c9
          top

          Comments

          Notice:
          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 mailing lists.
          Packit 90a5c9
          <script type="text/javascript">
          Packit 90a5c9
          var comments_shortname = 'httpd';
          Packit 90a5c9
          var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_proxy_balancer.html';
          Packit 90a5c9
          (function(w, d) {
          Packit 90a5c9
              if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
          Packit 90a5c9
                  d.write('
          <\/div>');
          Packit 90a5c9
                  var s = d.createElement('script');
          Packit 90a5c9
                  s.type = 'text/javascript';
          Packit 90a5c9
                  s.async = true;
          Packit 90a5c9
                  s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
          Packit 90a5c9
                  (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
          Packit 90a5c9
              }
          Packit 90a5c9
              else { 
          Packit 90a5c9
                  d.write('
          Comments are disabled for this page at the moment.<\/div>');
          Packit 90a5c9
              }
          Packit 90a5c9
          })(window, document);
          Packit 90a5c9
          //--></script>
          Packit 90a5c9

          Copyright 2018 The Apache Software Foundation.
          Licensed under the Apache License, Version 2.0.

          Packit 90a5c9

          Modules | Directives | FAQ | Glossary | Sitemap

          <script type="text/javascript">
          Packit 90a5c9
          if (typeof(prettyPrint) !== 'undefined') {
          Packit 90a5c9
              prettyPrint();
          Packit 90a5c9
          }
          Packit 90a5c9
          //--></script>
          Packit 90a5c9
          </body></html>