HAProxy : Guide détaillé des directives de configuration

Publié le : 13/12/2024 à 10:00 Mis à jour le : 19/06/2026 à 18:43 Vues : 539

1. acl

Listes de contrôle d'accès pour les tests logiques. Disponible depuis la version 1.1.

Structure

La syntaxe générale est : acl <nom> <critère> <valeurs>. Le nom permet de réutiliser le test plus tard.

is_api

Utilise path_beg pour tester le début du chemin de l'URL.

acl is_api path_beg /api

Cette ligne crée une règle nommée 'is_api' qui est validée si l'URL commence par /api.

is_static

Utilise path_end pour identifier les fichiers par leurs extensions.

acl is_static path_end .jpg .png

Cette commande définit la règle 'is_static' pour filtrer les requêtes vers des fichiers d'images.

2. balance

Définit l'algorithme de répartition de charge. Disponible depuis la version 1.0.

Structure

La syntaxe est : balance <algorithme>. Elle se place généralement dans une section backend.

roundrobin

L'algorithme par défaut pour une distribution égale.

balance roundrobin

Chaque nouveau client est envoyé au serveur suivant dans la liste de manière circulaire.

leastconn

Optimisé pour les traitements longs.

balance leastconn

HAProxy choisit le serveur ayant le plus petit nombre de sessions ouvertes au moment de la requête.

3. bind

Définit les adresses et ports d'écoute du frontend. Disponible depuis la version 1.0.

Structure

La syntaxe est : bind [<adresse>]:<port_range> [options].

Interface et Port

Spécifie le point d'entrée réseau.

bind *:80

HAProxy acceptera les connexions sur toutes les interfaces réseau disponibles sur le port 80.

SSL/TLS

Active le chiffrement sur le point d'entrée.

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

Écoute sur le port 443 en utilisant le fichier certificat PEM spécifié pour la terminaison SSL.

4. http-check

Configuration avancée des Health Checks applicatifs. Disponible depuis la version 2.2.

Structure

Utilisé en complément de option httpchk pour personnaliser le test de santé.

send

Définit la requête à envoyer au serveur.

http-check send meth GET uri /health

HAProxy enverra une requête HTTP GET sur /health pour tester la vitalité de l'application.

expect

Vérifie la réponse du serveur.

http-check expect status 200

Le serveur n'est considéré comme 'UP' que s'il répond avec un code d'état 200.

5. http-request

Manipule ou filtre les requêtes HTTP entrantes. Disponible depuis la version 1.5.

Structure

La syntaxe est : http-request <action> [if/unless <condition>].

deny

Bloque l'accès selon une condition.

http-request deny if { src 192.168.1.50 }

Rejette immédiatement la requête si l'IP source est 192.168.1.50.

set-header

Ajoute ou modifie des entêtes HTTP.

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

Insère l'entête 'X-Proxy-By' dans la requête transmise au serveur backend.

6. mode

Définit le protocole de fonctionnement de l'instance. Disponible depuis la version 1.0.

Structure

La syntaxe est simple : mode <http|tcp>.

http

Analyse de la couche 7.

mode http

Permet à HAProxy de comprendre et modifier le contenu des paquets HTTP.

tcp

Analyse de la couche 4.

mode tcp

HAProxy agit comme un relais de flux binaire sans lire le contenu protocolaire applicatif.

7. server

Déclare un serveur backend et ses options de santé. Disponible depuis la version 1.0.

Structure

La syntaxe est : server <nom> <adresse>[:port] [options].

Nom et Adresse

Déclaration de base d'un serveur.

server web1 10.0.0.1:80

Définit un serveur nommé 'web1' localisé à l'adresse IP 10.0.0.1 sur le port 80.

check

Activation du monitoring.

server web1 10.0.0.1:80 check

Le mot-clé 'check' active les tests de santé réguliers pour s'assurer que le serveur est opérationnel.

8. stats

Configure l'interface de monitoring. Disponible depuis la version 1.1.

Structure

S'utilise avec plusieurs options pour définir le comportement de la page de rapport.

enable / uri

Activation et point d'accès.

stats enable
stats uri /haproxy?stats

Active la page de statistiques et la rend accessible via l'URI spécifiée.

auth

Sécurisation par mot de passe.

stats auth admin:rousseltm

Restreint l'accès aux statistiques à l'utilisateur 'admin' avec le mot de passe 'rousseltm'.

9. timeout

Gère les délais d'expiration des connexions. Disponible depuis la version 1.2.

Structure

La syntaxe est : timeout <type> <durée>. Les durées peuvent être en ms, s, m, h.

connect

timeout connect 5s

Définit le temps maximum d'attente pour que HAProxy établisse une connexion TCP avec le serveur backend.

client

timeout client 30s

Définit le temps maximum d'inactivité autorisé côté client une fois la connexion établie.

server

timeout server 30s

Définit le temps maximum d'attente pour que le serveur backend traite la requête et commence à répondre.

10. use_backend

Route dynamiquement vers un groupe de serveurs. Disponible depuis la version 1.1.

Structure

Définit le choix du backend. Syntaxe : use_backend <nom> [if/unless <condition>].

if

Routage basé sur une ACL.

use_backend api_cluster if is_api

Envoie la requête au pool de serveurs 'api_cluster' si l'ACL 'is_api' est vérifiée.

11. server-template

Permet de générer dynamiquement des serveurs backend sans les déclarer un par un. Très utilisé avec Docker, DNS et Kubernetes.

Structure

La syntaxe est : server-template <base-name> <start-end> <dns-template> [options].

base-name : nom de base utilisé pour générer les serveurs (ex : web → web1, web2, web3).

start-end : nombre d'éléments à sélectionner. Si c'est un entier, correspond au nombre d'instances souhaitées dans l'ordre des résultats de la résolution. Si plage numérique, correspond à la plage souhaitée (ex : 2-5 → 4 serveurs mais du 2e au 5e).

dns-template : nom DNS ou template résolu dynamiquement par HAProxy (ex : web.service.local ou backend.internal).

options : paramètres additionnels comme check, resolvers, resolve-prefer pour gérer santé et résolution DNS.

Exemple Docker / DNS

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

Permet à HAProxy de créer automatiquement les serveurs web1 à web5 et en déduisant leurs noms/IP via résolution DNS.

12. option

Active des comportements globaux ou spécifiques dans frontend ou backend.

Structure

La directive option active des fonctionnalités additionnelles dans HAProxy.

Exemples courants

option forwardfor
option httpchk
option redispatch
option httplog
option dontlognull

forwardfor

Ajoute automatiquement l'IP client dans X-Forwarded-For.

httpchk

Active les health checks HTTP sur les serveurs backend.

11. Autres directives

Paramètres globaux et comportementaux. Disponibles depuis la version 1.0.

Structure

Ensemble de paramètres de configuration système et de comportements par défaut.

log

log global

Indique à HAProxy d'utiliser la configuration de journalisation définie dans la section 'global'.

maxconn

maxconn 4096

Limite le nombre total de connexions simultanées pour éviter la saturation des ressources système.

user / group

user haproxy
group haproxy

Définit les privilèges système sous lesquels le processus HAProxy doit s'exécuter une fois démarré.

option forwardfor

option forwardfor

Ajoute l'entête HTTP 'X-Forwarded-For' contenant l'IP réelle du client avant de transmettre la requête au serveur.

retries

retries 3

Définit le nombre de tentatives de reconnexion au serveur backend en cas d'échec de connexion TCP.