HAProxy Complete Guide

A HAProxy knowledge document for product teams and developers, covering core concepts, configuration practices, and operational essentials.

💡 Applicable versions: HAProxy 2.0+ (including 2.4 / 2.6 / 2.8 LTS)

1. Overview

1.1 What is HAProxy?

HAProxy(High Availability Proxy) is an open-source, high-performance TCP/HTTP reverse proxy and load balancer. It uses Single-process, event-driven, non-blocking The architecture can stably handle massive concurrent connections with extremely low resource consumption (a single machine can easily support tens of thousands to hundreds of thousands of concurrent connections), and is an extremely mature and reliable component in internet infrastructure.

1.2 Core Features at a Glance

Functional module	Specific capabilities
Load balancing	Supports multiple algorithms such as round robin (roundrobin), least connections (leastconn), source IP hash (source), URI hash, and more.
Health check	Actively probe backend service status, automatically isolate faulty nodes, and seamlessly rejoin after recovery.
Layer 7 routing	Fine-grained traffic distribution based on conditions such as URL path, HTTP headers, cookies, and request method.
Session persistence	Through Cookie injection or source IP hashing, ensure that requests from the same user always land on the same backend.
SSL/TLS offloading	Centrally handle HTTPS encryption and decryption at the proxy layer to reduce backend load.
High availability support	Work with Keepalived to implement active-standby hot failover and eliminate single points of failure.
Broad protocol support	Supports both HTTP/HTTPS and native TCP proxy (MySQL, Redis, SMTP, etc.)

1.3 Typical Application Scenarios

• Web application load balancing: Distribute massive user requests across multiple web servers to improve throughput and availability

• Microservice Gateway / K8s Ingress As the ingress controller for a Kubernetes cluster, implement routing based on domain names and paths

• Database / cache proxy: Provides connection load balancing and failover for MySQL, Redis, PostgreSQL, etc.

• API Gateway Rate limiting, upfront authentication, and version-based routing for external API requests

• Service mesh data plane: Acts as a Sidecar proxy, handling load balancing and circuit breaking for inter-service communication.

2. Core Concepts

To understand HAProxy, you must first master three core configuration blocks:

2.1 frontend(Frontend)

Definition How to integrate the client It specifies the IP address and port to listen on, and determines how received traffic is processed, which rules are matched, and which backend it is forwarded to.

frontend web_frontend
    bind *:80
    mode http
    default_backend app_backend

2.2 backend(Backend)

Definition a set of real servers(referred to as server), and configure the load balancing algorithm, health check policy, and session persistence method.

backend app_backend
    mode http
    balance roundrobin
    option httpchk GET /health
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check

2.3 listen(Monitoring)

listen Yes frontend+backend simplified combined syntax, suitable for simple scenarios (such as proxying a single port to a group of backends).

listen mysql_cluster
    bind *:3306
    mode tcp
    balance leastconn
    server db1 10.0.0.1:3306 check
    server db2 10.0.0.2:3306 check

3. Detailed Explanation of Load Balancing Algorithms

HAProxy supports multiple algorithms; which one to choose depends on business characteristics:

algorithm	Keyword	Applicable scenarios
polling	roundrobin	Server performance is similar, requests are evenly distributed (default, supports dynamic weight adjustment)
least connections	leastconn	For long-lived connection scenarios (such as database connections, WebSocket), assign to the backend with the fewest currently active connections.
Source IP hash	source	Session persistence requirement: the same source IP always goes to the same backend (suitable for cookie-less scenarios)
URI hash	uri	Cache-friendly: requests with the same URI hit the same backend, improving the cache hit rate.
URL parameter hash	url_param	Perform hash-based distribution based on specified parameters in the URL (such as user_id).
Random	random	Cooperate hash-balance-factor Can achieve approximately uniform distribution, suitable for large-scale backend pools

Example:

backend myapp
    balance leastconn      # Prioritize long-connection scenarios.
    # balance source        # Can be switched if session persistence is needed
    server app1 10.0.0.1:8080 check
    server app2 10.0.0.2:8080 check

4. Configuration Details (Practical Examples)

4.1 Global Configuration (global)

Set process runtime parameters, logs, maximum connections, user/group, etc.

global
    log /dev/log local0    # Output logs to syslog
    maxconn 40000          # Maximum number of connections per process
    user haproxy
    group haproxy
    daemon                 # Run in the background
    stats socket /var/run/haproxy.sock mode 600 level admin  # Management interface
    tune.ssl.default-dh-param 2048

4.2 Default configuration (defaults)

for frontend,backend and listen Provide default values to reduce repetitive configuration.

defaults
    mode http
    log global
    option httplog          # Record detailed HTTP request logs
    option dontlognull      # Do not log empty connections
    retries 3
    timeout connect 5000ms  # Connection to backend timed out
    timeout client 50000ms  # Client idle timeout
    timeout server 50000ms  # Server idle timeout
    errorfile 400 /etc/haproxy/errors/400.http
    errorfile 503 /etc/haproxy/errors/503.http

4.3 Complete Web Load Balancing Example

Scene Provide HTTPS services externally, route requests by URL path to two backends (API and static resources), and enable health checks.

global
    log /dev/log local0
    maxconn 30000
    user haproxy
    group haproxy
    daemon

defaults
    mode http
    log global
    option httplog
    option dontlognull
    retries 3
    timeout connect 5s
    timeout client 30s
    timeout server 30s

# ---------- HTTPS Frontend ----------
frontend https_in
    bind *:443 ssl crt /etc/ssl/certs/myapp.pem
    reqadd X-Forwarded-Proto:\ https
    default_backend api_servers

    # Forward based on path: static resources go to the static backend
    use_backend static_servers if { path_beg /static/ /images/ /css/ /js/ }

# ---------- API Backend ----------
backend api_servers
    balance roundrobin
    option httpchk GET /api/health
    server api1 192.168.1.10:8080 check rise 2 fall 3
    server api2 192.168.1.11:8080 check rise 2 fall 3
    server api3 192.168.1.12:8080 check rise 2 fall 3 backup   # Standby node

# ---------- Static Resource Backend ----------
backend static_servers
    balance source         # Source IP hashing to improve cache hit rate
    option httpchk HEAD /index.html
    server static1 192.168.1.20:80 check
    server static2 192.168.1.21:80 check

5. Health Check Configuration

Health checks are key to ensuring high availability; HAProxy supports multiple check methods:

Check type	Configuration method	Applicable scenarios
TCP port check	check(Default)	Only check whether the port is listening.
HTTP layer inspection	option httpchk+http-check	Verify the application's returned status code (2xx/3xx considered healthy)
Custom script check	external-check	Execute external scripts for complex business validation.
Passive inspection	observe+error-limit	Passively determine health status by observing the number of request failures.

Advanced Example: Perform a detailed check on the API service—require the response body to contain a specific string.

backend api_backend
    option httpchk GET /health
    http-check expect string "OK"
    server api1 10.0.0.1:8080 check inter 2000 rise 2 fall 3

Parameter description:

• inter 2000 Check every 2 seconds

• rise 2: Marked as healthy after 2 consecutive successes

• fall 3: Mark as faulty after 3 consecutive failures

6. ACL (Access Control List)

ACLs are the core of HAProxy Layer 7 routing; they can match requests based on various conditions and then determine the forwarding policy.

Common ACL conditions:

Condition	Example
Path prefix	{ path_beg /api /v1 }
path suffix	{ path_end .jpg .png .css }
domain name	{ hdr(host) -i example.com }
HTTP Method	{ method POST }
Request header	{ hdr(user-agent) -i mobile }
Source IP	{ src 192.168.1.0/24 }
URL parameters	{ url_param(user_id) 12345 }

Practical scenarios: Conduct a canary release based on the source IP.

frontend web
    bind *:80
    use_backend canary_backend if { src 10.0.10.0/24 }   # Internal network test IPs go through canary release.
    default_backend prod_backend

7. Session Persistence (Sticky Sessions)

For applications that need to maintain session state (such as shopping carts), this can be implemented in the following ways:

Method 1: Cookie Injection (Recommended)

HAProxy inserts on the first response SERVERID Cookie; subsequent requests are routed based on this.

backend app
    balance roundrobin
    cookie SERVERID insert indirect nocache
    server app1 10.0.0.1:80 cookie app1 check
    server app2 10.0.0.2:80 cookie app2 check

Method 2: Source IP hash

backend app
    balance source
    hash-type consistent    # Consistent hashing, reducing remapping when nodes change
    server app1 10.0.0.1:80 check
    server app2 10.0.0.2:80 check

8. High Availability Architecture (Keepalived Integration)

HAProxy itself has no active-standby mechanism and must be used in conjunction with Keepalived Implement VIP (Virtual IP) drift.

Simple deployment architecture:

Keepalived configuration key points(Master node):

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass 1234
    }
    virtual_ipaddress {
        10.0.0.100/24
    }
}

The standby node will state Change to BACKUP,priority Lower (e.g., 90).

9. Monitoring and Statistics Page

HAProxy's built-in statistics page greatly facilitates operations monitoring:

frontend stats
    bind *:8080
    stats enable
    stats uri /stats
    stats refresh 10s
    stats auth admin:password
    stats show-legends
    stats show-node

Visit http://your-haproxy:8080/stats You can then see the real-time traffic, number of connections, health status, etc. of each frontend/backend/server.

集成 Prometheus 监控:

• through stats socket Exposure indicators, use haproxy_exporter Collection

• Or enable the built-in Prometheus endpoint (HAProxy 2.0+):

frontend prometheus
    bind *:8404
    http-request use-service prometheus-exporter if { path /metrics }

10. Performance Tuning Recommendations

Tuning dimensions	Suggestion
kernel parameters	Adjustment net.core.somaxconn,net.ipv4.ip_local_port_range,net.ipv4.tcp_tw_reuse wait
Connection timed out	Set reasonably according to the business.timeout client/server, too short affects long connections; too long wastes resources
Maximum connections	maxconn Based on memory (approximately 1~2MB/connection) and traffic volume settings
Thread mode	HAProxy 2.0+ supports multithreading, through nbproc and cpu-map Bind CPU core
Zero-copy	Enable tune.bufsize and tune.pipesize Improve large file transfer efficiency
Log sampling	Use in high-concurrency scenarios log-sampler Reduce log volume to avoid syslog becoming a bottleneck

11. Common Troubleshooting

Problem symptom	Possible causes	Inspection method
Backend health check failed	Backend service not started / blocked by firewall	curl Manually check the health endpoint and review the HAProxy logs."Health check failed"
Request 503 error	All backends are unavailable.	Check stats Page server status, check default_backend Is it correct?
Frequent session loss	Cookie not set correctly / hash algorithm changed	Confirm cookie configuration or hash-type consistent
High CPU usage	Excessive logs / intensive SSL handshakes	Reduce the log level and enable SSL session caching.ssl.cachesize
Connections exhausted	maxconn Set too low or backend response is slow	Turn up maxconn Optimize backend response time

12. Version Upgrade and Maintenance

• Version Selection: For production environments, it is recommended to use the latest LTS (Long-Term Support) version, such as 2.4 LTS or 2.6 LTS

• Smooth overload: Use haproxy -f /etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid) Implement seamless loading of new configurations

• Configuration Check: Run after each modification haproxy -c -f /etc/haproxy/haproxy.cfg Verify grammar

13. Enterprise Practice Cases

• DigitalOcean: Using HAProxy as the core engine of its Load Balancing as a Service (LBaaS) to carry massive cloud tenant traffic

• Microsoft Yammer: Running over 60,000 HAProxy instances, handling a peak of 450,000 requests per second

• Clover: Using HAProxy's weighted routing to implement "rainbow deployment," precisely directing different customer traffic to different versions

• DoubleVerify: Migrating from F5 hardware to HAProxy, handling billions of requests daily, and significantly reducing TCO

14. Quick Reference Card

Operation	command
Start HAProxy	haproxy -f /etc/haproxy/haproxy.cfg
smooth reload	haproxy -f haproxy.cfg -sf $(pidof haproxy)
Check configuration syntax	haproxy -c -f haproxy.cfg
View statistics page	Browser access http://haproxy_ip:8080/stats(stats configuration required)
View real-time connection count	`echo "show info"
Check server status	`echo "show servers state"