HAProxy: a detailed guide to configuration directives

1. acl #

Access control lists for logical tests. Available since version 1.1.

Structure #

The general syntax is: acl <name> <criterion> <values>. The name lets you reuse the test later.

is_api #

Uses path_beg to test the beginning of the URL path.

acl is_api path_beg /api

This line creates a rule named 'is_api' that matches if the URL starts with /api.

is_static #

Uses path_end to identify files by their extensions.

acl is_static path_end .jpg .png

This command defines the 'is_static' rule to filter requests for image files.

2. balance #

Defines the load balancing algorithm. Available since version 1.0.

Structure #

The syntax is: balance <algorithm>. It usually goes in a backend section.

roundrobin #

The default algorithm, for an even distribution.

balance roundrobin

Each new client is sent to the next server in the list, in a circular way.

leastconn #

Optimized for long-running processing.

balance leastconn

HAProxy picks the server with the fewest open sessions at the time of the request.

3. bind #

Defines the frontend's listening addresses and ports. Available since version 1.0.

Structure #

The syntax is: bind [<address>]:<port_range> [options].

Interface and port #

Specifies the network entry point.

bind *:80

HAProxy accepts connections on all available network interfaces on port 80.

SSL/TLS #

Enables encryption on the entry point.

bind *:443 ssl crt /etc/ssl/certs/site.pem

Listens on port 443 using the specified PEM certificate file for SSL termination.

4. http-check #

Advanced configuration of application health checks. Available since version 2.2.

Structure #

Used together with option httpchk to customize the health check.

send #

Defines the request to send to the server.

http-check send meth GET uri /health

HAProxy sends an HTTP GET request to /health to test the application's health.

expect #

Checks the server's response.

http-check expect status 200

The server is only considered 'UP' if it responds with a 200 status code.

5. http-request #

Manipulates or filters incoming HTTP requests. Available since version 1.5.

Structure #

The syntax is: http-request <action> [if/unless <condition>].

deny #

Blocks access based on a condition.

http-request deny if { src 192.168.1.50 }

Immediately rejects the request if the source IP is 192.168.1.50.

set-header #

Adds or modifies HTTP headers.

http-request set-header X-Proxy-By HAProxy

Inserts the 'X-Proxy-By' header into the request forwarded to the backend server.

6. mode #

Defines the instance's operating protocol. Available since version 1.0.

Structure #

The syntax is simple: mode <http|tcp>.

http #

Layer 7 analysis.

mode http

Lets HAProxy understand and modify the content of HTTP packets.

tcp #

Layer 4 analysis.

mode tcp

HAProxy acts as a binary stream relay without reading the application protocol content.

7. server #

Declares a backend server and its health options. Available since version 1.0.

Structure #

The syntax is: server <name> <address>[:port] [options].

Name and address #

Basic server declaration.

server web1 10.0.0.1:80

Defines a server named 'web1' located at IP address 10.0.0.1 on port 80.

check #

Enabling monitoring.

server web1 10.0.0.1:80 check

The 'check' keyword enables regular health checks to make sure the server is operational.

8. stats #

Configures the monitoring interface. Available since version 1.1.

Structure #

Used with several options to define the behavior of the report page.

enable / uri #

Enabling and access point.

stats enable
stats uri /haproxy?stats

Enables the statistics page and makes it accessible at the specified URI.

auth #

Password protection.

stats auth admin:rousseltm

Restricts access to the statistics to the user 'admin' with the password 'rousseltm'.

9. timeout #

Manages connection timeouts. Available since version 1.2.

Structure #

The syntax is: timeout <type> <duration>. Durations can be in ms, s, m, h.

connect #

timeout connect 5s

Defines the maximum time HAProxy waits to establish a TCP connection with the backend server.

client #

timeout client 30s

Defines the maximum inactivity time allowed on the client side once the connection is established.

server #

timeout server 30s

Defines the maximum time to wait for the backend server to process the request and start responding.

10. use_backend #

Dynamically routes to a server group. Available since version 1.1.

Structure #

Defines the backend choice. Syntax: use_backend <name> [if/unless <condition>].

if #

Routing based on an ACL.

use_backend api_cluster if is_api

Sends the request to the 'api_cluster' server pool if the 'is_api' ACL matches.

11. server-template #

Dynamically generates backend servers without declaring them one by one. Widely used with Docker, DNS and Kubernetes.

Structure #

The syntax is: server-template <base-name> <start-end> <dns-template> [options].

base-name: base name used to generate the servers (e.g. web → web1, web2, web3).

start-end: number of items to select. If it is an integer, it is the number of instances wanted, in the order of the resolution results. If it is a numeric range, it is the wanted range (e.g. 2-5 → 4 servers, from the 2nd to the 5th).

dns-template: DNS name or template resolved dynamically by HAProxy (e.g. web.service.local or backend.internal).

options: additional parameters such as check, resolvers, resolve-prefer to manage health and DNS resolution.

Docker / DNS example #

server-template web 1-5 web.service.local:80 check resolvers docker

Lets HAProxy automatically create servers web1 to web5, deriving their names/IPs through DNS resolution.

12. option #

Enables global or specific behaviors in a frontend or backend.

Structure #

The option directive enables additional features in HAProxy.

Common examples #

option forwardfor
option httpchk
option redispatch
option httplog
option dontlognull

forwardfor #

Automatically adds the client IP in X-Forwarded-For.

httpchk #

Enables HTTP health checks on backend servers.

11. Other directives #

Global and behavioral settings. Available since version 1.0.

Structure #

A set of system configuration settings and default behaviors.

log #

log global

Tells HAProxy to use the logging configuration defined in the 'global' section.

maxconn #

maxconn 4096

Limits the total number of simultaneous connections to avoid saturating system resources.

user / group #

user haproxy
group haproxy

Defines the system privileges under which the HAProxy process runs once started.

option forwardfor #

option forwardfor

Adds the 'X-Forwarded-For' HTTP header containing the client's real IP before forwarding the request to the server.

retries #

retries 3

Defines the number of reconnection attempts to the backend server when a TCP connection fails.