Operating System Debian

How to Install and Configure HAProxy on Debian 13 (Trixie)

Install HAProxy 3.0 on Debian 13, load-balance two web servers with HTTP health checks, enable the statistics page and validate the configuration.

HAProxy is a TCP and HTTP load balancer and reverse proxy. Placed in front of two or more web servers, it spreads requests between them and stops sending traffic to a server that fails its health check. This guide installs HAProxy on Debian 13 (Trixie), configures it to balance HTTP traffic across two backend servers, and enables the statistics page.

Older tutorials on this topic covered HAProxy 1.7 on Debian 9. Both are end-of-life. Debian 13 ships the HAProxy 3.0 long-term-support branch, Debian 12 ships 2.6, and the configuration below works on both. Where you need a newer branch, the Debian HAProxy packaging team provides one, as shown in step 1.

Requirements

  • One Debian 13 server for HAProxy with a user that has sudo rights. The examples use the public address 203.0.113.10.
  • Two or more backend servers that already serve the same website or application over HTTP. The examples use 198.51.100.11 and 198.51.100.12 on port 80.
  • Port 80 open on the HAProxy server, and the backends reachable from it.

Step 1: Install HAProxy

The package in the Debian repositories is the simplest choice and receives security updates from Debian:

sudo apt update
sudo apt install haproxy

Confirm the version and that the service is running:

haproxy -v
systemctl status haproxy

On Debian 13 the version starts with 3.0; on Debian 12 with 2.6. The service is started and enabled at boot by the package.

Optional: install a newer branch

If you need a feature from a later release, the packaging team's site haproxy.debian.net offers a selector for your distribution and the branch you want. For Debian 13 it currently lists 3.0 from the official repositories and 3.2, 3.3 and 3.4 from its own repository. For example, for the 3.2 LTS branch on Trixie:

sudo curl https://haproxy.debian.net/haproxy-archive-keyring.gpg \
     --create-dirs --output /etc/apt/keyrings/haproxy-archive-keyring.gpg
echo deb "[signed-by=/etc/apt/keyrings/haproxy-archive-keyring.gpg]" \
     https://haproxy.debian.net trixie-backports-3.2 main \
     | sudo tee /etc/apt/sources.list.d/haproxy.list
sudo apt-get update
sudo apt-get install haproxy=3.2.\*

Always take the exact commands from that page, because the available branches change. On Debian 12 replace trixie with bookworm. Prefer an LTS branch for production.

Step 2: Review the global and defaults sections

The configuration lives in /etc/haproxy/haproxy.cfg. Keep a copy of the packaged file, then open it:

sudo cp /etc/haproxy/haproxy.cfg /etc/haproxy/haproxy.cfg.orig
sudo nano /etc/haproxy/haproxy.cfg

The file starts with two sections. global holds process-wide settings: logging, the unprivileged haproxy user and group, the chroot directory and the admin socket. defaults holds settings inherited by every proxy you define below it. Debian's defaults already set mode http, HTTP logging and sensible timeouts, so only a few additions are needed.

In global, set an upper limit for concurrent connections. HAProxy stops accepting new connections when the limit is reached, which protects the machine from running out of memory under a flood of requests:

global
    # keep the existing lines and add:
    maxconn 4096

In defaults, add:

defaults
    # keep the existing lines and add:
    option forwardfor
    option redispatch

option forwardfor adds an X-Forwarded-For header with the client's IP address to each request. Without it, your web servers only see the address of the load balancer. option redispatch lets HAProxy retry a request on another server when the connection to the chosen one fails.

Older guides also added option http-server-close. Current HAProxy versions keep connections alive on both the client and the server side by default, which suits most sites. Add option http-server-close only if your backend servers handle idle keep-alive connections badly; it closes the server-side connection after each response while clients keep theirs.

Step 3: Add a frontend and a backend

A frontend defines where HAProxy listens; a backend defines the servers that receive the traffic. Append both to the end of the file:

frontend www
    bind *:80
    default_backend web_servers

backend web_servers
    balance roundrobin
    option httpchk
    http-check send meth GET uri / ver HTTP/1.1 hdr Host example.com
    server web1 198.51.100.11:80 check
    server web2 198.51.100.12:80 check

What the backend lines do:

  • balance roundrobin uses each server in turn. leastconn picks the server with the fewest connections and is the better choice for long-lived sessions; source hashes the client IP so a visitor keeps reaching the same server.
  • check on a server line enables health checks. On its own, a check only tests whether a TCP connection can be opened.
  • option httpchk together with http-check send upgrades the check to a real HTTP request. Responses with a 2xx or 3xx status count as healthy. Set the Host header to a name your web servers answer for, and point uri at a lightweight page.

If your application stores sessions locally on each web server, add cookie-based persistence so a visitor stays on one server:

backend web_servers
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk
    http-check send meth GET uri / ver HTTP/1.1 hdr Host example.com
    server web1 198.51.100.11:80 check cookie web1
    server web2 198.51.100.12:80 check cookie web2

Step 4: Enable the statistics page

HAProxy has a built-in status page showing every frontend, backend and server with its health and traffic counters. Give it a port of its own:

listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s
    stats hide-version
    stats auth admin:use-a-long-random-password

The password is stored in clear text in the configuration file and sent with HTTP basic authentication, so do not reuse one from elsewhere. Restrict port 8404 in your firewall to your own IP address, or bind it to 127.0.0.1:8404 and reach it through an SSH tunnel.

Step 5: Validate the configuration and reload

Check the file before applying it:

sudo haproxy -c -V -f /etc/haproxy/haproxy.cfg

A correct file produces Configuration file is valid. Errors are reported with the line number. Then load the new configuration:

sudo systemctl reload haproxy

Step 6: Test the load balancer

Send a few requests to the HAProxy address from another machine:

for i in 1 2 3 4; do curl -s -o /dev/null -w '%{http_code}\n' http://203.0.113.10/; done

Each request should return 200. To see the distribution, watch the access logs on both web servers, or temporarily serve a page that shows each server's hostname. Then open http://203.0.113.10:8404/stats and log in: both servers should be listed as UP.

Now stop the web server on one backend. Within a few seconds the statistics page marks it as DOWN and all requests go to the remaining server. Start it again and it returns to the rotation automatically.

Service messages are available with:

sudo journalctl -u haproxy --since "10 minutes ago"

A 503 Service Unavailable response from HAProxy means no server in the backend is considered healthy. Check that the backends are reachable from the HAProxy server with curl -I http://198.51.100.11/ and that the health-check request returns a 2xx or 3xx status.

Next steps: HTTPS and client addresses

To terminate TLS on the load balancer, concatenate the certificate chain and private key into one PEM file, add a second bind line and redirect plain HTTP:

frontend www
    bind *:80
    bind *:443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
    http-request redirect scheme https unless { ssl_fc }
    default_backend web_servers

On the web servers, configure the access log or the real-IP module of your web server (mod_remoteip for Apache, ngx_http_realip_module for Nginx) to trust X-Forwarded-For only from the HAProxy address. All keywords used here are described in the HAProxy configuration manual.

Frequently asked questions

Which HAProxy version should I run?

For most servers, the version in the distribution: 3.0 on Debian 13, 2.6 on Debian 12, 3.2 on Ubuntu 26.04 LTS and 2.8 on Ubuntu 24.04 LTS. These are LTS branches and get security fixes through the normal package updates. Use the haproxy.debian.net repository (or the matching PPA on Ubuntu) only when you need something from a newer branch.

Does a reload interrupt visitors?

No. systemctl reload haproxy starts new worker processes with the new configuration while the old ones finish the connections they already have. systemctl restart haproxy stops the service first and drops open connections, so keep it for cases where a reload is not enough.

Is the HAProxy server itself a single point of failure?

Yes, with one load balancer. The usual answer is a second HAProxy server with the same configuration and a floating IP address that moves between them, managed by a tool such as Keepalived or by your provider's failover-IP feature.

Can HAProxy balance things other than HTTP?

Yes. With mode tcp in a frontend and backend it forwards any TCP protocol, for example database or mail traffic. HTTP-specific options such as option forwardfor, cookies and http-check do not apply in that mode.

Share story:

Continue reading other guides on How VPS.