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 an address:port
2. ACL evaluation — optional acl rules match host, path, headers, or source IP
3. Backend selection — use_backend or default_backend picks a backend pool
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 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 vs L4 passthrough
• balance roundrobin — distribute requests evenly (also: leastconn, source for sticky)
• Health checks — option httpchk or TCP checks; servers go UP/DOWN automatically
• Stats page — built-in monitoring UI on a dedicated bind (often port 8404)
• ACLs — acl is_api path_beg /api then use_backend api_servers if is_api
• X-Forwarded-For — option forwardfor passes client IP to backends

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)