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
sudorights. The examples use the public address203.0.113.10. - Two or more backend servers that already serve the same website or application over HTTP. The examples use
198.51.100.11and198.51.100.12on 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 roundrobinuses each server in turn.leastconnpicks the server with the fewest connections and is the better choice for long-lived sessions;sourcehashes the client IP so a visitor keeps reaching the same server.checkon aserverline enables health checks. On its own, a check only tests whether a TCP connection can be opened.option httpchktogether withhttp-check sendupgrades the check to a real HTTP request. Responses with a 2xx or 3xx status count as healthy. Set theHostheader to a name your web servers answer for, and pointuriat 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.