Kahibaro
Discord Login Register ☰
☰
Previous
Up
Next

HAProxy fundamentals

Table of Contents

Role of HAProxy in Load Balancing

HAProxy is a high‑performance, open‑source TCP/HTTP load balancer and reverse proxy commonly used in front of web servers, APIs, and other TCP services. In the broader context of load balancing, HAProxy:

Here we focus on its basic architecture, configuration model, and core concepts you must know to operate it.

Installation and Basic Concepts

Installing HAProxy

Commands vary by distribution; examples: 

  sudo apt update
  sudo apt install haproxy
  sudo dnf install haproxy

Service management (systemd-based systems): 

sudo systemctl enable haproxy
sudo systemctl start haproxy
sudo systemctl status haproxy

The main configuration file is usually /etc/haproxy/haproxy.cfg.

HAProxy Process Model and Modes

Key ideas:

HAProxy Configuration Structure

All configuration is in haproxy.cfg. It is a declarative text file with sections:

A minimal skeleton: 

global
    log /dev/log local0
    maxconn 4096
    user haproxy
    group haproxy
    daemon
defaults
    log     global
    mode    http
    timeout connect 5s
    timeout client  50s
    timeout server  50s
frontend http_in
    bind *:80
    default_backend web_servers
backend web_servers
    balance roundrobin
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

Global Section Basics

Common global directives:

Example: 

global
    log /dev/log local0
    log /dev/log local1 notice
    maxconn 10000
    user haproxy
    group haproxy
    daemon
    nbthread 4

Defaults Section

Reduces repetition. Typical items:

Example: 

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout http-keep-alive 10s
    timeout connect         5s
    timeout client          50s
    timeout server          50s

Frontends and Backends

Frontends: Entry Points for Clients

A frontend defines:

Example HTTP frontend: 

frontend public_http
    bind *:80
    mode http
    # Basic logging options could be inherited from defaults
    default_backend web_pool

Example TCP frontend (e.g. for MySQL): 

frontend mysql_front
    bind 0.0.0.0:3306
    mode tcp
    default_backend mysql_pool

The `bind` Directive

bind chooses IP/port and encryption settings:

Multiple binds are allowed per frontend.

Backends: Pools of Destination Servers

A backend defines:

Example: 

backend web_pool
    mode http
    balance roundrobin
    option httpchk GET /health
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

TCP backend: 

backend mysql_pool
    mode tcp
    balance leastconn
    server db1 10.0.0.21:3306 check
    server db2 10.0.0.22:3306 check

The `listen` Section

For simple setups, listen combines frontend+backend: 

listen stats
    bind 127.0.0.1:9000
    mode http
    stats enable
    stats uri /stats

For serious production configs, separate frontend and backend blocks give more flexibility and clarity.

Basic Load‑Balancing Algorithms

Select with balance in a backend.

Common algorithms:

Example: 

backend api_pool
    mode http
    balance leastconn
    server api1 10.0.0.31:8080 check
    server api2 10.0.0.32:8080 check

Weighted servers: 

backend weighted_web
    mode http
    balance roundrobin
    server web1 10.0.0.11:80 weight 1 check
    server web2 10.0.0.12:80 weight 3 check

weight controls traffic share; in the above, web2 gets about three times as much traffic as web1.

Health Checks and Server States

Basic Health Checks

Health checks ensure traffic goes only to healthy servers.

Example HTTP health check: 

backend web_pool
    mode http
    option httpchk GET /health
    http-check expect status 200
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

If a check fails repeatedly, HAProxy marks the server DOWN and stops sending it traffic until it recovers.

Server Line Options (Basics)

Useful per‑server options:

Example: 

backend web_pool
    mode http
    balance roundrobin
    option httpchk GET /health
    server web1 10.0.0.11:80 check rise 2 fall 3
    server web2 10.0.0.12:80 check rise 2 fall 3 backup

HTTP‑Specific Fundamentals

HTTP Mode and Logging

Using mode http enables:

For better logging, use: 

defaults
    mode http
    option httplog
    option dontlognull

This produces Apache‑style access logs via syslog (e.g. in /var/log/haproxy.log depending on your system).

Basic ACLs and Content Switching

ACLs (Access Control Lists) define conditions; you can route traffic based on them.

Example: route /api to api_pool, everything else to web_pool: 

frontend public_http
    bind *:80
    mode http
    acl is_api path_beg /api
    use_backend api_pool if is_api
    default_backend web_pool
backend api_pool
    mode http
    balance roundrobin
    server api1 10.0.0.41:8080 check
    server api2 10.0.0.42:8080 check
backend web_pool
    mode http
    balance roundrobin
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

Example: route by Host header (virtual hosts): 

frontend public_http
    bind *:80
    mode http
    acl blog_host hdr(host) -i blog.example.com
    acl shop_host hdr(host) -i shop.example.com
    use_backend blog_backend if blog_host
    use_backend shop_backend if shop_host
    default_backend default_web

X‑Forwarded‑For and Proxy Headers

Since HAProxy sits between clients and backends, backends need to know the real client IP.

In HTTP mode, enable: 

backend web_pool
    mode http
    balance roundrobin
    option forwardfor
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

option forwardfor adds/updates the X-Forwarded-For header with the client IP.

Often combined with http-request set-header for additional headers: 

backend web_pool
    http-request set-header X-Forwarded-Proto https if { ssl_fc }

Basic SSL/TLS Termination

HAProxy can terminate TLS and forward plain HTTP to backends (offloading CPU-heavy encryption).

In the frontend: 

frontend https_in
    bind *:443 ssl crt /etc/haproxy/certs/example.com.pem
    mode http
    default_backend web_pool

Notes:

Basic HTTP → HTTPS redirect: 

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

HAProxy Stats and Basic Monitoring

HAProxy includes a simple web-based stats interface and a socket for administration.

Enabling the Stats Page

Example: 

listen stats
    bind 127.0.0.1:9000
    mode http
    stats enable
    stats uri /stats
    stats refresh 10s
    stats auth admin:StrongPassword

Browse to http://127.0.0.1:9000/stats (from the host, or expose appropriately) to see:

Stats Socket (Basics)

A UNIX socket allows runtime operations (disable/enable servers, etc.). Minimal example: 

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

You can then use: 

echo "show stat" | socat /run/haproxy/admin.sock stdio

Full use of the admin socket is more advanced, but knowing it exists is important for automation and fine‑grained control.

Managing Configuration and Reloads

Validating Configuration

Always validate before reloading: 

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

If there are syntax errors, HAProxy prints them without reloading the service.

Reloading Without Dropping Connections

On systemd distros: 

sudo systemctl reload haproxy

This typically performs a graceful reload:

If your distro doesn’t support graceful reload by default, a common pattern is: 

sudo service haproxy reload

(or an init script calling haproxy with -sf to send a soft-stop signal to the old process).

Putting It Together: Simple HTTP Load Balancer

An end‑to‑end example for a basic web setup: 

global
    log /dev/log local0
    maxconn 5000
    user haproxy
    group haproxy
    daemon
defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5s
    timeout client  50s
    timeout server  50s
frontend http_in
    bind *:80
    mode http
    # redirect to HTTPS
    http-request redirect scheme https code 301 if !{ ssl_fc }
frontend https_in
    bind *:443 ssl crt /etc/haproxy/certs/example.com.pem
    mode http
    # route /api to API servers, everything else to web servers
    acl is_api path_beg /api
    use_backend api_pool if is_api
    default_backend web_pool
backend web_pool
    mode http
    balance roundrobin
    option httpchk GET /health
    option forwardfor
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check
backend api_pool
    mode http
    balance leastconn
    option httpchk GET /health
    option forwardfor
    server api1 10.0.0.21:8080 check
    server api2 10.0.0.22:8080 check
listen stats
    bind 127.0.0.1:9000
    mode http
    stats enable
    stats uri /stats
    stats auth admin:StrongPassword

This demonstrates:

Next Steps Beyond Fundamentals

Once comfortable with these fundamentals, typical progression includes:

Previous
Up
Next

Views: 21

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro

Visitors: 1541 / 24h

Impressum / Imprint

Datenschutz / Data Policy