HAProxy Config Generator

HAProxy Configuration Guide

HAProxy (High Availability Proxy) is a free, open-source load balancer and reverse proxy for TCP and HTTP-based applications. Used by high-traffic websites like GitHub, Reddit, and Stack Overflow, it’s known for extreme performance, reliability, and a rich set of Layer 4/7 features. Configuration lives in /etc/haproxy/haproxy.cfg and follows a section-based structure.

HAProxy vs Nginx vs Envoy

HAProxy Config Structure

HAProxy configuration has five main sections, each controlling a different aspect of the proxy:

global          # Process-wide settings (maxconn, chroot, user)
defaults        # Default settings for all proxies (timeouts, mode)
frontend name   # Client-facing listener (bind, ACLs, routing)
backend name    # Server pool (balance algorithm, server lines)
listen name     # Combined frontend+backend (used for stats)

Health Check Strategies

Health checks are HAProxy's killer feature. Unlike Nginx (which requires the paid Plus edition for active health checks), HAProxy includes sophisticated health checking in the free version. The right health check strategy prevents routing traffic to unhealthy backends.

# Health check tuning parameters
backend web_servers
    balance roundrobin
    option httpchk GET /health HTTP/1.1\r\nHost:\ myapp.com
    http-check expect status 200

    # check: enable health checks
    # inter: check interval (default 2s)
    # fall: consecutive failures before marking DOWN (default 3)
    # rise: consecutive successes before marking UP (default 2)
    server web1 10.0.0.1:8080 check inter 3s fall 3 rise 2
    server web2 10.0.0.2:8080 check inter 3s fall 3 rise 2
    server web3 10.0.0.3:8080 check inter 3s fall 3 rise 2 backup

SSL Termination vs SSL Passthrough

HAProxy supports three SSL modes, each with different trade-offs between security, performance, and backend complexity:

Load Balancing Algorithms

Rate Limiting with Stick Tables

HAProxy's stick tables track connection rates per client IP without external tools. This is one of the most powerful features for DDoS mitigation and API rate limiting:

frontend http_front
    bind *:80

    # Track request rate per client IP (10-second sliding window)
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src

    # Deny if more than 100 requests in 10 seconds
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }

    # Slow down (tarpit) abusive clients instead of blocking
    http-request tarpit if { sc_http_req_rate(0) gt 200 }

    default_backend web_servers

Essential Timeouts

Misconfigured timeouts are the #1 cause of HAProxy issues in production. Here's what each timeout controls and recommended values:

Always set timeout http-request — without it, Slowloris attacks can exhaust all connections by sending headers very slowly. For WebSocket backends, set timeout tunnel to a high value (1h+) to prevent idle WebSocket connections from being closed.

ACL-Based Routing Patterns

HAProxy's ACLs (Access Control Lists) enable powerful content-based routing at Layer 7. You can route requests based on URL paths, headers, query parameters, and more — all without backend changes:

frontend http_front
    bind *:80

    # Path-based routing (microservices)
    acl is_api     path_beg /api/
    acl is_static  path_beg /static/ /assets/ /images/
    acl is_ws      path_beg /ws/
    acl is_admin   path_beg /admin/

    use_backend api_servers    if is_api
    use_backend static_servers if is_static
    use_backend ws_servers     if is_ws
    use_backend admin_servers  if is_admin
    default_backend web_servers

    # Host-based routing (multi-tenant / multi-domain)
    acl is_app1    hdr(host) -i app1.example.com
    acl is_app2    hdr(host) -i app2.example.com
    use_backend app1_servers if is_app1
    use_backend app2_servers if is_app2

    # A/B testing (route 10% of traffic to canary)
    acl is_canary  rand(100) lt 10
    use_backend canary_servers if is_canary

    # Block by User-Agent or IP
    acl is_bot     hdr_sub(User-Agent) -i bot crawler spider
    acl is_banned  src 1.2.3.4 5.6.7.0/24
    http-request deny if is_bot OR is_banned

    # Add headers for backends
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Real-IP %[src]

ACLs are evaluated in order. The first matching use_backend wins. Combine ACLs with OR / AND (implicit) for complex routing logic. Use -i for case-insensitive matching.

HAProxy Logging & Monitoring

HAProxy logging provides detailed per-request metrics essential for debugging and capacity planning. Logs are sent to syslog and can be parsed by Prometheus, Grafana, or ELK:

# Enable detailed HTTP logging (in defaults or frontend)
defaults
    log     /dev/log local0
    option  httplog       # Detailed HTTP log format (vs tcplog for L4)
    option  log-health-checks  # Log health check results

# Custom log format with timing breakdown
frontend http_front
    log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %ts %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"

# Timing fields explained:
# TR = time to receive full HTTP request from client
# Tw = time spent in queue waiting for a server
# Tc = time to establish TCP connection to backend
# Tr = time for backend to send response headers
# Ta = total active time (TR + Tw + Tc + Tr + data transfer)

# Prometheus metrics (HAProxy 2.0+)
frontend stats
    bind *:8405
    http-request use-service prometheus-exporter if { path /metrics }
    # Scrape with: curl http://haproxy:8405/metrics

The Ta timing field is the most useful for identifying slow requests. If Tc is high, the backend server is slow to accept connections. If Tr is high, the backend application is slow to respond.

Troubleshooting Common HAProxy Issues

Connection Draining & Zero-Downtime Deploys

HAProxy excels at graceful deploys. When a backend server is put into maintenance mode or removed, existing connections finish normally while new connections are routed to healthy servers:

# Drain a server via HAProxy Runtime API (Unix socket)
echo "set server web_servers/web1 state drain" | socat stdio /var/run/haproxy.sock

# Check current connections before removing
echo "show stat" | socat stdio /var/run/haproxy.sock | grep web1

# Set to maintenance (stops health checks, rejects new connections)
echo "set server web_servers/web1 state maint" | socat stdio /var/run/haproxy.sock

# Bring back online
echo "set server web_servers/web1 state ready" | socat stdio /var/run/haproxy.sock

# Reload config without dropping connections (seamless reload)
systemctl reload haproxy

Privacy First

All configuration is generated entirely in your browser using JavaScript. Your server addresses, certificate paths, and infrastructure details are never sent to any server. This tool has zero backend dependencies.