HAProxy Cheat Sheet
Configuration syntax for HAProxy frontends, backends, load-balancing algorithms, and health checks in high-availability setups.
2 PagesAdvancedFeb 10, 2026
Frontend & Backend
Route HTTP traffic to a pool of backend servers.
haproxy
frontend http_front bind *:80 default_backend http_backbackend http_back balance roundrobin option httpchk GET /healthz server web1 10.0.0.1:3000 check server web2 10.0.0.2:3000 check server web3 10.0.0.3:3000 check backup
SSL Termination
Terminate TLS at HAProxy and forward plaintext to backends.
haproxy
frontend https_front bind *:443 ssl crt /etc/haproxy/certs/example.pem mode http redirect scheme https code 301 if !{ ssl_fc } default_backend http_backfrontend http_redirect bind *:80 redirect scheme https code 301
Load-Balancing Algorithms
Common 'balance' directive values.
- roundrobin- Cycles requests evenly across servers; default and simplest choice
- leastconn- Sends new requests to the server with fewest active connections; good for long-lived connections
- source- Hashes client IP so the same client consistently hits the same server (sticky by IP)
- uri- Hashes the request URI, useful for cache-friendly routing
- static-rr- Round robin with weights fixed at start (no dynamic reweighing)
- first- Sends to the first server with available capacity, keeping others idle until needed
Stats Page & ACLs
Expose the built-in dashboard and route by path.
haproxy
listen stats bind *:8404 stats enable stats uri /stats stats refresh 10sfrontend http_front bind *:80 acl is_api path_beg /api use_backend api_back if is_api default_backend web_back
ACLs & Header-Based Routing
Combine multiple ACL conditions to route by host, header, and cookie.
haproxy
frontend http_front bind *:80 acl is_app1 hdr(host) -i app1.example.com acl is_app2 hdr(host) -i app2.example.com acl has_mobile_ua hdr_sub(user-agent) -i mobile acl is_canary cookie(canary) -m found use_backend canary_back if is_canary use_backend mobile_back if is_app1 has_mobile_ua use_backend app1_back if is_app1 use_backend app2_back if is_app2 default_backend default_back
Sticky Sessions with Cookies
Persist a client to the same backend server using an inserted cookie.
haproxy
backend web_back balance roundrobin cookie SRVID insert indirect nocache server web1 10.0.0.1:3000 check cookie web1 server web2 10.0.0.2:3000 check cookie web2 # Alternative: stick-table keyed on source IP, no cookie requiredbackend web_back_ip balance leastconn stick-table type ip size 200k expire 30m stick on src server web1 10.0.0.1:3000 check server web2 10.0.0.2:3000 check
Rate Limiting & Connection Abuse Protection
Throttle abusive clients using stick-tables tracking request rate.
haproxy
frontend http_front bind *:80 stick-table type ip size 100k expire 30s store http_req_rate(10s) http-request track-sc0 src http-request deny deny_status 429 if { sc_http_req_rate(0) gt 50 } # Reject clients that open too many concurrent connections stick-table type ip size 100k expire 30s store conn_cur http-request track-sc1 src http-request deny deny_status 429 if { sc_conn_cur(1) gt 20 }
HTTP/2 and gRPC Backends
Terminate HTTP/2 at the edge and proxy gRPC over h2 to backends.
haproxy
frontend grpc_front bind *:443 ssl crt /etc/haproxy/certs/example.pem alpn h2,http/1.1 mode http acl is_grpc hdr(content-type) -i application/grpc use_backend grpc_back if is_grpc default_backend http_backbackend grpc_back mode http balance roundrobin default-server proto h2 server grpc1 10.0.0.10:50051 check server grpc2 10.0.0.11:50051 check
Runtime API & Observability
Inspect and modify a running HAProxy instance without a config reload.
- socat stdio /var/run/haproxy.sock- Open the admin socket to run runtime commands interactively
- show stat- Print CSV stats for every frontend/backend/server, useful for scripting dashboards
- set server <be>/<srv> state maint- Drain and take a server out of rotation without editing the config
- set weight <be>/<srv> 50- Adjust a server's weight live for canary or blue-green shifts
- show info- Process-level stats: uptime, current connections, memory, SSL cache usage
- clear counters- Reset stick-table and stats counters without restarting the process
- reload via systemctl reload haproxy- Uses the -sf (seamless fork) mechanism so existing connections drain instead of dropping
Pro Tip
Use 'option httpchk' with a dedicated lightweight health endpoint rather than checking '/', so backend health reflects application readiness, not just whether the web server process is alive.
Was this cheat sheet helpful?
Explore Topics
#HAProxy#HAProxyCheatSheet#DevOps#Advanced#FrontendBackend#SSLTermination#LoadBalancingAlgorithms#StatsPageACLs#Algorithms#CheatSheet#SkillVeris
