Configuration basics

Backends

On this page

A backend section defines a pool of servers to which the load balancer will route requests.

The following video is an overview of backends in an HAProxy configuration file and showcases several load balancing algorithms.

You can add as many backend sections as needed. Each backend keyword is followed by a label, such as web_servers, to differentiate it from others.

haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check
haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check

The label is mostly for readability, but it does come into play when referencing stick tables and categorizing traffic metrics. It should consist of only upper or lowercase letters, digits, dashes, underscores, dots, and colons.

Backend configuration example Jump to heading

The following example shows a pool of servers that are defined within the backend named web_servers. The server keyword identifies each server’s IP address and port, which the load balancer will use to send traffic to that server. The basic syntax of a server line includes a unique name, an IP address, and a port.

haproxy
frontend myfrontend
  mode http
  bind :80
  default_backend web_servers
backend web_servers
  mode http
  balance roundrobin
  server myfirstserver  192.168.1.25:80 check
  server mysecondserver 192.168.1.26:80 check
  server mythirdserver  192.168.1.27:80 check
haproxy
frontend myfrontend
  mode http
  bind :80
  default_backend web_servers
backend web_servers
  mode http
  balance roundrobin
  server myfirstserver  192.168.1.25:80 check
  server mysecondserver 192.168.1.26:80 check
  server mythirdserver  192.168.1.27:80 check

Define multiple backends Jump to heading

You can add multiple backend sections to service traffic for multiple websites or applications. In the configuration sample below, frontend foo_and_bar listens for all incoming HTTP requests and uses the use_backend directive to route traffic to either foo_servers or bar_servers, depending on the host HTTP header.

haproxy
frontend foo_and_bar
  mode http
  bind :80
  use_backend foo_servers if { req.hdr(host) -i foo.com }
  use_backend bar_servers if { req.hdr(host) -i bar.com  }
backend foo_servers
  mode http
  balance roundrobin
  server foo1 192.168.1.25:80 check
  server foo2 192.168.1.26:80 check
  server foo3 192.168.1.27:80 check
backend bar_servers
  mode http
  balance roundrobin
  server bar1 192.168.1.35:80 check
  server bar2 192.168.1.36:80 check
  server bar3 192.168.1.37:80 check
haproxy
frontend foo_and_bar
  mode http
  bind :80
  use_backend foo_servers if { req.hdr(host) -i foo.com }
  use_backend bar_servers if { req.hdr(host) -i bar.com  }
backend foo_servers
  mode http
  balance roundrobin
  server foo1 192.168.1.25:80 check
  server foo2 192.168.1.26:80 check
  server foo3 192.168.1.27:80 check
backend bar_servers
  mode http
  balance roundrobin
  server bar1 192.168.1.35:80 check
  server bar2 192.168.1.36:80 check
  server bar3 192.168.1.37:80 check

Change the load balancing algorithm Jump to heading

The load balancer selects a backend server for each request or connection based on the load balancing algorithm you choose. Add or change the balance directive in your backend to change the load balancing algorithm. By default, if you don’t specify an algorithm:

  • In versions 3.3 and later, the load balancer selects two candidate servers at random (balance random) and sends the request to whichever server is less loaded.
  • In versions 3.2 and earlier, requests are distributed across all backend servers in a rotating sequence while respecting the servers’ weights (balance roundrobin).

In this example, we’ve set the balance directive to roundrobin:

haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check
haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check

Other load balancing algorithms, explained further in the sections below, include hash, first, leastconn, and more. See all the available load-balancing algorithms in HAProxy Configuration Manual’s balance.

roundrobin Jump to heading

Info

This is the default load balancing algorithm in versions 3.2 and earlier.

The roundrobin load balancing algorithm sends each new request to the next available server in the pool. By cycling through servers in order, it helps ensure that traffic is distributed evenly across all servers in the backend. Since the servers will receive requests in a predictable order, this can help with troubleshooting, as it’s easier to determine which server will receive the next request. This algorithm provides smooth and fair load balancing when backend servers have similar capacities and requests are short-lived and similar in duration. This predictable load distribution makes this algorithm a good choice for traditional web applications and APIs.

leastconn Jump to heading

When balance is set to leastconn, the server with the lowest number of connections receives the connection (request). Use this algorithm when you expect long-lived connections, such as for SQL databases, gRPC streams, LDAP, and other protocols that keep connections open for an extended period of time. This algorithm is not well suited for protocols that have short sessions, such as HTTP. It takes server weights and queued connections into account as well when choosing the best server.

random Jump to heading

Info

This is the default load balancing algorithm in versions 3.3 and later.

The random load balancing algorithm is a good choice for general-purpose load balancing. This algorithm implements the concept of the Power of Two Choices and provides efficient server selection that’s resilient to servers being added and removed frequently. It selects a server without having to analyze all servers, and since it will choose the least loaded of two randomly-chosen servers, it won’t select the most-loaded servers. This helps to smooth the distribution of requests across servers. This algorithm works particularly well with backends whose list of servers changes frequently, and it takes server weights into account when selecting the less-loaded server.

Tip

You can provide an additional argument to balance random called draws (balance random <draws>). Draws is an integer that determines how many servers will be selected as candidates. By default, the number of draws is two. We recommend you don’t change this value unless balance random 2 produces significantly uneven distribution across your servers. Increasing this value from 2 uses more CPU, though if your number of servers is large and your number of requests for each is no more than a few per second, you could see better distribution setting draws to 3 or 4.

first Jump to heading

Use balance first in cases where you power down servers that aren’t in active use. This algorithm will choose the first server in the list with open connection slots and send connections to it until it can’t receive any more connections, at which point it will move to the next server in the list. It ignores server weights. You must use the maxconn directive with this algorithm to establish the maximum number of connections for each server:

haproxy
backend web_servers
  mode http
  balance first
  server s1 192.168.1.25:80 check maxconn 100
  server s2 192.168.1.26:80 check maxconn 100
  server s3 192.168.1.27:80 check maxconn 100
haproxy
backend web_servers
  mode http
  balance first
  server s1 192.168.1.25:80 check maxconn 100
  server s2 192.168.1.26:80 check maxconn 100
  server s3 192.168.1.27:80 check maxconn 100

Tip

Be sure to monitor the number of queued connections per server to determine if you need to power on more servers. Use the show stat Runtime API command, keeping an eye on the value for each server’s qcur or the number of currently queued connections. Queued connections are waiting to access a backend server and a qcur value greater than zero may indicate you need more servers to handle connections.

hash Jump to heading

Use hash-based algorithms when you need to maintain affinity, or requests from the same client should reach the same server. Use balance hash to select the correct server. This algorithm takes an expression which, when evaluated, is used to compute the hash key and select the appropriate server.

Tip

There are several other load balancing algorithms that offer options similar to balance hash for simple hashing without needing to execute complex logic to compute the hash key. Use balance source when you want server affinity based on IP address. Use balance hdr(<header>) to assign server affinity based on the content of a particular HTTP header. Use balance uri for cache servers.

For example, if you wanted server affinity using IP addresses, you could use balance source. If, however, you wanted server affinity based on a /24 subnet instead of specific IP addresses, you could use balance hash with an expression that computes the subnet:

haproxy
backend web_servers {0-1}
  balance hash src,ipmask(24)
  server app1 10.0.0.1:8080 check
  server app2 10.0.0.2:8080 check
  server app3 10.0.0.3:8080 check
haproxy
backend web_servers {0-1}
  balance hash src,ipmask(24)
  server app1 10.0.0.1:8080 check
  server app2 10.0.0.2:8080 check
  server app3 10.0.0.3:8080 check

Enable health checks Jump to heading

Adding the check argument to each server line is a good practice; this enables health checking to remove unhealthy servers that don’t respond to a TCP connection from the load balancing rotation.

haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check
haproxy
backend web_servers
  mode http
  balance roundrobin
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check
  server s3 192.168.1.27:80 check

See also Jump to heading

For complete information on these directives that can be used in backends, see the HAProxy Configuration Manual:

  • To select a load balancing algorithm, see the balance directive reference.
  • To specify the type of traffic being processed, see mode.
  • For complete information on server directive syntax and options, see server.
  • To direct traffic to a specific backend, see use_backend.

Do you have any suggestions on how we can improve the content of this page?

Previous page Frontends Next page Listens
© 2026 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences