HAProxy Configuration File

The HAProxy configuration file (typically located at /etc/haproxy/haproxy.cfg) is the central file used to define how HAProxy operates. It controls load balancing, proxying, and health checking of backend servers, and is divided into several key sections. Each section has a distinct role in managing the behavior of HAProxy.

Key Sections

1. global

The global section sets process-wide settings that affect logging, user privileges, maximum connections, and other low-level parameters.

Example:

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

2. defaults

The defaults section specifies default parameters for all subsequent frontend, backend, and listen sections. This section covers settings like timeouts, logging, and error handling.

Example:

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5000ms
    timeout client  50000ms
    timeout server  50000ms

3. frontend

The frontend section defines how HAProxy listens for incoming client connections. It specifies the IP address, port, and ACLs (Access Control Lists) used to route requests.

Example:

frontend http-in
    bind *:80
    default_backend servers

4. backend

The backend section defines the real servers that will handle client requests. It includes load balancing algorithms, server health checks, and parameters that control how requests are distributed.

Example:

backend servers
    balance roundrobin
    server server1 192.168.1.101:80 check
    server server2 192.168.1.102:80 check

5. listen

The listen section is a combined frontend and backend definition. It is used when both roles are defined in a single block, often for simple setups.

Example:

listen stats
    bind *:1936
    mode http
    stats enable
    stats hide-version
    stats realm Haproxy\ Statistics
    stats uri /stats

Additional Directives

  • ACLs and Use Backend Rules: ACLs can be used within frontend sections to decide which backend should serve the request. For example:

    acl is_static path_end .jpg .png .css .js
    use_backend static_servers if is_static
  • Logging and Error Handling: You can customize logging formats and define error pages.

  • Health Checks: Servers in backends can be configured with health check options (check, inter, etc.) to ensure they are responsive before routing traffic.

Best Practices

  • Modular Configuration: Split your configuration into multiple files or use includes if the configuration grows large, for easier management.

  • Testing: Always test configuration changes using haproxy -c -f /etc/haproxy/haproxy.cfg to check for syntax errors.

  • Documentation: Refer to the official HAProxy documentation for detailed explanations of every directive and advanced configuration options.

  • Security: Secure the stats socket and web interface with authentication and appropriate access controls.

Conclusion

The HAProxy configuration file is a versatile and powerful way to control HAProxy’s behavior, enabling detailed management of load balancing, proxying, and health checking. By understanding and properly configuring sections such as global, defaults, frontend, backend, and listen, administrators can build robust, scalable, and secure HAProxy deployments that meet the needs of diverse network environments.

Last updated