HAProxy guide

What HAProxy does in production

HAProxy sits in front of application servers and distributes incoming connections according to configured rules. It handles HTTP routing (host/path ACLs), TCP passthrough, TLS termination, session persistence, and automatic removal of unhealthy backends. Unlike a general web server, HAProxy is specialized for proxying and load balancing at scale.

How a request is handled

For HTTP mode, the typical workflow is:

1. Bind — a frontend accepts connections on one or more bind directives (address:port pairs)
2. ACL evaluation — optional acl rules match host, path, headers, or source IP; use_backend rules are checked in order until a match is found
3. Backend selection — use_backend rules (optionally with ACL conditions) select a backend; default_backend is the fallback if no rule matches
4. Server choice — the load-balancing algorithm (balance) picks a healthy server line
5. Health check — servers marked DOWN are skipped until checks pass again
6. Proxy — HAProxy forwards the request, handles connection pooling, applies any configured header modifications, and streams the response; stats and logs record the result

Configuration structure

Main config is usually /etc/haproxy/haproxy.cfg, organized in sections:

• global — process-wide settings (user, max connections, stats socket)
• defaults — inherited settings for frontends and backends (timeouts, mode, logging)
• frontend — client-facing listener; binds ports and routes to backends
• backend — pool of servers with balancing and health checks
• listen — combined frontend + backend in one block (common for simple setups)

Validate before reload: haproxy -c -f /etc/haproxy/haproxy.cfg.

Key concepts to know

• mode http vs mode tcp — L7 HTTP routing (parses headers, ACLs, rewrites) vs L4 passthrough (raw TCP, no inspection)
• balance roundrobin — distribute requests evenly (also: leastconn, source for sticky)
• balance — load-balancing algorithm. The default roundrobin distribute requests evenly, leastconn for long-lived sessions, source for sticky sessions, uri for cache-friendly
• Health checks — active (option httpchk for HTTP, option tcp-check for TCP checks) or passive (observing failures); servers are marked UP/DOWN automatically based on check results
• Stats page — built-in monitoring UI on a dedicated bind (often port 8404)
• ACLs — flexible rules matching path, headers, cookies, source IP, SSL, etc; combined with use_backend or http-request
• X-Forwarded-For — option forwardfor adds client IP header; essential when backend needs original source IP (for logging, rate-limiting, geo-location)
• log — HAProxy logs are rich and detailed. Check these first when troubleshooting

HAProxy vs nginx

Nginx can reverse-proxy and load-balance but HAProxy is purpose-built for advanced balancing, health checks, and high-connection throughput. Many architectures use HAProxy as the edge load balancer and nginx or app servers behind it.

Learning resources

• HAProxy documentation — haproxy.org/#docs (official docs index)
• Configuration manual — haproxy-dconv configuration (directive reference)
• Starter guide — haproxy.com/blog/haproxy-basic-configuration-tutorial (introductory walkthrough)