HAProxy Skill

Complete guide for HAProxy - the reliable, high-performance TCP/HTTP load balancer.

Quick Reference

Configuration Sections

Section	Purpose
global	Process-wide settings
defaults	Default settings for all sections
frontend	Client-facing listeners
backend	Server pools
listen	Combined frontend/backend

Key Files

/etc/haproxy/haproxy.cfg    # Main config
/var/log/haproxy.log        # Logs
/var/run/haproxy/admin.sock # Admin socket

---

1. Installation

Ubuntu/Debian

sudo apt update
sudo apt install haproxy

# Enable and start
sudo systemctl enable haproxy
sudo systemctl start haproxy

CentOS/RHEL

sudo dnf install haproxy
sudo systemctl enable haproxy
sudo systemctl start haproxy

Docker

services:
  haproxy:
    image: haproxy:latest
    container_name: haproxy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8404:8404"
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
      - ./certs:/etc/ssl/certs:ro

---

2. Basic Configuration

Minimal haproxy.cfg

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    maxconn 4096

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5s
    timeout client  50s
    timeout server  50s
    errorfile 400 /etc/haproxy/errors/400.http
    errorfile 403 /etc/haproxy/errors/403.http
    errorfile 408 /etc/haproxy/errors/408.http
    errorfile 500 /etc/haproxy/errors/500.http
    errorfile 502 /etc/haproxy/errors/502.http
    errorfile 503 /etc/haproxy/errors/503.http
    errorfile 504 /etc/haproxy/errors/504.http

frontend http_front
    bind *:80
    default_backend http_back

backend http_back
    balance roundrobin
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

---

3. Load Balancing Algorithms

Round Robin (Default)

backend http_back
    balance roundrobin
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

Least Connections

backend http_back
    balance leastconn
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

Source IP Hash (Sticky)

backend http_back
    balance source
    hash-type consistent
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

Weighted Round Robin

backend http_back
    balance roundrobin
    server server1 192.168.1.10:80 weight 3 check
    server server2 192.168.1.11:80 weight 1 check

URI Hash

backend http_back
    balance uri
    hash-type consistent
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

---

4. Health Checks

HTTP Health Check

backend http_back
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server server1 192.168.1.10:80 check inter 5s fall 3 rise 2
    server server2 192.168.1.11:80 check inter 5s fall 3 rise 2

TCP Health Check

backend tcp_back
    mode tcp
    balance roundrobin
    option tcp-check
    server server1 192.168.1.10:3306 check inter 5s
    server server2 192.168.1.11:3306 check inter 5s

Health Check Options

# inter: check interval
# fall: failures before marking down
# rise: successes before marking up
# slowstart: gradual traffic increase after recovery

server server1 192.168.1.10:80 check inter 3s fall 3 rise 2 slowstart 60s

---

5. SSL/TLS Termination

HTTPS Frontend

frontend https_front
    bind *:443 ssl crt /etc/ssl/certs/combined.pem
    mode http
    default_backend http_back

Combined Certificate (PEM)

# Combine certificate and key
cat certificate.crt ca-bundle.crt private.key > combined.pem
chmod 600 combined.pem

SSL with Redirect

frontend http_front
    bind *:80
    mode http
    redirect scheme https code 301 if !{ ssl_fc }

frontend https_front
    bind *:443 ssl crt /etc/ssl/certs/combined.pem
    mode http
    default_backend http_back

SSL Passthrough

frontend tcp_front
    bind *:443
    mode tcp
    default_backend tcp_back

backend tcp_back
    mode tcp
    server server1 192.168.1.10:443 check

Multiple Certificates (SNI)

frontend https_front
    bind *:443 ssl crt /etc/ssl/certs/
    # All .pem files in directory are loaded
    # HAProxy selects based on SNI

---

6. ACLs and Routing

Host-Based Routing

frontend http_front
    bind *:80
    acl is_api hdr(host) -i api.example.com
    acl is_web hdr(host) -i www.example.com

    use_backend api_back if is_api
    use_backend web_back if is_web
    default_backend web_back

Path-Based Routing

frontend http_front
    bind *:80
    acl is_api path_beg /api
    acl is_static path_beg /static

    use_backend api_back if is_api
    use_backend static_back if is_static
    default_backend web_back

Method-Based Routing

frontend http_front
    bind *:80
    acl is_post method POST
    acl is_get method GET

    use_backend write_back if is_post
    use_backend read_back if is_get

IP-Based ACL

frontend http_front
    bind *:80
    acl is_internal src 192.168.0.0/16 10.0.0.0/8

    use_backend internal_back if is_internal
    default_backend public_back

---

7. Session Persistence

Cookie-Based

backend http_back
    balance roundrobin
    cookie SERVERID insert indirect nocache
    server server1 192.168.1.10:80 check cookie s1
    server server2 192.168.1.11:80 check cookie s2

Stick Tables

backend http_back
    balance roundrobin
    stick-table type ip size 200k expire 30m
    stick on src
    server server1 192.168.1.10:80 check
    server server2 192.168.1.11:80 check

Application Cookie

backend http_back
    balance roundrobin
    cookie JSESSIONID prefix nocache
    server server1 192.168.1.10:80 check cookie s1
    server server2 192.168.1.11:80 check cookie s2

---

8. Rate Limiting

Connection Rate Limiting

frontend http_front
    bind *:80
    stick-table type ip size 100k expire 30s store conn_cur,conn_rate(3s)

    # Deny if more than 20 connections per 3 seconds
    acl too_fast src_conn_rate gt 20
    tcp-request connection reject if too_fast

Request Rate Limiting

frontend http_front
    bind *:80
    stick-table type ip size 100k expire 30s store http_req_rate(10s)

    # Tarpit (slow down) if more than 100 requests per 10 seconds
    acl too_many_requests src_http_req_rate gt 100
    http-request tarpit if too_many_requests

Per-URL Rate Limiting

frontend http_front
    bind *:80
    stick-table type string len 128 size 100k expire 30s store http_req_rate(10s)

    # Track by URL path
    http-request track-sc0 path
    acl api_abuse sc0_http_req_rate gt 50
    http-request deny if api_abuse { path_beg /api }

---

9. Stats and Monitoring

Stats Page

listen stats
    bind *:8404
    mode http
    stats enable
    stats uri /stats
    stats refresh 30s
    stats admin if LOCALHOST
    stats auth admin:password

Prometheus Metrics

frontend stats
    bind *:8405
    mode http
    http-request use-service prometheus-exporter if { path /metrics }
    stats enable
    stats uri /stats

Runtime API

global
    stats socket /var/run/haproxy/admin.sock mode 660 level admin

# Usage
echo "show stat" | socat stdio /var/run/haproxy/admin.sock
echo "show servers state" | socat stdio /var/run/haproxy/admin.sock
echo "disable server http_back/server1" | socat stdio /var/run/haproxy/admin.sock

---

10. High Availability

Keepalived Integration

# /etc/keepalived/keepalived.conf
vrrp_script chk_haproxy {
    script "killall -0 haproxy"
    interval 2
    weight 2
}

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 101
    advert_int 1

    virtual_ipaddress {
        192.168.1.100
    }

    track_script {
        chk_haproxy
    }
}

Graceful Reload

# Check config
haproxy -c -f /etc/haproxy/haproxy.cfg

# Graceful reload
systemctl reload haproxy

# Or manual
haproxy -f /etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid)

---

11. TCP Load Balancing

Database (MySQL)

listen mysql
    bind *:3306
    mode tcp
    balance leastconn
    option mysql-check user haproxy
    server mysql1 192.168.1.10:3306 check
    server mysql2 192.168.1.11:3306 check backup

Redis

listen redis
    bind *:6379
    mode tcp
    balance first
    option tcp-check
    tcp-check send PING\r\n
    tcp-check expect string +PONG
    server redis1 192.168.1.10:6379 check inter 1s
    server redis2 192.168.1.11:6379 check inter 1s

SMTP

listen smtp
    bind *:25
    mode tcp
    balance roundrobin
    server smtp1 192.168.1.10:25 check
    server smtp2 192.168.1.11:25 check

---

12. Troubleshooting

Common Issues

Connection refused:

# Check HAProxy is running
systemctl status haproxy

# Check ports
ss -tlnp | grep haproxy

# Check backend servers
curl -v http://192.168.1.10:80/

503 Service Unavailable:

# Check backend health
echo "show servers state" | socat stdio /var/run/haproxy/admin.sock

# View stats page
# http://haproxy-ip:8404/stats

Configuration errors:

# Validate config
haproxy -c -f /etc/haproxy/haproxy.cfg

# View logs
journalctl -u haproxy -f
tail -f /var/log/haproxy.log

Debug Mode

global
    log stdout format raw local0 debug

defaults
    log global
    option httplog

Useful Commands

# Show stat summary
echo "show stat" | socat stdio /var/run/haproxy/admin.sock | cut -d, -f1,2,18

# Show errors
echo "show errors" | socat stdio /var/run/haproxy/admin.sock

# Enable/disable server
echo "disable server http_back/server1" | socat stdio /var/run/haproxy/admin.sock
echo "enable server http_back/server1" | socat stdio /var/run/haproxy/admin.sock

# Set server weight
echo "set server http_back/server1 weight 50" | socat stdio /var/run/haproxy/admin.sock

---

Best Practices

1. Always validate config before reload:

   haproxy -c -f config

2. Use health checks on all backends
3. Enable logging for debugging and monitoring
4. Set appropriate timeouts - not too short, not too long
5. Use ACLs for complex routing logic
6. Monitor with stats page or Prometheus
7. Use keepalived for HAProxy high availability
8. Secure stats page with authentication and IP restrictions
9. Use stick tables for rate limiting and abuse prevention
10. Regular config backups before changes