HAProxy 3.4.4 Documentation

• 1: Fundamentaux de la répartition de charge
• 2: Qu'est-ce qu'HAProxy et comment il fonctionne
• 3: Fonctionnalités de base
• 4: Fonctionnalités standard
• 5: Fonctionnalités avancées
• 6: Taille et performance
• 7: Versions, Paquets et Mises à jour
• 8: Produits complémentaires et alternatives
• 9: Documentation et communauté
• 10: 1. Petit rappel sur HTTP
• 11: 2. Configuration de HAProxy
• 12: 3. Section globale
• 13: 4. Proxies
• 14: 5. Options de liaison et de serveur
• 15: 6. Mise en cache
• 16: 7. Listes de contrôle d'accès et extraction d'échantillon
• 17: 8. Journalisation
• 18: 9. Filtres pris en charge
• 19: 10. Applications FastCGI
• 20: 11. Tables de persistance et pairs
• 21: 12. Autres sections
• 22: 1. Prérequis
• 23: 2. HAProxy Architecture
• 24: 3. Démarrage de HAProxy
• 25: 4. Arrêt et redémarrage de HAProxy
• 26: 5. Limites des descripteurs de fichiers
• 27: 6. Gestion de la mémoire
• 28: 7. Utilisation du CPU
• 29: 8. Journalisation
• 30: 9. Statistiques et surveillance
• 31: 10. Gestion de configuration simplifiée
• 32: 11. Pièges courants à éviter
• 33: 12. Problèmes de débogage et de performance
• 34: 13. Considérations de sécurité

1 - Fundamentaux de la répartition de charge

Ce document présente HAProxy à l’intention de tous ceux qui ne le connaissent pas, ainsi que de ceux qui souhaitent le redécouvrir après avoir utilisé des versions antérieures. Son objectif principal est de fournir à l’utilisateur toutes les informations nécessaires pour décider si HAProxy correspond ou non à ses besoins. Les utilisateurs avancés pourront y trouver certaines solutions à des idées qu’ils avaient eues, simplement parce qu’ils ignoraient une fonctionnalité récente. Des indications de dimensionnement sont également fournies, le cycle de vie du produit est expliqué, ainsi que des comparaisons avec des produits partiellement similaires.

Ce document ne fournit aucune aide ou indication de configuration, mais explique où trouver les documents pertinents. Le guide est présenté sous la forme d’une séquence plane de pages thématiques dans la barre latérale HAProxy.

La répartition de charge consiste à regrouper plusieurs composants afin d’obtenir une capacité de traitement totale supérieure à celle de chaque composant individuellement, sans intervention de l’utilisateur final et de manière évolutif. Cela permet d’exécuter simultanément un plus grand nombre d’opérations pendant le temps nécessaire à un composant pour exécuter une seule opération. Une opération unique reste toutefois traitée par un seul composant à la fois et n’est pas plus rapide qu’en l’absence de répartition de charge. Elle nécessite toujours au moins autant d’opérations que de composants disponibles, ainsi qu’un mécanisme de répartition de charge efficace pour tirer parti de tous les composants et bénéficier pleinement de la répartition de charge. Un bon exemple en est le nombre de voies sur une autoroute, qui permet à autant de véhicules de passer pendant le même intervalle de temps sans augmenter leur vitesse individuelle.

Exemples de répartition de charge :

• Planification des processus dans les systèmes à plusieurs processeurs
• Répartition de charge sur les liens (par exemple, EtherChannel, Bonding)
• Répartition de charge par adresse IP (par exemple, ECMP, round-robin DNS)
• Répartition de charge sur les serveurs (via des répartiteurs de charge)

Le mécanisme ou composant qui effectue l’opération de répartition de charge est appelé un répartiteur de charge. Dans les environnements web, ces composants sont désignés comme un « répartiteur de charge réseau », et plus couramment un « répartiteur de charge », étant donné que cette activité constitue de loin le cas le plus connu de répartition de charge.

Un répartiteur de charge peut agir :

• au niveau du lien : il s’agit de la répartition de charge au niveau du lien, qui consiste à choisir le lien réseau par lequel envoyer un paquet ;

• au niveau du réseau : cela s’appelle la répartition de charge réseau, et consiste à choisir le chemin suivi par une série de paquets ;

• au niveau du serveur : il s’agit de la répartition de charge au niveau du serveur, qui consiste à déterminer quel serveur traitera une connexion ou une requête.

Deux technologies distinctes existent et répondent à des besoins différents, bien qu’elles se chevauchent parfois. Dans chaque cas, il est essentiel de garder à l’esprit que la répartition de charge consiste à détourner le trafic de son flux naturel, et qu’un minimum de précaution est toujours nécessaire pour maintenir le niveau requis de cohérence entre toutes les décisions de routage.

La première agit au niveau des paquets et les traite plus ou moins individuellement. La relation entre paquets d’entrée et de sortie est de 1 à 1 ; un analyseur réseau classique peut donc suivre le trafic de part et d’autre du répartiteur. Cette technologie peut être très peu coûteuse et extrêmement rapide. Elle est généralement implémentée dans le matériel (ASIC), ce qui permet d’atteindre le débit de ligne, par exemple avec des commutateurs ECMP. Habituellement sans état, elle peut aussi conserver un état en tenant compte de la session du paquet ; on parle alors de layer4-LB ou L4. Elle peut prendre en charge le DSR (retour direct du serveur sans repasser par le répartiteur) lorsque les paquets ne sont pas modifiés, mais n’offre presque aucune connaissance du contenu. Cette technologie convient particulièrement à la répartition de charge réseau, bien qu’elle serve parfois à une répartition serveur très simple à haut débit.

Le deuxième agit sur le contenu des sessions. Il nécessite que les flux d’entrée soient reconstitués et traités dans leur intégralité. Le contenu peut être modifié, et le flux de sortie est segmenté en nouveaux paquets. C’est pourquoi cette opération est généralement réalisée par des proxies, qui sont souvent appelés répartiteurs de charge au niveau 7 ou L7. Cela implique qu’il existe deux connexions distinctes de chaque côté, et qu’aucune relation n’existe entre les tailles ou les nombres de paquets d’entrée et de sortie. Les clients et les serveurs ne sont pas tenus d’utiliser le même protocole (par exemple IPv4 contre IPv6, clair contre SSL). Les opérations sont toujours étatiques, et le trafic de retour doit passer par le répartiteur de charge. Ce traitement supplémentaire comporte un coût, si bien qu’il n’est pas toujours possible d’atteindre un débit en ligne, notamment avec des paquets de petite taille. En revanche, il offre de nombreuses possibilités et est généralement réalisé par logiciel pur, même lorsqu’il est intégré à des appareils matériels. Cette technologie convient particulièrement bien à la répartition de charge des serveurs.

Les répartiteurs de charge basés sur les paquets sont généralement déployés en mode cut-through, ce qui signifie qu’ils sont installés sur le chemin normal du trafic et le redirigent selon la configuration. Le trafic de retour n’est pas nécessairement acheminé via le répartiteur de charge. Des modifications peuvent être apportées à l’adresse réseau de destination afin de diriger le trafic vers la destination appropriée. Dans ce cas, il est obligatoire que le trafic de retour passe par le répartiteur de charge. Si les routes ne permettent pas cette configuration, le répartiteur de charge peut également remplacer l’adresse source des paquets par la sienne afin de forcer le trafic de retour à passer par lui.

Les répartiteurs de charge basés sur un proxy sont déployés comme un serveur disposant de leurs propres adresses IP et ports, sans nécessiter de modification de l’architecture. Parfois, cela exige d’apporter certaines adaptations aux applications afin que les clients soient correctement redirigés vers l’adresse IP du répartiteur de charge et non directement vers celle du serveur. Certains répartiteurs de charge peuvent devoir ajuster certaines réponses des serveurs pour permettre cette redirection (par exemple, le champ d’en-tête HTTP Location utilisé dans les redirections HTTP). Certains répartiteurs de charge basés sur un proxy peuvent intercepter le trafic destiné à une adresse qu’ils ne possèdent pas, et masquer l’adresse du client lors de la connexion au serveur. Cela leur permet d’être déployés comme un routeur ou un pare-feu classique, en mode pass-through très similaire à celui des répartiteurs de charge basés sur les paquets. Cette caractéristique est particulièrement appréciée pour les produits qui combinent à la fois le mode paquet et le mode proxy. Dans ce cas, le DSR reste évidemment impossible, et le trafic de retour doit toujours être acheminé de retour vers le répartiteur de charge.

Une approche à plusieurs niveaux très évolutive consisterait à mettre en place un routeur frontal qui reçoit le trafic provenant de plusieurs liens répartis en charge, et qui utilise ECMP pour distribuer ce trafic à une première couche de plusieurs répartiteurs de charge basés sur les paquets et état ( L4 ). Ces répartiteurs de charge L4 transmettent ensuite le trafic à un nombre encore plus important de répartiteurs basés sur des proxies ( L7 ), qui doivent analyser le contenu pour déterminer quel serveur recevra finalement le trafic.

Le nombre de composants et de chemins possibles pour le trafic augmente le risque de défaillance ; dans des environnements très volumineux, il est même normal de voir en permanence quelques composants défaillants en cours de réparation ou de remplacement. La répartition de charge effectuée sans prise de conscience de l’état global de la pile dégrade significativement la disponibilité. Pour cette raison, tout répartiteur de charge raisonnable vérifiera que les composants auxquels il entend acheminer le trafic sont toujours actifs et accessibles, et il cesse de distribuer du trafic aux composants défaillants. Cela peut être réalisé à l’aide de diverses méthodes.

Le cas le plus courant consiste à envoyer périodiquement des sondes afin de vérifier que le composant reste opérationnel. Ces sondes sont appelées « contrôles d’état ». Elles doivent être représentatives du type de panne à détecter. Par exemple, un contrôle basé sur ping ne détectera pas qu’un serveur web a cessé de fonctionner et ne répond plus sur un port, tandis qu’une connexion au port permet de vérifier cela, et une requête plus avancée peut même valider que le serveur fonctionne toujours et que la base de données dont il dépend reste accessible. Les contrôles d’état comportent souvent quelques tentatives afin de compenser les erreurs de mesure occasionnelles. L’intervalle entre les contrôles doit être suffisamment court pour garantir que le composant défaillant n’est pas utilisé trop longtemps après la survenue d’une erreur.

D’autres méthodes échantillonnent le trafic de production envoyé à une destination pour vérifier son traitement et écarter les composants qui renvoient des réponses inappropriées. Cela sacrifie toutefois une partie du trafic de production, ce qui n’est pas toujours acceptable. Combiner ces deux mécanismes offre le meilleur de chaque approche : ils servent ensemble à détecter une panne, tandis que les contrôles d’état seuls en détectent la fin. Une dernière méthode repose sur un rapport centralisé : un agent de supervision met périodiquement à jour tous les répartiteurs avec l’état des composants. Chacun dispose ainsi d’une vue globale de l’infrastructure, parfois moins précise ou moins réactive. Cette approche convient surtout aux environnements comportant de nombreux répartiteurs et serveurs.

Les répartiteurs de charge au niveau 7 font également face à un autre défi connu sous le nom de persistance ou « sticky session ». Le principe consiste à orienter généralement plusieurs requêtes ou connexions successives provenant d’une même origine (par exemple, un utilisateur final) vers la même cible. L’exemple le plus connu est le panier d’achat sur un site marchand en ligne. Si chaque clic entraîne une nouvelle connexion, l’utilisateur doit toujours être acheminé vers le serveur qui détient son panier. La prise en compte du contenu facilite la détection d’éléments dans la requête afin d’identifier le serveur à qui la requête doit être acheminée, mais cela ne suffit pas toujours. Par exemple, si l’adresse source est utilisée comme clé pour sélectionner un serveur, on peut décider d’utiliser un algorithme basé sur un hachage, selon lequel une adresse IP donnée sera toujours acheminée vers le même serveur, en fonction d’une division de l’adresse par le nombre de serveurs disponibles. Mais si un serveur tombe en panne, le résultat change et tous les utilisateurs sont soudainement redirigés vers un autre serveur, ce qui fait perdre leur panier. La solution à ce problème consiste à mémoriser la cible choisie, de sorte que chaque fois qu’un même visiteur est détecté, il soit dirigé vers le même serveur, indépendamment du nombre de serveurs disponibles. Cette information peut être stockée en mémoire du répartiteur de charge, auquel cas elle doit éventuellement être répliquée sur d’autres répartiteurs de charge s’il n’est pas seul, ou stockée en mémoire du client à l’aide de diverses méthodes, à condition que le client soit capable de présenter cette information à chaque requête (insertion de cookie, redirection vers un sous-domaine, etc.). Ce mécanisme présente l’avantage supplémentaire de ne pas dépendre d’informations instables ou inégalement réparties (comme l’adresse IP source). C’est en réalité la raison la plus forte d’adopter un répartiteur de charge au niveau 7 plutôt qu’au niveau 4.

Afin d’extraire des informations telles qu’un cookie, un champ d’en-tête d’hôte, une URL ou tout autre élément, un répartiteur de charge peut devoir déchiffrer le trafic SSL/TLS, voire le réchiffrer lorsqu’il le transmet au serveur. Cette opération coûteuse explique pourquoi, dans certaines infrastructures à fort trafic, il peut y avoir un grand nombre de répartiteurs de charge.

Puisqu’un répartiteur de charge au niveau 7 peut effectuer un certain nombre d’opérations complexes sur le trafic (décrypter, analyser, modifier, comparer les cookies, décider quel serveur contacter, etc.), il peut effectivement causer des problèmes et est très fréquemment accusé à tort d’être à l’origine de nombreux dysfonctionnements qu’il n’a fait que révéler. Il arrive souvent que l’on découvre que les serveurs sont instables et passent périodiquement de l’état actif à l’état inactif, ou que, pour les serveurs web, ils renvoient des pages contenant des liens codés en dur qui obligent les clients à se connecter directement à un serveur spécifique sans passer par le répartiteur de charge, ou encore qu’ils mettent une éternité à répondre sous forte charge, provoquant des délais d’expiration. C’est pourquoi la journalisation constitue un aspect extrêmement important de la répartition de charge au niveau 7. Dès qu’un problème est signalé, il est essentiel de déterminer si le répartiteur de charge a pris une décision erronée et, le cas échéant, pourquoi, afin qu’il ne se reproduise plus.

2 - Qu'est-ce qu'HAProxy et comment il fonctionne

La graphie « HAProxy » désigne le produit, tandis que « haproxy » désigne le programme exécutable, le paquet logiciel ou un processus. Ces graphies sont toutefois couramment utilisées dans chaque contexte et se prononcent H-A-Proxy. À l’origine, « haproxy » signifiait « high availability proxy » et le nom s’écrivait en deux mots distincts ; aujourd’hui, il ne signifie plus rien d’autre que « HAProxy ».

3.1. Ce qu’est et ce qu’il n’est pas HAProxy

HAProxy est :

• un proxy TCP : il peut accepter une connexion TCP sur un socket d’écoute, se connecter à un serveur et associer ces sockets afin que le trafic circule dans chaque direction. Les sockets IPv4, IPv6 et même UNIX sont pris en charge de part et d’autre, ce qui permet de traduire facilement les adresses entre différentes familles.

• un proxy inverse HTTP (appelé « passerelle » en terminologie HTTP) : il se présente comme un serveur, reçoit les requêtes HTTP sur des connexions établies via une socket TCP d’écoute, puis transmet les requêtes provenant de ces connexions vers des serveurs en utilisant des connexions distinctes. Il peut utiliser n’importe quelle combinaison de HTTP/1.x ou HTTP/2 sur chaque côté et détecte même automatiquement le protocole utilisé sur chaque côté lorsque ALPN est utilisé sur TLS.

• un terminateur, initiateur ou déchargeur SSL : SSL/TLS peut être utilisé sur la connexion provenant du client, sur celle allant vers le serveur, ou simultanément sur ces connexions. De nombreux paramètres peuvent être appliqués par nom (SNI) et mis à jour à l’exécution sans redémarrage. Ces configurations passent extrêmement bien à l’échelle ; des déploiements comportant des dizaines ou des centaines de milliers de certificats ont été signalés.

• un normalisateur TCP : puisque le système d’exploitation termine les connexions localement, il n’existe aucune relation entre les extrémités. Le trafic anormal, tel que des paquets invalides, des combinaisons de drapeaux, des annonces de fenêtre, des numéros de séquence ou des connexions incomplètes (SYN flood), n’est donc pas transmis à l’autre extrémité. Cela protège les piles TCP fragiles contre les attaques de protocole et permet d’optimiser les paramètres de connexion côté client sans modifier ceux de la pile TCP des serveurs.

• un normalisateur HTTP : lorsqu’il est configuré pour traiter le trafic HTTP, seules les requêtes complètes et valides sont transmises. Cela protège contre de nombreux attaques basées sur le protocole. En outre, les écarts au protocole pour lesquels une tolérance est prévue dans la spécification sont corrigés afin qu’ils n’entraînent pas de problème sur les serveurs (par exemple, les en-têtes sur plusieurs lignes).

• outil de correction HTTP : il peut modifier, corriger, ajouter, supprimer ou réécrire l’URL ou n’importe quel en-tête de requête ou de réponse. Cela permet de résoudre les problèmes d’interopérabilité dans des environnements complexes.

• un commutateur basé sur le contenu : il peut prendre en compte n’importe quel élément de la requête pour déterminer le serveur vers lequel acheminer la requête ou la connexion. Il devient ainsi possible de gérer plusieurs protocoles sur un même port (par exemple, HTTP, HTTPS, SSH).

• un répartiteur de charge : il peut répartir les connexions TCP et les requêtes HTTP. En mode TCP, les décisions de répartition sont prises pour toute la connexion. En mode HTTP, les décisions sont prises par requête.

• un régulateur de trafic : il peut appliquer une limitation de débit à divers emplacements, protéger les serveurs contre la surcharge, ajuster les priorités du trafic en fonction du contenu, et transmettre même ces informations aux couches inférieures et aux composants du réseau externe en marquant les paquets.

• une protection contre les attaques DDoS et l’abus de service : elle peut conserver un grand nombre de statistiques par adresse IP, URL, cookie, etc., détecter lorsqu’un abus a lieu, puis prendre des mesures (ralentir les auteurs d’abus, les bloquer, les rediriger vers des contenus obsolètes, etc.).

• un point d’observation pour le dépannage réseau : en raison de la précision des informations rapportées dans les journaux, il est souvent utilisé pour restreindre le champ des problèmes liés au réseau.

• un déchargeur de compression HTTP : il peut compresser les réponses qui n’ont pas été compressées par le serveur, réduisant ainsi le temps de chargement des pages pour les clients ayant une connectivité médiocre ou utilisant des réseaux mobiles à forte latence.

• un proxy de mise en mémoire tampon : il peut mettre en mémoire tampon des réponses en RAM afin que les requêtes ultérieures pour le même objet évitent le coût d’une nouvelle transmission réseau depuis le serveur, tant que l’objet reste présent et valide. Il ne stockera toutefois pas les objets dans un stockage persistant. Veuillez noter que cette fonction de mise en mémoire tampon est conçue pour être entièrement autonome et se concentre exclusivement sur la conservation des ressources précieuses de HAProxy, et non sur la préservation des ressources du serveur. Les mécanismes de mise en mémoire tampon visant à optimiser les serveurs nécessitent bien plus de réglages et de flexibilité. Si vous avez besoin d’une telle mise en mémoire tampon avancée, veuillez utiliser Varnish Cache, qui s’intègre parfaitement à HAProxy, notamment lorsque le chiffrement SSL/TLS est requis sur l’une ou l’autre des extrémités.

• un passerelle FastCGI : FastCGI peut être considéré comme une représentation différente du protocole HTTP, et HAProxy peut donc équilibrer la charge directement sur une ferme composée de tout ensemble combiné de serveurs d’applications FastCGI, sans nécessiter de placer un niveau supplémentaire de passerelle entre eux. Cela permet de réaliser des économies de ressources et de réduire les coûts de maintenance.

HAProxy n’est pas :

• un proxy HTTP explicite, c’est-à-dire le proxy utilisé par les navigateurs pour accéder à Internet. Il existe de nombreux logiciels open source dédiés à cette tâche, tels que Squid. Toutefois, HAProxy peut être installé devant un tel proxy afin de fournir une répartition de charge et une haute disponibilité.

• un nettoyeur de données : il ne modifie ni le corps des requêtes ni celui des réponses.

• un serveur web statique : au démarrage, il s’isole dans une prison chroot et abandonne ses privilèges, de sorte qu’il ne réalise aucune opération d’accès au système de fichiers une fois lancé. En conséquence, il ne peut pas être utilisé comme serveur web statique (les serveurs dynamiques sont pris en charge via FastCGI toutefois). Il existe de nombreux logiciels open source excellents à cet effet, tels qu’Apache ou NGINX, et HAProxy peut facilement être installé devant eux pour assurer la répartition de charge, la haute disponibilité et l’accélération.

• un répartiteur de charge basé sur les paquets : il ne traite ni les paquets IP ni les datagrammes UDP, n’effectue pas de NAT, ni encore moins de DSR. Ces tâches relèvent des couches inférieures. Certains composants basés noyau, comme IPVS (Linux Virtual Server), s’en occupent déjà très bien et s’associent parfaitement à HAProxy.

3.2. Comment fonctionne HAProxy

HAProxy est un moteur événementiel, non bloquant, combinant une couche I/O très rapide à un planificateur multithreadé basé sur la priorité. Conçu avec pour objectif principal le transfert de données, son architecture est optimisée pour acheminer les données aussi rapidement que possible, avec un nombre minimal d’opérations. Il se concentre sur l’optimisation de l’efficacité du cache CPU en maintenant les connexions sur le même processeur aussi longtemps que possible. En conséquence, il met en œuvre un modèle en couches offrant des mécanismes de bypass à chaque niveau, garantissant que les données n’atteignent pas les niveaux supérieurs sauf si nécessaire. La majeure partie du traitement est effectuée dans le noyau, et HAProxy fait tout son possible pour aider le noyau à accomplir son travail aussi rapidement que possible, en fournissant certains indices ou en évitant certaines opérations lorsqu’il estime qu’elles pourraient être regroupées ultérieurement. En conséquence, les chiffres typiques montrent que 15 % du temps de traitement sont consacrés à HAProxy contre 85 % dans le noyau en mode TCP ou HTTP fermé, et environ 30 % pour HAProxy contre 70 % pour le noyau en mode HTTP keep-alive.

Un seul processus peut exécuter de nombreux instances de proxy ; des configurations comprenant jusqu’à 300 000 proxies distincts dans un seul processus ont été signalées comme fonctionnant correctement. Une configuration à un seul cœur, un seul processeur est largement suffisante pour plus de 99 % des utilisateurs, et les utilisateurs de conteneurs et de machines virtuelles sont donc encouragés à utiliser les images les plus petites possibles afin de réduire les coûts opérationnels et de simplifier le dépannage. Toutefois, la machine sur laquelle HAProxy s’exécute ne doit jamais échanger, et son CPU ne doit jamais être artificiellement limité (allocation sous-entière de CPU dans les hyperviseurs) ni partagé avec des processus intensifs en calcul, ce qui entraînerait une latence de basculement de contexte très élevée.

Le thread permet d’utiliser toute la capacité de traitement disponible en utilisant un thread par cœur processeur. Cela est principalement utile pour le chiffrement SSL ou lorsque des débits de transfert de données supérieurs à 40 Gbps sont requis. Dans ces cas, il est essentiel d’éviter les communications entre plusieurs processeurs physiques, qui peuvent entraîner des goulets d’étranglement importants dans la pile réseau et dans HAProxy lui-même. Bien que cela puisse sembler contre-intuitif pour certains, la première action à entreprendre lorsqu’on rencontre des problèmes de performance est souvent de réduire le nombre de cœurs sur lesquels HAProxy s’exécute.

HAProxy nécessite uniquement l’exécutable haproxy et un fichier de configuration pour s’exécuter. Pour la journalisation, il est fortement recommandé de disposer d’un démon syslog correctement configuré ainsi que de rotations de journaux en place. Les journaux peuvent également être envoyés vers stdout/stderr, ce qui peut être utile dans les conteneurs. Les fichiers de configuration sont analysés avant le démarrage, puis HAProxy tente de lier tous les sockets d’écoute, et refuse de démarrer en cas d’échec. À partir de ce point, il ne peut plus échouer. Cela signifie qu’il n’y a pas d’échec en temps d’exécution, et que s’il accepte de démarrer, il fonctionnera jusqu’à son arrêt.

Une fois HAProxy lancé, il effectue exactement 3 opérations :

• traite les connexions entrantes ;

• vérifier périodiquement l’état des serveurs (appelé contrôle d’état);

• échanger des informations avec d’autres nœuds HAProxy.

Le traitement des connexions entrantes est sans doute la tâche la plus complexe, car elle dépend de nombreuses possibilités de configuration, mais elle peut être résumée en 9 étapes ci-dessous :

• accepter les connexions entrantes provenant des sockets d’écoute appartenant à une entité de configuration connue sous le nom de « frontal », qui référence une ou plusieurs adresses d’écoute ;

• appliquer les règles spécifiques au frontal à ces connexions, ce qui peut entraîner leur blocage, la modification de certains en-têtes ou leur interception afin d’exécuter certains applets internes, tels que la page de statistiques ou l’interface CLI ;

• transmettre ces connexions entrantes à une autre entité de configuration représentant une ferme de serveurs appelée « backend », qui contient la liste des serveurs et la stratégie de répartition de charge pour cette ferme ;

• appliquer les règles spécifiques au backend à ces connexions ;

• détermine quel serveur doit recevoir la connexion selon la stratégie de répartition de charge ;

• appliquer les règles spécifiques au backend au traitement des données de la réponse ;

• appliquer les règles spécifiques au frontal au traitement des données de réponse ;

• émet un journal pour rapporter ce qui s’est passé en détail ;

• en HTTP, bouclez vers la deuxième étape pour attendre une nouvelle requête, sinon fermez la connexion.

Les frontaux et les backends sont parfois considérés comme des demi-proxies, car ils ne traitent qu’un seul côté d’une connexion bout-en-bout ; le frontal ne s’intéresse qu’aux clients, tandis que le backend ne s’intéresse qu’aux serveurs. HAProxy prend également en charge les proxies complets, qui sont exactement la union d’un frontal et d’un backend. Lorsqu’une traitement HTTP est requis, la configuration est généralement divisée en frontaux et backends, car cela ouvre de nombreuses possibilités, puisqu’un frontal quelconque peut transférer une connexion à un backend quelconque. Avec des proxies ne gérant que le protocole TCP, l’utilisation de frontaux et de backends apporte rarement d’avantage, et la configuration peut être plus lisible avec des proxies complets.

3 - Fonctionnalités de base

Cette section énumère un certain nombre de fonctionnalités implémentées par HAProxy, certaines étant généralement attendues d’un répartiteur de charge moderne, et d’autres constituant un avantage direct de l’architecture d’HAProxy. Les fonctionnalités avancées seront détaillées dans la section suivante.

3.3.1. Fonctionnalités de base : Proxys

Le proxy consiste à transférer des données entre un client et un serveur via deux connexions indépendantes. Les fonctionnalités de base suivantes sont prises en charge par HAProxy en matière de proxy et de gestion des connexions :

• Fournir au serveur une connexion propre afin de les protéger contre toute défaillance ou attaque côté client ;

• Écouter plusieurs adresses IP et/ou ports, y compris des plages de ports ;

• Acceptation transparente : intercepter le trafic ciblant une adresse IP arbitraire, même n’appartenant pas au système local ;

• Le port serveur n’a pas besoin d’être lié au port d’écoute, et peut même être décalé par un offset fixe (utile avec les plages) ;

• Connexion transparente : masquer l’adresse IP du client (ou toute autre adresse) si nécessaire lors de la connexion au serveur ;

• Fournir une adresse IP de retour fiable aux serveurs dans les équilibreurs de charge multi-sites ;

• Réduire la charge du serveur grâce à l’utilisation de tampons et éventuellement de connexions à durée de vie courte, afin de diminuer le nombre de connexions simultanées et la consommation mémoire ;

• Optimiser les piles TCP (par exemple SACK), le contrôle de congestion et réduire les impacts du RTT ;

• Prendre en charge différentes familles de protocoles de part et d’autre (par exemple IPv4, IPv6 ou Unix) ;

• Application du délai d’expiration : HAProxy prend en charge plusieurs niveaux de délais d’expiration selon l’étape de la connexion, afin qu’un client ou serveur défaillant, ou un attaquant, ne puisse pas monopoliser les ressources trop longtemps ;

• Validation du protocole : le HTTP, le SSL ou le chargement utile est inspecté et les éléments de protocole non valides sont rejetés, sauf instruction contraire pour les accepter malgré tout ;

• Application de la politique : garantir que seules les requêtes autorisées sont acheminées ;

• Les connexions entrantes et sortantes peuvent être limitées à certains espaces de noms réseau (Linux uniquement), ce qui facilite la mise en œuvre d’un répartiteur de charge multi-locataires et cross-conteneur ;

• Le protocole PROXY expose l’adresse IP du client au serveur, même pour le trafic non HTTP. Il s’agit d’une extension HAProxy adoptée par plusieurs produits tiers, au moins ceux-ci au moment de la rédaction :

  • client : HAProxy, stud, stunnel, exaproxy, ELB, squid
  • server : HAProxy, stud, postfix, exim, NGINX, squid, node.js, varnish

3.3.2. Fonctionnalités de base : SSL

La pile SSL d’HAProxy est reconnue comme l’une des plus riches en fonctionnalités selon les ingénieurs de Google (http://istlsfastyet.com/ ). Les fonctionnalités les plus couramment utilisées, qui en font une solution très complète, sont :

• Hébergement multi-hôtes basé sur SNI, sans limite sur le nombre de sites, avec un accent sur les performances. Au moins une déployment est connue pour gérer 50 000 domaines avec leurs certificats respectifs ;

• la prise en charge des certificats wildcard réduit la nécessité de nombreux certificats ;

• authentification client basée sur un certificat, avec des politiques configurables en cas de non-présentation d’un certificat valide. Cela permet de présenter une ferme serveur différente afin de régénérer le certificat client, par exemple ;

• L’authentification du backend garantit que le serveur backend est bien le véritable serveur et non un intermédiaire malveillant ;

• L’authentification avec le serveur backend permet au serveur backend de savoir qu’il s’agit réellement du nœud HAProxy attendu qui se connecte à celui-ci ;

• Les extensions TLS NPN et ALPN permettent de transférer de manière fiable les connexions SPDY/HTTP2 et de les transmettre en clair aux serveurs backend ;

• Le stapling OCSP réduit davantage le temps de chargement de la première page en livrant inline une réponse OCSP lorsque le client demande un statut de certificat ;

• La taille dynamique des enregistrements offre à la fois des performances élevées et une latence faible, et réduit fortement le temps de chargement des pages en permettant au navigateur de commencer à télécharger de nouveaux objets pendant que les paquets sont encore en transit ;

• accès permanent à toutes les informations pertinentes au niveau SSL/TLS pour la journalisation, le contrôle d’accès, le reporting, etc. Ces éléments peuvent être intégrés dans un en-tête HTTP ou même comme extension du protocole PROXY, afin que le serveur déchargé dispose de toutes les informations qu’il aurait eu s’il avait lui-même effectué la terminaison SSL.

• Détecter, journaliser et bloquer certains attaques connues, même sur des bibliothèques SSL vulnérables, telles que l’attaque Heartbleed affectant certaines versions d’OpenSSL.

• prise en charge de la reprise de session sans état (extension TLS Ticket RFC 5077). Les tickets TLS peuvent être mis à jour depuis la ligne de commande, ce qui permet d’implémenter une confidentialité parfaite en les renouvelant fréquemment.

3.3.3. Fonctionnalités de base : Surveillance

HAProxy accorde une grande importance à la disponibilité. En conséquence, il surveille l’état des serveurs et signale son propre état aux autres composants du réseau :

• L’état des serveurs est surveillé en continu à l’aide de paramètres propres à chaque serveur. Cela garantit que le chemin vers le serveur est opérationnel pour le trafic régulier ;

• Les contrôles d’état prennent en charge deux seuils d’hystérésis pour les transitions vers haut et bas, afin de protéger contre les fluctuations d’état ;

• Les vérifications peuvent être envoyées à une adresse, un port ou un protocole différents : cela facilite le contrôle d’un service unique considéré comme représentatif de plusieurs autres, par exemple le port HTTPS pour un serveur HTTP+HTTPS.

• Les serveurs peuvent suivre d’autres serveurs et tomber en même temps : cela garantit que les serveurs hébergeant plusieurs services échouent de manière atomique, et qu’aucun client ne sera dirigé vers un serveur partiellement défaillant ;

• Les agents peuvent être déployés sur le serveur pour surveiller la charge et l’état : un serveur peut être intéressé par le rapport de sa charge, de son état opérationnel et de son état administratif, indépendamment de ce que les contrôles d’état peuvent détecter. En exécutant un agent simple sur le serveur, il est possible de prendre en compte la vision du serveur concernant son propre état, en complément des contrôles d’état qui valident l’intégralité du chemin ;

• Plusieurs méthodes de vérification sont disponibles : connexion TCP, requête HTTP, message SMTP, message SSL, LDAP, SQL, Redis, scripts envoi/réception, avec ou sans SSL ;

• Le changement d’état est notifié dans les journaux et la page de statistiques avec la raison de la défaillance (par exemple, la réponse HTTP reçue au moment où la défaillance a été détectée). Un courrier électronique peut également être envoyé à une adresse configurable en cas de tel changement ;

• L’état du serveur est également rapporté sur l’interface de statistiques et peut être utilisé pour prendre des décisions de routage, afin d’envoyer le trafic vers des fermes différentes selon leurs tailles et/ou leur état de santé (par exemple, perte d’une liaison inter-DC) ;

• HAProxy peut utiliser les requêtes de contrôle d’état pour transmettre des informations aux serveurs, telles que leurs noms, leur poids, le nombre d’autres serveurs dans la ferme, etc., afin que les serveurs puissent ajuster leur réponse et leurs décisions en fonction de ces données (par exemple, différer les sauvegardes pour préserver plus de ressources CPU) ;

• Les serveurs peuvent utiliser des contrôles d’état pour signaler un état plus détaillé que simple actif/inactif (par exemple : je souhaite m’arrêter, veuillez cesser d’envoyer de nouveaux visiteurs) ;

• HAProxy peut rapporter son état à des composants externes, tels que des routeurs ou d’autres équilibreurs de charge, permettant ainsi de mettre en œuvre des infrastructures multi-chemins et multi-niveaux très complètes.

3.3.4. Fonctionnalités de base : Haute disponibilité

Tout comme tout répartiteur de charge sérieux, HAProxy accorde une grande importance à la disponibilité afin d’assurer la meilleure continuité de service globale :

• Seules les serveurs valides sont utilisés ; les autres sont automatiquement exclus des fermes de répartition de charge ; dans certaines conditions, il est toutefois possible de forcer leur utilisation ;

• Prise en charge d’un arrêt progressif afin de pouvoir retirer des serveurs d’une ferme sans affecter les connexions en cours ;

• Les serveurs de sauvegarde sont automatiquement utilisés lorsque les serveurs actifs sont hors ligne et les remplacent afin de préserver les sessions lorsque cela est possible. Cela permet également de créer plusieurs chemins pour atteindre le même serveur (par exemple, plusieurs interfaces) ;

• Capacité à renvoyer un statut global d’échec pour une ferme lorsque trop de serveurs sont hors ligne. Cela, combiné aux capacités de surveillance, permet à un composant amont de choisir un autre nœud de répartition de charge pour un service donné ;

• Un design sans état permet de faciliter la mise en cluster : par conception, HAProxy fait tout son possible pour garantir la continuité du service sans avoir à stocker d’informations pouvant être perdues en cas de panne. Cela assure une reprise opérationnelle aussi fluide que possible ;

• Intègre parfaitement le démon standard de basculement VRRP keepalived : HAProxy informe facilement keepalived de son état et gère très bien les adresses IP virtuelles flottantes. Remarque : n’utilisez les protocoles de redondance IP (VRRP/CARP) que sur des solutions basées sur un cluster (Heartbeat, …) car ce sont les seuls à offrir un basculement rapide, transparent et fiable.

3.3.5. Fonctionnalités de base : répartition de charge

HAProxy propose un ensemble assez complet de fonctionnalités de répartition de charge, dont la plupart ne sont malheureusement pas disponibles dans un certain nombre d’autres produits de répartition de charge :

• au moins 10 algorithmes de répartition de charge sont pris en charge, dont certains s’appliquent aux données d’entrée pour offrir une liste infinie de possibilités. Les plus courants sont : round-robin (pour les connexions courtes, sélectionne chaque serveur tour à tour), leastconn (pour les connexions longues, sélectionne le serveur ayant le moins de connexions actives et le moins récemment utilisé), source (pour les fermes SSL ou les fermes de serveurs terminaux, le serveur dépend directement de l’adresse source du client), URI (pour les caches HTTP, le serveur dépend directement de l’URI HTTP), hdr (le serveur dépend directement du contenu d’un champ d’en-tête HTTP spécifique), first (pour les machines virtuelles à durée de vie courte, toutes les connexions sont regroupées sur le sous-ensemble le plus petit possible de serveurs afin que les serveurs inutilisés puissent être mis hors tension).

• tous les algorithmes ci-dessus prennent en charge les pondérations par serveur, ce qui permet d’intégrer des générations de serveurs différentes dans une ferme, ou de diriger une petite fraction du trafic vers des serveurs spécifiques (mode de débogage, exécution de la prochaine version du logiciel, etc.) ;

• les poids dynamiques sont pris en charge pour les algorithmes round-robin, leastconn et hachage cohérent ; cela permet de modifier les poids des serveurs en temps réel depuis la ligne de commande ou même par un agent en cours d’exécution sur le serveur ;

• le démarrage progressif est pris en charge chaque fois qu’une pondération dynamique est prise en charge ; cela permet à un serveur de prendre progressivement le trafic. Cette fonctionnalité est essentielle pour les serveurs d’applications fragiles qui doivent compiler des classes en cours d’exécution, ainsi que pour les caches froids qui doivent être remplis avant de fonctionner à plein régime ;

• Le hachage peut s’appliquer à divers éléments tels qu’une adresse source cliente, des composants d’URL, un élément de chaîne de requête, des valeurs de champ d’en-tête, un paramètre POST ou un cookie RDP ;

• le hachage cohérent protège les fermes de serveurs contre une redistribution massive lors de l’ajout ou de la suppression de serveurs dans une ferme. Cela est particulièrement important dans les grandes fermes de mise en mémoire tampon et permet d’utiliser le démarrage progressif pour remplir les mémoires tampon froides ;

• un certain nombre de métriques internes, telles que le nombre de connexions par serveur, par backend, ou le nombre de slots de connexion disponibles dans un backend, permet de mettre en œuvre des stratégies de répartition de charge très avancées.

3.3.6. Fonctionnalités de base : Persistance

La répartition de charge applicative serait inutile sans la persistance de session. HAProxy propose un ensemble assez complet de possibilités pour maintenir un visiteur sur le même serveur, même en cas d’événements variés tels que l’ajout ou la suppression de serveurs, les cycles de mise hors ligne/mise en ligne, et certaines méthodes sont conçues pour résister à la distance entre plusieurs nœuds de répartition de charge, car elles n’exigent aucune réplication :

• les informations de persistance peuvent être individuellement correspondantes et apprises à partir de différentes sources, si nécessaire. Par exemple, un cookie JSESSIONID peut être correspondant à la fois dans un cookie et dans l’URL. Jusqu’à 8 sources parallèles peuvent être apprises simultanément, chacune pouvant pointer vers une table de persistance différente ;

• Les informations de persistance peuvent provenir de tout élément visible dans une requête ou une réponse, y compris l’adresse source, le décalage et la longueur du chargement TCP, les éléments de chaîne de requête HTTP, les valeurs de champs d’en-tête, les cookies, etc.

• les tables de persistance sont répliquées entre tous les nœuds de manière multi-maître ;

• éléments couramment utilisés, tels que l’ID SSL ou les cookies RDP (pour les fermes TSE), sont directement accessibles pour faciliter leur manipulation ;

• toutes les règles de maintien peuvent être conditionnées dynamiquement par des listes de contrôle d’accès ;

• il est possible de décider de ne pas rester attaché à certains serveurs, tels que des serveurs de sauvegarde, afin que, lorsque le serveur nominal revient en ligne, il reprend automatiquement la charge. Cela est souvent utilisé dans les environnements multi-chemins ;

• en HTTP, il est souvent préférable de ne rien apprendre et de manipuler à la place un cookie dédié à la persistance. Pour cela, il est possible de détecter, modifier, insérer ou préfixer un tel cookie afin que le client mémorise quel serveur lui a été attribué ;

• le serveur peut décider de modifier ou de supprimer le cookie de persistance à la déconnexion, afin que les visiteurs quittant la session soient automatiquement déliés du serveur ;

• en utilisant des règles basées sur les ACL, il est également possible d’ignorer ou d’imposer sélectivement la persistance de session, indépendamment de l’état du serveur ; combiné à des contrôles d’état avancés, cela permet aux administrateurs de vérifier que le serveur qu’ils installent est opérationnel avant de le rendre accessible à l’ensemble du monde ;

• un mécanisme innovant permettant de définir un délai maximal d’inactivité et une durée pour les cookies assure que la persistance peut être arrêtée de manière fluide sur les appareils qui ne sont jamais fermés (smartphones, téléviseurs, appareils domestiques) sans avoir à les stocker sur un support persistant ;

• plusieurs entrées de serveur peuvent partager les mêmes clés de persistance afin de ne pas perdre la persistance dans les environnements à chemins multiples lorsque l’un des chemins tombe en panne ;

• soft-stop garantit que seuls les utilisateurs possédant des informations de persistance continueront à accéder au serveur qui leur a été attribué, mais aucun nouvel utilisateur n’y sera dirigé.

3.3.7. Fonctionnalités de base : Journalisation

La journalisation est une fonctionnalité extrêmement importante pour un répartiteur de charge, tout d’abord parce qu’un répartiteur de charge est souvent injustement accusé de provoquer les problèmes qu’il révèle, et ensuite parce qu’il est placé à un point critique dans une infrastructure où toute activité normale ou anormale doit être analysée et corrélée avec les autres composants.

HAProxy fournit des journaux très détaillés, avec une précision au millième de seconde et l’heure exacte d’acceptation de la connexion, pouvant être recherchée dans les journaux des pare-feu (par exemple pour la corrélation NAT). Par défaut, les journaux TCP et HTTP sont assez détaillés et contiennent tout ce qui est nécessaire au dépannage, tel que l’adresse IP source et le port, le frontal, le backend, le serveur, les temporisateurs (durée de réception de la requête, durée d’attente en file, temps de mise en place de la connexion, temps d’envoi des en-têtes de réponse, temps de transfert de données), l’état global du processus, le nombre de connexions, l’état de la file d’attente, le nombre de tentatives, les actions de persistance détaillées et les raisons de déconnexion, ainsi que les captures d’en-têtes avec une encodage de sortie sécurisé. Il est alors possible d’étendre ou de remplacer ce format afin d’inclure toute donnée échantillonnée, variable ou capture, aboutissant à des informations très détaillées. Par exemple, il est possible de journaliser le nombre de requêtes cumulées ou le nombre d’URL différentes visitées par un client.

Le niveau de journalisation peut être ajusté par requête à l’aide des ACL standards, ce qui permet d’automatiquement masquer certaines traces considérées comme de la pollution, tout en générant des avertissements lorsque se produit un comportement anormal pour une petite partie du trafic (par exemple, un trop grand nombre d’URLs ou d’erreurs HTTP provenant d’une même adresse source). Les journaux administratifs sont également émis avec leurs propres niveaux afin d’informer sur la perte ou la récupération d’un serveur, par exemple.

Chaque frontal et chaque backend peut utiliser plusieurs sorties de journalisation indépendantes, ce qui facilite la multi-locataire. Les journaux sont préférablement envoyés en UDP, éventuellement encodés au format JSON, et tronqués après une longueur de ligne configurable afin de garantir leur livraison. Il est également possible de les envoyer vers stdout/stderr ou tout descripteur de fichier, ainsi que vers un tampon circulaire auquel un client peut se abonner pour les récupérer.

3.3.8. Fonctionnalités de base : Statistiques

HAProxy fournit une interface web de rapport statistique avec authentification, niveaux de sécurité et portées. Il est ainsi possible de fournir à chaque client hébergé une page personnalisée affichant uniquement ses propres instances. Cette page peut être située dans une partie cachée de l’URL du site web régulier, sans nécessiter l’ouverture d’un nouveau port. Elle peut également indiquer la disponibilité d’autres nœuds HAProxy, afin de repérer facilement, d’un coup d’œil, si tout fonctionne comme prévu. La vue est synthétique, avec un accès à de nombreuses informations détaillées (comme les causes d’erreur, la dernière connexion ou la durée de la dernière modification, etc.), qui sont également disponibles sous forme de tableau CSV pouvant être importé par d’autres outils pour tracer des graphiques. La page peut se rafraîchir automatiquement, afin d’être utilisée comme page de surveillance sur un grand écran. En mode administration, la page permet également de modifier l’état des serveurs pour faciliter les opérations de maintenance.

Un exportateur Prometheus est également fourni afin que les statistiques puissent être consommées dans un format différent selon le déploiement.

4 - Fonctionnalités standard

Dans cette section, sont énumérées certaines fonctionnalités très couramment utilisées avec HAProxy mais qui ne sont pas nécessairement disponibles sur d’autres répartiteurs de charge.

3.4.1. Fonctionnalités standard : Échantillonnage et conversion d’informations

HAProxy prend en charge l’extraction d’échantillons à l’aide d’une large gamme de « fonctions d’extraction d’échantillon ». Le principe consiste à extraire des éléments d’information appelés échantillons, destinés à une utilisation immédiate. Cela est utilisé pour la persistance de session, la création de conditions, la génération d’informations dans les journaux ou l’enrichissement des en-têtes HTTP.

Les échantillons peuvent être récupérés à partir de diverses sources :

• constants : entiers, chaînes, adresses IP, blocs binaires ;

• le processus : date, variables d’environnement, état du serveur/ frontal/ backend/ processus, comptes/débits en octets/connexions, longueur de file d’attente, générateur aléatoire, …

• variables : variables par session, par requête, par réponse ;

• la connexion cliente : adresses source et destination, ports, ainsi que toutes les statistiques associées compteurs ;

• la session client SSL : protocole, version, algorithme, chiffre, taille de clé, identifiant de session, tous les champs du certificat client et serveur, numéro de série du certificat, SNI, ALPN, NPN, prise en charge par le client de certaines extensions ;

• contenu des tampons de requête et de réponse : charge utile arbitraire à l’offset/longueur, longueur des données, RDP cookie, décodage du type SSL hello, décodage du SNI TLS;

• HTTP (requête et réponse) : méthode, URI, chemin, arguments de chaîne de requête, code d’état, en-têtes, valeurs d’en-tête positionnelles, cookies, captures, authentification, éléments du corps ;

Un échantillon peut ensuite passer par un certain nombre d’opérateurs appelés « convertisseurs » afin d’effectuer une transformation. Un convertisseur consomme un échantillon et en produit un nouveau, éventuellement de type complètement différent. Par exemple, un convertisseur peut être utilisé pour ne retourner que la longueur entière de la chaîne d’entrée, ou pour convertir une chaîne en majuscules. Un nombre arbitraire de convertisseurs peut être appliqué en série à un échantillon avant son utilisation finale. Parmi tous les convertisseurs d’échantillons disponibles, les suivants sont les plus couramment utilisés :

• opérateurs arithmétiques et logiques : ils permettent d’effectuer des calculs avancés sur les données d’entrée, tels que le calcul de rapports, de pourcentages ou simplement la conversion d’une unité à une autre ;

• Les masques d’adresse IP sont utiles lorsque certaines adresses doivent être regroupées par réseaux plus grands ;

• représentation des données : décodage URL, base64, hexadécimal, chaînes JSON, hachage ;

• conversion de chaîne : extraire des sous-chaînes à des positions fixes, de longueur fixe, extraire des champs spécifiques autour de délimiteurs donnés, extraire des mots précis, modifier la casse, appliquer une substitution basée sur une expression régulière ;

• conversion de date : convertir au format de date HTTP, convertir entre heure locale et UTC, et ajouter ou supprimer un décalage ;

• rechercher une entrée dans une table de persistance afin de consulter des statistiques ou un serveur affecté ;

• conversion clé-valeur basée sur une carte à partir d’un fichier (utilisée principalement pour la géolocalisation).

3.4.2. Fonctionnalités standard : Maps

Les cartes sont un type puissant de convertisseur consistant à charger un fichier à deux colonnes en mémoire au démarrage, puis à rechercher chaque échantillon d’entrée dans la première colonne et à renvoyer le motif correspondant de la deuxième colonne s’il est trouvé, ou une valeur par défaut sinon. Comme la sortie est également un échantillon, elle peut à son tour subir d’autres transformations, y compris d’autres recherches dans des cartes. Les cartes sont principalement utilisées pour traduire l’adresse IP du client en numéro de AS ou code pays, car elles prennent en charge la correspondance la plus longue pour les adresses réseau, mais elles peuvent être utilisées à divers autres fins.

Une partie de leur efficacité provient de leur capacité à être mises à jour en temps réel, soit depuis la ligne de commande, soit à l’aide de certaines actions via d’autres exemples, ce qui leur permet de stocker et de récupérer des informations entre des accès successifs. Une autre force réside dans l’indexation basée sur un arbre binaire, qui les rend extrêmement rapides, même lorsqu’elles contiennent des centaines de milliers d’entrées, rendant la géolocalisation très peu coûteuse et facile à mettre en œuvre.

3.4.3. Fonctionnalités standard : ACL et conditions

La plupart des opérations dans HAProxy peuvent être rendues conditionnelles. Les conditions sont construites en combinant plusieurs ACL à l’aide d’opérateurs logiques (ET, OU, NON). Chaque ACL est une série de tests fondés sur les éléments suivants :

• une méthode d’extraction d’échantillon pour récupérer l’élément à tester ;

• une série facultative de convertisseurs permettant de transformer l’élément ;

• une liste de modèles à comparer ;

• une méthode correspondante pour indiquer comment comparer les modèles avec l’échantillon

Par exemple, l’échantillon peut être extrait de l’en-tête HTTP « Host », puis converti en minuscules, avant d’être comparé à plusieurs modèles regex à l’aide de la méthode de correspondance regex.

Techniquement, les ACL sont basées sur le même noyau que les cartes ; elles partagent exactement la même structure interne, les mêmes méthodes de correspondance de motifs et les mêmes performances. La seule différence réelle réside dans le fait qu’au lieu de renvoyer un échantillon, elles ne renvoient que « trouvé » ou « non trouvé ». En matière d’utilisation, les motifs ACL peuvent être déclarés en ligne dans le fichier de configuration et n’ont pas besoin de fichier dédié. Les ACL peuvent être nommées afin de faciliter leur utilisation ou d’améliorer la lisibilité des configurations. Une ACL nommée peut être déclarée plusieurs fois, et elle évaluera toutes les définitions successivement jusqu’à ce qu’une correspondance soit trouvée.

Environ 13 méthodes différentes de correspondance de modèles sont proposées, dont le masque d’adresse IP, les plages d’entiers, les sous-chaînes et les expressions régulières. Elles fonctionnent comme des fonctions, et tout comme dans n’importe quel langage de programmation, seules les parties nécessaires sont évaluées. Ainsi, lorsqu’une condition impliquant un OU est déjà vraie, les suivantes ne sont pas évaluées, et de même, lorsque une condition impliquant un ET est déjà fausse, le reste de la condition n’est pas évalué.

Il n’existe aucune limite pratique au nombre d’ACL déclarées, et un certain nombre d’ACL couramment utilisées sont fournies. Toutefois, l’expérience a montré que les configurations utilisant de nombreuses ACL nommées sont souvent difficiles à dépanner, et qu’il peut parfois être plus simple d’utiliser des ACL anonymes en inline, car cela réduit le nombre de références en dehors de la portée analysée.

3.4.4. Fonctionnalités standard : Commutation de contenu

HAProxy implémente un mécanisme connu sous le nom de commutation basée sur le contenu. Le principe consiste à ce qu’une connexion ou une requête arrive sur un frontal, puis que les informations transportées par cette requête ou cette connexion soient traitées ; à ce stade, il est possible d’écrire des conditions basées sur des ACLs utilisant ces informations pour déterminer quel backend traitera la requête. Ainsi, le trafic est acheminé vers un backend ou un autre en fonction du contenu de la requête. L’exemple le plus courant consiste à utiliser l’en-tête Host et/ou des éléments du chemin (sous-répertoires ou extensions de nom de fichier) pour décider si une requête HTTP cible un objet statique ou l’application, puis à acheminer le trafic des objets statiques vers un backend composé de serveurs rapides et légers, et tout le reste du trafic vers un serveur d’application plus complexe, constituant ainsi une solution de hébergement virtuel à granularité fine. Cela est particulièrement pratique pour faire coexister plusieurs technologies dans le cadre d’une solution plus globale.

Un autre cas d’utilisation du commutateur de contenu consiste à utiliser des algorithmes de répartition de charge différents selon divers critères. Un cache peut utiliser un hachage d’URI tandis qu’une application peut utiliser une répartition en roue libre.

Enfin, il permet à plusieurs clients d’utiliser une petite part d’une ressource commune en imposant des limites de connexion par backend (donc par client).

Les règles de commutation de contenu se montrent très performantes, bien que leur efficacité puisse dépendre du nombre et de la complexité des ACL en usage. Il est toutefois possible d’écrire des règles de commutation de contenu dynamiques où une valeur d’échantillonnage se transforme directement en nom de backend, sans faire appel aux ACL. De telles configurations ont été rapportées comme fonctionnant correctement, même avec au moins 300 000 backends en production.

3.4.5. Fonctionnalités standard : tables de persistance

Les tables de persistance sont couramment utilisées pour stocker des informations de persistance, c’est-à-dire pour conserver une référence au serveur vers lequel un visiteur donné a été dirigé. La clé est alors l’identifiant associé au visiteur (son adresse source, l’ID SSL de la connexion, un cookie HTTP ou RDP, le numéro de client extrait de l’URL ou du contenu, …) et la valeur stockée est ensuite l’identifiant du serveur.

Les tables de persistance peuvent utiliser trois types d’échantillons différents pour leurs clés : des entiers, des chaînes de caractères et des adresses. Une seule table de persistance peut être référencée dans un proxy, et elle est désignée partout par le nom du proxy. Jusqu’à 8 clés peuvent être suivies en parallèle. L’identifiant du serveur est fixé pendant le traitement d’une requête ou d’une réponse, une fois que la clé et le serveur sont connus.

Le contenu de la table de persistance peut être répliqué en mode actif-actif avec d’autres nœuds HAProxy appelés « peers », ainsi qu’avec le nouveau processus lors d’une opération de rechargement, afin que tous les nœuds de répartition de charge partagent les mêmes informations et prennent les mêmes décisions de routage lorsque les requêtes clients sont réparties sur plusieurs nœuds.

Étant donné que les tables de stickiness sont indexées sur les éléments permettant d’identifier un client, elles sont souvent utilisées pour stocker des informations supplémentaires, telles que des statistiques par client. Ces statistiques supplémentaires consomment de l’espace supplémentaire et doivent être déclarées explicitement. Les types de statistiques pouvant être stockées incluent la bande passante entrante et sortante, le nombre de connexions simultanées, le débit et le nombre de connexions sur une période donnée, la quantité et la fréquence des erreurs, certains balises et compteurs spécifiques, etc. Afin de permettre le stockage de ces informations sans être contraint de rester lié à un serveur donné, une fonctionnalité spéciale « suivi » est mise en œuvre, permettant de suivre jusqu’à 3 clés simultanées provenant de tables différentes en même temps, indépendamment des règles de stickiness. Chaque statistique stockée peut être recherchée, affichée ou effacée depuis l’interface CLI et enrichit les capacités de dépannage en temps réel.

Bien que ce mécanisme puisse être utilisé pour surclasser un visiteur retour ou ajuster la qualité du service fourni en fonction du comportement (bon ou mauvais), il est principalement employé pour lutter contre l’abus de service et, plus généralement, les attaques DDoS, car il permet de mettre en œuvre des modèles complexes pour détecter certains comportements malveillants à une vitesse de traitement élevée.

3.4.6. Fonctionnalités standard : chaînes formatées

HAProxy doit manipuler de nombreuses chaînes de caractères, par exemple dans les journaux, les redirections, l’ajout d’en-têtes, etc. Afin de garantir la plus grande flexibilité, la notion de chaînes formatées a été introduite, initialement pour les journaux, ce qui explique pourquoi elle est toujours appelée « log-format ». Ces chaînes contiennent des caractères d’échappement permettant d’insérer diverses données dynamiques, y compris des variables et des expressions d’extraction d’échantillon, ainsi que de modifier le codage pendant la conversion du résultat en chaîne (par exemple, en ajoutant des guillemets). Cela permet de construire efficacement le contenu d’en-têtes, de générer des données de réponse ou même des modèles de réponse, ou encore de personnaliser les lignes de journal. En outre, pour simplifier la construction des chaînes les plus courantes, environ 50 balises spéciales sont fournies comme raccourcis pour des informations fréquemment utilisées dans les journaux.

3.4.7. Fonctionnalités standard : réécriture et redirection HTTP

Installer un répartiteur de charge devant une application conçue sans tenir compte de cette configuration peut s’avérer une tâche difficile sans les outils appropriés. L’une des opérations les plus fréquemment demandées dans ce cas consiste à ajuster les en-têtes des requêtes et des réponses afin que le répartiteur de charge semble être le serveur d’origine et corriger les informations codées en dur. Cela implique de modifier le chemin des requêtes (ce qui est fortement déconseillé), de modifier le champ d’en-tête Host, de modifier le champ d’en-tête de réponse Location pour les redirections, de modifier les attributs de chemin et de domaine pour les cookies, et ainsi de suite. Il arrive également qu’un certain nombre de serveurs soient excessivement verbeux et tendent à révéler trop d’informations dans les réponses, ce qui les rend plus vulnérables aux attaques ciblées. Bien que, théoriquement, ce ne soit pas le rôle d’un répartiteur de charge de nettoyer ces informations, en pratique, il se trouve au meilleur emplacement dans l’infrastructure pour garantir que tout soit correctement nettoyé.

De même, le répartiteur de charge peut parfois devoir intercepter certaines requêtes et répondre par une redirection vers une nouvelle URL cible. Bien que certaines personnes confondent souvent les redirections et la réécriture, il s’agit de deux concepts totalement différents : la réécriture fait voir des choses différentes au client et au serveur (et entraîne un désaccord sur l’emplacement de la page visitée), tandis que les redirections demandent au client de visiter la nouvelle URL afin qu’il voie le même emplacement que le serveur.

Pour ce faire, HAProxy prend en charge diverses possibilités de réécriture et de redirection, parmi lesquelles :

• réécriture d’URL et d’en-têtes basée sur des expressions régulières dans les requêtes et les réponses. Les expressions régulières sont l’outil le plus couramment utilisé pour modifier les valeurs d’en-tête, car elles sont faciles à manipuler et bien comprises ;

• Les en-têtes peuvent également être ajoutés, supprimés ou remplacés selon des chaînes formatées, afin de transmettre des informations (par exemple, l’algorithme et le chiffre TLS côté client) ;

• Les redirections HTTP peuvent utiliser n’importe quel code 3xx vers une URI relative, absolue ou entièrement dynamique (chaîne formatée) ;

• Les redirections HTTP prennent également en charge certaines options supplémentaires, telles que la définition ou la suppression d’un cookie spécifique, le rejet de la chaîne de requête, l’ajout d’une barre oblique si elle est manquante, etc. ;

• un directive “return” puissante permet de personnaliser chaque partie d’une réponse, comme le statut, les en-têtes ou le corps, en utilisant des contenus dynamiques ou même des fichiers modèles.

• toutes les opérations prennent en charge des conditions basées sur les listes de contrôle d’accès ;

3.4.8. Fonctionnalités standard : protection des serveurs

HAProxy met tout en œuvre pour maximiser la disponibilité du service, et à cet effet, il déploie de grands efforts pour protéger les serveurs contre la surcharge et les attaques. Le premier et le plus important point est que seules les requêtes complètes et valides sont acheminées vers les serveurs. La raison première est que HAProxy doit identifier les éléments du protocole nécessaires pour rester synchronisé avec le flux d’octets, et la deuxième raison est qu’aussi longtemps que la requête n’est pas complète, il n’existe aucun moyen de savoir si certains éléments pourraient modifier son sémantique. Le bénéfice direct de cette approche est que les serveurs ne sont pas exposés à des requêtes invalides ou incomplètes. Cela constitue une protection très efficace contre les attaques slowloris, qui ont presque aucun impact sur HAProxy.

Un autre point important est que HAProxy dispose de tampons pour stocker les requêtes et les réponses, et qu’en n’envoyant une requête au serveur que lorsqu’elle est complète, et en lisant entièrement la réponse très rapidement depuis le réseau local, la connexion côté serveur est utilisée pendant une durée très brève, ce qui préserve au maximum les ressources du serveur.

Une extension directe de cette fonctionnalité est que HAProxy peut limiter artificiellement le nombre de connexions simultanées ou de requêtes en attente vers un serveur, garantissant ainsi que le serveur ne sera jamais surchargé, même en cas de pointe de trafic où il fonctionnerait continuellement à 100 % de sa capacité. Toutes les requêtes excédentaires seront simplement mises en file d’attente pour être traitées lorsque une place se libère. En fin de compte, cette économie importante de ressources garantit souvent des temps de réponse du serveur bien meilleurs, ce qui se traduit par une performance réelle supérieure à celle obtenue en surchargeant le serveur. Les requêtes en attente peuvent être réacheminées vers d’autres serveurs, ou même annulées en file d’attente si le client se déconnecte, ce qui protège également les serveurs contre l’effet « rechargement », où chaque clic sur « recharger » d’un visiteur sur une page à chargement lent déclenche généralement une nouvelle requête et maintient le serveur dans un état surchargé.

Le mécanisme de démarrage progressif protège également les serveurs redémarrés contre des niveaux élevés de trafic pendant qu’ils finalisent encore leur démarrage ou qu’ils compilent certaines classes.

En ce qui concerne la protection au niveau du protocole, il est possible de relâcher l’analyseur HTTP afin d’accepter des requêtes ou réponses non conformes mais inoffensives, voire de les corriger. Cela permet d’accéder à des applications défectueuses pendant qu’une correction est en cours de développement. Parallèlement, les messages problématiques sont entièrement capturés avec un rapport détaillé qui aide les développeurs à identifier la cause dans l’application. Les violations de protocole les plus dangereuses sont correctement détectées, traitées et corrigées. Par exemple, les requêtes ou réponses malformées comportant deux en-têtes Content-Length sont soit corrigées si leurs valeurs sont identiques, soit rejetées si elles diffèrent, car cela devient un problème de sécurité. L’inspection de protocole n’est pas limitée à HTTP, elle est également disponible pour d’autres protocoles tels que TLS ou RDP.

Lorsqu’une violation de protocole ou une attaque est détectée, diverses options sont disponibles pour répondre à l’utilisateur, telles que le renvoi de la réponse HTTP 400 standard « mauvaise requête », la fermeture de la connexion par un réinitialisation TCP, ou la simulation d’une erreur après un délai prolongé (« tarpit ») afin de troubler l’attaquant. Toutes ces mesures contribuent à protéger les serveurs en décourageant le client fautif de poursuivre une attaque devenue très coûteuse à maintenir.

HAProxy propose également des options plus avancées pour protéger contre les fuites de données accidentelles et les chevauchements de session. Non seulement il peut journaliser les réponses du serveur suspectes, mais il peut également journaliser et, optionnellement, bloquer une réponse pouvant compromettre la confidentialité d’un visiteur donné. Un exemple en est un cookie pouvant être mis en mémoire tampon apparaissant dans une réponse pouvant être mise en mémoire tampon, ce qui pourrait entraîner la livraison de ce cookie à un autre visiteur par un cache intermédiaire, provoquant ainsi un partage de session accidentel.

5 - Fonctionnalités avancées

3.5.1. Fonctionnalités avancées : Gestion

HAProxy est conçu pour rester extrêmement stable et sécurisé à gérer dans un environnement de production classique. Il est fourni sous forme d’un seul fichier exécutable ne nécessitant aucun processus d’installation. Plusieurs versions peuvent coexister facilement, ce qui permet (et est recommandé) de mettre à jour les instances progressivement, par ordre de priorité, plutôt que de les migrer toutes en même temps. Les fichiers de configuration sont facilement versionnés. La vérification de configuration se fait hors ligne, sans nécessiter de redémarrer un service susceptible de échouer. Pendant la vérification de configuration, un certain nombre d’erreurs avancées peuvent être détectées (par exemple, une règle masquant une autre, ou une persistance qui ne fonctionnera pas), et des avertissements détaillés ainsi que des suggestions de configuration sont proposés pour les corriger. La compatibilité des fichiers de configuration avec les versions antérieures s’étend très loin dans le temps : la version 1.5 supporte encore entièrement les configurations écrites pour les versions 1.1, il y a 13 ans, et la version 1.6 n’a abandonné le support que pour des mots-clés presque inutilisés et obsolètes, pouvant être remplacés autrement. Le mécanisme de mise à jour de la configuration et du logiciel est fluide et non disruptif, car il permet à des processus anciens et nouveaux de coexister sur le système, chacun gérant ses propres connexions. L’état du système, les options de compilation et la compatibilité des bibliothèques sont rapportés au démarrage.

Certaines fonctionnalités avancées permettent à un administrateur d’application d’arrêter un serveur de manière fluide, de détecter lorsqu’il n’y a plus d’activité dessus, puis de le retirer du service, de l’arrêter, de le mettre à jour, et de s’assurer qu’il ne reçoit aucune requête pendant la mise à jour, puis de le tester à nouveau via le chemin normal sans le rendre accessible au public, et tout cela sans modifier HAProxy. Cela garantit que même des opérations de production complexes peuvent être effectuées pendant les heures d’ouverture, avec l’ensemble des ressources techniques disponibles.

Le processus tente de préserver au maximum les ressources, utilise des pools de mémoire pour réduire le temps d’allocation et limiter la fragmentation mémoire, libère les tampons de charge utile dès que leurs contenus ont été envoyés, et prend en charge l’application de limites mémoire strictes, au-delà desquelles les connexions doivent attendre qu’un tampon devienne disponible au lieu d’allouer davantage de mémoire. Ce système permet de garantir l’utilisation mémoire dans certains environnements stricts.

Une interface en ligne de commande (CLI) est disponible sous forme de socket UNIX ou TCP, afin d’effectuer diverses opérations et de récupérer des informations utiles au dépannage. Toutes les actions effectuées sur cette socket ne nécessitent pas de modification de configuration, aussi est-elle principalement utilisée pour des changements temporaires. Grâce à cette interface, il est possible de modifier l’adresse, le poids et l’état d’un serveur, de consulter les statistiques et de réinitialiser les compteurs, de sauvegarder et vider les tables de persistance, éventuellement de manière sélective selon des critères clés, de sauvegarder et interrompre les connexions côté client ou côté serveur, de sauvegarder les erreurs capturées avec une analyse détaillée de la cause exacte et de l’emplacement de l’erreur, de sauvegarder, ajouter ou supprimer des entrées dans les listes ACL et les cartes, de mettre à jour les secrets TLS partagés, d’appliquer des limites de connexion et de débit en temps réel sur des frontaux arbitraires (utile dans les environnements d’hébergement partagé), et de désactiver un frontend spécifique afin de libérer un port d’écoute (utile lorsque les opérations diurnes sont interdites et qu’une correction s’impose tout de même). Il est permis de mettre à jour les certificats et leur configuration en temps réel, ainsi que d’activer et de consulter les traces de chaque étape du traitement du trafic.

Dans les environnements où SNMP est obligatoire, il existe au moins deux agents. L’un est fourni avec les sources HAProxy et repose sur le module Perl Net-SNMP. L’autre accompagne les paquets commerciaux et ne requiert pas Perl. Ils offrent une couverture globalement équivalente.

Il est souvent recommandé d’installer les quatre utilitaires suivants sur la machine où HAProxy est déployé :

• socat (afin de se connecter à l’interface CLI, bien que certaines variantes de netcat puissent également le faire dans une certaine mesure) ;

• halog depuis la dernière version d’HAProxy : il s’agit d’un outil d’analyse de journaux, qui analyse très rapidement les journaux TCP et HTTP natifs (de 1 à 2 Go par seconde) et extrait des informations et statistiques utiles, telles que le nombre de requêtes par URL, par adresse source, les URLs triées par temps de réponse ou taux d’erreur, les codes de terminaison, etc. Il a été conçu pour être déployé sur les serveurs de production afin d’aider au dépannage des problèmes en temps réel, il doit donc être présent et prêt à être utilisé ;

• tcpdump : il est fortement recommandé d’utiliser tcpdump pour capturer les traces réseau nécessaires au dépannage d’un problème apparu dans les journaux. Il arrive un moment où l’analyse effectuée par l’application et celle effectuée par HAProxy divergent, et les traces réseau sont la seule manière de déterminer qui a raison et qui a tort. Il est également fréquent de détecter des bugs dans les piles réseau ou les hyperviseurs grâce à tcpdump.

• strace : il est le complément de tcpdump. Il indique ce que HAProxy voit réellement et permet de distinguer les problèmes liés au système d’exploitation de ceux liés à HAProxy. strace est souvent demandé lorsqu’un bug dans HAProxy est suspecté ;

3.5.2. Fonctionnalités avancées : Capacités spécifiques au système

Selon le système d’exploitation sur lequel HAProxy est déployé, certaines fonctionnalités supplémentaires peuvent être disponibles ou nécessaires. Bien qu’il soit pris en charge sur plusieurs plates-formes, HAProxy est principalement développé sous Linux, ce qui explique pourquoi certaines fonctionnalités ne sont disponibles que sur cette plate-forme.

Les fonctionnalités de liaison transparente et de connexion, le support de la liaison des connexions à une interface réseau spécifique, ainsi que la possibilité de lier plusieurs processus au même adresse IP et ports ne sont disponibles que sur les systèmes Linux et BSD, bien que seul Linux effectue une répartition de charge côté noyau des requêtes entrantes entre les processus disponibles.

Sur Linux, plusieurs fonctionnalités et optimisations supplémentaires sont disponibles, notamment le support des espaces de noms réseau (également appelés « conteneurs »), permettant à HAProxy d’agir comme passerelle entre tous les conteneurs, la possibilité de définir la taille maximale de segment (MSS), les marques Netfilter et le champ IP TOS sur la connexion côté client, le support du TCP FastOpen côté écoute, les délais d’expiration utilisateur TCP pour permettre au noyau de tuer rapidement les connexions lorsque le client disparaît avant l’expiration configurée, le découpage TCP pour permettre au noyau de transférer les données entre les deux extrémités d’une connexion, évitant ainsi plusieurs copies en mémoire, la possibilité d’activer l’option bind « defer-accept » afin de ne recevoir une notification d’une connexion entrante qu’une fois que des données sont disponibles dans les tampons du noyau, ainsi que la possibilité d’envoyer la requête avec l’ACK confirmant la connexion (parfois appelé « piggy-back »), activée par l’option « tcp-smart-connect ». Sur Linux, HAProxy prend également grand soin à manipuler les accusés de réception différés TCP afin de réduire au maximum le nombre de paquets sur le réseau.

Certains systèmes disposent d’une horloge peu fiable, qui saute indéfiniment dans le passé et dans le futur. Cela se produisait autrefois sur certains systèmes NUMA où plusieurs processeurs ne voyaient pas exactement la même heure, et cela devient désormais plus fréquent dans les environnements virtualisés, où l’horloge virtuelle n’a aucune relation avec l’horloge réelle, entraînant des sauts temporels importants (des sauts de jusqu’à 30 secondes ont été observés). Cela pose de nombreux problèmes en ce qui concerne l’application des délais d’expiration en général. En raison de cette imperfection de ces systèmes, HAProxy maintient sa propre horloge monotone, basée sur l’horloge système mais où le dérive est mesuré et compensé. Cela garantit que, même avec une horloge système très défaillante, les temporisateurs restent raisonnablement précis et que les délais d’expiration continuent de fonctionner. Notez que ce problème affecte tous les logiciels s’exécutant sur de tels systèmes et n’est pas spécifique à HAProxy. Les effets courants sont des délais d’expiration erronés ou des blocages d’applications. Par conséquent, si ce comportement est détecté sur un système, il doit être corrigé, quelle que soit la protection offerte par HAProxy.

Sous Linux, un nouveau processus de démarrage peut communiquer avec l’ancien afin de réutiliser ses descripteurs de fichiers d’écoute, de sorte que les sockets d’écoute ne soient jamais interrompus pendant le remplacement du processus.

3.5.3. Fonctionnalités avancées : Scripting

HAProxy peut être compilé avec prise en charge du langage embarqué Lua, ce qui ouvre un large éventail de possibilités liées à la manipulation complexe des requêtes ou des réponses, aux décisions de routage, au traitement des statistiques, etc. En utilisant Lua, il est même possible d’établir des connexions parallèles avec d’autres serveurs afin d’échanger des informations. Ainsi, il devient possible (bien que complexe) de développer un système d’authentification, par exemple. Pour en savoir plus sur l’utilisation de Lua, reportez-vous à la documentation disponible dans le fichier “doc/lua-api/index.rst”.

3.5.4. Fonctionnalités avancées : Suivi

À tout moment, un administrateur peut se connecter via l’interface CLI et activer le traçage dans divers sous-systèmes internes. Des niveaux de détail variés sont fournis par défaut, de sorte qu’en pratique, on puisse récupérer entre une ligne par requête et 500 lignes par requête. Des filtres ainsi qu’un mécanisme automatique d’activation/désactivation/pause de la capture sont disponibles, permettant ainsi réellement d’attendre un événement spécifique et de l’observer en détail. Cela est extrêmement pratique pour diagnostiquer des violations de protocole provenant de serveurs ou de clients défaillants, ou des attaques par déni de service.

6 - Taille et performance

Les valeurs typiques d’utilisation du processeur montrent que 15 % du temps de traitement sont consacrés à HAProxy contre 85 % au noyau en mode TCP ou HTTP fermé, et environ 30 % pour HAProxy contre 70 % pour le noyau en mode HTTP keep-alive. Cela signifie que le système d’exploitation et son réglage ont une influence forte sur les performances globales.

Les usages varient beaucoup d’un utilisateur à l’autre : certains se concentrent sur le débit, d’autres sur le taux de requêtes, d’autres sur la concurrence des connexions, d’autres encore sur les performances SSL. Cette section vise à fournir quelques éléments pour faciliter cette tâche.

Il est important de garder à l’esprit que chaque opération comporte un coût, de sorte que chaque opération individuelle ajoute son surcoût aux autres, ce qui peut être négligeable dans certains cas, mais peut aussi dominer dans d’autres.

Lors du traitement des requêtes émanant d’une connexion, on peut dire que :

• le transfert des données coûte moins cher que l’analyse des en-têtes de requête ou de réponse ;

• analyser les en-têtes de requête ou de réponse coûte moins cher que d’établir puis de fermer une connexion vers un serveur ;

• établir ou fermer une connexion coûte moins qu’une opération de reprise TLS ;

• une opération de reprise TLS coûte moins cher qu’une négociation TLS complète avec calcul de clé ;

• une connexion inactif consomme moins de CPU qu’une connexion dont les tampons contiennent des données ;

• un contexte TLS consomme encore plus de mémoire qu’une connexion avec des données ;

En pratique, il est donc moins coûteux de traiter les octets de charge utile que les octets d’en-tête, ce qui rend plus facile l’atteinte d’un débit réseau élevé avec des objets volumineux (peu de requêtes par unité de volume) qu’avec des objets de petite taille (nombreuses requêtes par unité de volume). C’est pourquoi le débit maximal est toujours mesuré avec des objets volumineux, tandis que le débit de requêtes ou le débit de connexions est mesuré avec des objets de petite taille.

Certaines opérations échelonnent bien sur plusieurs processus répartis sur plusieurs processeurs, tandis que d’autres ne s’échelonnent pas aussi efficacement. La bande passante réseau ne s’échelonne pas très loin, car le processeur n’est rarement pas le goulot d’étranglement pour de grands objets, le goulot étant principalement la bande passante réseau et les bus de données pour atteindre les interfaces réseau. Le débit de connexion ne s’échelonne pas bien sur plusieurs processeurs en raison de quelques verrous dans le système lors de la gestion du tableau des ports locaux. Le débit de requêtes sur des connexions persistantes s’échelonne très bien, car il implique peu de mémoire ni de bande passante réseau et ne nécessite pas d’accéder à des structures verrouillées. Le calcul de la clé TLS s’échelonne très bien, car il est entièrement limité par le processeur. La reprise TLS s’échelonne modérément bien, mais atteint ses limites vers 4 processus, où la surcharge liée à l’accès au tableau partagé compense les gains faibles attendus d’une puissance accrue.

Les performances qu’on peut attendre d’un système très bien optimisé se situent dans la plage suivante. Il est important de les considérer comme des ordres de grandeur, et de s’attendre à des variations importantes dans n’importe quelle direction, en fonction du processeur, des paramètres IRQ, du type de mémoire, du type d’interface réseau, de l’optimisation du système d’exploitation, etc.

Les chiffres suivants ont été obtenus sur un processeur Core i7 fonctionnant à 3,7 GHz, équipé de deux ports réseau 10 Gbps, sous un noyau Linux 3,10, HAProxy 1,6 et OpenSSL 1,0,2. HAProxy était exécuté en tant que processus unique sur un cœur CPU dédié, et deux cœurs supplémentaires étaient dédiés aux interruptions réseau :

• 20 Gbps de bande passante réseau maximale en clair pour les objets de 256 ko ou plus, 10 Gbps pour les objets de 41 ko ou plus ;

• 4,6 Gbps de trafic TLS utilisant le chiffrement AES256-GCM avec des objets volumineux ;

• 83000 connexions TCP par seconde depuis le client vers le serveur ;

• 82000 connexions HTTP par seconde du client vers le serveur ;

• 97000 requêtes HTTP par seconde en mode server-close (keep-alive avec le client, fermeture avec le serveur);

• 243000 requêtes HTTP par seconde en mode keep-alive end-to-end ;

• 300000 connexions TCP filtrées par seconde (anti-DDoS)

• 160000 requêtes HTTPS par seconde en mode keep-alive sur des connexions TLS persistantes ;

• 13100 requêtes HTTPS par seconde en utilisant des connexions TLS réinitialisées ;

• 1300 connexions HTTPS par seconde utilisant des connexions TLS renégociées avec RSA2048 ;

• 20000 connexions simultanées saturées par Go de RAM, incluant la mémoire nécessaire aux tampons système ; il est possible d’obtenir de meilleurs résultats avec un réglage soigné, mais ce résultat est facile à atteindre.

• environ 8000 connexions TLS simultanées (côté client uniquement) par Go de mémoire vive, incluant la mémoire nécessaire aux tampons système ;

• environ 5000 connexions TLS de bout en bout simultanées, côté client et côté serveur, par Go de RAM, y compris la mémoire requise pour les tampons système ;

Une benchmark plus récente, mettant en œuvre HAProxy 2.4 activé en multithread sur un processeur ARM Graviton2 à 64 cœurs dans AWS, a atteint 2 millions de requêtes HTTPS par seconde avec un temps de réponse inférieur à un milliseconde, ainsi qu’un débit de 100 Gbps :

https://www.haproxy.com/blog/haproxy-forwards-over-2-million-http-requests-per-second-on-a-single-aws-arm-instance/

Ainsi, une bonne règle empirique à garder à l’esprit est que le débit des requêtes est divisé par 10 entre le maintien de la connexion TLS et la reprise TLS, ainsi qu’entre la reprise TLS et la renegotiation TLS, tandis qu’il n’est divisé que par 3 entre le maintien de la connexion HTTP et la fermeture HTTP. Une autre bonne règle empirique consiste à se souvenir qu’un cœur à fréquence élevée disposant d’instructions AES peut traiter environ 20 Gbps de AES-GCM par cœur.

Une autre règle pratique consiste à considérer qu’un même serveur peut permettre à HAProxy de saturer :

• environ 5 à 10 serveurs statiques ou proxies de mise en cache ;

• environ 100 proxies anti-virus ;

• et environ 100 à 1000 serveurs d’applications, selon la technologie utilisée.

7 - Versions, Paquets et Mises à jour

HAProxy est un projet open source soumis à la licence GPLv2, ce qui signifie que toute personne est autorisée à le redistribuer à condition de fournir l’accès au code source sur demande, notamment si des modifications ont été apportées.

HAProxy évolue via une branche de développement principale appelée « master » ou « mainline », à partir de laquelle de nouvelles branches sont créées une fois que le code est jugé stable. De nombreux sites web exécutent des branches de développement en production de manière volontaire, soit pour participer au projet, soit parce qu’ils ont besoin d’une fonctionnalité de pointe, et leurs retours sont précieux pour corriger les bogues et évaluer la qualité et la stabilité globales de la version en développement.

Les nouvelles branches créées lorsque le code est suffisamment stable constituent une version stable et sont généralement maintenues pendant plusieurs années, de sorte qu’il n’y a pas d’urgence à migrer vers une branche plus récente, même si vous n’êtes pas sur la dernière. Une fois qu’une branche stable est publiée, elle ne reçoit que des correctifs de bogues, et très rarement des mises à jour mineures lorsque cela facilite la vie des utilisateurs. Tous les correctifs intégrés à une branche stable proviennent nécessairement de la branche master. Cela garantit qu’aucun correctif ne sera perdu après une mise à jour. Pour cette raison, si vous corrigez un bogue, veuillez appliquer votre correctif à la branche master, et non à la branche stable. Vous pourriez même découvrir qu’il était déjà corrigé. Ce processus garantit également que les régressions dans une branche stable sont extrêmement rares, si bien qu’il n’y a jamais d’excuse pour ne pas mettre à jour vers la dernière version de votre branche actuelle.

Les branches sont numérotées avec deux chiffres séparés par un point, par exemple “1.6”. Depuis la version 1.9, les branches dont le deuxième chiffre est impair sont principalement consacrées à des mises à jour techniques sensibles et s’adressent davantage aux utilisateurs avancés, car elles sont susceptibles de provoquer plus de bogues que les autres. Elles sont maintenues pendant environ un an seulement et ne doivent pas être déployées là où un retour arrière d’urgence n’est pas possible. Une version complète inclut une ou deux sous-versions indiquant le niveau de correction. Par exemple, la version 1.5.14 est la 14e version corrigée de la branche 1.5 après la publication de la version 1.5.0. Elle contient 126 corrections pour des bogues individuels, 24 mises à jour de la documentation et 75 autres correctifs importés, dont la plupart étaient nécessaires pour corriger les 126 bogues mentionnés ci-dessus. Une fonctionnalité existante ne peut jamais être modifiée ni supprimée dans une branche stable, afin de garantir que les mises à jour au sein de la même branche seront toujours sans risque.

HAProxy est disponible depuis plusieurs sources, selon des rythmes de publication différents :

• Le site web officiel de la communauté : http://www.haproxy.org/ : ce site fournit les sources de la dernière version de développement, de toutes les versions stables, ainsi que des instantanés nocturnes pour chaque branche. Le cycle de publication n’est pas rapide, plusieurs mois séparent les versions stables ou les instantanés de développement. Des versions très anciennes sont toujours prises en charge. Tout est fourni uniquement sous forme de sources, il faut donc reconstruire et/ou repackager tout ce qui provient de ce site.

• GitHub : https://github.com/haproxy/haproxy/ : ce miroir est réservé à la branche de développement uniquement, il permet l’intégration avec le suivi des problèmes, les outils d’intégration continue et de couverture du code. Il est exclusivement destiné aux contributeurs ;

• Certains systèmes d’exploitation, tels que les distributions Linux et les ports BSD. Ces systèmes fournissent généralement des versions maintenues à long terme, qui ne contiennent pas toujours tous les correctifs des versions officielles, mais qui incluent au moins les correctifs critiques. Il s’agit souvent d’une bonne option pour la plupart des utilisateurs qui ne recherchent pas de configurations avancées et souhaitent simplement simplifier les mises à jour ;

• Versions commerciales à partir de http://www.haproxy.com/ : il s’agit de paquets professionnels pris en charge, construits pour divers systèmes d’exploitation ou fournis sous forme d’appareils, basés sur les dernières versions stables et incluant un certain nombre de fonctionnalités portées en arrière depuis la prochaine version, pour lesquelles la demande est forte. C’est l’option idéale pour les utilisateurs souhaitant bénéficier des dernières fonctionnalités avec la fiabilité d’une branche stable, un temps de réponse le plus rapide possible pour corriger les bogues, ou simplement des contrats de support sur un produit open source ;

Afin de vous assurer que la version que vous utilisez est la plus récente dans votre branche, procédez comme suit :

• vérifiez quel exécutable HAProxy vous exécutez : certains systèmes le livrent par défaut et les administrateurs installent leurs versions ailleurs sur le système, il est donc important de vérifier dans les scripts de démarrage quel exécutable est utilisé ;

• détermine la source de votre version de HAProxy. Pour cela, il suffit généralement de taper « HAProxy -v ». Une version de développement apparaît alors sous cette forme, avec le mot « dev » après le numéro de branche :

HAProxy version 2.4-dev18-a5357c-137 2021/05/09 - https://haproxy.org/

Une version stable s'affiche comme suit, tout comme les versions stables non modifiées

versions fournies par les éditeurs de systèmes d’exploitation :

HAProxy version 1.5.14 2015/07/02

Et une capture nocturne d'une version stable apparaît comme suit, avec une séquence hexadécimale après la version, ainsi qu'une date de la capture.

à la place de la date de la version :

HAProxy version 1.5.14-e4766ba 2015/07/29

Tout autre format peut indiquer un paquet spécifique au système, doté de son propre jeu de correctifs. Par exemple, les versions HAProxy Enterprise apparaîtront avec le

au format (<branch>-<latest commit>-<revision>):

HAProxy version 1.5.0-994126-357 2015/07/02

Veuillez noter qu’historiquement, les versions antérieures à 2.4 affichaient le nom du processus avec un trait d’union entre « HA » et « Proxy », y compris celles qui ont été ajustées pour afficher le format correct uniquement, il est donc préférable de l’ignorer ou d’utiliser une correspondance souple dans les scripts. En outre, les versions modernes ajoutent une URL pointant vers la page d’accueil du projet.

Enfin, les versions 2.1 et ultérieures incluront une ligne « Statut » indiquant si la version est sûre pour la production ou non, et le cas échéant, jusqu’à quand, ainsi qu’un lien vers la liste des bogues connus affectant cette version.

• pour les paquets spécifiques au système, vous devez consulter le dépôt de paquets de votre fournisseur ou mettre à jour votre système afin de vous assurer que celui-ci est toujours pris en charge et que des correctifs sont toujours fournis pour votre branche. Pour les versions communautaires provenant de HAProxy.org, rendez-vous simplement sur le site, vérifiez l’état de votre branche et comparez la dernière version avec la vôtre afin de savoir si vous êtes à jour. Si ce n’est pas le cas, vous pouvez procéder à une mise à niveau. Si votre branche n’est plus maintenue, vous êtes certainement très en retard et devrez envisager une mise à niveau vers une branche plus récente (lisez attentivement le README lors de cette opération).

HAProxy doit être mis à jour conformément à la source d’où il provient. En général, cela suit la méthode utilisée par le fournisseur du système pour mettre à jour un paquet. Si HAProxy a été obtenu à partir des sources, veuillez lire le fichier README du répertoire des sources après extraction des sources et suivez les instructions propres à votre système d’exploitation.

8 - Produits complémentaires et alternatives

HAProxy s’intègre assez bien avec certains produits listés ci-dessous, ce qui justifie leur mention ici, même s’ils ne sont pas directement liés à HAProxy.

4.1. Serveur HTTP Apache

Apache est le serveur HTTP de facto. Il s’agit d’un projet très complet et modulaire, capable de servir des fichiers ainsi que du contenu dynamique. Il peut agir de front-end pour certains serveurs d’applications. Il peut même acheminer des requêtes et mettre en mémoire tampon les réponses. Dans tous ces cas d’utilisation, un répartiteur de charge frontal est généralement nécessaire. Apache peut fonctionner dans divers modes, certains étant plus lourds que d’autres. Certains modules nécessitent encore le modèle pré-forké plus lourd, ce qui empêche Apache de bien évoluer avec un grand nombre de connexions. Dans ce cas, HAProxy peut apporter une aide considérable en imposant des limites de connexion par serveur à une valeur sûre, ce qui accélère significativement le serveur et préserve ses ressources, qui seront mieux utilisées par l’application.

Apache peut extraire l’adresse du client à partir de l’en-tête X-Forwarded-For en utilisant l’extension “mod_rpaf”. HAProxy alimente automatiquement cet en-tête lorsque l’option forwardfor est spécifiée dans sa configuration. HAProxy peut également offrir une protection efficace à Apache lorsqu’il est exposé à internet, lui permettant de mieux résister à un large éventail de types d’attaques de type DoS.

4.2. NGINX

NGINX est le second serveur HTTP de facto. Comme Apache, il couvre un large éventail de fonctionnalités. Conçu selon un modèle similaire à HAProxy, il gère sans difficulté des dizaines de milliers de connexions simultanées. Lorsqu’il sert de passerelle vers des applications, par exemple avec PHP FPM, limiter les connexions en frontal peut réduire la charge de l’application PHP. HAProxy est alors utile tant comme répartiteur de charge classique que comme régulateur de trafic pour désengorger PHP. Comme ces produits consomment très peu de CPU grâce à leur architecture événementielle, il est souvent facile d’installer HAProxy et NGINX sur le même système. NGINX implémente le protocole PROXY de HAProxy ; HAProxy peut donc lui transmettre les informations de connexion du client afin que l’application dispose de tout le contexte utile. Des benchmarks ont aussi montré que, pour servir de gros fichiers statiques, un hachage cohérent dans HAProxy devant NGINX peut améliorer le taux de succès du cache du système d’exploitation, qui est essentiellement multiplié par le nombre de nœuds serveurs.

4.3. Varnish

Varnish est un proxy inversé intelligent à mémoire cache, probablement le mieux décrit comme un accélérateur d’applications web. Varnish n’implémente pas SSL/TLS et souhaite consacrer l’intégralité de ses cycles processeur à ce qu’il fait le mieux. Varnish implémente également le protocole PROXY d’HAProxy, de sorte qu’HAProxy peut être déployé très facilement devant Varnish en tant qu’offloader SSL ainsi qu’en tant que répartiteur de charge, tout en transmettant à Varnish toutes les informations pertinentes relatives au client. Varnish prend naturellement en charge la décompression depuis le cache lorsque le serveur fournit un objet compressé, mais ne compresse pas lui-même. HAProxy peut alors être utilisé pour compresser les données sortantes lorsque les serveurs backend ne mettent pas en œuvre la compression, bien que ce ne soit généralement pas une bonne idée de compresser sur le répartiteur de charge, sauf si le trafic est faible.

Lors de la mise en place de fermes de mise en cache étendues sur plusieurs nœuds, HAProxy peut utiliser le hachage URL cohérent pour répartir intelligemment la charge sur les nœuds de mise en cache et éviter la duplication de cache, ce qui permet d’obtenir une taille totale de cache égale à la somme de celles de tous les nœuds de mise en cache. En outre, la mise en cache de petits objets simples pendant une courte durée sur HAProxy peut parfois permettre d’éviter des allers-retours réseau et de réduire la charge CPU sur les nœuds HAProxy et Varnish. Cela n’est possible que si aucune opération n’est effectuée sur ces objets sur Varnish (ce cas est souvent désigné sous le terme de « cache favicon », permettant parfois d’éviter une proportion importante de requêtes inutiles en aval). Toutefois, ne pas activer la mise en cache sur HAProxy pendant une durée prolongée (plusieurs secondes) devant toute autre cache, car cela compliquerait considérablement le dépannage sans apporter de gains réellement significatifs.

4.4. Alternatives

Le répartiteur de charge Linux Virtual Server (LVS ou IPVS) est un répartiteur de charge au niveau 4 intégré au noyau Linux. Il fonctionne au niveau des paquets et gère TCP et UDP. Dans la plupart des cas, il s’agit davantage d’un complément que d’une alternative, car il ne possède aucune connaissance au niveau 7.

Pound est un autre répartiteur de charge bien connu. Il est beaucoup plus simple et offre nettement moins de fonctionnalités que HAProxy, mais Pound comme HAProxy peuvent convenir à de nombreuses configurations élémentaires. Son auteur a toujours privilégié l’auditabilité du code et souhaite conserver un ensemble restreint de fonctionnalités. Son architecture à base de threads passe moins bien à l’échelle avec un grand nombre de connexions, mais le produit reste solide.

Pen est un répartiteur de charge relativement léger. Il prend en charge le SSL, maintient la persistance grâce à une table de taille fixe contenant les adresses IP de ses clients. Il prend en charge un mode orienté paquets, permettant de supporter le retour direct du serveur et le UDP dans une certaine mesure. Il est destiné à des charges faibles (la table de persistance ne comporte que 2048 entrées).

NGINX peut effectuer une répartition de charge à certains égards, bien qu’il ne s’agisse clairement pas de sa fonction principale. Le trafic de production sert à détecter les défaillances de serveur, les algorithmes de répartition de charge sont plus limités, et la persistance est très limitée. Toutefois, cela peut avoir un sens dans certains scénarios de déploiement simples où NGINX est déjà présent. Le point positif est qu’étant donné son intégration très fluide avec HAProxy, il n’y a rien de mal à ajouter HAProxy ultérieurement lorsque les limites de NGINX ont été atteintes.

Varnish effectue également une répartition de charge sur ses serveurs backend et prend en charge des contrôles d’état réels. Il ne met toutefois pas en œuvre de persistance de session, de sorte qu’à l’instar de NGINX, cela peut suffire pour démarrer, à condition que la persistance ne soit pas requise. De même, puisque HAProxy et Varnish s’intègrent si bien, il est aisé d’ajouter Varnish ultérieurement dans la chaîne afin de compléter l’ensemble des fonctionnalités.

9 - Documentation et communauté

1. Documentation disponible

La documentation complète de HAProxy est contenue dans les documents suivants. Veuillez vous assurer de consulter la documentation pertinente afin d’économiser du temps et d’obtenir la réponse la plus précise à vos besoins. Veuillez également vous abstenir d’envoyer des questions à la liste de diffusion dont les réponses sont déjà disponibles dans ces documents.

• intro.txt (ce document) : il présente les bases de la répartition de charge, HAProxy en tant que produit, ses fonctionnalités, ses limites, certains pièges à éviter, certaines limitations propres aux systèmes d’exploitation, comment l’obtenir, son évolution, comment s’assurer d’exécuter une version avec tous les correctifs connus, comment le mettre à jour, ainsi que des compléments et des alternatives.

• management.txt : il explique comment démarrer HAProxy, comment le gérer en temps réel, comment le gérer sur plusieurs nœuds, et comment procéder à des mises à jour sans interruption.

• configuration.txt : le manuel de référence détaille tous les mots-clés de configuration et leurs options. Il est utilisé lorsqu’une modification de configuration est nécessaire.

• coding-style.txt : destiné aux développeurs souhaitant proposer du code au projet. Il décrit le style à adopter pour le code. Il n’est pas très strict et l’ensemble du code ne le respecte pas entièrement, mais les contributions s’en écartant trop seront rejetées.

• proxy-protocol.txt : il s’agit de la spécification de facto du protocole PROXY, implémentée par HAProxy et un certain nombre de produits tiers.

• security.txt : comment signaler un problème de sécurité, et ce qui constitue ou ne constitue pas une vulnérabilité.

• README : comment compiler HAProxy à partir des sources

5. Contacts

Si vous souhaitez contacter les développeurs ou un membre de la communauté à propos de quoi que ce soit, la meilleure façon de procéder est généralement d’envoyer votre message à la liste de diffusion à l’adresse haproxy@formilux.org . Veuillez noter que cette liste est publique ainsi que ses archives, vous devez donc éviter de divulguer des informations sensibles. Des milliers d’utilisateurs, de tous niveaux d’expérience, y sont présents, et les questions les plus complexes trouvent généralement une réponse optimale relativement rapidement. Les suggestions sont également les bienvenues. Pour les utilisateurs ayant des difficultés avec le courrier électronique, une plateforme Discourse est disponible à l’adresse http://discourse.haproxy.org/ . Toutefois, veuillez garder à l’esprit qu’un nombre réduit de personnes lisent les questions posées là-bas, et que la plupart sont traitées par une équipe extrêmement réduite. Dans tous les cas, veuillez être patient et respectueux envers ceux qui consacrent leur temps libre à aider les autres.

Si vous pensez avoir découvert un bogue mais n’en êtes pas certain, il est préférable de le signaler sur la liste de diffusion. Si vous êtes convaincu d’avoir trouvé un bogue, que votre version est à jour dans sa branche, et que vous disposez déjà d’un compte GitHub, vous pouvez directement vous rendre sur https://github.com/haproxy/haproxy/ et soumettre un problème en incluant toutes les informations disponibles. Encore une fois, cela est public, veillez donc à ne pas publier d’informations que vous pourriez regretter plus tard. Étant donné que le suivi des problèmes s’affiche sous la forme d’un fil très long, évitez de coller des extraits très longs (plusieurs centaines de lignes ou plus) et joignez-les à la place.

Si vous pensez avoir découvert un problème de sécurité, veuillez vous référer au fichier doc/security.txt. Il explique ce qui constitue ou ne constitue pas une vulnérabilité dans HAProxy, ainsi que la procédure à suivre pour signaler une vulnérabilité réelle de manière confidentielle. La plupart des problèmes suspectés s’avèrent être des bogues ordinaires, mieux signalés comme décrit ci-dessus.

Configuration locale complète manuelle

• Guide de démarrage
• Manuel de configuration
• Guide de gestion

Édition provenance

• Édition : HAProxy 3.4.4, balise v3.4.4
• Commit source : 7f03ae65c286
• Version rendue de la documentation : docs.HAProxy.org/3.4/
• Copies locales de la licence : avis de licence HAProxy et GPLv2

10 - 1. Petit rappel sur HTTP

Ce document traite du langage de configuration tel qu’il est implémenté dans la version indiquée ci-dessus. Il ne fournit aucune indication, exemple ou conseil. Pour ce type de documentation, veuillez vous référer au Manuel de référence ou au Manuel d’architecture. Les chapitres numérotés sont ordonnés dans la barre latérale plate de HAProxy pour une navigation directe.

Lorsque HAProxy fonctionne en mode HTTP, la requête et la réponse sont entièrement analysées et indexées, ce qui permet de définir des critères de correspondance sur presque tout élément présent dans leur contenu.

Toutefois, il est essentiel de comprendre comment les requêtes et réponses HTTP sont structurées, ainsi que la manière dont HAProxy les décompose. Il sera alors plus facile d’écrire des règles correctes et de déboguer les configurations existantes.

Tout d’abord, HTTP est standardisé par une série de RFC que HAProxy suit aussi strictement que possible :

• RFC 9110 : Sémantique HTTP (explique le sens des éléments du protocole)
• RFC 9111 : Mise en mémoire tampon HTTP (explique les règles à suivre pour un cache HTTP)
• RFC 9112 : HTTP/1.1 (représentation, règles d’interopérabilité, sécurité)
• RFC 9113 : HTTP/2 (représentation, règles d’interopérabilité, sécurité)
• RFC 9114 : HTTP/3 (représentation, règles d’interopérabilité, sécurité)

En complément de ces éléments, les RFC 8999 à 9002 définissent la couche transport QUIC utilisée par le protocole HTTP/3.

1.1. Le modèle de transaction HTTP

Le protocole HTTP est fondé sur des transactions. Cela signifie qu’une requête entraîne une et une seule réponse. À l’origine, avec la version 1.0 du protocole, il y avait une seule requête par connexion : une connexion TCP est établie depuis le client vers le serveur, le client envoie une requête sur la connexion, le serveur répond, puis la connexion est fermée. Une nouvelle requête nécessite donc une nouvelle connexion :

[CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...

En ce mode, souvent appelé le mode « fermeture HTTP », le nombre d’établissements de connexion correspond au nombre de transactions HTTP. Comme la connexion est fermée par le serveur après la réponse, le client n’a pas besoin de connaître la longueur du contenu ; il considère la réponse comme complète lorsque la connexion se termine. Cela signifie également qu’en cas de troncature de certaines réponses due à des erreurs réseau, le client pourrait à tort considérer qu’une réponse était complète, ce qui pouvait entraîner parfois l’affichage d’images tronquées à l’écran.

En raison de la nature transactionnelle du protocole, il a été possible d’optimiser celui-ci afin d’éviter la fermeture de la connexion entre deux transactions successives. Toutefois, en ce mode, il est obligatoire que le serveur indique la longueur du contenu pour chaque réponse, afin que le client ne reste pas en attente indéfiniment. Pour cela, une en-tête spéciale est utilisée : « Content-length ». Ce mode est appelé le mode « keep-alive », et est apparu avec HTTP/1.1 (certains agents HTTP/1.0 le supportent), et les connexions réutilisées entre requêtes sont appelées des « connexions persistantes » :

[CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...

Ses avantages sont une latence réduite entre les transactions, une charge de traitement moindre côté serveur, et la capacité à détecter une réponse tronquée. Il est généralement plus rapide que le mode close, mais pas toujours, car certains clients limitent souvent leur nombre de connexions simultanées à une valeur plus faible, ce qui compense moins une connectivité réseau médiocre. En outre, certains serveurs doivent maintenir la connexion ouverte longtemps en attendant une éventuelle nouvelle requête et peuvent subir une utilisation mémoire élevée en raison du grand nombre de connexions, et fermer trop rapidement peut interrompre certaines requêtes arrivées au moment où la connexion était fermée.

En ce mode, la taille de la réponse doit être connue à l’avance, ce qui n’est pas toujours possible avec des contenus générés dynamiquement ou compressés. Pour cette raison, un autre mode a été mis en œuvre, le « mode chunké », dans lequel, au lieu d’annoncer la taille totale d’un coup, l’expéditeur indique uniquement la taille du prochain « morceau » de réponse déjà présent dans un tampon, et peut terminer à tout moment avec un morceau de taille nulle. En ce mode, l’en-tête Content-Length n’est pas utilisé.

Une autre amélioration des communications est le mode de pipeline. Il utilise toujours keep-alive, mais le client n’attend pas la première réponse pour envoyer la deuxième requête. Cela est utile pour récupérer un grand nombre d’images composant une page :

[CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...

Cela peut évidemment offrir un bénéfice considérable en performance, car la latence réseau est éliminée entre les requêtes successives. De nombreux agents HTTP ne prennent pas correctement en charge le pipelining, car il n’existe aucun moyen d’associer une réponse à la requête correspondante en HTTP. Pour cette raison, il est obligatoire que le serveur réponde dans le même ordre exact que celui des requêtes reçues. En pratique, après plusieurs tentatives de divers clients pour le mettre en œuvre, il a été complètement abandonné en raison de son manque de fiabilité sur certains serveurs. Toutefois, il est obligatoire que les serveurs le prennent en charge.

L’amélioration suivante est le mode multiplexé, tel qu’il est implémenté dans HTTP/2 et HTTP/3. Plusieurs transactions, c’est-à-dire des paires requête-réponse, sont transmises en parallèle sur une seule connexion et progressent chacune à leur propre rythme. Les protocoles multiplexés ont introduit la notion de « flux » pour représenter ces communications parallèles. Chaque flux reçoit généralement un identifiant unique pour la connexion, utilisé par chaque extrémité pour acheminer les données. Les clients ouvrent couramment de nombreux flux, jusqu’à 100 ou davantage, sur la même connexion et laissent le serveur répondre dans l’ordre de disponibilité. Le multiplexage réduit fortement les allers-retours et accélère le chargement des pages sur les réseaux à forte latence. Sur les sites riches en images, celles-ci semblent alors se charger en parallèle.

Ces protocoles ont également amélioré leur efficacité en adoptant des mécanismes de compression des en-têtes afin de réduire le nombre d’octets transmis sur le réseau. Par conséquent, sans outils appropriés, ils ne sont pas réellement manipulables à la main ni lisibles à l’œil nu, contrairement à HTTP/1. Pour cette raison, divers exemples de messages HTTP continuent d’être représentés dans la littérature (y compris dans ce document) à l’aide de la syntaxe HTTP/1, même pour les versions plus récentes du protocole.

HTTP/2 présente certaines limitations liées à sa conception, telles que les pertes de paquets qui affectent simultanément toutes les flux, et si un client met trop de temps à récupérer un objet (par exemple, s’il doit le stocker sur le disque), cela peut ralentir sa récupération et rendre impossible l’accès aux données en attente derrière celui-ci durant cette période. Ce phénomène est appelé « blocage en tête de file » ou « HoL blocking », ou parfois simplement « HoL ».

HTTP/3 est implémenté sur QUIC, lui-même implémenté sur UDP. QUIC résout le blocage en tête de file au niveau du transport grâce à des flux gérés indépendamment. En effet, en cas de perte de paquets, un flux impacté n’affecte pas les autres flux, qui peuvent tous être accessibles en parallèle. QUIC offre également un support du déplacement de connexion, mais HAProxy ne le prend pas en charge actuellement.

Par défaut, HAProxy utilise le mode keep-alive pour les connexions persistantes : il traite chaque requête et chaque réponse, puis laisse la connexion inactive de part et d’autre entre la fin d’une réponse et le début de la requête suivante. Lorsqu’un client établit une connexion HTTP/2, HAProxy traite les requêtes en parallèle puis laisse la connexion inactive en attendant de nouvelles requêtes, comme pour une connexion HTTP keep-alive.

HAProxy prend en charge essentiellement trois modes de connexion :

• keep-alive : toutes les requêtes et réponses sont traitées, et les connexions côté client ainsi que celles côté serveur sont maintenues ouvertes pour de nouvelles requêtes. Ceci est le comportement par défaut et convient aux web modernes et aux protocoles modernes (HTTP/2 et HTTP/3).

• server close : la connexion côté serveur est fermée après la réponse.

• close : la connexion est activement fermée de part et d’autre après la fin de la réponse.

En complément, par défaut, la connexion orientée serveur est réutilisable par toute requête provenant de n’importe quel client, conformément à la spécification du protocole HTTP, de sorte que toute information relative à un client spécifique doit être transmise avec chaque requête, le cas échéant (par exemple, l’adresse source du client, etc.). Lorsqu’HTTP/2 est utilisé avec un serveur, HAProxy affecte par défaut cette connexion au même client afin d’éviter le risque de blocage en tête de file entre clients.

1.2. Terminologie

À l’intérieur d’HAProxy, la terminologie a évolué au fil du temps pour suivre les évolutions du protocole HTTP et de ses usages. À l’origine, aucune différence significative n’existait entre une connexion, une session, un flux ou une transaction, mais ces termes se sont précisés au fil du temps afin de correspondre étroitement à ce qui existe dans les versions modernes du protocole HTTP, bien que certains termes persistent dans la configuration ou l’interface en ligne de commande afin de préserver la compatibilité historique.

Voici quelques définitions applicables à la version actuelle de HAProxy :

• connection : une connexion est un canal de communication unidirectionnel unique entre un agent distant (client ou serveur) et HAProxy, au niveau le plus bas possible. En général, elle correspond à une socket TCP établie entre une paire d’adresses IP et de ports. Du côté client, les connexions sont les premières entités instanciées lorsqu’un client se connecte à HAProxy, et les règles s’appliquant au niveau de la connexion sont les premières à s’appliquer.

• session : une session ajoute des informations contextuelles associées à une connexion. Cela inclut des informations spécifiques au niveau du transport (par exemple, les clés TLS, etc.) ou des variables. Ce terme est utilisé depuis longtemps dans HAProxy pour désigner les communications HTTP/1.0 bout à bout entre deux extrémités, et il reste visible dans le nom de certaines commandes CLI ou statistiques, même s’il désigne désormais des flux, mais les messages d’aide et les descriptions cherchent à éviter toute ambiguïté. Il reste pertinent dans le cadre de la terminologie au niveau réseau (par exemple, les sessions TCP au sein du système d’exploitation ou les sessions TCP à travers un pare-feu), ou pour les applications utilisateur non HTTP (par exemple, une session telnet ou une session SSH). Il ne doit pas être confondu avec les « sessions applicatives », qui servent à stocker un contexte utilisateur complet dans un cookie et nécessitent d’être envoyées au même serveur.

• stream : un flux correspond exactement à une communication bidirectionnelle point à point au niveau de l’application, où des analyses et des transformations peuvent être appliquées. En HTTP, il contient une seule requête et sa réponse associée, et est instancié à l’arrivée de la requête, se terminant avec la fin de la livraison de la réponse. Dans ce contexte, il existe une relation 1:1 entre un tel flux et le flux d’un protocole multiplexé. En communication TCP, il existe un seul flux par connexion.

• transaction : une transaction n’est qu’une paire constituée d’une requête et de la réponse associée. Ce terme était utilisé en conjonction avec les sessions avant les flux, mais aujourd’hui, une relation 1:1 existe entre une transaction et un flux. Cela est essentiellement visible dans la portée des variables « txn », qui est valable pendant toute la transaction, donc pendant tout le flux.

• requête : elle désigne le trafic allant du client vers le serveur. Elle est principalement utilisée dans le cadre du protocole HTTP pour indiquer où les opérations sont effectuées. Ce terme existe également pour les opérations TCP afin d’indiquer où les données sont traitées. Les requêtes apparaissent souvent dans les compteurs comme unité de trafic ou d’activité. Elles n’impliquent pas toujours de réponse (par exemple en cas d’erreur), mais comme il n’existe pas de réponses spontanées sans requête, les requêtes restent un indicateur pertinent de l’activité globale. En TCP, le nombre de requêtes est égal au nombre de connexions.

• réponse : désigne le trafic circulant du serveur vers le client, ou parfois du serveur HAProxy vers le client, lorsque HAProxy génère lui-même la réponse (par exemple, une redirection HTTP).

• service : cela indique généralement un traitement interne dans HAProxy qui n’exige pas de serveur, comme la page de statistiques, le cache ou un code Lua destiné à implémenter une petite application. Un service lit généralement une requête, effectue certaines opérations et produit une réponse.

1.3. Requête HTTP

Tout d’abord, examinons cette requête HTTP :

Line     Contents
number
   1     GET /serv/login.php?lang=en&profile=2 HTTP/1.1
   2     Host: www.mydomain.com
   3     User-agent: my small browser
   4     Accept: image/jpeg, image/gif
   5     Accept: image/png

1.3.1. Ligne de requête

Ligne 1 est la « ligne de requête ». Elle est toujours composée de 3 champs :

• méthode : GET
• URI : /serv/login.php?lang=en&profile=2
• balise de version : HTTP/1.1

Tous sont délimités par ce que la norme appelle LWS (espaces blancs linéaires), qui sont généralement des espaces, mais peuvent aussi être des tabulations ou des sauts de ligne ou retours chariot suivis d’espaces ou de tabulations. La méthode elle-même ne peut contenir aucun deux-points (’:’) et est limitée aux lettres alphabétiques. Ces différentes combinaisons rendent souhaitable que HAProxy effectue lui-même la séparation plutôt que de laisser l’utilisateur écrire une expression régulière complexe ou inexacte.

L’URI lui-même peut prendre plusieurs formes :

• Une « URI relative » :

  /serv/login.php?lang=en&profile=2

It is a complete URL without the host part. This is generally what is
received by servers, reverse proxies and transparent proxies.

• Un « URI absolu », également appelé « URL » :

  http://192.168.0.12:8080/serv/login.php?lang=en&profile=2

It is composed of a "scheme" (the protocol name followed by '://'), a host
name or address, optionally a colon (':') followed by a port number, then
a relative URI beginning at the first slash ('/') after the address part.
This is generally what proxies receive, but a server supporting HTTP/1.1
must accept this form too.

• étoile (’*’) : cette forme n’est acceptée que dans le cadre de la méthode OPTIONS et n’est pas relaisable. Elle est utilisée pour interroger les fonctionnalités d’un saut suivant.

• une combinaison adresse:port : 192.168.0.12:80. Cette option est utilisée avec la méthode CONNECT, qui permet d’établir des tunnels TCP à travers des proxies HTTP, généralement pour HTTPS, mais parfois aussi pour d’autres protocoles.

Dans une URI relative, deux sous-parties sont identifiées. La partie située avant le point d’interrogation est appelée le « chemin ». Elle correspond généralement au chemin relatif vers des objets statiques sur le serveur. La partie située après le point d’interrogation est appelée la « chaîne de requête ». Elle est principalement utilisée avec les requêtes GET envoyées à des scripts dynamiques et est très spécifique à la langue, au framework ou à l’application utilisés.

HTTP/2 et HTTP/3 ne transmettent pas d’information de version avec la requête, la version est donc supposée être la même que celle du protocole sous-jacent (par exemple, « HTTP/2 »). En outre, ces protocoles n’envoient pas de ligne de requête comme une seule entité, mais la divisent en champs individuels appelés « pseudo-en-têtes », dont le nom commence par deux-points, et qui sont réassemblés de manière pratique par HAProxy en une ligne de requête équivalente. Pour cette raison, les lignes de requête présentes dans les journaux peuvent légèrement différer entre HTTP/1.x et HTTP/2 ou HTTP/3.

1.3.2. Les en-têtes de requête

Les en-têtes commencent à la deuxième ligne. Ils sont composés d’un nom au début de la ligne, immédiatement suivi d’un deux-points (’:’). Traditionnellement, un LWS est ajouté après le deux-points, mais cela n’est pas obligatoire. Ensuite viennent les valeurs. Plusieurs en-têtes identiques peuvent être regroupés sur une seule ligne, les valeurs étant séparées par des virgules, à condition de respecter leur ordre. Cela est couramment observé dans le champ « Cookie: ». Un en-tête peut s’étendre sur plusieurs lignes si les lignes suivantes commencent par un LWS. Dans l’exemple de la section 1.3, les lignes 4 et 5 définissent au total trois valeurs pour l’en-tête « Accept: ». Enfin, tous les LWS situés au début ou à la fin d’un en-tête sont ignorés et ne font pas partie de la valeur, conformément à la spécification.

Contrairement à une idée reçue courante, les noms d’en-tête ne sont pas sensibles à la casse, ni leurs valeurs lorsqu’elles font référence à d’autres noms d’en-tête (comme l’en-tête « Connection: »). En HTTP/2 et HTTP/3, les noms d’en-tête sont toujours envoyés en minuscules, comme on peut le constater en mode débogage. Internalement, tous les noms d’en-tête sont normalisés en minuscules afin que HTTP/1.x, HTTP/2 et HTTP/3 utilisent exactement la même représentation, et ils sont transmis tel quel de l’autre côté. Cela explique pourquoi une requête HTTP/1.x saisie en casse camélisée est livrée en minuscules.

La fin des en-têtes est indiquée par la première ligne vide. On dit souvent qu’il s’agit d’un double saut de ligne, ce qui n’est pas exact, même si un double saut de ligne constitue une forme valide de ligne vide.

Heureusement, HAProxy gère toutes ces combinaisons complexes lors de l’indexation des en-têtes, de la vérification des valeurs et de leur comptage, si bien qu’il n’y a aucune raison de s’inquiéter quant à la manière dont ils peuvent être écrits, mais il est important de ne pas accuser une application de présenter un comportement défectueux si elle effectue des actions inhabituelles, mais valides.

Note importante :

As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
in the middle of headers by LWS in order to join multi-line headers. This
is necessary for proper analysis and helps less capable HTTP parsers to work
correctly and not to be fooled by such complex constructs.

1.4. Réponse HTTP

Une réponse HTTP ressemble beaucoup à une requête HTTP. Ces éléments sont appelés des messages HTTP. Considérons la réponse suivante :

Line     Contents
number
   1     HTTP/1.1 200 OK
   2     Content-length: 350
   3     Content-Type: text/html

En tant que cas particulier, HTTP prend en charge ce qu’on appelle des « réponses informatives » sous forme de codes d’état 1xx. Ces messages sont spéciaux car ils ne transmettent aucune partie de la réponse ; ils servent uniquement de message de signalisation, par exemple pour demander au client de poursuivre l’envoi de sa requête. Dans le cas d’une réponse 100, les informations demandées seront transportées par le message de réponse suivant qui n’est pas un code 100. Cela implique qu’une même requête peut recevoir plusieurs réponses, et que cela ne fonctionne que lorsque le maintien de la connexion est activé (les messages 1xx ont été introduits dans HTTP/1.1). HAProxy gère ces messages et est capable de les acheminer correctement tout en les ignorant, en ne traitant que la prochaine réponse non 100. En conséquence, ces messages ne sont ni journalisés ni transformés, sauf indication contraire explicite. Les réponses 101 indiquent qu’un changement de protocole a lieu sur la même connexion, et que HAProxy doit passer en mode tunnel, comme s’une requête CONNECT avait eu lieu. Dans ce cas, l’en-tête Upgrade contiendra des informations supplémentaires sur le type de protocole vers lequel la connexion effectue la bascule.

1.4.1. Ligne de réponse

Ligne 1 est la « ligne de réponse ». Elle est toujours composée de 3 champs :

• une version d’étiquette : HTTP/1.1
• un code de statut : 200
• une raison : OK

Le code d’état est toujours composé de trois chiffres. Le premier chiffre indique un état général :

• 1xx = message d’information à ignorer (par exemple 100, 101)
• 2xx = OK, le contenu suit (par exemple 200, 206)
• 3xx = OK, aucun contenu ne suit (par exemple 302, 304)
• 4xx = erreur provoquée par le client (par exemple 401, 403, 404)
• 5xx = erreur provoquée par le serveur (par exemple 500, 502, 503)

Les codes d’état supérieurs à 599 ne doivent pas être émis dans les communications, bien que certains agents puissent les produire dans les journaux pour signaler leurs états internes. Veuillez vous référer à RFC9110 pour la signification détaillée de tous ces codes. HTTP/2 et les versions ultérieures ne comportent pas d’étiquette de version et utilisent l’en-tête pseudo « :status » pour rapporter le code d’état.

Le champ « reason » est simplement une indication, mais n’est pas analysé par les clients. Tout peut y être trouvé, mais il est courant de respecter les messages établis. Il peut être composé d’un ou plusieurs mots, tels que « OK », « Found » ou « Authentication Required ». Ce champ n’existe pas en HTTP/2 et versions ultérieures, et n’est pas émis dans ces versions. Lorsqu’une réponse provenant d’HTTP/2 ou d’une version ultérieure est transmise à un client HTTP/1, HAProxy produira un champ raison courant correspondant au code de statut.

HAProxy peut émettre les codes d’état suivants par lui-même :

Code  When / reason
 200  access to stats page, and when replying to monitoring requests
 301  when performing a redirection, depending on the configured code
 302  when performing a redirection, depending on the configured code
 303  when performing a redirection, depending on the configured code
 307  when performing a redirection, depending on the configured code
 308  when performing a redirection, depending on the configured code
 400  for an invalid or too large request
 401  when an authentication is required to perform the action (when
      accessing the stats page)
 403  when a request is forbidden by a "http-request deny" rule
 404  when the requested resource could not be found
 408  when the request timeout strikes before the request is complete
 410  when the requested resource is no longer available and will not
      be available again
 413  when a HTTP/1.0 GET/HEAD/DELETE requests has a payload, also see
      the "h1-accept-payload-with-any-method" option
 500  when HAProxy encounters an unrecoverable internal error, such as a
      memory allocation failure, which should never happen
 501 when HAProxy is unable to satisfy a client request because of an
     unsupported feature
 502  when the server returns an empty, invalid or incomplete response, or
      when an "http-response deny" rule blocks the response.
 503  when no server was available to handle the request, or in response to
      monitoring requests which match the "monitor fail" condition
 504  when the response timeout strikes before the server responds

Les codes d’erreur 4xx et 5xx ci-dessus peuvent être personnalisés (voir “errorloc” dans section 4.2 ). D’autres codes d’état peuvent être émis intentionnellement par des actions spécifiques (voir les actions “deny”, “return” et “redirect” dans section 4.3 par exemple).

1.4.2. Les en-têtes de réponse

Les en-têtes de réponse fonctionnent exactement comme les en-têtes de requête ; HAProxy utilise donc la même fonction pour les analyser. Reportez-vous au paragraphe 1.3.2 pour plus de détails.

11 - 2. Configuration de HAProxy

2.1. Format du fichier de configuration

Le processus de configuration d’HAProxy repose sur 3 sources majeures de paramètres :

• les arguments en ligne de commande, qui ont toujours la priorité
• le(s) fichier(s) de configuration, dont le format est décrit ici
• l’environnement du processus en cours d’exécution, en cas de référence explicite à certaines variables d’environnement

Le fichier de configuration suit un format hiérarchique assez simple qui obéit à quelques règles fondamentales :

1. a configuration file is an ordered sequence of statements

2. a statement is a single non-empty line before any unprotected "#" (hash)

3. a line is a series of tokens or "words" delimited by unprotected spaces or
   tab characters

4. the first word or sequence of words of a line is one of the keywords or
   keyword sequences listed in this document

5. all other words are all arguments of the first one, some being well-known
   keywords listed in this document, others being values, references to other
   parts of the configuration, or expressions

6. certain keywords delimit a section inside which only a subset of keywords
   are supported

7. a section ends at the end of a file or on a special keyword starting a new
   section

C’est tout ce qu’il faut savoir pour écrire un générateur de configuration simple mais fiable, mais cela ne suffit pas à analyser de manière fiable n’importe quelle configuration ni à déterminer comment traiter certains cas limites.

Tout d’abord, plusieurs conséquences découlent des règles ci-dessus. La règle 6 et la règle 7 impliquent que les mots-clés utilisés pour définir une nouvelle section sont valables partout et ne peuvent avoir une signification différente dans une section spécifique. Ces mots-clés sont toujours un seul mot (contrairement à une suite de mots), et la section qui suit traditionnellement porte le même nom. Par exemple, lorsqu’on parle de la « section global », cela désigne la section de configuration qui suit le mot-clé « global ». Cette convention est fréquemment utilisée dans les messages d’erreur afin d’aider à localiser les parties à corriger.

Plusieurs sections créent un objet interne ou un espace de configuration, qui doit être distingué des autres. Dans ce cas, elles incluent un mot supplémentaire définissant le nom de cette section particulière. Pour certaines d’entre elles, le nom de section est obligatoire. Par exemple, « frontend foo » crée une nouvelle section de type « frontend » nommée « foo ». En général, un nom est spécifique à sa section, et deux sections de types différents peuvent utiliser le même nom, mais cela n’est pas recommandé car cela complique la gestion de la configuration.

Une conséquence directe de la règle 7 est que, lorsqu’un nombre de fichiers est lu simultanément, chacun d’eux doit commencer par une nouvelle section, et la fin de chaque fichier marque la fin d’une section. Un fichier ne peut pas contenir de sous-sections ni terminer une section existante tout en en commençant une nouvelle.

Règle 1 indique que l’ordre a de l’importance. En effet, certains mots-clés créent des directives pouvant être répétées plusieurs fois afin de former des séquences ordonnées de règles à appliquer dans un ordre précis. Par exemple, « tcp-request » peut être utilisé pour alterner des règles « accept » et « reject » selon des critères variés. En conséquence, un processeur de fichier de configuration doit toujours conserver l’ordre d’une section lors de l’édition d’un fichier. L’ordre des sections ne compte généralement pas, sauf pour la section globale, qui doit être placée avant les autres sections, bien qu’elle puisse être répétée si nécessaire. En outre, certains identifiants automatiques peuvent être attribués automatiquement à certains objets créés (par exemple, des proxies), et en réorganisant les sections, leurs identifiants changeront. Ces identifiants apparaissent par exemple dans les statistiques. Ainsi, la configuration ci-dessous attribuera à « foo » un numéro d’identifiant inférieur à celui de son homologue « bar ». Cet ordre sera inversé si les deux sections sont échangées :

listen foo
    bind:80

listen bar
    bind:81

Un autre point important est que, conformément aux règles 2 et 3 ci-dessus, les lignes vides, espaces, tabulations et commentaires suivant le caractère non protégé “#” ne font pas partie de la configuration, car ils ne servent qu’à délimiter les éléments. Cela implique que les configurations suivantes sont strictement équivalentes :

    global#this is the global section
daemon#daemonize
    frontend         foo
mode             http   # or tcp

et :

global
    daemon

# this is the public web frontend
frontend foo
    mode http

La pratique courante consiste à aligner à gauche uniquement le mot-clé qui introduit une nouvelle section, et à insérer des espaces (c’est-à-dire préfixer un caractère de tabulation ou quelques espaces) pour les autres mots-clés afin qu’il soit immédiatement visible qu’ils appartiennent à la même section (comme dans l’exemple ci-dessus). Placer des commentaires avant une nouvelle section aide le lecteur à déterminer s’il s’agit de la section souhaitée. Laisser une ligne vide à la fin d’une section aide également visuellement à repérer sa fin lors de son édition.

Les tabulations sont très pratiques pour la mise en retrait, mais elles ne se copient pas bien. Si l’on utilise des espaces à la place, il est recommandé d’en éviter un trop grand nombre (de 2 à 4) afin que l’édition dans le champ ne devienne pas une contrainte avec les éditeurs limités ne prenant pas en charge l’indentation automatique.

Dans les premiers temps, il était courant de voir les arguments séparés à des positions de tabulation fixes, car la plupart des mots-clés ne prenaient pas plus de deux arguments. Avec les versions modernes, qui intègrent des expressions complexes, cette pratique n’est plus valable et n’est pas recommandée.

2.2. Citation et échappement

Dans les configurations modernes, certains arguments exigent l’utilisation de caractères qui étaient auparavant considérés comme des délimiteurs purs. Afin de rendre cela possible, HAProxy prend en charge l’échappement des caractères en préfixant le caractère à échapper d’une barre oblique inverse (’\’), la citation faible en entourant un morceau de texte de guillemets doubles ("") et la citation forte en entourant un morceau de texte de guillemets simples (’’).

Cela ressemble fortement à ce qui est fait dans plusieurs langages de programmation et est très proche de ce qu’on rencontre couramment dans le shell Bourne. Le principe est le suivant : pendant que le parseur de configuration découpe les lignes en mots, il prend également en compte les guillemets et les barres obliques inversées pour déterminer si un caractère est un séparateur ou la représentation brute de ce caractère dans le mot courant. Lorsque cela est fait, le caractère d’échappement est supprimé, les guillemets sont supprimés, et le mot restant est utilisé tel quel comme mot-clé ou argument, par exemple.

Si une barre oblique inverse est nécessaire dans un mot, elle doit soit être échappée en utilisant elle-même (c’est-à-dire une barre oblique inverse en double), soit être fortement citée.

La sortie des guillemets est obtenue en précédant un caractère spécial d’un backslash (\):

\    to mark a space and differentiate it from a delimiter
\#   to mark a hash and differentiate it from a comment
\\   to use a backslash
\'   to use a single quote and differentiate it from strong quoting
\"   to use a double quote and differentiate it from weak quoting

En outre, quelques caractères non imprimables peuvent être émis en utilisant leur représentation habituelle en langage C :

\n   to insert a line feed (LF, character \x0a or ASCII 10 decimal)
\r   to insert a carriage return (CR, character \x0d or ASCII 13 decimal)
\t   to insert a tab (character \x09 or ASCII 9 decimal)
\xNN to insert character having ASCII code hex NN (e.g \x0a for LF).

La citation faible est obtenue en entourant de guillemets doubles ("") le caractère ou la séquence de caractères à protéger. La citation faible empêche l’interprétation de :

     space or tab as a word separator
'    single quote as a strong quoting delimiter

#    hash as a comment start

La citation faible permet l’interprétation des variables d’environnement (qui ne sont pas évaluées en dehors des guillemets) en les précédant d’un signe dollar (’$’). Si un caractère dollar est nécessaire à l’intérieur de guillemets doubles, il doit être échappé à l’aide d’une barre oblique inverse.

Une citation forte est obtenue en entourant les caractères ou la séquence de caractères à protéger de guillemets simples (’’). À l’intérieur des guillemets simples, aucun caractère n’est interprété ; il s’agit de la méthode la plus efficace pour citer des expressions régulières.

En conséquence, voici la matrice indiquant comment les caractères spéciaux peuvent être saisis dans différents contextes (les caractères non imprimables sont remplacés par leur nom entre chevrons). Notez que certains caractères qui ne peuvent être représentés qu’avec une échappement n’ont aucune représentation possible entre guillemets simples, d’où leur absence dans ce cas :

  Character  |  Unquoted     |  Weakly quoted              |  Strongly quoted
  -----------+---------------+-----------------------------+-----------------
    <TAB>    |  \<TAB>, \x09 |  "<TAB>", "\<TAB>", "\x09"  |  '<TAB>'
  -----------+---------------+-----------------------------+-----------------
    <LF>     |  \n, \x0a     |  "\n", "\x0a"               |
  -----------+---------------+-----------------------------+-----------------
    <CR>     |  \r, \x0d     |  "\r", "\x0d"               |
  -----------+---------------+-----------------------------+-----------------
    <SPC>    |  \<SPC>, \x20 |  "<SPC>", "\<SPC>", "\x20"  |  '<SPC>'
  -----------+---------------+-----------------------------+-----------------
    "        |  \", \x22     |  "\"", "\x22"               |  '"'
  -----------+---------------+-----------------------------+-----------------
    #        |  \#, \x23     |  "#", "\#", "\x23"          |  '#'
  -----------+---------------+-----------------------------+-----------------
    $        |  $, \$, \x24  |  "\$", "\x24"               |  '$'
  -----------+---------------+-----------------------------+-----------------
    '        |  \', \x27     |  "'", "\'", "\x27"          |
  -----------+---------------+-----------------------------+-----------------
    \        |  \\, \x5c     |  "\\", "\x5c"               |  '\'
  -----------+---------------+-----------------------------+-----------------

Exemple :

# those are all strictly equivalent:
log-format %{+Q}o\ %t\ %s\ %{-Q}r
log-format "%{+Q}o %t %s %{-Q}r"
log-format '%{+Q}o %t %s %{-Q}r'
log-format "%{+Q}o %t"' %s %{-Q}r'
log-format "%{+Q}o %t"' %s'\ %{-Q}r

Il existe un cas particulier où une deuxième niveau de citation ou d’échappement peut être nécessaire. Certains mots-clés prennent des arguments entre parenthèses, parfois séparés par des virgules. Ces arguments sont généralement des entiers ou des mots prédéfinis, mais lorsqu’ils sont des chaînes arbitraires, il peut être nécessaire d’effectuer un niveau d’échappement supplémentaire afin de distinguer les caractères appartenant à l’argument de ceux utilisés pour délimiter les arguments eux-mêmes. Un cas assez courant est le convertisseur « regsub ». Il prend une expression régulière en argument, et si une parenthèse fermante est nécessaire à l’intérieur, celle-ci devra être elle-même citée.

L’analyseur d’arguments en mot-clé est identique à celui du niveau supérieur en ce qui concerne les guillemets, à ceci près que les séquences d’échappement \#, \$, et \xNN ne sont pas traitées. Mais ce qui n’est pas toujours évident, c’est que les délimiteurs utilisés à l’intérieur doivent d’abord être échappés ou mis entre guillemets afin qu’ils ne soient pas résolus au niveau supérieur.

Prenons cet exemple utilisant le convertisseur « regsub », qui prend trois arguments : une expression régulière, une chaîne de remplacement et un ensemble d’indicateurs :

# replace all occurrences of "foo" with "blah" in the path:
http-request set-path %[path,regsub(foo,blah,g)]

Ici, aucune citation particulière n’était nécessaire. Mais si nous voulons maintenant remplacer soit « foo » soit « bar » par « blah », nous devrons utiliser l’expression régulière « (foo|bar) ». Nous ne pouvons pas écrire :

http-request set-path %[path,regsub((foo|bar),blah,g)]

car nous souhaitons que la chaîne soit coupée de cette manière :

    http-request set-path %[path,regsub((foo|bar),blah,g)]
                                       |---------|----|-|
                                 arg1 _/         /    /
                                 arg2 __________/    /
                                 arg3 ______________/

mais en réalité ce qui est transmis est une chaîne entre les parenthèses d’ouverture et de fermeture, suivie de déchets :

    http-request set-path %[path,regsub((foo|bar),blah,g)]
                                       |--------|--------|
                        arg1=(foo|bar _/        /
                    trailing garbage  _________/

La solution évidente semble ici être de citer le parenthèse fermante, mais cela ne fonctionnera pas seul, car, comme mentionné ci-dessus, les guillemets sont traités par l’analyseur de niveau supérieur, qui les résout avant le traitement de ce mot :

http-request set-path %[path,regsub("(foo|bar)",blah,g)]
------------ -------- ----------------------------------
   word1       word2    word3=%[path,regsub((foo|bar),blah,g)]

Ainsi, nous n’avons apporté aucune modification au parseur d’arguments au second niveau, qui continue de voir une expression régulière tronquée comme seul argument, ainsi que des données aléatoires à la fin de la chaîne. En échappant les guillemets, ceux-ci seront transmis inchangés au second niveau :

    http-request set-path %[path,regsub(\"(foo|bar)\",blah,g)]
    ------------ -------- ------------------------------------
       word1       word2    word3=%[path,regsub("(foo|bar)",blah,g)]
                                                |---------||----|-|
                                arg1=(foo|bar) _/          /    /
                                    arg2=blah  ___________/    /
                                        arg3=g _______________/

Une autre approche consiste à utiliser des guillemets simples à l’extérieur de toute la chaîne et des guillemets doubles à l’intérieur (afin que les guillemets doubles ne soient pas supprimés à nouveau) :

    http-request set-path '%[path,regsub("(foo|bar)",blah,g)]'
    ------------ --------  ----------------------------------
       word1       word2    word3=%[path,regsub("(foo|bar)",blah,g)]
                                                |---------||----|-|
                                arg1=(foo|bar) _/          /    /
                                          arg2 ___________/    /
                                          arg3 _______________/

Mais dans ce cas, il est important de noter que les délimiteurs intégrés dans la chaîne de niveau supérieur restent des caractères purs et ne sont plus des délimiteurs. Cela signifie notamment que les espaces et tabulations autour des virgules font partie de la chaîne. L’exemple ci-dessous est erroné pour plusieurs raisons :

    http-request set-path '%[path, regsub("(foo|bar)", blah, g)]'
    ------------ --------  --------------------------------------
       word1       word2    word3=%[path, regsub("(foo|bar)", blah, g)]
                                        |--------|---------||-----|--|
                       converter=" regsub" _/        /         /   /
                                    arg1=(foo|bar) _/         /   /
                                     arg2=" blah" ___________/   /
                                        arg3=" g" ______________/

Le simple fait d’entourer les virgules d’espaces a fait que ces espaces faisaient partie du champ lui-même, d’où la conversion « regsub » (commençant par un espace), qui ne sera pas trouvée et déclenchera une erreur, mais de manière plus subtile, la chaîne de remplacement « blah » insérera un espace dans la sortie. Une bonne règle générale consiste à ne jamais insérer d’espaces inutiles à l’intérieur des expressions.

Lorsque l’on utilise des expressions régulières, il peut arriver que le caractère dollar (’$’) apparaisse dans l’expression ou qu’une barre oblique inverse (’\’) soit utilisée dans la chaîne de remplacement. Dans ce cas, celles-ci seront également traitées à l’intérieur des guillemets doubles, d’où la préférence pour les guillemets simples (ou l’échappement double). Exemple :

    http-request set-path '%[path,regsub("^/(here)(/|$)","my/\1",g)]'
    ------------ --------  -----------------------------------------
       word1       word2    word3=%[path,regsub("^/(here)(/|$)","my/\1",g)]
                                                |-------------| |-----||-|
                              arg1=(here)(/|$) _/               /      /
                                    arg2=my/\1 ________________/      /
                                          arg3 ______________________/

Souvenez-vous que les barres obliques inverses ne sont pas des caractères d’échappement entre guillemets simples, et que tout le mot ci-dessus est déjà protégé contre elles grâce aux guillemets simples. À l’inverse, si des guillemets doubles avaient été utilisés autour de l’expression entière, le caractère dollar et les barres obliques auraient été résolus au niveau supérieur, rompant ainsi le contenu de l’argument au second niveau.

Malheureusement, comme les guillemets simples ne peuvent pas être échappés à l’intérieur d’une citation forte, si vous devez inclure des guillemets simples dans votre argument, vous devrez les échapper ou les citer deux fois. Il existe plusieurs façons de procéder :

http-request set-var(txn.foo) str("\\'foo\\'")
http-request set-var(txn.foo) str(\"\'foo\'\")
http-request set-var(txn.foo) str(\\\'foo\\\')

En cas de doute, il est préférable de ne jamais utiliser de guillemets, puis d’ajouter des guillemets simples ou doubles autour des arguments nécessitant une virgule ou une parenthèse fermante, en envisageant d’échapper ces guillemets à l’aide d’un backslash si la chaîne contient un dollar ou un backslash. Encore une fois, cela ressemble fortement à ce qui est utilisé sous un shell Bourne lorsqu’on échappe deux fois une commande passée à « eval ». Pour les auteurs d’API, la meilleure approche consiste probablement à entourer chaque argument d’un guillemet échappé, quelle que soit sa teneur. Les utilisateurs constateront probablement que l’utilisation de guillemets simples autour de l’expression entière et de guillemets doubles autour de chaque argument rend les configurations plus lisibles.

2.3. Variables d’environnement

La configuration d’HAProxy prend en charge les variables d’environnement. Ces variables ne sont interprétées qu’à l’intérieur de guillemets doubles. Les variables sont étendues pendant l’analyse de la configuration. Les noms de variables doivent être précédés du signe dollar ("$") et éventuellement entourés d’accolades ("{}"), de manière similaire à ce qui est fait dans le shell Bourne. Les noms de variables peuvent contenir des caractères alphanumériques ou le caractère souligné ("_"), mais ne doivent pas commencer par un chiffre. Si la variable contient une liste de plusieurs valeurs séparées par des espaces, elle peut être étendue en arguments individuels en entourant la variable d’accolades et en ajoutant le suffixe ‘[*]’ avant la fermeture de l’accolade. Il est également possible de spécifier une valeur par défaut à utiliser lorsque la variable n’est pas définie, en ajoutant cette valeur après un trait de soulignement ‘-’ à côté du nom de la variable. Notez que la valeur par défaut ne remplace que les variables non définies, pas les variables vides.

Exemple :

bind "fd@${FD_APP1}"

log "${LOCAL_SYSLOG-127.0.0.1}:514" local0 notice  # send to local server

user "$HAPROXY_USER"

Certains variables sont définis par HAProxy, ils peuvent être utilisés dans le fichier de configuration. Ces variables sont listées dans le tableau ci-dessous et sont classées selon quatre catégories :

• utilisable : la variable est accessible à partir de la configuration, soit pour être résolue telle quelle, soit utilisée dans des blocs conditionnels ou des prédicats afin d’activer ou de désactiver certains fragments de configuration, comme décrit dans section 2.4 « Blocs conditionnels ».

• modifiable : la variable peut être redéfinie ou supprimée dans la configuration via les mots-clés “setenv”/“unsetenv”.

• répertorié : la variable est répertoriée dans la sortie de la commande CLI “show env”, décrite dans la section 9.3 “Commandes sockets Unix” du guide de gestion.

Il existe également deux sous-catégories, « master » et « worker », marquées respectivement par « M » et « W » dans le tableau ci-dessous, illustrant les différences entre les deux processus lorsque HAProxy est lancé en mode master-worker.

• master : la variable est définie et accessible depuis le processus principal. Elle apparaît donc dans la sortie de la commande CLI du processus principal « show env » et peut être utilisée dans des blocs conditionnels ou des directives afin d’activer certaines configurations spéciales pour le processus principal (voir les exemples dans la section 2.4 « Blocs conditionnels »).

• worker : la variable est définie et accessible depuis le processus worker. Elle apparaît dans la commande “show env” de l’interface CLI du worker (ou de l’interface CLI principale avec “@1 show env”), et peut également conditionner certains paramètres du processus worker (voir les exemples dans la section 2.4 “Blocs conditionnels”).

En mode autonome (sans l’option “-W” ni le mot-clé “master-worker”), le processus se comporte comme un worker, à l’exception des variables “HAPROXY_MASTER_CLI” et “HAPROXY_MWORKER” qui ne sont pas définies.

Certains variables sont marqués comme non utilisables et non modifiables :

• FICHIERS_DE_CONFIG_HAPROXY
• TRAVAILLEUR_M_HAPROXY
• CLI_HAPROXY
• CLI_PRIMAIRE_HAPROXY
• PAIR_LOCAL_HAPROXY

Leurs valeurs sont indéfinies pendant l’analyse de la configuration ; elles sont définies ultérieurement lors de l’initialisation. Il est donc recommandé de ne pas utiliser ces variables au sein de blocs conditionnels, ni de les référencer dans les mots-clés “setenv”/“resetenv”/“unsetenv” de la section globale.

Le tableau ci-dessous résume l’état de chaque variable pour les différents modes de fonctionnement :

  +---------------------------+---------+------------+-----------+
  |          variable         | usable  | modifiable |  listed   |
  |                           +---------+------------+-----------+
  |                           |  M | W  |   M  |  W  |  M  |  W  |
  +---------------------------+----+----+------+-----+-----+-----+
  | HAPROXY_STARTUP_VERSION   |  X | X  |      |     |  X  |  X  |
  | HAPROXY_BRANCH            |  X | X  |      |     |  X  |  X  |
  | HAPROXY_CFGFILES          |    |    |      |     |  X  |  X  |
  | HAPROXY_MWORKER           |    |    |      |     |  X  |  X  |
  | HAPROXY_CLI               |    |    |      |     |     |  X  |
  | HAPROXY_MASTER_CLI        |    |    |      |     |  X  |     |
  | HAPROXY_LOCALPEER         |    | X  |      |     |     |  X  |
  | HAPROXY_HTTP_LOG_FMT      |    | X  |      |  X  |     |     |
  | HAPROXY_HTTP_CLF_LOG_FMT  |    | X  |      |  X  |     |     |
  | HAPROXY_HTTPS_LOG_FMT     |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_LOG_FMT       |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_CLF_LOG_FMT   |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_FC_LOG_FMT |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_BC_LOG_FMT |    | X  |      |  X  |     |     |
  +---------------------------+----+----+------+-----+-----+-----+

Les variables en question sont les suivantes :

• HAPROXY_LOCALPEER : défini au démarrage du processus et contient le nom de l’homologue local. (Voir “-L” dans le guide d’administration.)

• HAPROXY_CFGFILES : liste des fichiers de configuration chargés par HAProxy, séparés par des points-virgules. Peut être utile dans le cas où vous avez spécifié un répertoire.

• HAPROXY_HTTP_LOG_FMT : contient la valeur du format de journalisation HTTP par défaut tel qu défini dans la section 8.2.3 « Format de journalisation HTTP ». Il peut être utilisé pour remplacer le format de journalisation par défaut sans avoir à copier l’ensemble de la définition originale.

• HAPROXY_HTTP_CLF_LOG_FMT : contient la valeur du format de journalisation HTTP CLF par défaut, tel qu défini dans la section 8.2.3 « Format de journalisation HTTP ». Il peut être utilisé pour remplacer le format de journalisation par défaut sans avoir à copier toute la définition originale.

Exemple :

# Add the rule that gave the final verdict to the log
log-format "${HAPROXY_TCP_LOG_FMT} lr=%[last_rule_file]:%[last_rule_line]"

• HAPROXY_HTTPS_LOG_FMT : similaire à HAPROXY_HTTP_LOG_FMT mais pour le format des journaux HTTPS tel qu’il est défini dans section 8.2.4 “Format des journaux HTTPS”.

• HAPROXY_TCP_LOG_FMT : similaire à HAPROXY_HTTP_LOG_FMT mais pour le format des journaux TCP tel qu défini dans la section 8.2.2 « Format des journaux TCP ».

• HAPROXY_TCP_CLF_LOG_FMT : similaire à HAPROXY_HTTP_CLF_LOG_FMT mais pour le format de journalisation TCP CLF tel qu défini dans la section 8.2.2 « Format de journalisation TCP ».

• HAPROXY_KEYLOG_FC_LOG_FMT : contient le format de journalisation des clés pour la connexion TLS du frontend (face client), avec les entrées de clés séparées par des sauts de ligne, ce qui peut entraîner une incompatibilité avec votre serveur syslog. “tune.ssl.keylog on” est obligatoire.

• HAPROXY_KEYLOG_BC_LOG_FMT : similaire à HAPROXY_KEYLOG_FC_LOG_FMT mais destiné à la connexion TLS côté backend (vers le serveur). Les entrées clés sont séparées par des sauts de ligne, ce qui peut entraîner une incompatibilité avec votre serveur syslog. “tune.ssl.keylog on” est obligatoire.

• HAPROXY_MWORKER : En mode master-worker, cette variable est définie à 1.

• HAPROXY_CLI : adresses des écouteurs configurés pour le socket de statistiques de chaque processus, séparées par des points-virgules.

• HAPROXY_MASTER_CLI : En mode master-worker, les adresses des écouteurs de l’interface CLI principale, séparées par des points-virgules.

• HAPROXY_STARTUP_VERSION : contient la version utilisée au démarrage, en mode master-worker, il s’agit de la version utilisée pour démarrer le master, même après mise à jour du binaire et rechargement.

• HAPROXY_BRANCH : contient la version de branche d’HAProxy (par exemple “2.8”). Il ne contient pas le numéro de version complet. Il peut être utile en cas de migration si les ressources (par exemple des cartes ou des certificats) sont situées dans un chemin contenant le numéro de branche.

En outre, certaines variables pseudo sont résolues internement et peuvent être utilisées comme des variables régulières. Les variables pseudo commencent toujours par un point (’.’), et ce sont les seules où l’utilisation du point est autorisée. La liste actuelle des variables pseudo est :

• .FICHIER : le nom du fichier de configuration actuellement en cours d’analyse.

• .LINE : le numéro de ligne du fichier de configuration actuellement analysé, commençant à un.

• .SECTION : le nom de la section actuellement analysée, ou son type si la section n’a pas de nom (par exemple « global »), ou une chaîne vide avant la première section.

Ces variables sont résolues à l’emplacement où elles sont analysées. Par exemple, si une variable “.LINE” est utilisée dans une directive « log-format » située dans une section « defaults », son numéro de ligne sera résolu avant l’analyse et la compilation de la directive « log-format », de sorte que ce même numéro de ligne sera réutilisé par les proxies ultérieurs.

Ainsi, il est possible d’émettre des informations afin d’aider à localiser une règle dans des variables, des journaux, des états d’erreur, des contrôles d’état, des valeurs d’en-tête, voire d’utiliser des numéros de ligne pour nommer certains objets de configuration, comme des serveurs par exemple.

2.4. Blocs conditionnels

Il peut parfois être pratique de pouvoir activer ou désactiver conditionnellement certaines parties arbitraires de la configuration, par exemple pour activer/désactiver le SSL ou les chiffres, activer ou désactiver certains écouteurs en pré-production sans modifier la configuration, ou ajuster la syntaxe de la configuration pour prendre en charge deux versions distinctes d’HAProxy pendant une migration. HAProxy fournit un ensemble de directives imbriquables du type préprocesseur, permettant d’intégrer ou d’ignorer certains blocs de texte. Ces directives doivent être placées sur une ligne à part et agissent sur les lignes qui les suivent. Deux d’entre elles prennent une expression, les autres ne font que basculer vers un bloc alternatif ou terminer un niveau actuel. Les 4 directives suivantes sont définies pour former des blocs conditionnels :

• .si <condition>
• .sinon_si <condition>
• .sinon
• .fin_si

La directive “.if” introduit un nouveau niveau, “.elif” reste au même niveau, “.else” également, et “.endif” ferme un niveau. Chaque “.if” doit être terminée par une directive “.endif” correspondante. La directive “.elif” ne peut être placée qu’après “.if” ou “.elif”, et il n’y a pas de limite au nombre de “.elif” pouvant être enchaînés. Il ne peut y avoir qu’une seule “.else” par “.if” et elle doit toujours être placée après “.if” ou après le dernier “.elif” d’un bloc.

Les commentaires peuvent être placés sur la même ligne si nécessaire, après un ‘#’, ils seront ignorés. Les directives sont tokenisées comme les autres directives de configuration, et il est donc possible d’utiliser des variables d’environnement dans les conditions.

Les conditions peuvent également être évaluées au démarrage grâce au paramètre -cc. Voir « 3. Démarrage de HAProxy » dans la documentation de gestion.

Les conditions sont soit une chaîne vide (qui renvoie alors false), soit une expression composée de toute combinaison de :

• l’entier zéro (‘0’), retourne toujours « false »
• un entier non nul (par exemple ‘1’), retourne toujours « true ».
• une prédicat suivie éventuellement de paramètre(s) entre parenthèses.
• une condition placée entre une paire de parenthèses ‘(’ et ‘)’
• un point d’exclamation (’!’) placé avant l’un quelconque des éléments ci-dessus non vides, qui inverse son état.
• des expressions combinées par une opération ET logique (’&&’), évaluées de gauche à droite jusqu’à ce qu’une retourne « false »
• des expressions combinées par une opération OU logique (’||’), évaluées de droite à gauche jusqu’à ce qu’une retourne « true »

Le même analyseur de lignes et parseur d’arguments est utilisé que pour le reste du langage de configuration. Les mots sont séparés autour de séries consécutives d’un ou plusieurs espaces ou tabulations non entre guillemets, puis réassemblés en utilisant un seul espace pour les séparer avant évaluation, afin de simplifier la tâche de l’utilisateur qui n’a pas à entourer toute la ligne de guillemets. Toutefois, cela signifie également que les espaces entourant les virgules ou les parenthèses font bien partie de la valeur, ce qui n’est pas toujours attendu. Par exemple, l’expression suivante :

.if defined( HAPROXY_MWORKER )

testera l’existence de la variable « HAPROXY_MWORKER » (avec des espaces), et celle-ci :

.if streq("$ENABLE_SSL",     1)

comparera la variable d’environnement “ENABLE_SSL” à la valeur « 1 » (avec un seul espace initial). La raison est que la ligne est d’abord divisée en mots de cette manière :

   .if streq("$ENABLE_SSL",     1)
  |---|--------------------|   |--|
    1           2               3

puis la citation faible est appliquée et la variable d’environnement “$ENABLE_SSL” est résolue (par exemple, supposons que ENABLE_SSL=0), avant que les mots ne soient finalement réassemblés en une chaîne unique en insérant un seul espace entre les mots :

   .if streq(0, 1)
  |---|-------|--|
    1     2     3

et uniquement alors est-il analysé comme une expression unique. L’espace inséré entre la virgule et « 1 » fait toujours partie de la valeur de l’argument, rendant cet argument « 1 » :

   .if streq(0, 1)
  |---|-----|-|--|
    \    \    \  \_ argument2: " 1"
     \    \    \___ argument1: "0"
      \    \_______ function: "streq"
       \___________ directive: ".if"

On constate ici que, même si ENABLE_SSL avait été égal à « 1 », il n’aurait pas correspondu à « 1 » car la chaîne aurait différé d’un espace.

Note : comme expliqué dans la section « 2.2. Citation et échappement », une bonne règle de base consiste à ne jamais insérer d’espaces inutiles à l’intérieur des expressions.

Notez que, comme dans d’autres langages, l’opérateur ET a une priorité supérieure à celle de l’opérateur OU, de sorte que « A && B || C && D » est évalué comme « (A && B) || (C && D) ».

La liste des prédicats actuellement pris en charge est la suivante :

• awslc_api_atleast(<ver>): retourne true si le numéro actuel de l’API awslc est au moins aussi récent que <ver> sinon false. Exemple : awslc_api_atleast(35)

• awslc_api_before(<ver>): renvoie true si le numéro actuel de l’API awslc est strictement inférieur à <ver> sinon false. Exemple : awslc_api_before(26)

• defined(<name>) : renvoie true si une variable d’environnement <name> existe, quelle que soit sa valeur

• feature(<name>) : renvoie true si la fonction <name> est indiquée comme présente dans la liste des fonctions signalées par “haproxy -vv” (ce qui signifie qu’un <name> apparaît après un ‘+’)

• openssl_version_atleast(<ver>): retourne true si la version actuelle d’OpenSSL est au moins aussi récente que <ver>, sinon false. Des bibliothèques comme LibreSSL, AWS-LC et WolfSSL fournissent également une version pseudo-OpenSSL. Exemple :

ssllib_name_startswith(OpenSSL) && openssl_version_atleast(1.1.1)

• openssl_version_before(<ver>): renvoie true si la version OpenSSL actuelle est strictement antérieure à <ver>, sinon false. Des bibliothèques comme LibreSSL, AWS-LC et WolfSSL fournissent également une version pseudo-OpenSSL. Exemple : openssl_version_before(3.5.0)

• ssllib_name_startswith(<name>) : renvoie true si le nom de la bibliothèque SSL avec laquelle HAProxy a été lié commence par <name>. Exemple : ssllib_name_startswith(wolfSSL)

• streq(<str1>,<str2>) : renvoie true uniquement si les deux chaînes sont égales

• strneq(<str1>,<str2>): renvoie true uniquement si les deux chaînes diffèrent

• strstr(<str1>,<str2>): renvoie true uniquement si la deuxième chaîne est trouvée dans la première.

• version_atleast(<ver>): renvoie true si la version actuelle de HAProxy est au moins aussi récente que <ver>, sinon false. La syntaxe des versions est la même que celle affichée par la commande “haproxy -v”, et les composantes manquantes sont supposées valoir zéro.

• version_before(<ver>): renvoie true si la version actuelle de HAProxy est strictement antérieure à <ver> sinon false. La syntaxe des versions est identique à celle affichée par la commande “haproxy -v” et les composantes manquantes sont supposées valoir zéro.

• enabled(<opt>) : retourne true si l’option <opt> est activée en cours d’exécution. Seul un sous-ensemble d’options est pris en charge :

POLL, EPOLL, KQUEUE, EVPORTS, SPLICE,
GETADDRINFO, REUSEPORT, FAST-FORWARD,
SERVER-SSL-VERIFY-NONE

Exemple :

# 1. HAPROXY_MWORKER variable is set automatically by HAProxy in master and
# in worker process environments (see HAProxy variables matrix from
# 2.3. Environment variables). Its presence enables an additional listener.

global
  master-worker

.if defined(HAPROXY_MWORKER) listen mwcli_px bind:1111 … .endif

# 2. HAPROXY_BRANCH is set automatically by HAProxy in master and in worker
# process environments (see HAProxy variables matrix from 2.3. Environment
# variables). We check HAPROXY_BRANCH value and conditionally enable
# mworker-max-reloads parameter.

global
  master-worker

.if streq("$HAPROXY_BRANCH",3.1) mworker-max-reloads 5 .endif

# 3. Some arbitrary environment variables are set by user in the global
# section. If HAProxy is started in master-worker mode, they are presented in
# master and in worker process environments. We check values of these
# variables and conditionally enable ports 80 and 443. Environment variables
# checks can be mixed with features and version checks.

global
  setenv WITH_SSL yes
  unsetenv SSL_ONLY

.if strneq("$SSL_ONLY",yes) bind:80 .endif

.if streq("$WITH_SSL",yes) .if feature(OPENSSL) bind:443 ssl crt … .endif .endif

.if feature(OPENSSL) && (streq("$WITH_SSL",yes) || streq("$SSL_ONLY",yes)) bind:443 ssl crt … .endif

.if version_atleast(2.4-dev19) profiling.memory on .endif

.if !feature(OPENSSL) .alert “SSL support is mandatory” .endif

Quatre autres directives sont fournies pour signaler certains états :

• .diag “message” : émettre ce message uniquement en mode diagnostic (-dD)
• .notice “message” : émettre ce message au niveau NOTICE
• .warning “message” : émettre ce message au niveau WARNING
• .alert “message” : émettre ce message au niveau ALERT

Les messages émis au niveau WARNING peuvent empêcher le démarrage du processus si l’option « zero-warning » est activée. Les messages émis au niveau ALERT provoquent toujours une erreur fatale. Ces messages peuvent être utilisés pour détecter certaines conditions inappropriées et fournir des conseils à l’utilisateur.

Exemple :

.if "${A}"
  .if "${B}"
     .notice "A=1, B=1"
  .elif "${C}"
     .notice "A=1, B=0, C=1"
  .elif "${D}"
     .warning "A=1, B=0, C=0, D=1"
  .else
     .alert "A=1, B=0, C=0, D=0"
  .endif
.else
     .notice "A=0"
.endif

.diag "WTA/2021-05-07: replace 'redirect' with 'return' after switch to 2.4"
      http-request redirect location /goaway if ABUSE

2.5. Format d’horodatage

Certains paramètres comportent des valeurs représentant une durée, telles que les délais d’expiration. Ces valeurs sont généralement exprimées en millisecondes (sauf indication contraire explicite), mais peuvent être exprimées dans toute autre unité en ajoutant l’unité à la valeur numérique. Il est important de le prendre en compte, car cela ne sera pas rappelé pour chaque mot-clé. Les unités prises en charge sont :

• us : microsecondes. 1us = 1/1000000s
• ms : millisecondes. 1ms = 1/1000s. Il s’agit de l’unité par défaut.
• s : secondes. 1s = 1000ms
• m : minutes. 1m = 60s = 60000ms
• h : heures. 1h = 60m = 3600s = 3600000ms
• d : jours. 1d = 24h = 1440m = 86400s = 86400000ms

2.6. Format de taille

Certains paramètres impliquent des valeurs représentant une taille, telles que les limites de débit. Ces valeurs sont généralement exprimées en octets (sauf indication contraire explicite), mais peuvent être exprimées dans n’importe quelle autre unité en ajoutant l’unité à la valeur numérique. Il est important de le prendre en compte, car cela ne sera pas rappelé pour chaque mot-clé. Les unités prises en charge sont insensibles à la casse :

• k : kilo-octets. 1 kilo-octet = 1024 octets
• m : méga-octets. 1 méga-octet = 1048576 octets
• g : giga-octets. 1 giga-octet = 1073741824 octets

Les formats de temps et de taille exigent des entiers ; la notation décimale n’est pas autorisée.

2.7. Format de nom pour les cartes et les listes ACL

Il est possible d’utiliser une liste de modèles pour les cartes ou les ACL. Une liste de modèles est identifiée par son nom et peut être utilisée à différents endroits dans la configuration. Les listes de modèles sont divisées en trois catégories selon le format du nom :

• Listes de motifs basées sur des fichiers réguliers : c’est le cas par défaut. Le nom du fichier, absolu ou relatif, est utilisé comme nom. Le fichier doit exister, sinon une erreur est déclenchée. Toutefois, il peut être vide. Le préfixe « file@ » peut également être spécifié, mais il ne fait pas partie du nom identifiant la liste. Un nom de fichier, avec ou sans préfixe, référence la même liste de motifs.

• Listes de motifs basées sur des fichiers facultatifs : le nom de fichier doit être précédé du préfixe “opt@”. L’existence du fichier est facultative. Si le fichier existe, son contenu est chargé, mais aucune erreur n’est signalée s’il est absent. Le préfixe ne fait pas partie du nom identifiant la liste. Cela signifie qu’un fichier facultatif et un fichier régulier portant le même nom référencent la même liste de motifs.

• Listes de motifs basées sur des fichiers virtuels : le nom n’est qu’un identifiant. Il ne fait pas référence à aucun fichier. Le préfixe « virt@ » doit être utilisé. Il fait partie du nom. Il ne peut donc pas être combiné avec d’autres types de listes.

Les fichiers virtuels sont utiles lorsque les modèles sont entièrement gérés de manière dynamique, sans modèles présents au démarrage ni lors d’un rechargement. Les fichiers facultatifs peuvent être utilisés dans les mêmes conditions. Toutefois, les modèles peuvent être sauvegardés dans le fichier, par le biais d’un script externe basé, par exemple, sur la commande CLI « show map ». Ainsi, il devient possible de conserver les modèles lors d’un rechargement.

Note : Même si cela est peu probable, cela signifie qu’aucun fichier régulier commençant par « file@ », « opt@ » ou « virt@ » ne peut être chargé, sauf en ajoutant explicitement « ./ » devant le nom de fichier (par exemple « file@./virt@map »).

2.8. Variables

Dans la configuration HAProxy, les variables peuvent être utilisées dans les fonctions d’extraction d’échantillon, les convertisseurs, les chaînes de format de journalisation ou les actions TCP/HTTP. Des variables propres au processus peuvent être définies, accessibles globalement pendant toute la durée de vie du processus. D’autres ont une durée de vie plus courte. Les variables sont similaires à celles utilisées dans les scripts shell. Il s’agit d’un nom symbolique pour une zone de mémoire. La taille des variables n’est pas limitée et est allouée dynamiquement. Elles doivent donc être utilisées avec précaution, notamment en cas d’utilisation intensive. Toutefois, il est possible de limiter la quantité maximale de mémoire utilisée par les variables en configurant les paramètres globaux “tune.vars”.

Les variables doivent être désignées en utilisant le format “<scope>.<name>”. Le <scope> est un mot unique indiquant la durée de vie de la variable. La partie <name>, à l’intérieur d’une portée, ne peut contenir que des caractères ‘a-z’, ‘A-Z’, ‘0-9’ et ‘_’. Elle est unique dans cette portée, mais le même nom utilisé dans des portées différentes peut faire référence à des variables différentes. Les portées prises en charge sont :

• proc : pour les variables connues pendant toute la durée de vie du processus et accessibles globalement. Les variables « proc » peuvent être manipulées depuis la ligne de commande à l’aide des commandes « get var » et « set var ». Elles peuvent également être définies depuis les sections « global » à l’aide des directives « set-var » et « set-var-fmt ».

• sess : pour les variables connues pendant toute la durée de vie d’une session. Les variables « sess » sont privées à une session, non visibles depuis l’extérieur et non partagées avec d’autres sessions.

• txn : pour les variables connues pendant toute la durée de vie d’une transaction. Les variables « txn » sont privées à un flux, non visibles depuis l’extérieur et non partagées avec d’autres flux.

• req : pour les variables connues pendant le traitement d’une requête sur un flux spécifique. Les variables « req » sont visibles depuis la création du flux jusqu’à la première tentative de connexion au serveur. Elles sont privées à un flux, non visibles depuis l’extérieur et non partagées avec d’autres flux. Il n’y a aucune superposition entre les variables « req » et « res ».

• res : pour les variables connues pendant le traitement de la réponse pour un flux spécifique. Les variables « res » sont visibles à partir de la première tentative de connexion au serveur jusqu’à la destruction du flux. Elles sont privées à un flux, non visibles depuis l’extérieur et non partagées avec d’autres flux. Il n’y a aucune superposition entre les variables « req » et « res ».

• check : pour les variables connues pendant l’exécution d’une vérification de santé. Les variables « check » sont privées à une vérification de santé, non visibles depuis l’extérieur de celle-ci et non partagées avec d’autres vérifications de santé. Elles peuvent être définies à l’aide des directives dédiées « tcp-check » ou « http-check ».

En fonction du contexte, des portées supplémentaires faisant référence au parent d’un flux actuel peuvent être utilisées :

• psess : identique à « sess » mais utilise la session du flux parent, le cas échéant.

• ptxn : identique à « txn » mais utilise la transaction du flux parent, le cas échéant.

• preq : identique à “req” mais utilise le flux parent, le cas échéant. Les variables “preq” ne sont accessibles que pendant le traitement de la requête du flux parent.

• pres : identique à « res » mais utilise le flux parent, le cas échéant. Les variables « pres » ne sont accessibles que pendant le traitement de la réponse du flux parent.

Les portées faisant référence au flux parent sont utilisables dès la définition de ce dernier. Dans la plupart des cas, aucun flux parent n’existe. Toutefois, s’il est applicable, cela sera explicitement précisé. Pour l’instant, il est uniquement possible de récupérer la valeur des variables définies dans une portée du flux parent. Il n’est pas possible de définir ni d’annuler de telles variables. En général, un flux enfant effectue un traitement pour le parent à un moment précis et empêche celui-ci de progresser jusqu’à la fin de l’opération qu’il effectue. Cela signifie que le parent peut être arrêté au milieu du traitement d’une requête ou d’une réponse, par exemple. En conséquence, certaines portées ne seront pas disponibles depuis le flux enfant. Par exemple, si une requête fait l’objet d’une analyse effectuée par un flux enfant, ce dernier ne trouvera aucune variable dans la portée « pres » car le parent n’est pas en train de traiter une réponse, et donc ne possède aucune variable dans sa portée « res ».

Le contenu d’une variable est le résultat d’une expression d’extraction d’échantillon et hérite du type de sortie de cette expression. Il est important de le prendre en compte lors de l’utilisation de la variable, car son type doit être compatible avec son usage. Par exemple, une variable contenant une chaîne utilisée dans le convertisseur « add() » doit être convertible en entier valide pour réussir. Cela est particulièrement vrai lorsque les variables sont comparées à des valeurs statiques. La méthode de correspondance appropriée doit être utilisée.

2.9. Formats d’adresses

Plusieurs instructions telles que « bind », « server », « nameserver » et « log » nécessitent une adresse.

Cette adresse peut être un nom d’hôte, une adresse IPv4, une adresse IPv6 ou ‘’. Le ‘’ est égal à l’adresse spéciale “0.0.0.0” et peut être utilisé, dans le cas de « bind » ou « dgram-bind », pour écouter sur toutes les adresses IPv4 du système. L’équivalent IPv6 est ‘::’.

Selon l’instruction, un port ou une plage de ports suit l’adresse IP. Cela est obligatoire dans l’instruction « bind », facultatif dans l’instruction « server ».

Cette adresse peut également commencer par une barre oblique « / ». Elle est considérée comme appartenant à la famille « unix », et les caractères « / » et suivants doivent obligatoirement être présents dans le chemin.

Le type de socket ou la méthode de transport par défaut, « datagram » ou « stream », dépend de l’instruction de configuration indiquant l’adresse. En effet, les directives « bind » et « server » utilisent par défaut un type de socket « stream », tandis que les directives « log », « nameserver » ou « dgram-bind » utilisent un type de socket « datagram ».

Optionnellement, un préfixe peut être utilisé pour forcer le type de famille d’adresses et/ou le type de socket et la méthode de transport.

2.9.1. Préfixes de famille d’adresses

‘abns@<name>’ suivant <name> est un espace de noms abstrait (Linux uniquement).

‘abnsz@<name>’ suivant <name> est un espace de noms abstrait terminé par un octet nul (Linux uniquement).

‘fd@<n>’ suivant est un descripteur de fichier <n> hérité du processus parent. Ce descripteur doit être lié et peut ou non déjà être en écoute.

L’adresse ‘ip@<address>[:port1[-port2]]’ suivant <address> est considérée comme une adresse IPv4 ou IPv6 selon la syntaxe. Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut être spécifié, ou doit l’être.

‘ipv4@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv4. Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut être spécifié, ou doit l’être.

‘ipv6@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv6. Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié.

‘sockpair@<n>’ : l’adresse qui suit est le descripteur de fichier d’un socket Unix connecté ou d’une paire de sockets. Lors d’une connexion, l’initiateur crée une paire de sockets connectés et transmet l’un d’eux à l’autre extrémité via le descripteur. L’écouteur attend de recevoir ce descripteur depuis le socket Unix et l’utilise comme celui renvoyé par accept(). Cette option doit être utilisée avec précaution.

           Bugs : Ce protocole est connu pour être peu fiable sous macOS en raison d'un problème dans l'implémentation de sendmsg(2) de macOS. La connexion pourrait ne pas être acceptée correctement.

‘unix@<path>’ : la chaîne qui suit est considérée comme le chemin <path> d’un socket Unix. Ce préfixe permet de déclarer un chemin de socket Unix qui ne commence pas par une barre oblique ‘/’.

2.9.2. Préfixes de type de socket

Les préfixes de famille d’adresses précédents peuvent également être utilisés pour forcer le type de socket et la méthode de transport. La valeur par défaut dépend de l’instruction utilisant cette adresse, mais dans certains cas, l’utilisateur peut la forcer à une autre valeur. C’est notamment le cas de l’instruction « log », dont la valeur par défaut est syslog via UDP, mais où l’on peut forcer l’utilisation de syslog via TCP.

Ces préfixes ont été conçus à usage interne ; les utilisateurs doivent préférer les alias de la section suivante « 2.9.3 Préfixes de protocole ». Toutefois, ils peuvent parfois s’avérer pratiques, par exemple en combinaison avec des sockets héritées identifiées par leur numéro de descripteur de fichier, auquel cas le domaine d’adresse est « fd » et le type de socket doit être déclaré.

Si les utilisateurs ont besoin de l’un de ces préfixes pour obtenir le comportement attendu, car ils ne peuvent pas configurer la même fonctionnalité à l’aide des préfixes de protocole, ils doivent en informer les responsables du maintien.

‘stream+<family>@<address>’ impose le type de socket et la méthode de transport à « stream »

‘dgram+<family>@<address>’ impose le type de socket et la méthode de transport par “datagramme”.

‘quic+<family>@<address>’ impose le type de socket à « datagram » et la méthode de transport à « stream ».

2.9.3. Préfixes de protocole

‘quic4@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv4, mais le type de socket est forcé à « datagram » et la méthode de transport est forcé à « stream ». Selon l’instruction utilisant cette adresse, un port UDP ou une plage de ports peut ou doit être spécifié. Cela équivaut à « quic+ipv4@ ».

‘quic6@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv6, mais le type de socket est forcé à « datagram » et la méthode de transport est forcé à « stream ». Selon l’instruction utilisant cette adresse, un port UDP ou une plage de ports peut ou doit être spécifié. Cela équivaut à « quic+ipv6@ ».

’tcp@<address>[:port1[-port2]]’ suivant <address> est considéré comme une adresse IPv4 ou IPv6 selon la syntaxe, mais le type de socket et la méthode de transport sont forcés à « stream ». Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de « stream+ip@ ».

’tcp4@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv4, mais le type de socket et la méthode de transport sont forcés à « stream ». Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de ‘stream+ipv4@’.

’tcp6@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv6, mais le type de socket et la méthode de transport sont forcés à « stream ». Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de « stream+ipv4@ ».

‘mptcp@<address>[:port1[-port2]]’ suivant <address> est considéré comme une adresse IPv4 ou IPv6 selon la syntaxe, mais le type de socket et la méthode de transport sont forcés à « stream », avec le protocole MPTCP. Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié.

‘mptcp4@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv4, mais le type de socket et la méthode de transport sont forcés à « stream », avec le protocole MPTCP. En fonction de l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié.

‘mptcp6@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv6, mais le type de socket et la méthode de transport sont forcés à « stream », avec le protocole MPTCP. En fonction de l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié.

‘udp@<address>[:port1[-port2]]’ suivant <address> est considéré comme une adresse IPv4 ou IPv6 selon la syntaxe, mais le type de socket et la méthode de transport sont forcés à « datagram ». Selon l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de « dgram+ip@ ».

‘udp4@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv4, mais le type de socket et la méthode de transport sont forcés à « datagram ». En fonction de l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de ‘dgram+ipv4@’.

‘udp6@<address>[:port1[-port2]]’ suivant <address> est toujours considéré comme une adresse IPv6, mais le type de socket et la méthode de transport sont forcés à « datagram ». En fonction de l’instruction utilisant cette adresse, un port ou une plage de ports peut ou doit être spécifié. Il est considéré comme un alias de ‘dgram+ipv4@’.

‘uxdg@<path>’ : la chaîne qui suit est considérée comme le chemin <path> d’un socket Unix, mais la méthode de transport est forcée à “datagram”. Ce préfixe est un alias de ‘dgram+unix@’.

‘uxst@<path>’ : la chaîne qui suit est considérée comme le chemin <path> d’un socket Unix, mais la méthode de transport est forcée à “stream”. Ce préfixe est un alias de ‘stream+unix@’.

Dans les versions futures, d’autres préfixes pourraient être utilisés pour spécifier des protocoles comme QUIC, qui propose un transport de flux basé sur des sockets de type « datagram ».

2.10. Exemples

# Simple configuration for an HTTP proxy listening on port 80 on all
    # interfaces and forwarding requests to a single backend "servers" with a
    # single server "server1" listening on 127.0.0.1:8000
    global
        daemon
        maxconn 256

    defaults
        mode http
        timeout connect 5000ms
        timeout client 50000ms
        timeout server 50000ms

    frontend http-in
        bind *:80
        default_backend servers

    backend servers
        server server1 127.0.0.1:8000 maxconn 32


    # The same configuration defined with a single listen block. Shorter but
    # less expressive, especially in HTTP mode.
    global
        daemon
        maxconn 256

    defaults
        mode http
        timeout connect 5000ms
        timeout client 50000ms
        timeout server 50000ms

    listen http-in
        bind *:80
        server server1 127.0.0.1:8000 maxconn 32

En supposant que HAProxy est dans $PATH, testez ces configurations dans un shell avec :

$ sudo haproxy -f configuration.conf -c

12 - 3. Section globale

Les paramètres de la section « global » sont applicables à l’ensemble du processus et souvent spécifiques au système d’exploitation. Ils sont généralement définis une fois pour toutes et n’exigent pas de modification une fois correctement configurés. Certains d’entre eux ont des équivalents en ligne de commande.

Les mots-clés suivants sont pris en charge dans la section « global » :

• Gestion des processus et sécurité

  • 51degrees-allow-unmatched
  • 51degrees-cache-size
  • 51degrees-data-file
  • 51degrees-difference
  • 51degrees-drift
  • 51degrees-property-name-list
  • 51degrees-property-separator
  • 51degrees-use-performance-graph
  • 51degrees-use-predictive-graph
  • ca-base
  • chroot
  • cluster-secret
  • cpu-affinity
  • cpu-map
  • cpu-policy
  • cpu-set
  • crt-base
  • daemon
  • default-path
  • description
  • deviceatlas-json-file
  • deviceatlas-log-level
  • deviceatlas-properties-cookie
  • deviceatlas-separator
  • dns-accept-family
  • expose-deprecated-directives
  • expose-experimental-directives
  • external-check
  • fd-hard-limit
  • gid
  • grace
  • group
  • h1-accept-payload-with-any-method
  • h1-case-adjust
  • h1-case-adjust-file
  • h1-do-not-close-on-insecure-transfer-encoding
  • h2-workaround-bogus-websocket-clients
  • hard-stop-after
  • harden.reject-privileged-ports.tcp
  • harden.reject-privileged-ports.quic
  • insecure-fork-wanted
  • insecure-setuid-wanted
  • issuers-chain-path
  • jwt.decrypt_alg_list
  • jwt.decrypt_enc_list
  • key-base
  • limited-quic
  • localpeer
  • log
  • log-send-hostname
  • log-tag
  • lua-load
  • lua-load-per-thread
  • lua-prepend-path
  • max-threads-per-group
  • mworker-max-reloads
  • nbthread
  • node
  • numa-cpu-mapping
  • ocsp-update.disable
  • ocsp-update.maxdelay
  • ocsp-update.mindelay
  • ocsp-update.httpproxy
  • ocsp-update.mode
  • pidfile
  • pp2-never-send-local
  • presetenv
  • prealloc-fd
  • resetenv
  • set-dumpable
  • set-var
  • setenv
  • ssl-default-bind-ciphers
  • ssl-default-bind-ciphersuites
  • ssl-default-bind-client-sigalgs
  • ssl-default-bind-curves
  • ssl-default-bind-options
  • ssl-default-bind-sigalgs
  • ssl-default-server-ciphers
  • ssl-default-server-ciphersuites
  • ssl-default-server-client-sigalgs
  • ssl-default-server-curves
  • ssl-default-server-options
  • ssl-default-server-sigalgs
  • ssl-dh-param-file
  • ssl-propquery
  • fournisseur-ssl
  • chemin-fournisseur-ssl
  • niveau-sécurité-ssl
  • vérification-serveur-ssl
  • ignorer-ca-auto-signé-ssl
  • statistiques
  • fichier-statistiques
  • limites-strictes
  • uid
  • limite-ressources-n
  • liaison-unix
  • supprimer-variable-environnement
  • utilisateur
  • taille-cache-wurfl
  • fichier-données-wurfl
  • liste-informations-wurfl
  • séparateur-liste-informations-wurfl

• Optimisation des performances

  • busy-polling
  • max-spread-checks
  • maxcompcpuusage
  • maxcomprate
  • maxconn
  • maxconnrate
  • maxpipes
  • maxsessrate
  • maxsslconn
  • maxsslrate
  • maxzlibmem
  • no-memory-trimming
  • noepoll
  • noevports
  • nogetaddrinfo
  • nokqueue
  • noktls
  • nopoll
  • noreuseport
  • nosplice
  • profiling.memory
  • profiling.tasks
  • server-state-base
  • server-state-file
  • spread-checks
  • ssl-engine
  • ssl-mode-async
  • tune.applet.zero-copy-forwarding
  • tune.buffers.limit
  • tune.buffers.reserve
  • tune.bufsize
  • tune.bufsize.large
  • tune.bufsize.small
  • tune.cli.max-payload-size
  • tune.comp.maxlevel
  • tune.defaults.purge
  • tune.disable-fast-forward
  • tune.disable-zero-copy-forwarding
  • tune.epoll.mask-events
  • tune.events.max-events-at-once
  • tune.fail-alloc
  • tune.fd.edge-triggered
  • tune.h1.be.glitches-threshold
  • tune.h1.fe.glitches-threshold
  • tune.h1.zero-copy-fwd-recv
  • tune.h1.zero-copy-fwd-send
  • tune.h2.be.glitches-threshold
  • tune.h2.be.initial-window-size
  • tune.h2.be.max-concurrent-streams
  • tune.h2.be.max-frames-at-once
  • tune.h2.be.rxbuf
  • tune.h2.fe.glitches-threshold
  • tune.h2.fe.initial-window-size
  • tune.h2.fe.max-concurrent-streams
  • tune.h2.fe.max-frames-at-once
  • tune.h2.fe.max-rst-at-once
  • tune.h2.fe.max-total-streams
  • tune.h2.fe.rxbuf
  • tune.h2.header-table-size
  • tune.h2.initial-window-size
  • tune.h2.max-concurrent-streams
  • tune.h2.max-frame-size
  • tune.h2.zero-copy-fwd-send
  • tune.http.cookielen
  • tune.http.logurilen
  • tune.http.maxhdr
  • tune.idle-pool.shared
  • tune.idletimer
  • tune.lua.bool-sample-conversion
  • tune.lua.burst-timeout
  • tune.lua.forced-yield
  • tune.lua.log.loggers
  • tune.lua.log.stderr
  • tune.lua.maxmem
  • tune.lua.openlibs
  • tune.lua.service-timeout
  • tune.lua.session-timeout
  • tune.lua.task-timeout
  • tune.max-checks-per-thread
  • tune.maxaccept
  • tune.maxpollevents
  • tune.maxrewrite
  • tune.max-rules-at-once
  • tune.memory.hot-size
  • tune.pattern.cache-size
  • tune.peers.max-updates-at-once
  • tune.pipesize
  • tune.pool-high-fd-ratio
  • tune.pool-low-fd-ratio
  • tune.pt.zero-copy-forwarding
  • tune.quic.be.cc.cubic-min-losses
  • tune.quic.be.cc.hystart
  • tune.quic.be.cc.max-frame-loss
  • tune.quic.be.cc.max-win-size
  • tune.quic.be.cc.reorder-ratio
  • tune.quic.be.max-idle-timeout
  • tune.quic.be.sec.glitches-threshold
  • tune.quic.be.stream.data-ratio
  • tune.quic.be.stream.max-concurrent
  • tune.quic.be.stream.rxbuf
  • tune.quic.be.tx.pacing
  • tune.quic.be.tx.udp-gso
  • tune.quic.cc.cubic.min-losses (obsolète)
  • tune.quic.cc-hystart (obsolète)
  • tune.quic.disable-tx-pacing (obsolète)
  • tune.quic.disable-udp-gso (obsolète)
  • tune.quic.fe.cc.cubic-min-losses
  • tune.quic.fe.cc.hystart
  • tune.quic.fe.cc.max-frame-loss
  • tune.quic.fe.cc.max-win-size
  • tune.quic.fe.cc.reorder-ratio
  • tune.quic.frontal.max-idle-timeout
  • tune.quic.frontal.sec.glitches-threshold
  • tune.quic.frontal.sec.retry-threshold
  • tune.quic.frontal.sock-per-conn
  • tune.quic.frontal.stream.data-ratio
  • tune.quic.frontal.stream.max-concurrent
  • tune.quic.frontal.stream.max-total
  • tune.quic.frontal.stream.rxbuf
  • tune.quic.frontal.tx.pacing
  • tune.quic.frontal.tx.udp-gso
  • tune.quic.frontal.max-data-size (obsolète)
  • tune.quic.frontal.max-idle-timeout (obsolète)
  • tune.quic.frontal.max-streams-bidi (obsolète)
  • tune.quic.frontal.max-tx-mem (obsolète)
  • tune.quic.frontal.stream-data-ratio (obsolète)
  • tune.quic.frontal.default-max-window-size (obsolète)
  • tune.quic.ecoute
  • tune.quic.max-frame-loss (obsolète)
  • tune.quic.mem.tx-max
  • tune.quic.reorder-ratio (obsolète)
  • tune.quic.retry-threshold (obsolète)
  • tune.quic.socket-owner (obsolète)
  • tune.quic.zero-copy-fwd-send
  • tune.renice.runtime
  • tune.renice.startup
  • tune.rcvbuf.backend
  • tune.rcvbuf.client
  • tune.rcvbuf.frontend
  • tune.rcvbuf.server
  • tune.recv_enough
  • tune.ring.queues
  • tune.runqueue-depth
  • tune.sched.low-latency
  • tune.sndbuf.backend
  • tune.sndbuf.client
  • tune.sndbuf.frontend
  • tune.sndbuf.server
  • tune.streams-elasticity
  • tune.stick-counters
  • tune.ssl.cachesize
  • tune.ssl.capture-buffer-size
  • tune.ssl.capture-cipherlist-size (obsolète)
  • tune.ssl.certificate-compression
  • tune.ssl.default-dh-param
  • tune.ssl.force-private-cache
  • tune.ssl.hard-maxrecord
  • tune.ssl.keylog
  • tune.ssl.keyupdate-rate-limit
  • tune.ssl.lifetime
  • tune.ssl.maxrecord
  • tune.ssl.ssl-ctx-cache-size
  • tune.ssl.ocsp-update.maxdelay (obsolète)
  • tune.ssl.ocsp-update.mindelay (obsolète)
  • tune.takeover-other-tg-connections
  • tune.vars.global-max-size
  • tune.vars.proc-max-size
  • tune.vars.reqres-max-size
  • tune.vars.sess-max-size
  • tune.vars.txn-max-size
  • tune.zlib.memlevel
  • tune.zlib.windowsize

• Débogage

  • anonkey
  • debug.counters
  • force-cfg-parser-pause
  • quiet
  • warn-blocked-traffic-after
  • zero-warning

• HTTPClient

  • httpclient.resolvers.disabled
  • httpclient.resolvers.id
  • httpclient.resolvers.prefer
  • httpclient.retries
  • httpclient.ssl.ca-file
  • httpclient.ssl.verify
  • httpclient.timeout.connect

3.1. Gestion des processus et sécurité

51degrees-data-file <file path>

51degrees-data-file <file path>

Chemin du fichier de données 51Degrees à utiliser pour fournir les services de détection de périphérique. Le fichier doit être décompressé et accessible par HAProxy, avec les autorisations appropriées.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.

51degrees-property-name-list [<string> ...]

51degrees-property-name-list [<string> ...]

Une liste de noms de propriétés 51Degrees à charger à partir de l’ensemble de données. Une liste complète des noms est disponible sur le site web 51Degrees : https://51degrees.com/resources/property-dictionary

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.

51degrees-property-separator <char>

51degrees-property-separator <char>

Caractère ajouté à la fin de chaque valeur de propriété dans un en-tête de réponse contenant des résultats 51Degrees. Si non défini, la valeur par défaut est « , ».

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.

51degrees-cache-size <number>

51degrees-cache-size <number>

Définit la taille du cache du convertisseur 51Degrees à <number> entrées. Il s’agit d’un cache LRU qui conserve les détections précédentes de périphériques et leurs résultats. Par défaut, ce cache est désactivé.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.

51degrees-use-performance-graph { on | off }

51degrees-use-performance-graph { on | off }

Active (‘on’) ou désactive (‘off’) l’utilisation du graphe de performance dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.

51degrees-use-predictive-graph { on | off }

51degrees-use-predictive-graph { on | off }

Active (‘on’) ou désactive (‘off’) l’utilisation du graphe prédictif dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.

51degrees-drift <number>

51degrees-drift <number>

Définit la valeur de dérive que la détection peut autoriser.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.

51degrees-difference <number>

51degrees-difference <number>

Définit la valeur de différence autorisée par une détection.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.

51degrees-allow-unmatched { on | off }

51degrees-allow-unmatched { on | off }

Active (‘on’) ou désactive (‘off’) l’utilisation des nœuds non appariés dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.

acme.scheduler { auto | off }

acme.scheduler { auto | off }

Active ou désactive le planificateur ACME.

Le planificateur ACME démarre au démarrage de HAProxy. Il parcourt les certificats et lance une tâche de renouvellement ACME lorsque la valeur notAfter est dépassée de curtime + (notAfter - notBefore) / 12, ou de 7 jours si notBefore n’est pas définie. Le planificateur s’endort ensuite et se réveille après 12 heures.

La valeur par défaut est « auto ».

Voir aussi : acme

ca-base <dir>

ca-base <dir>

Attribue un répertoire par défaut pour récupérer les certificats CA et les listes de révocation de certificats (CRL) lorsqu’un chemin relatif est utilisé avec les directives « ca-file », « ca-verify-file » ou « crl-file ». Les emplacements absolus spécifiés dans « ca-file », « ca-verify-file » et « crl-file » ont la priorité et ignorent « ca-base ».

chroot { <jail dir> | auto }

chroot { <jail dir> | auto }

Change le répertoire courant vers <jail dir> et effectue un chroot() dans ce répertoire avant de réduire les privilèges. Cela augmente le niveau de sécurité en cas d’exploitation d’une vulnérabilité inconnue, car cela rend très difficile pour l’attaquant d’exploiter le système. Il est essentiel de s’assurer que <jail dir> est à la fois vide et non accessible en écriture par quiconque. Lorsque le processus est lancé avec des privilèges de superutilisateur, le chroot() est effectué directement. Sur Linux, lorsqu’il est lancé sans privilèges, HAProxy tente de l’effectuer depuis un nouvel espace utilisateur créé avec unshare(CLONE_NEWUSER); si ce mécanisme n’est pas disponible, le chroot() échoue avec l’erreur habituelle.

En tant que cas particulier, <jail dir> peut être défini sur « auto », auquel cas HAProxy crée un répertoire temporaire anonyme, le supprime, puis effectue un chroot dedans. La prison résultante n’a pas de nom dans le système de fichiers, est vide et en lecture seule, ce qui élimine la nécessité de préparer un répertoire dédié pour la prison.

Lorsque HAProxy est lancé avec des privilèges de superutilisateur, un avertissement est affiché si aucun chroot n’est utilisé, afin d’encourager les utilisateurs à toujours utiliser ce mécanisme. Si, pour une raison quelconque, il existe une raison impérative de ne pas utiliser chroot (par exemple, l’accès à un serveur via un socket UNIX dont le chemin est peu pratique), il reste possible de supprimer l’avertissement en ajoutant explicitement « chroot / », ce qui présente l’avantage d’être visible dans la configuration.

close-spread-time <time>

close-spread-time <time>

Définir une fenêtre de temps pendant laquelle les connexions inactives et les connexions actives en cours de fermeture sont réparties en cas d’arrêt doux. Après la réception d’un SIGUSR1 et l’expiration de la période de grâce (le cas échéant), les connexions inactives seront toutes fermées en même temps si cette option n’est pas définie, et les connexions HTTP actives ou HTTP2 seront terminées après la réception de la requête suivante, soit en ajoutant une ligne « Connection: close » à la réponse HTTP, soit en envoyant un cadre GOAWAY en cas de HTTP2. Lorsque cette option est définie, la fermeture des connexions sera répartie sur cette fenêtre <time>. Si le délai de répartition de la fermeture est défini sur « infinite », la fermeture des connexions actives pendant un arrêt doux sera désactivée. L’en-tête « Connection: close » ne sera plus ajouté aux réponses HTTP (ni GOAWAY pour HTTP2) et les connexions inactives ne seront fermées qu’une fois leur délai d’expiration atteint (selon les délais configurés).

Arguments :

<time>  is a time window (by default in milliseconds) during which
        connection closing will be spread during a soft-stop operation, or
        "infinite" if active connection closing should be disabled.

Il est recommandé de définir ce paramètre à une valeur inférieure à celle utilisée dans l’option « hard-stop-after », si celle-ci est utilisée, afin que toutes les connexions aient la possibilité de se fermer correctement avant l’arrêt du processus.

Voir aussi : grace, hard-stop-after, idle-close-on-response

cluster-secret <secret>

cluster-secret <secret>

Définir une chaîne ASCII secrète partagée entre plusieurs nœuds appartenant au même cluster. Elle peut être utilisée à différentes fins. Elle est notamment utilisée pour dériver des jetons de réinitialisation sans état pour toutes les connexions QUIC instanciées par ce processus. C’est également le cas pour dériver les secrets utilisés pour chiffrer les jetons Retry.

Si ce paramètre n’est pas défini, une valeur aléatoire sera sélectionnée au démarrage du processus. Cela permet d’utiliser des fonctionnalités qui en dépendent, bien que certaines limitations s’appliquent.

cpu-map [auto:]<thread-group>[/<thread-set>] <cpu-set>[,...] [...]

cpu-map [auto:]<thread-group>[/<thread-set>] <cpu-set>[,...] [...]

Sur certains systèmes d’exploitation, il est possible d’attribuer un groupe de threads ou un thread à un ensemble spécifique de processeurs. Cela signifie que les threads désignés ne s’exécuteront jamais sur d’autres processeurs. La directive « cpu-map » spécifie les ensembles de processeurs pour des threads individuels ou des groupes de threads. Le premier argument est une plage de groupes de threads, suivie éventuellement d’un ensemble de threads. Ces plages ont le format suivant :

all | odd | even | number[-[number]]

<number> doit être un nombre compris entre 1 et 32 ou 64, selon la taille mot de la machine. Tous les identifiants de groupe au-dessus de « thread-groups » et tous les identifiants de thread au-dessus de la taille mot de la machine sont ignorés. Tous les numéros de thread sont relatifs au groupe auquel ils appartiennent. Il est possible de spécifier une plage en utilisant deux tels nombres séparés par un trait d’union (’-’). Il est également possible de spécifier tous les threads à la fois en utilisant « all », uniquement les nombres impairs en utilisant « odd » ou les nombres pairs en utilisant « even », tout comme avec la directive « thread » bind. Les seconds et futurs arguments sont des ensembles de processeurs. Chaque ensemble de processeurs est soit un nombre unique commençant à 0 pour le premier processeur, soit une plage composée de deux tels nombres séparés par un trait d’union (’-’). Ces numéros de processeur et plages peuvent être répétés en les séparant par des virgules ou en ajoutant de nouvelles plages en tant qu’arguments supplémentaires sur la même ligne. Hors des systèmes d’exploitation Linux et BSD, il peut y avoir une limitation sur l’indice maximal de processeur à 31 ou 63. Plusieurs directives « cpu-map » peuvent être spécifiées, mais chaque directive « cpu-map » remplace les précédentes lorsqu’elles se chevauchent.

Les plages peuvent être définies partiellement. La borne supérieure peut être omise. Dans ce cas, elle est remplacée par la valeur maximale correspondante, 32 ou 64 selon la taille du mot machine.

Le préfixe « auto: » peut être ajouté avant l’ensemble de threads pour permettre à HAProxy de lier automatiquement un ensemble de threads à un processeur en incrémentant les threads et les ensembles de processeurs. Pour être valide, les deux ensembles doivent avoir la même taille. Quel que soit l’ordre de déclaration des ensembles de processeurs, le lien s’établit du plus bas au plus élevé. Il n’est pas pris en charge d’avoir à la fois un groupe et une plage de threads avec le préfixe « auto: ». Une seule plage est prise en charge ; l’autre doit être un nombre fixe.

Notez que les plages de groupes sont prises en charge pour des raisons historiques. De nos jours, un nombre isolé désigne un groupe de threads et doit valoir 1 si les groupes de threads ne sont pas utilisés, et spécifier une plage ou un nombre de threads exige d’ajouter “1/” devant s’ils ne sont pas utilisés. Enfin, “1” est strictement équivalent à “1/all” et désigne tous les threads du groupe.

Exemples :

cpu-map 1/all 0-3 # bind all threads of the first group on the
                  # first 4 CPUs

cpu-map 1/1- 0-   # will be replaced by "cpu-map 1/1-64 0-63"
                  # or "cpu-map 1/1-32 0-31" depending on the machine's
                  # word size.

# all these lines bind thread 1 to the cpu 0, the thread 2 to cpu 1
# and so on.
cpu-map auto:1/1-4   0-3
cpu-map auto:1/1-4   0-1 2-3
cpu-map auto:1/1-4   3 2 1 0
cpu-map auto:1/1-4   3,2,1,0

# bind each thread to exactly one CPU using all/odd/even keyword
cpu-map auto:1/all   0-63
cpu-map auto:1/even  0-31
cpu-map auto:1/odd   32-63

# invalid cpu-map because thread and CPU sets have different sizes.
cpu-map auto:1/1-4   0    # invalid
cpu-map auto:1/1     0-3  # invalid

# map 40 threads of those 4 groups to individual CPUs
cpu-map auto:1/1-10   0-9
cpu-map auto:2/1-10   10-19
cpu-map auto:3/1-10   20-29
cpu-map auto:4/1-10   30-39

# Map 80 threads to one physical socket and 80 others to another socket
# without forcing assignment. These are split into 4 groups since no
# group may have more than 64 threads.
cpu-map 1/1-40   0-39,80-119    # node0, siblings 0 & 1
cpu-map 2/1-40   0-39,80-119
cpu-map 3/1-40   40-79,120-159  # node1, siblings 0 & 1
cpu-map 4/1-40   40-79,120-159

cpu-affinity <affinity>

cpu-affinity <affinity>

Définit la manière dont les threads doivent être liés aux processeurs. Il accepte actuellement les valeurs suivantes :

• par-cœur : chaque thread sera lié à tous les threads matériels d’un cœur.
• par-groupe : chaque thread sera lié à tous les threads matériels du groupe. C’est le comportement par défaut, sauf si « threads-per-core 1 » est utilisé dans « cpu-policy ». « par-groupe » accepte un argument facultatif, permettant de préciser la manière dont les processeurs doivent être alloués. Lorsqu’une liste de processeurs est plus grande que le nombre maximal de processeurs par groupe autorisé et doit être répartie entre plusieurs groupes, une option supplémentaire permet de choisir la manière dont les groupes seront liés à ces processeurs :
  • auto : chaque groupe de threads ne sera affecté qu’à une part équitable de cœurs processeurs contigus, dédiés exclusivement à ce groupe et non partagés avec d’autres groupes. C’est le comportement par défaut, car il est généralement plus optimal.
  • lache : chaque groupe pourra toujours utiliser n’importe quel processeur de la liste. Cela entraîne généralement plus de contention, mais peut parfois aider à mieux gérer les charges parasites s’exécutant sur les mêmes processeurs.
• auto : la valeur « per-group » sera utilisée, sauf si « threads-per-core 1 » est spécifié dans « cpu-policy », auquel cas la valeur « per-core » sera utilisée. Cette option est la valeur par défaut.
• per-thread : chaque thread sera lié à un seul thread matériel. Si « threads-per-core 1 » est utilisé dans « cpu-policy », chaque thread sera lié à un thread matériel d’un cœur différent.
• per-ccx : chaque thread sera lié à tous les threads matériels d’un CCX.

cpu-policy <policy> [threads-per-core 1 | auto]

cpu-policy <policy> [threads-per-core 1 | auto]

Sélectionne la politique d’allocation du CPU à utiliser.

Sur les systèmes multi-CPU, plusieurs raisons peuvent justifier de ne pas utiliser tous les cœurs disponibles, and/or afin de les regrouper en groupes de threads distincts, pour des raisons de performance, de latence, de coût ou de gestion des ressources au niveau du système. La directive « cpu-set » permet déjà d’exclure un certain nombre de cœurs, mais une fois cette opération effectuée, il est nécessaire de décider comment affecter les cœurs restants aux threads et groupes de threads.

Ce mappage est généralement effectué à l’aide de la directive « cpu-map », bien qu’il puisse être particulièrement difficile à maintenir sur des systèmes hétérogènes.

La directive « cpu-policy » permet de choisir parmi un petit nombre de politiques d’allocation à utiliser à la place lorsque « cpu-map » n’est pas utilisée. Les politiques suivantes sont actuellement prises en charge, « performance » étant la politique par défaut :

• none aucun post-traitement particulier n’est effectué. Tous les processeurs activés seront utilisables, et si le nombre de threads n’est pas défini, il sera fixé au nombre de processeurs disponibles, mais sans dépasser 32 sur les systèmes 32 bits ou 64 sur les systèmes 64 bits, par groupe de threads. Le nombre de groupes de threads, s’il n’est pas défini, sera fixé à 1.

• efficacité, exactement comme « group-by-ccx » ci-dessous, sauf que les clusters de CPU composés de cœurs dont les performances dépassent de plus de 25 % celles du cœur suivant moins performant sont exclus. Ce sont généralement des cœurs « big » ou « performance ». Cela signifie qu’en cas de détection de plusieurs types de cœurs de CPU, seul le cœur efficace sera utilisé. Cette configuration peut être pertinente en cas de charges modérées lorsque les cœurs les plus puissants doivent être disponibles pour une application ou un composant de sécurité. Certains processeurs modernes disposent d’un grand nombre de tels cœurs efficaces, capables collectivement de fournir un niveau de performance acceptable tout en consommant moins d’énergie.

• premier nœud utilisable si les processeurs n’ont pas été précédemment restreints au démarrage (par exemple à l’aide de l’outil “taskset”), et si la directive “nbthread” n’a pas été définie, alors le premier nœud NUMA ayant des processeurs activés sera utilisé, et ce nombre de processeurs sera utilisé comme nombre de threads. Un seul groupe de threads sera activé avec tous ceux-ci, dans la limite de 32 ou 64 selon le système.

• group-by-2-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les deux CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX comportant peu de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.

• group-by-2-clusters : identique à « group-by-cluster », mais crée un groupe tous les deux clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre les clusters est lente. Cette option est généralement déconseillée.

• group-by-3-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les trois CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX à faible nombre de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.

• group-by-3-clusters : identique à « group-by-cluster », mais crée un groupe tous les trois clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer un trop grand nombre de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets néfastes sur les performances lorsque la communication entre les clusters est lente. Cette configuration est généralement déconseillée.

• group-by-4-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les quatre CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX à faible nombre de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.

• group-by-4-clusters : identique à « group-by-cluster », mais crée un groupe tous les quatre clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre les clusters est lente. Cette option est généralement déconseillée.

• group-by-ccx si ni « nbthread » ni « nbtgroups » ne sont définis, un groupe de threads est créé pour chaque complexe de processeurs (« CCX ») disposant de processeurs disponibles, chaque groupe comportant autant de threads que de processeurs. Un CCX regroupe des processeurs ayant un accès similairement rapide à la mémoire cache de niveau supérieur (« LLC »), généralement la L3 cache. Sur la plupart des machines modernes, il est essentiel pour les performances de ne pas mélanger des processeurs provenant de CCX éloignés au sein du même groupe de threads. Tous les threads d’un groupe sont ensuite liés à tous les processeurs du CCX, afin que les communications intra-groupe restent locales au CCX sans imposer un lien trop strict. Les limites par groupe de threads et les limites des groupes de threads sont respectées. Cette configuration est recommandée sur les systèmes multi-socket et NUMA, ainsi que sur les processeurs présentant des latences inter-CCX élevées.

• group-by-cluster si ni « nbthread » ni « nbtgroups » ne sont définis, un groupe de threads est créé pour chaque cluster de processeur disposant de processeurs disponibles, chacun avec autant de threads que de processeurs. Tous les threads d’un groupe sont liés à tous les processeurs du cluster afin que les communications intra-groupe restent locales au cluster sans imposer une liaison trop stricte. Les limites par groupe de threads et les limites des groupes de threads sont respectées. Cette configuration est recommandée sur les systèmes multi-socket et NUMA, ainsi que sur les processeurs présentant de mauvaises latences inter-CCX. Sur la plupart des machines serveur, les clusters et les CCX sont identiques, mais sur les machines hétérogènes (« performance » vs « efficacité » ou « big » vs « little »), un cluster est généralement constitué d’une partie d’un CCX composée uniquement de processeurs très similaires (même type, différence de fréquence maximale de +/-5%). Cette différence est visible sur les ordinateurs portables et les postes de travail modernes utilisés par les développeurs et les administrateurs pour valider les configurations.

• performances identiques à celles de « group-by-ccx » ci-dessus, à ceci près que les clusters CPU composés de cœurs dont les performances sont inférieures à 80 % de celles du cœur suivant plus performant sont exclus. Ce sont généralement des cœurs « petits » ou « efficaces », dont l’ajout apporte généralement peu de gains significatifs et peut facilement être contre-productif (par exemple, lors des échanges TLS). En général, conserver ces cœurs pour d’autres tâches, comme la gestion du réseau, s’avère bien plus efficace. Sur les systèmes de développement, ils peuvent également être utilisés pour exécuter des outils auxiliaires tels que des générateurs de charge ou des outils de surveillance. Il s’agit de la politique par défaut.

• ressource qui fonctionne comme « group-by-cluster » ci-dessus, sauf que seul le cluster CPU le plus petit et le plus efficace sera utilisé, tandis que tous les autres seront ignorés. Cela peut être utilisé pour limiter l’utilisation des ressources au strict minimum permettant encore des performances décentes, par exemple pour réduire davantage la consommation d’énergie ou minimiser le nombre de cœurs nécessaires sur certains systèmes loués dans une configuration sidecar, afin de faciliter la mise à l’échelle du système vers le bas. Notez qu’en cas de présence d’un seul cluster, celui-ci sera toutefois entièrement utilisé.

Un mot-clé facultatif peut être ajouté : « threads-per-core ». Il peut accepter deux valeurs : « 1 » et « auto ». Si réglé sur « 1 », alors une seule thread par cœur sera créée, indépendamment du nombre de threads matériels que possède le cœur. Si réglé sur « auto », alors une thread sera créée par thread matériel. Si aucune affinité n’est spécifiée et que « threads-per-core 1 » est utilisé, alors l’affinité sera par défaut par cœur.

Voir aussi : « cpu-map », « cpu-set », « nbthread »

cpu-set <directive>...

cpu-set <directive>...

Permet de décrire de manière symbolique les ensembles de processeurs sur lesquels s’exécuter. La directive prend en charge les mots-clés suivants : - reset : annule toute limitation précédente qui aurait pu être héritée par un gestionnaire de services ou une commande « taskset », par exemple. - drop-cpu <set> : ne pas lier aux processeurs de cet ensemble. - only-cpu <set> : ne pas lier aux processeurs n’appartenant pas à cet ensemble. - drop-node <set> : ne pas lier aux processeurs appartenant à cette nœud NUMA. - only-node <set> : ne pas lier aux processeurs n’appartenant pas à ce nœud NUMA. - drop-cluster <set> : ne pas lier aux processeurs de ce numéro de cluster matériel. - only-cluster <set> : ne pas lier aux processeurs d’autres numéros de cluster matériel. - drop-core <set> : ne pas lier aux processeurs de ce numéro de cœur matériel. - only-core <set> : ne pas lier aux processeurs d’autres numéros de cœur matériel. - drop-thread <set> : ne pas lier aux processeurs de ce numéro de thread matériel. - only-thread <set> : ne pas lier aux processeurs d’autres numéros de thread matériel. Voir également : « cpu-policy »

crt-base <dir>

crt-base <dir>

Attribue un répertoire par défaut pour récupérer les certificats SSL lorsqu’un chemin relatif est utilisé avec les directives crtfile ou crt. Les emplacements absolus spécifiés prévalent et ignorent crt-base.

daemon

daemon

Met le processus en arrière-plan. Il s’agit du mode de fonctionnement recommandé. Il équivaut à l’argument de ligne de commande “-D”. Il peut être désactivé par l’argument de ligne de commande “-db”. Cette option est ignorée en mode systemd.

default-path { current | config | parent | origin <path> }

default-path { current | config | parent | origin <path> }

Par défaut, HAProxy charge tous les fichiers dont le chemin est relatif à partir du répertoire depuis lequel le processus est lancé. Dans certains cas, il peut être souhaitable de forcer tous les chemins relatifs à commencer à partir d’un emplacement différent, comme si le processus avait été lancé depuis cet emplacement. C’est précisément l’objectif de cette directive. Techniquement, elle effectue un changement temporaire de répertoire (chdir()) vers l’emplacement désigné pendant le traitement de chaque fichier de configuration, puis revient au répertoire d’origine après avoir traité chaque fichier. Elle prend un argument indiquant la politique à appliquer lors du chargement des fichiers dont le chemin ne commence pas par une barre oblique (’/’): - “current” indique que tous les fichiers relatifs doivent être chargés à partir du répertoire depuis lequel le processus est lancé ; c’est la valeur par défaut.

- "config" indique que tous les fichiers relatifs doivent être chargés à partir du répertoire contenant le fichier de configuration. Plus précisément, si le fichier de configuration contient une barre oblique ('/'), la plus longue partie jusqu'à la dernière barre oblique est utilisée comme répertoire de changement, sinon le répertoire courant est utilisé. Ce mode est pratique pour regrouper des cartes, des fichiers d'erreur, des certificats et des scripts Lua dans des paquets déplaçables. Lorsque plusieurs fichiers de configuration sont chargés, le répertoire est mis à jour pour chacun d'eux.

-  « parent » indique que tous les fichiers relatifs doivent être chargés depuis le répertoire parent du répertoire contenant le fichier de configuration. Plus précisément, si le fichier de configuration contient une barre oblique ('/'), ".." est ajouté au plus long segment jusqu'à la dernière barre oblique, qui est utilisé comme répertoire de changement, sinon le répertoire est "..". Ce mode est pratique pour regrouper des cartes, des fichiers d'erreur, des certificats et des scripts Lua ensemble sous forme de paquets déplaçables, tout en permettant à chaque composant d'être situé dans un sous-répertoire différent (par exemple, « config/ », « certs/ », « maps/ », ...).

-  « origin » indique que tous les fichiers relatifs doivent être chargés à partir du chemin désigné (obligatoire). Cette option peut être utilisée pour simplifier la gestion de plusieurs instances HAProxy s'exécutant en parallèle sur un système, où chaque instance utilise un préfixe différent, tout en rendant le reste des sections facilement déplaçables.

Chaque directive « default-path » remplace instantanément toute directive précédente et peut entraîner un changement de répertoire. Bien que cela doive toujours entraîner le comportement souhaité, il ne s’agit pas d’une bonne pratique d’utiliser plusieurs directives default-path, et si elles sont utilisées, la politique doit rester cohérente dans tous les fichiers de configuration.

Avertissement : certains éléments de configuration, tels que les cartes ou les certificats, sont identifiés de manière unique par leur chemin configuré. En utilisant une disposition déplaçable, il devient possible que plusieurs d’entre eux se retrouvent avec le même nom unique, ce qui rend difficile leur mise à jour en cours d’exécution, en particulier lorsque plusieurs fichiers de configuration sont chargés depuis des répertoires différents. Il est essentiel d’observer une stratégie stricte de nommage de fichiers sans collision avant d’adopter des chemins relatifs. Une approche robuste pourrait consister à préfixer tous les noms de fichiers par le nom du site correspondant, ou à le faire au niveau du répertoire.

description <text>

description <text>

Ajoutez un texte qui décrit l’instance.

Veuillez noter qu’il est nécessaire d’échapper certains caractères (par exemple #) et que ce texte est inséré dans une page HTML, vous devez donc éviter d’utiliser les caractères “<” et “>”.

deviceatlas-json-file <path>

deviceatlas-json-file <path>

Définit le chemin du fichier de données JSON DeviceAtlas à charger par l’API. Le chemin doit désigner un fichier JSON valide et être accessible au processus HAProxy.

deviceatlas-log-level <value>

deviceatlas-log-level <value>

Définit le niveau d’information retourné par l’API. Cette directive est facultative et vaut 0 par défaut si non définie.

deviceatlas-properties-cookie <name>

deviceatlas-properties-cookie <name>

Définit le nom du cookie client utilisé pour détecter si le composant côté client DeviceAtlas a été utilisé lors de la requête. Cette directive est facultative et vaut DAPROPS par défaut si elle n’est pas définie.

deviceatlas-separator <char>

deviceatlas-separator <char>

Définit le séparateur de caractères pour les résultats des propriétés de l’API. Cette directive est facultative et vaut | par défaut si elle n’est pas définie.

dns-accept-family <family>[,...]

dns-accept-family <family>[,...]

Par défaut, les résolveurs DNS acceptent à la fois les adresses IPv4 et IPv6. Ce comportement peut être influencé par les mots-clés « resolve-prefer » dans les lignes server, ainsi que par l’argument family de l’action « do-resolve », mais il s’agit uniquement d’une préférence qui ne bloque pas l’utilisation de l’autre famille lorsque celle-ci est la seule disponible. Dans certains environnements où le double empilement n’est pas utilisable, la découverte d’un enregistrement DNS inaccessible uniquement en IPv6 peut entraîner des problèmes importants, car il remplacerait un enregistrement IPv4 précédent qui aurait pu continuer à fonctionner jusqu’à la requête suivante. L’option globale « dns-accept-family » permet d’imposer l’utilisation d’une seule famille d’adresses (ou des deux). L’argument est une liste séparée par des virgules des mots suivants : - « ipv4 » : interroger et accepter les adresses IPv4 (enregistrements « A ») - « ipv6 » : interroger et accepter les adresses IPv6 (enregistrements « AAAA ») - « auto » : utiliser IPv4, et IPv6 si le système dispose d’une passerelle par défaut pour celle-ci. Le résultat de la dernière vérification est mis en cache pendant 30 secondes.

Lorsqu’une seule famille est utilisée, aucune requête n’est envoyée aux résolveurs pour l’autre famille, et toute réponse provenant de cette dernière est ignorée. La valeur par défaut depuis la version 3.3 est « auto », qui active effectivement les deux familles uniquement une fois que l’IPv6 a été vérifié comme routable, sinon elle reste sur IPv4. Voir également : « resolve-prefer », « do-resolve »

expose-deprecated-directives

expose-deprecated-directives

Cette instruction doit apparaître avant d’utiliser certains directives marquées comme obsolètes afin de supprimer les avertissements et de garantir que le fichier de configuration ne sera pas rejeté. Toutes les directives obsolètes ne sont pas concernées, uniquement celles pour lesquelles aucune solution de remplacement n’existe.

expose-experimental-directives

expose-experimental-directives

Cette directive doit apparaître avant toute utilisation de directives marquées comme expérimentales, faute de quoi le fichier de configuration sera rejeté. Veuillez noter que les fonctionnalités couvertes par cette option ne sont pas garanties d’être stables et peuvent présenter des dysfonctionnements pendant le cycle de maintenance. Les développeurs les maintiendront dans un état de meilleur effort pendant la mise au point de la prochaine version, et s’efforceront de toute évidence d’éviter toute rupture, sans garantie. Pour ces raisons, ces fonctionnalités ne sont pas censées être prises en charge au-delà du lancement de la prochaine version LTS. Les utilisateurs souhaitant expérimenter ces fonctionnalités sont invités à effectuer une mise à jour rapide afin de bénéficier des améliorations apportées à ces fonctionnalités. Pour savoir si cette directive est encore nécessaire, il est simple : si elle est activée sans être utilisée par une telle fonctionnalité, un avertissement sera émis pour suggérer de la désactiver. Ainsi, en l’absence d’avertissement, cela signifie qu’elle est encore nécessaire.

external-check [preserve-env]

external-check [preserve-env]

Permet d’utiliser un agent externe pour effectuer les contrôles d’état. Cette fonctionnalité est désactivée par défaut en tant que mesure de sécurité, et même activée, les contrôles peuvent échouer sauf si « insecure-fork-wanted » est également activé. Si le programme lancé utilise un exécutable setuid (ce qui devrait en réalité être évité), vous devrez peut-être également définir « insecure-setuid-wanted » dans la section globale. Par défaut, les contrôles démarrent dans un environnement propre ne contenant que les variables définies dans la commande « external-check » de la section backend. Il peut parfois être souhaitable de préserver l’environnement, par exemple lorsque des scripts complexes récupèrent leurs chemins ou informations supplémentaires à partir de celui-ci. Cela peut être réalisé en ajoutant le mot-clé « preserve-env ». Dans ce cas, il est fortement conseillé de ne pas exécuter le programme en tant qu’utilisateur setuid ni en tant qu’utilisateur privilégié, afin d’éviter toute exposition à des attaques potentielles. Voir « option external-check », « insecure-fork-wanted » et « insecure-setuid-wanted » pour plus de détails.

fd-hard-limit <number>

fd-hard-limit <number>

Définit une limite supérieure au nombre maximum de descripteurs de fichiers utilisés par le processus, indépendamment des limites système. Bien que les paramètres « ulimit-n » et « maxconn » puissent être utilisés pour imposer une valeur, lorsque ces paramètres ne sont pas définis, le processus sera limité à la limite dure du paramètre RLIMIT_NOFILE tel que rapporté par la commande « ulimit -n -H ». Toutefois, certains systèmes d’exploitation modernes autorisent désormais des valeurs extrêmement élevées ici (de l’ordre d’un milliard), ce qui consommerait bien trop de mémoire vive pour une utilisation régulière. Le paramètre fd-hard-limit est fourni afin d’imposer une limite éventuellement plus basse à cette limite. Cela signifie qu’il respectera toujours les limites imposées par le système lorsqu’elles sont inférieures à <number>, mais utilisera la valeur spécifiée si les limites imposées par le système sont plus élevées. Par défaut, fd-hard-limit est défini à 1048576. Cette valeur par défaut peut être modifiée via la variable de compilation DEFAULT_MAXFD, qui peut servir de limite maximale (noyau) système, si la limite dure RLIMIT_NOFILE est extrêmement élevée. La définition de fd-hard-limit dans la section globale permet de remplacer temporairement la valeur fournie via DEFAULT_MAXFD au moment de la compilation. Dans l’exemple ci-dessous, aucune autre configuration n’est spécifiée et la valeur de maxconn s’ajustera automatiquement à la plus faible entre « fd-hard-limit » et la limite RLIMIT_NOFILE.

global
    # use as many FDs as possible but no more than 50000
    fd-hard-limit 50000

Voir aussi : ulimit-n, maxconn

gid <number>

gid <number>

Change l’identifiant de groupe du processus en <number>. Il est recommandé que cet identifiant de groupe soit dédié à HAProxy ou à un petit ensemble de démons similaires. HAProxy doit être lancé avec un utilisateur appartenant à ce groupe, ou avec des privilèges de superutilisateur. Notez qu’en cas de lancement depuis un utilisateur ayant des groupes supplémentaires, HAProxy ne pourra supprimer ces groupes que s’il est lancé avec des privilèges de superutilisateur. Voir également « group » et « uid ».

grace <time>

grace <time>

Définit un délai entre SIGUSR1 et l’arrêt doux réel.

Arguments :

<time>  is an extra delay (by default in milliseconds) after receipt of the
        SIGUSR1 signal that will be waited for before proceeding with the
        soft-stop operation.

Cela est utilisé pour assurer la compatibilité avec les environnements hérités où le processus HAProxy doit être arrêté, mais où certains composants externes doivent détecter l’état avant que les écouteurs ne soient déliés. Le principe consiste à définir la variable interne « stopping » (qui est rapportée par la fonction d’extraction d’échantillon « stopping ») à true, tout en maintenant l’acceptation des connexions par les écouteurs sans interruption, jusqu’à expiration du délai, après quoi l’arrêt doux classique s’effectuera. Cette option ne doit pas être utilisée avec des processus qui sont rechargés, car cela empêcherait le processus ancien de se délier, et pourrait empêcher le nouveau processus de démarrer, ou simplement provoquer des problèmes.

Exemple :

global
  grace 10s

# Returns 200 OK until stopping is set via SIGUSR1
frontend ext-check
  bind:9999
  monitor-uri /ext-check
  monitor fail if { stopping }

Veuillez noter qu’une approche plus souple et durable consisterait, pour un système d’orchestration, à définir une variable globale depuis la ligne de commande, à utiliser cette variable pour répondre aux vérifications externes, puis à envoyer le signal SIGUSR1 après un délai.

Exemple :

# Returns 200 OK until proc.stopping is set to non-zero. May be done
# from HTTP using set-var(proc.stopping) or from the CLI using:
# > set var proc.stopping int(1)
frontend ext-check
  bind:9999
  monitor-uri /ext-check
  monitor fail if { var(proc.stopping) -m int gt 0 }

Voir aussi : hard-stop-after, monitor

group <group name>

group <group name>

Similaire à « gid » mais utilise le GID du nom de groupe <group name> provenant de /etc/group.. Voir également « gid » et « user ».

h1-accept-payload-with-any-method

h1-accept-payload-with-any-method

N’interdit pas les requêtes HTTP/1.0 GET/HEAD/DELETE dont le corps provoque une réponse HTTP 413 Payload Too Large.

Bien que cela soit explicitement autorisé dans HTTP/1.1, HTTP/1.0 ne précise pas clairement ce point, et certains serveurs anciens ne s’attendent pas à avoir de charge utile et ne vérifient jamais la longueur du corps (via les en-têtes Content-Length ou Transfer-Encoding). Cela signifie que certains intermédiaires peuvent correctement gérer la charge utile pour les requêtes HTTP/1.0 GET/HEAD/DELETE, tandis que d’autres peuvent la ignorer totalement. Cela peut entraîner des problèmes de sécurité, car une attaque de camouflage de requête est possible. Par conséquent, par défaut, HAProxy rejette les requêtes HTTP/1.0 GET/HEAD/DELETE comportant une charge utile.

Toutefois, cela peut poser problème avec certains clients anciens. Dans ce cas, cette option globale peut être configurée.

h1-do-not-close-on-insecure-transfer-encoding

h1-do-not-close-on-insecure-transfer-encoding

Conformément à la spécification HTTP/1.1 (RFC9112#6.1), la présence simultanée d’un champ d’en-tête Transfer-Encoding et d’un champ d’en-tête Content-Length dans un même message représente un risque sérieux d’attaque par camouflage de contenu si un agent HTTP/1.0 se trouve dans la chaîne en amont ou en aval, et, en pareil cas, un agent doit absolument fermer la connexion après la réponse afin d’éviter toute exploitation. Toutefois, cela peut avoir un impact sur les performances avec certains clients très anciens, notamment s’ils doivent renégocier une connexion TLS pour chaque requête. Cette option est mise à disposition afin de demander à HAProxy de ne pas appliquer cette règle, et de ne faire que nettoyer le message tout en maintenant la connexion ouverte après la réponse. Cette action ne peut être entreprise que si l’on est absolument certain qu’aucun agent HTTP/1.0 n’est présent dans la chaîne et que toutes les implémentations situées en amont d’HAProxy sont pleinement conformes à HTTP/1.1 aux règles applicables à ces champs d’en-tête. Dans tous les cas, HAProxy continuera à ignorer et à supprimer le champ Content-Length superflu afin de ne pas induire en erreur le prochain saut.

Lorsqu’on active cette option pour contourner un client ou un serveur ancien défectueux, il est essentiel de comprendre que, qu’il en soit besoin ou non, un tel agent qui enfreint cette règle court le risque d’avoir ses messages tronqués par des agents anciens qui considèrent Content-Length et ignorent Transfer-Encoding, car la taille cumulée des tailles des tronçons encodés n’est pas prise en compte. En conséquence, la règle ci-dessus n’est pas seulement une question de sécurité, mais aussi une mesure visant à éliminer les agents susceptibles de rencontrer des problèmes de communication en raison d’incompatibilités avec des versions plus anciennes.

h1-case-adjust <from> <to>

h1-case-adjust <from> <to>

Définit l’ajustement de casse à appliquer, lorsqu’il est activé, au nom de l’en-tête <from>, pour le convertir en <to> avant de l’envoyer aux clients ou serveurs HTTP/1. <from> doit être en minuscules, et <from> ainsi que <to> doivent ne différer que par leur casse. Cette directive peut être répétée si plusieurs noms d’en-tête doivent être ajustés. Les entrées en double ne sont pas autorisées. Si un grand nombre de noms d’en-tête doivent être ajustés, il peut être plus pratique d’utiliser « h1-case-adjust-file ». Veuillez noter qu’aucune transformation ne sera appliquée à moins que « option h1-case-adjust-bogus-client » ou « option h1-case-adjust-bogus-server » ne soit spécifiée dans un proxy.

Il n’existe pas de cas standard pour les noms d’en-têtes, car, comme indiqué dans RFC7230, ils sont insensibles à la casse. Les applications doivent donc les traiter de manière insensible à la casse. Toutefois, certaines applications incorrectes violent les normes et s’appuient erronément sur les cas les plus couramment utilisés par les navigateurs. Ce problème devient critique avec HTTP/2 car tous les noms d’en-têtes doivent être échangés en minuscules, et HAProxy adopte la même convention. Tous les noms d’en-têtes sont envoyés en minuscules aux clients et aux serveurs, indépendamment de la version HTTP.

Les applications qui ne traitent pas correctement les requêtes ou les réponses peuvent nécessiter l’utilisation temporaire de telles solutions de contournement afin d’ajuster les noms d’en-têtes envoyés pendant la durée nécessaire à la correction de l’application. Veuillez noter qu’une application qui requiert de telles solutions de contournement pourrait être vulnérable aux attaques d’envoi de contenu masqué et doit être corrigée absolument.

Exemple :

global
  h1-case-adjust content-length Content-Length

Voir « h1-case-adjust-file », « option h1-case-adjust-bogus-client » et « option h1-case-adjust-bogus-server ».

h1-case-adjust-file <hdrs-file>

h1-case-adjust-file <hdrs-file>

Définit un fichier contenant une liste de paires key/value utilisées pour ajuster la casse de certains noms d’en-têtes avant de les envoyer aux clients ou serveurs HTTP/1. Le fichier <hdrs-file> doit contenir deux noms d’en-têtes par ligne. Le premier doit être en minuscules, et les deux doivent différer uniquement par leur casse. Les lignes commençant par ‘#’ sont ignorées, tout comme les lignes vides. Les tabulations et espaces en début et fin de ligne sont supprimés. Les entrées en double ne sont pas autorisées. Veuillez noter qu’aucune transformation ne sera appliquée à moins que « option h1-case-adjust-bogus-client » ou « option h1-case-adjust-bogus-server » soit spécifiée dans un proxy.

Si cette directive est répétée, seule la dernière sera traitée. Il s’agit d’une alternative à la directive « h1-case-adjust » lorsque de nombreux noms d’en-têtes doivent être ajustés. Veuillez lire les risques associés à son utilisation.

Voir « h1-case-adjust », « option h1-case-adjust-bogus-client » et « option h1-case-adjust-bogus-server ».

h2-workaround-bogus-websocket-clients

h2-workaround-bogus-websocket-clients

88. Cela désactive l’annonce de la prise en charge des websockets h2 aux clients. Cela peut être utilisé pour contourner les clients présentant des problèmes lors de l’implémentation du RFC8441 relativement récent, tels que Firefox . Pour permettre aux clients de passer automatiquement à http/1.1 pour le tunnel websocket, spécifiez la prise en charge de h2 dans la ligne bind en utilisant “alpn” sans mot-clé explicite “proto”. Si cette option était précédemment activée, elle peut être désactivée en préfixant le mot-clé par “no”.

hard-stop-after <time>

hard-stop-after <time>

Définit le temps maximum autorisé pour effectuer une extinction douce propre.

Arguments :

<time>  is the maximum time (by default in milliseconds) for which the
        instance will remain alive when a soft-stop is received via the
        SIGUSR1 signal.

Cela peut être utilisé pour garantir que l’instance s’arrête même si des connexions restent ouvertes pendant un arrêt doux (par exemple avec des délais d’expiration longs pour un proxy en mode tcp). Cela s’applique aussi bien en mode TCP qu’en mode HTTP.

Exemple :

global
  hard-stop-after 30s

Voir aussi : grace

harden.reject-privileged-ports.tcp { on | off }

harden.reject-privileged-ports.tcp { on | off }
harden.reject-privileged-ports.quic { on | off }

Protection par protocole activée/désactivée, qui interdit les communications avec les clients utilisant des ports privilégiés comme port source. Cette plage de ports est définie conformément au RFC 6335. Par défaut, la protection est active pour le protocole QUIC, car ce comportement est suspect et peut être utilisé dans le cadre d’une attaque d’usurpation d’identité ou d’amplification DNS/NTP.

http-err-codes [+-]<range>[,...] [...]

http-err-codes [+-]<range>[,...] [...]

Remplace, réduit ou étend la liste des codes d’état qui définissent une erreur selon les codes de terminaison et le compteur “http_err_cnt” dans les tables de persistance. La plage par défaut pour les erreurs est 400 à 499, mais dans certains contextes, certains utilisateurs préfèrent exclure des codes spécifiques, notamment lors du suivi des erreurs client (par exemple, 404 sur des systèmes à contenus générés dynamiquement). Voir également « http-fail-codes » et “http_err_cnt”.

Une plage spécifiée sans ‘+’ ni ‘-’ redéfinit la plage existante par la nouvelle plage. Une plage commençant par ‘+’ étend la plage existante pour inclure également la plage spécifiée, qui peut chevaucher ou non la plage existante. Une plage commençant par ‘-’ retire la plage spécifiée de la plage existante. Une plage est composée d’un nombre compris entre 100 et 599, suivi éventuellement de “-” et d’un autre nombre supérieur ou égal au premier pour indiquer la borne supérieure de la plage. Plusieurs plages peuvent être séparées par des virgules pour une même opération add/del/replace.

Exemple :

http-err-codes 400,402-444,446-480,490   # sets exactly these codes
http-err-codes 400-499 -450 +500         # sets 400 to 500 except 450
http-err-codes -450-459                  # removes 450 to 459 from range
http-err-codes +501,505                  # adds 501 and 505 to range

http-fail-codes [+-]<range>[,...] [...]

http-fail-codes [+-]<range>[,...] [...]

Remplace, réduit ou étend la liste des codes d’état qui définissent une erreur selon les codes de terminaison et le compteur “http_fail_cnt” dans les tables de persistance. La plage par défaut des erreurs est comprise entre 500 et 599, à l’exception des codes 501 et 505, qui peuvent être déclenchés par les clients et indiquent normalement une erreur du serveur pour traiter la requête. Certains utilisateurs préfèrent exclure certains codes dans certains contextes où ils sont connus pour ne pas être pertinents, par exemple le code 500 dans certains environnements SOAP, où il ne traduit pas nécessairement une erreur du serveur. La syntaxe est identique à celle de http-err-codes ci-dessus. Voir également « http-err-codes » et “http_fail_cnt”.

insecure-fork-wanted

insecure-fork-wanted

Par défaut, HAProxy s’efforce de prévenir toute création de thread ou de processus après son démarrage. Cette mesure est particulièrement importante lors de l’utilisation de fichiers Lua d’origine incertaine, ainsi que lors de l’expérimentation avec des versions de développement pouvant encore contenir des bogues dont l’exploitabilité est incertaine. En général, il s’agit d’une bonne pratique pour s’assurer qu’aucune activité en arrière-plan imprévue ne puisse être déclenchée par le trafic. Toutefois, cela empêche les vérifications externes de fonctionner et peut rompre certains scripts Lua très spécifiques qui dépendent activement de la capacité à fork. Cette option permet de désactiver cette protection. Notez qu’il est une mauvaise idée de la désactiver, car une vulnérabilité dans une bibliothèque ou dans HAProxy lui-même deviendra plus facile à exploiter une fois désactivée. En outre, le fork depuis Lua ou n’importe où ailleurs n’est pas fiable, car le processus forké peut aléatoirement héberger un verrou défini par un autre thread et ne jamais parvenir à terminer une opération. Il est donc fortement recommandé de ne jamais utiliser cette option et de reconsidérer toute charge de travail nécessitant un fork, en la transférant vers une solution plus sûre (comme des agents au lieu de vérifications externes). Cette option prend en charge le préfixe « no » pour la désactiver. Elle peut également être activée via “-dI” en ligne de commande HAProxy.

insecure-setuid-wanted

insecure-setuid-wanted

HAProxy n’a pas besoin d’appeler d’exécutables au moment de l’exécution (sauf lors de l’utilisation de vérifications externes, qui sont fortement déconseillées), et doit même être isolé dans un environnement chroot vide. En conséquence, il n’existe pratiquement aucune raison valable de permettre l’appel d’un exécutable setuid sans que l’utilisateur en soit pleinement conscient des risques. Dans une situation où HAProxy devrait appeler des vérifications externes and/or, la désactivation du chroot pourrait permettre l’exécution d’un programme externe si une vulnérabilité est présente dans une bibliothèque ou dans HAProxy lui-même. Sur Linux, il est possible de verrouiller le processus de manière à ignorer tout bit setuid présent sur un tel exécutable. Cela réduit fortement le risque d’élévation de privilèges dans une telle situation. C’est précisément ce que HAProxy fait par défaut. Si cela pose problème à une vérification externe (par exemple une qui nécessiterait la commande « ping »), il est possible de désactiver cette protection en ajoutant explicitement cette directive dans la section global. Si activée, il est possible de la désactiver à nouveau en préfixant la directive par le mot-clé « no ».

issuers-chain-path <dir>

issuers-chain-path <dir>

Attribue un répertoire pour charger la chaîne de certificats afin de compléter l’émetteur. Tous les fichiers doivent être au format PEM. Pour les certificats chargés avec « crt » ou « crt-list », si la chaîne de certificats n’est pas incluse dans le PEM (appelée couramment certificat intermédiaire), HAProxy complétera la chaîne si l’émetteur du certificat correspond au premier certificat de la chaîne chargée via « issuers-chain-path ». Un fichier « crt » contenant Clé privée + Certificat + IntermediateCA2 + IntermediateCA1 peut être remplacé par Clé privée + Certificat. HAProxy complétera la chaîne si un fichier contenant IntermediateCA2 + IntermediateCA1 est présent dans le répertoire « issuers-chain-path ». Tous les autres certificats ayant le même émetteur partageront la chaîne en mémoire.

Les fonctionnalités OCSP sont capables d’utiliser la chaîne complète lorsqu’aucun champ .issuer n’a été utilisé, ou lorsqu’aucune chaîne n’a été fournie au format PEM.

jwt.decrypt_alg_list <list>

jwt.decrypt_alg_list <list>

Définir la liste des algorithmes autorisés dans les convertisseurs jwt_decrypt_XXX. Les jetons JWT utilisant un algorithme non pris en charge ou désactivé ne seront jamais déchiffrés. Les algorithmes spécifiés doivent avoir le même format que celui décrit dans la section 4.1 de RFC7518 et être séparés par des deux-points. Le nom spécial « ALL » peut être utilisé pour activer tous les algorithmes pris en charge (voir le convertisseur “jwt_decrypt_jwk” pour la liste complète), et un « ! » peut être ajouté au nom d’un algorithme pour le désactiver explicitement. Veuillez noter qu’à moins que « ALL » ne soit spécifié, l’utilisation de cette option désactivera tout algorithme non explicitement mentionné dans la liste fournie.

Exemples :

# Enable all algorithms but the "ECDH-ES" one
jwt.decrypt_alg_list ALL:!ECDH-ES

# Only enable ECDH-ES algorithms
jwt.decrypt_alg_list ECDH-ES:ECDH-ES+A128KW:ECDH-ES+A192KW:ECDH-ES+A256KW

jwt.decrypt_enc_list <list>

jwt.decrypt_enc_list <list>

Définissez la liste des algorithmes de chiffrement autorisés dans les convertisseurs jwt_decrypt_XXX. Les jetons JWT utilisant un algorithme de chiffrement non pris en charge ou désactivé ne seront jamais déchiffrés. Les algorithmes spécifiés doivent avoir le même format que celui indiqué dans section 5.1 de RFC7518 et être séparés par des deux-points. Le nom spécial « ALL » peut être utilisé pour activer tous les algorithmes pris en charge (voir le convertisseur “jwt_decrypt_jwk” pour la liste complète) et un « ! » peut être ajouté au nom d’un algorithme pour le désactiver explicitement. Veuillez noter qu’à moins que « ALL » ne soit spécifié, l’utilisation de cette option désactivera tout algorithme non explicitement mentionné dans la liste fournie.

Exemples :

# Enable only AES GCM encrypting algorithms
jwt.decrypt_enc_list A128GCM:A192GCM:A256GCM

key-base <dir>

key-base <dir>

Attribue un répertoire par défaut pour récupérer les clés privées SSL lorsque l’option « key » utilise un chemin relatif. Les emplacements absolus spécifiés prévalent et ignorent « key-base ». Cette option ne fonctionne qu’avec une ligne de chargement « crt-store ».

limited-quic

limited-quic

Ce paramètre doit être utilisé pour activer explicitement les liaisons d’écouteur QUIC lorsque haproxy est compilé avec une version d’OpenSSL ne prenant pas en charge QUIC. Il active une couche de compatibilité interne à HAProxy qui doit avoir été sélectionnée au moment de la compilation avec USE_QUIC_OPENSSL_COMPAT=1. Cette couche de compatibilité prend en charge la plupart des opérations TLS nécessaires, bien qu’elle ne permette pas la fonctionnalité QUIC 0-RTT.

Cette fonctionnalité est principalement destinée à OpenSSL antérieur à la version 3.5.2, où l’API QUIC n’était pas implémentée ou seulement partiellement. La couche de compatibilité peut toutefois être activée pour les versions 3.5.2 et ultérieures, mais cela est probablement inutile.

Si l’option limited-quic est définie, mais que la couche de compatibilité n’a pas été sélectionnée au moment de la compilation, l’option est ignorée sans message et les opérations QUIC TLS s’appuient sur la bibliothèque TLS.

localpeer <name>

localpeer <name>

Définit le nom de l’instance locale. Ce paramètre sera ignoré si l’argument en ligne de commande “-L” est spécifié ou si cette directive est utilisée après la définition de la section “peers”. Dans ces cas, un message d’avertissement sera émis pendant l’analyse de la configuration.

Cette option définit également la variable d’environnement HAPROXY_LOCALPEER. Voir également “-L” dans le guide de gestion et la section « peers » ci-dessous.

log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]

log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
    [profile <prof>] <facility> [max level [min level]]

Ajoute un serveur syslog global. Plusieurs serveurs globaux peuvent être définis. Ils recevront les journaux relatifs aux démarrages et arrêts, ainsi que tous les journaux des proxies configurés avec « log global ». Voir l’option « log » pour les proxies pour plus de détails.

log-send-hostname [<string>]

log-send-hostname [<string>]

Définit le champ nom d’hôte dans l’en-tête syslog. Si le paramètre facultatif « string » est défini, l’en-tête est défini sur le contenu de la chaîne, sinon il utilise le nom d’hôte du système. Généralement utilisé lorsqu’on ne relaie pas les journaux via un serveur syslog intermédiaire ou pour personnaliser simplement le nom d’hôte affiché dans les journaux.

log-tag <string>

log-tag <string>

Définit le champ tag dans l’en-tête syslog à cette chaîne. La valeur par défaut est le nom du programme tel qu’il a été lancé depuis la ligne de commande, qui est généralement « HAProxy ». Il peut parfois être utile de distinguer plusieurs processus s’exécutant sur le même hôte. Voir également la directive « log-tag » par proxy.

lua-load <file> [ <arg1> [ <arg2> [ ... ] ] ]

lua-load <file> [ <arg1> [ <arg2> [ ... ] ] ]

Ce directive globale charge et exécute un fichier Lua dans le contexte partagé, visible par tous les threads. Toute variable définie dans ce contexte est accessible depuis n’importe quel thread. Il s’agit de la méthode la plus simple et recommandée pour charger des programmes Lua, mais elle ne se prête pas bien à une grande quantité d’appels Lua, car un seul thread peut s’exécuter à la fois sur l’état global. Un programme chargé de cette manière verra toujours la valeur 0 dans la variable “core.thread”. Cette directive peut être utilisée plusieurs fois.

Les arguments sont disponibles dans le fichier Lua à l’aide du code ci-dessous, placé dans le corps du fichier. N’oubliez pas que les tableaux Lua commencent à l’index 1. Une variable déclarée en tant que « local » dans un fichier est disponible dans l’ensemble du fichier et non dans les autres fichiers.

 local args = table.pack(...)

lua-load-per-thread <file> [ <arg1> [ <arg2> [ ... ] ] ]

lua-load-per-thread <file> [ <arg1> [ <arg2> [ ... ] ] ]

Ce directive global charge et exécute un fichier Lua dans chaque thread démarré. Toute variable globale a une visibilité locale au thread, de sorte que chaque thread peut voir une valeur différente. Il est donc fortement recommandé de ne pas utiliser de variables globales dans les programmes chargés de cette manière. Une copie indépendante est chargée et initialisée pour chaque thread, tout est effectué séquentiellement et dans l’ordre numérique des threads de 1 à nbthread. Si certaines opérations doivent être effectuées une seule fois, le programme doit vérifier la variable “core.thread” afin de déterminer quel thread est en cours d’initialisation. Les programmes chargés de cette manière s’exécutent en parallèle sur tous les threads et sont hautement évolutifs. Il s’agit de la méthode recommandée pour charger des fonctions simples qui enregistrent des collectes d’échantillons, des convertisseurs, des actions ou des services, une fois assuré que le programme ne dépend pas de variables globales. Pour des raisons de simplicité, la directive est disponible même si un seul thread est utilisé, ou même si les threads sont désactivés (auquel cas elle équivaut à lua-load). Cette directive peut être utilisée plusieurs fois.

Voir lua-load pour l’utilisation des arguments.

lua-prepend-path <string> [<type>]

lua-prepend-path <string> [<type>]

Préfixe la chaîne donnée suivie d’un point-virgule à la variable Lua package.<type>. <type> doit être soit “path” soit “cpath”. Si <type> n’est pas fourni, sa valeur par défaut est “path”.

Les chemins Lua sont des listes séparées par des points-virgules spécifiant comment la fonction require tente de localiser le fichier source d’une bibliothèque. Les points d’interrogation (?) figurant dans un motif sont remplacés par le nom du module. Le chemin est évalué de gauche à droite. Cela implique que les chemins ajoutés en tête seront vérifiés en premier.

Par exemple, en spécifiant le chemin suivant :

lua-prepend-path /usr/share/haproxy-lua/?/init.lua
lua-prepend-path /usr/share/haproxy-lua/?.lua

Lorsque require "example" est appelé, Lua tentera d’abord de charger le script /usr/share/haproxy-lua/example.lua. Si celui-ci n’existe pas, le script /usr/share/haproxy-lua/example/init.lua sera tenté, puis les chemins par défaut, si celui-ci n’existe pas non plus.

Voir https://www.lua.org/pil/8.1.html pour les détails dans la documentation Lua.

master-worker (deprecated)

master-worker (deprecated)

Mode maître-worker. Il est équivalent à l’argument de ligne de commande “-W”.

Ce mot-clé est obsolète. Veuillez démarrer en mode master-worker en utilisant “-W” ou “-Ws”.

Ce mode lancera un « master » qui fera fork d’un « worker » après lecture de la configuration, afin de traiter le trafic. Le master sert de gestionnaire de processus et surveillera les « workers ».

Utilisez ce mode pour recharger HAProxy directement en envoyant le signal SIGUSR2 au processus principal. Le rechargement demande au processus principal de lire à nouveau la configuration et de créer un nouveau processus worker. Le processus worker précédent sera conservé jusqu’à la fin de ses tâches.

Le mode master-worker est compatible avec le mode en premier plan ou le mode démon.

Par défaut, si un worker quitte avec un code de retour incorrect, par exemple en cas de segmentation fault, tous les workers seront tués et le processus principal s’arrêtera. Il est pratique de combiner ce comportement avec Restart=on-failure dans un fichier d’unité systemd afin de relancer l’ensemble du processus. Si vous ne souhaitez pas ce comportement, vous devez utiliser le mot-clé « no-exit-on-failure ».

Voir également “-W” dans le guide de gestion.

master-worker no-exit-on-failure

master-worker no-exit-on-failure

En mode maître-worker, par défaut, si un worker se termine avec un code de retour incorrect, par exemple en cas de violation d’accès mémoire, tous les workers seront tués et le maître quittera également. Il est pratique de combiner ce comportement avec Restart=on-failure dans un fichier d’unité systemd afin de relancer l’ensemble du processus.

Ce mot-clé permet de maintenir les processus restants en vie lorsque un worker a planté, au lieu de tuer tout le monde. Il doit être utilisé avec précaution, car il n’est destiné qu’à la débogage et pourrait mettre le processus principal dans un état anormal.

max-threads-per-group <number>

max-threads-per-group <number>

Définit le nombre maximal de threads dans un groupe de threads. À moins que le nombre de groupes de threads ne soit fixé avec la directive « thread-groups », HAProxy créera autant de groupes de threads qu’il en faut pour satisfaire le nombre de threads demandé. La valeur minimale est 1, et la valeur maximale est 64 (sur les systèmes 64 bits), ou 32 (sur les systèmes 32 bits). Des valeurs plus faibles réduisent la contention provoquée par les opérations atomiques sur les états partagés, mais peuvent augmenter le nombre de sockets nécessaires pour créer tous les écouteurs et maintenir les connexions backend inactives. Des valeurs plus élevées réduisent ces coûts, au prix d’une utilisation CPU plus élevée en cas de contention, et d’un débit de connexions plus faible. La valeur par défaut est 16, qui représente le meilleur compromis trouvé expérimentalement sur divers systèmes testés, y compris des processeurs x86_64 de plusieurs constructeurs, ainsi que des systèmes Arm64 de grande taille, qu’ils soient exécutés en natif ou sous hyperviseur.

mworker-max-reloads <number>

mworker-max-reloads <number>

En mode maître-ouvrier, cette option limite le nombre de fois qu’un ouvrier peut survivre à une relecture. Si l’ouvrier ne quitte pas après une relecture, une fois que son nombre de relectures dépasse cette valeur, il recevra un SIGTERM. Cette option permet de maintenir sous contrôle le nombre d’ouvrages. Voir également « show proc » dans le guide d’administration.

Par défaut, cette valeur est définie à 50.

nbthread <number>

nbthread <number>

Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il fait exécuter HAProxy sur <number> threads. Le paramètre « nbthread » fonctionne également lorsque HAProxy est lancé en mode frontal. Sur certaines plates-formes prenant en charge l’affinité processeur, la valeur par défaut de « nbthread » est automatiquement ajustée au nombre de processeurs auxquels le processus est lié au démarrage. Cela signifie que le nombre de threads peut être facilement ajusté depuis le processus appelant à l’aide de commandes telles que « taskset » ou « cpuset ». Sinon, cette valeur par défaut est égale à 1. La valeur par défaut est indiquée dans la sortie de la commande « HAProxy -vv ». Notez que les valeurs définies ici ou détectées automatiquement sont soumises à la limite fixée par « thread-hard-limit » (le cas échéant).

numa-cpu-mapping

numa-cpu-mapping

Lorsqu’il est exécuté sur une plateforme sensible au NUMA, cette option permet à la directive « cpu-policy » d’inspecter la topologie afin de déterminer l’ensemble optimal de processeurs à utiliser ainsi que le nombre correspondant de threads. Toutefois, si l’affectation appliquée n’est pas optimale sur une architecture particulière, elle peut être désactivée à l’aide de l’instruction « no numa-cpu-mapping ». Ce lien automatique n’est pas appliqué non plus si une directive « nbthread » est présente dans la configuration, si l’affinité du processus est déjà définie (par exemple via la directive « cpu-map » ou l’outil taskset), ou si la directive « cpu-policy » est définie sur une autre valeur. Voir également « cpu-map », « cpu-policy », « cpu-set ».

ocsp-update.disable [ on | off ]

ocsp-update.disable [ on | off ]

Désactive complètement le mécanisme ocsp-update dans HAProxy. Toute configuration ocsp-update sera ignorée. Valeur par défaut : « off ». Voir l’option « ocsp-update » pour plus d’informations sur le mécanisme de mise à jour automatique.

ocsp-update.httpproxy <address>[:port]

ocsp-update.httpproxy <address>[:port]

Permet d’utiliser un proxy HTTP pour les mises à jour OCSP. Cela ne fonctionne qu’avec HTTP ; HTTPS n’est pas pris en charge. Cette option permet à l’updater OCSP d’envoyer une URI absolue dans la requête au proxy.

ocsp-update.maxdelay <number>

ocsp-update.maxdelay <number>
tune.ssl.ocsp-update.maxdelay <number> (deprecated)

Définit l’intervalle maximal entre deux mises à jour automatiques de la même réponse OCSP. Cette durée est exprimée en secondes et vaut 3600 par défaut (1 heure). Elle doit être définie à une valeur supérieure à “ocsp-update.mindelay”. Pour plus d’informations sur le mécanisme de mise à jour automatique, voir l’option « ocsp-update ».

ocsp-update.mindelay <number>

ocsp-update.mindelay <number>
tune.ssl.ocsp-update.mindelay <number> (deprecated)

Définit l’intervalle minimal entre deux mises à jour automatiques de la même réponse OCSP. Cette durée est exprimée en secondes et vaut 300 par défaut (5 minutes). Elle est particulièrement utile pour les réponses OCSP ne disposant pas de temps d’expiration explicite. Elle doit être définie à une valeur inférieure à “ocsp-update.maxdelay”. Pour plus d’informations sur le mécanisme de mise à jour automatique, voir l’option « ocsp-update ».

ocsp-update.mode [ on | off ]

ocsp-update.mode [ on | off ]

Définit le mode par défaut d’actualisation OCSP pour tous les certificats utilisés dans la configuration. Cette option globale peut être remplacée par l’option « ocsp-update » du bloc crt-list. Cette option est définie sur « off » par défaut. Voir l’option « ocsp-update » pour plus d’informations sur le mécanisme d’actualisation automatique.

pidfile <pidfile>

pidfile <pidfile>

Écrit les PID de tous les démons dans le fichier <pidfile> en mode démon, ou le PID du processus principal dans le fichier <pidfile> en mode principal-travailleur. Cette option est équivalente à l’argument en ligne de commande “-p”. Le fichier doit être accessible à l’utilisateur lançant le processus. Voir également « daemon » et « master-worker ».

pp2-never-send-local

pp2-never-send-local

Une erreur dans l’implémentation du protocole PROXY v2 était présente dans HAProxy jusqu’à la version 2.1, provoquant l’émission d’une commande PROXY au lieu d’une commande LOCAL pour les contrôles d’état. Cela est particulièrement mineur mais perturbe les journaux de certains serveurs. Malheureusement, cette erreur a été découverte très tardivement, révélant que certains serveurs, qui n’avaient éventuellement testé leur implémentation du protocole PROXY qu’avec HAProxy, ne gèrent pas correctement la commande LOCAL, et restent définitivement en état « down » lorsque HAProxy les vérifie. Lorsque cela se produit, il est possible d’activer cette option globale afin de revenir temporairement au comportement antérieur (incorrect) pendant le temps nécessaire à la mise en contact des fournisseurs des composants concernés et à leur correction. Cette option est désactivée par défaut et s’applique à tous les serveurs ayant la directive « send-proxy-v2 ».

presetenv <name> <value>

presetenv <name> <value>

Définit la variable d’environnement <name> avec la valeur <value>. Si la variable existe, elle n’est PAS remplacée. Les modifications prennent effet immédiatement, de sorte que la ligne suivante dans le fichier de configuration voit la nouvelle valeur. Voir également « setenv », « resetenv » et « unsetenv ».

prealloc-fd

prealloc-fd

Effectue une ouverture unique du descripteur de fichier maximum, ce qui entraîne une pré-allocation des structures de données du noyau. Cela évite les pauses brèves lorsque nbthread > 1 et qu’HAProxy ouvre un descripteur de fichier nécessitant une extension des structures de données du noyau.

resetenv [<name> ...]

resetenv [<name> ...]

Supprime toutes les variables d’environnement sauf celles spécifiées en argument. Cela permet d’utiliser un environnement propre et contrôlé avant de définir de nouvelles valeurs avec setenv ou unsetenv. Veuillez noter que certaines fonctions internes peuvent utiliser certaines variables d’environnement, telles que les fonctions de manipulation du temps, OpenSSL ou encore les vérifications externes. Cette directive doit être utilisée avec une extrême prudence et uniquement après validation complète. Les modifications prennent effet immédiatement, de sorte que la ligne suivante du fichier de configuration voit le nouvel environnement. Voir également « setenv », « presetenv » et « unsetenv ».

server-state-base <directory>

server-state-base <directory>

Spécifie le préfixe de répertoire à ajouter devant les noms de fichiers d’état des serveurs, pour ceux qui ne commencent pas par un ‘/’. Voir également « server-state-file », « load-server-state-from-file » et « server-state-file-name ».

server-state-file <file>

server-state-file <file>

Spécifie le chemin vers le fichier contenant l’état des serveurs. Si le chemin commence par une barre oblique (’/’), il est considéré comme absolu, sinon il est considéré comme relatif au répertoire spécifié par « server-state-base » (le cas échéant) ou au répertoire courant. Avant de recharger HAProxy, il est possible de sauvegarder l’état actuel des serveurs en utilisant la commande de statistiques « show servers state ». La sortie de cette commande doit être écrite dans le fichier pointé par <file>. Lors du démarrage, avant de traiter le trafic, HAProxy lira, chargera et appliquera l’état de chaque serveur présent dans le fichier et disponible dans sa configuration en cours d’exécution. Voir également « server-state-base » et « show servers state », « load-server-state-from-file » et « server-state-file-name »

set-dumpable [ on | off | libs ]

set-dumpable [ on | off | libs ]

Cette option permet de choisir le comportement en cas de panne du processus. Les options disponibles sont :

• : cela active le débogage en mémoire au niveau du processus si celui-ci était auparavant désactivé.

• off désactive le débogage en mode noyau, précédemment activé.

• libs active la génération de fichiers de débogage contenant une copie intégrée des binaires et des bibliothèques nécessaires. Cette fonction peut être demandée par les développeurs. Dans ce cas, HAProxy tentera de charger les bibliothèques dont il dépend en mémoire et de les conserver en mémoire. Si le processus se bloque, ces éléments seront inclus dans le fichier de débogage, ce qui évite de devoir les récupérer depuis le système de fichiers et élimine tout risque de désynchronisation avec le fichier de débogage. Cette fonction consomme quelques mégaoctets à une dizaine de mégaoctets supplémentaires de mémoire RAM, il est donc préférable de ne pas l’utiliser sur les systèmes à ressources limitées.

Cette option est préférable laissée désactivée par défaut et activée uniquement sur demande d’un développeur. Par défaut, elle est désactivée. Sans argument, elle est par défaut définie sur « on ». Si elle a été activée, elle peut toutefois être fortement désactivée en la préfixant par le mot-clé « no » ou en la définissant sur « off ». Elle n’a aucune incidence sur les performances ni la stabilité, mais tente activement de réactiver les dumps de noyau qui auraient pu être désactivés par des limites de taille de fichier (ulimit -f), des limites de taille de dump (ulimit -c) ou la « dumpabilité » d’un processus après avoir modifié son UID/GID (comme /proc/sys/fs/suid_dumpable sous Linux). Les dumps de noyau peuvent toutefois être limités par les permissions du répertoire courant (vérifiez quel répertoire est utilisé pour le démarrage du fichier), les permissions du répertoire chroot (il peut être nécessaire de désactiver temporairement la directive chroot ou de le déplacer vers un emplacement dédié et accessible en écriture), ou toute autre contrainte spécifique au système. Par exemple, certaines distributions Linux sont réputées pour remplacer le chemin par défaut du fichier de dump par un chemin vers un exécutable non installé sur le système (vérifiez /proc/sys/kernel/core_pattern). En général, il suffit souvent d’écrire « core », « core.%p » ou « /var/log/core/core.%p » pour résoudre le problème. Lorsqu’on tente d’activer cette option en attendant la réapparition d’un problème rare, il est souvent judicieux de d’abord essayer d’obtenir un tel dump en émettant, par exemple, « kill -11 » au processus « HAProxy » et de vérifier qu’un dump est bien généré à l’endroit attendu lors de sa mort.

set-var <var-name> <expr>

set-var <var-name> <expr>

Définit la variable globale ‘<var-name>’ avec le résultat de l’évaluation de l’expression d’extraction <expr>. La variable ‘<var-name>’ ne peut être qu’une variable globale (utilisant le préfixe ‘proc.’). Son fonctionnement est identique à l’action « set-var » dans les règles TCP ou HTTP, à ceci près que l’expression est évaluée au moment de l’analyse de la configuration et que la variable est immédiatement définie. Les fonctions d’extraction d’échantillon et convertisseurs autorisés dans l’expression ne sont que ceux utilisant des données internes, typiquement « int(valeur) » ou « str(valeur) ». Il est également possible de référencer des variables précédemment allouées. Ces variables pourront alors être lues (et modifiées) depuis les ensembles de règles réguliers.

Exemple :

global
    set-var proc.current_state str(primary)
    set-var proc.prio int(100)
    set-var proc.threshold int(200),sub(proc.prio)

set-var-fmt <var-name> <fmt>

set-var-fmt <var-name> <fmt>

Définit la variable globale ‘<var-name>’ à la chaîne résultant de l’évaluation du format de journal <fmt>. La variable ‘<var-name>’ ne peut être qu’une variable globale (en utilisant le préfixe ‘proc.’). Elle fonctionne exactement comme l’action ‘set-var-fmt’ dans les règles TCP ou HTTP, sauf que l’expression est évaluée au moment de l’analyse de la configuration et que la variable est immédiatement définie. Les fonctions d’extraction d’échantillon et convertisseurs autorisés dans l’expression sont uniquement ceux utilisant des données internes, typiquement ‘int(valeur)’ ou ‘str(valeur)’. Il est possible de référencer des variables précédemment allouées. Ces variables seront ensuite accessibles (et modifiables) depuis les ensembles de règles réguliers. Voir la section 8.2.6 pour les détails sur la syntaxe des formats de journal personnalisés.

Exemple :

global
    set-var-fmt proc.current_state "primary"
    set-var-fmt proc.bootid        "%pid|%t"

setcap <name>[,<name>...]

setcap <name>[,<name>...]

Définit une liste de capacités à préserver lors du démarrage et de l’exécution, soit en tant qu’utilisateur non root (uid > 0), soit en démarrant avec uid 0 (root) puis en basculant vers un utilisateur non root. Par défaut, toutes les permissions sont perdues lors du changement d’uid, mais certaines sont souvent nécessaires lors de la connexion à un serveur depuis une adresse étrangère en mode proxy transparent, ou lors de la liaison à un port inférieur à 1024, par exemple lors de l’utilisation de « tune.quic.fe.sock-per-conn default-on », entraînant des configurations s’exécutant entièrement sous uid 0. Affecter des capacités est généralement une solution plus sûre, car seules les capacités nécessaires sont conservées. Cette fonctionnalité est spécifique à l’OS et n’est activée que sous Linux lorsque USE_LINUX_CAP=1 est défini au moment de la compilation. La liste des capacités prises en charge dépend également de l’OS et est indiquée par le message d’erreur affiché en cas de passage d’un nom de capacité invalide ou vide. Plusieurs capacités peuvent être spécifiées, séparées par des virgules. Parmi celles couramment utilisées, “cap_net_raw” permet de lier de manière transparente à une adresse étrangère, et “cap_net_bind_service” permet de lier à un port privilégié et peut être utilisé par QUIC. Si le processus est lancé et exécuté sous le même utilisateur non root, les capacités nécessaires doivent être définies sur le binaire HAProxy à l’aide de setcap, en conjonction avec cette directive. Pour plus de détails sur la configuration des capacités sur le binaire HAProxy, se référer à la section 13.1 Prise en charge des capacités Linux du guide de gestion.

Exemple :

global
    setcap cap_net_bind_service,cap_net_admin

setenv <name> <value>

setenv <name> <value>

Définit la variable d’environnement <name> avec la valeur <value>. Si la variable existe, elle est remplacée. Les modifications prennent effet immédiatement, de sorte que la ligne suivante dans le fichier de configuration voit la nouvelle valeur. Voir également « presetenv », « resetenv » et « unsetenv ».

shm-stats-file <name>

shm-stats-file <name>

Lorsque cette directive est définie, elle active l’utilisation de la mémoire partagée pour le stockage des compteurs de statistiques. <name> est utilisé comme argument de shm_open() pour ouvrir la mémoire partagée à un emplacement unique. Cela signifie également que la directive n’est disponible que sur les systèmes qui prennent en charge shm_open(). Lorsque la mémoire partagée est utilisée pour les statistiques, tous les compteurs partageables des frontaux, backends, écouteurs et serveurs seront stockés dans la mémoire partagée, à condition qu’ils disposent d’un GUID défini. Lors du rechargement de HAProxy, le nouveau processus tentera de scanner la mémoire partagée afin de trouver des objets pouvant être associés aux objets définis dans la configuration, en fonction du GUID et du type ; l’objectif est de pouvoir conserver certaines valeurs de compteurs lors du rechargement. En revanche, lorsque HAProxy est arrêté correctement, les objets de mémoire partagée sont libérés, ce qui signifie que les compteurs sont effectivement réinitialisés. Il est également possible de supprimer manuellement le fichier avant de démarrer un nouveau processus afin de forcer une réinitialisation.

Voir également « guid », « guid-prefix » et « shm-stats-file-max-objects »

shm-stats-file-max-objects <number>

shm-stats-file-max-objects <number>

Ce paramètre définit le nombre maximum d’objets que la mémoire partagée utilisée pour les compteurs partagés pourra stocker par groupe de threads. Il est directement lié à la taille maximale de la shm et sert à « prémapper » la shm à une taille donnée afin d’éviter un remappage en cours d’exécution. Sa valeur par défaut est de 2k, ce qui convient à la plupart des configurations sans risquer une utilisation mémoire inappropriée, mais peut être facilement modifié si nécessaire. haproxy signalera une erreur au démarrage si cette valeur est trop faible pour enregistrer les objets attendus dans la mémoire partagée. Ce paramètre n’est pertinent que lorsque « shm-stats-file » a été défini.

Voir également « thread-groups »

ssl-default-bind-ciphers <ciphers>

ssl-default-bind-ciphers <ciphers>

Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement (“cipher suite”) négociés lors de l’échange SSL/TLS jusqu’à TLSv1.2 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL. Pour des informations complémentaires et des recommandations, consulter par exemple (https://wiki.mozilla.org/Security/Server_Side_TLS ) et (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Pour la configuration des chiffrements TLSv1.3, se référer à la directive « ssl-default-bind-ciphersuites ». Pour plus d’informations, consulter la directive « bind ».

ssl-default-bind-ciphersuites <ciphersuites>

ssl-default-bind-ciphersuites <ciphersuites>

Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré et si OpenSSL 1.1.1 ou une version ultérieure a été utilisée pour compiler HAProxy. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement (“cipher suite”) négociés lors de la négociation TLSv1.3 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL, dans la section « ciphersuites ». Pour la configuration des chiffrements TLSv1.2 et versions antérieures, veuillez consulter le mot-clé « ssl-default-bind-ciphers ». Ce paramètre peut accepter des suites de chiffrement TLSv1.2, mais cette fonctionnalité n’est pas documentée et n’est pas recommandée, car elle pourrait être incohérente ou défaillante. Les suites de chiffrement TLSv1.3 par défaut d’OpenSSL sont : “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256”

TLSv1.3 ne prend en charge que 5 suites de chiffrement :

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_CCM_SHA256
• TLS_AES_128_CCM_8_SHA256

Veuillez consulter le mot-clé « bind » pour plus d’informations.

Exemple :

global
    ssl-default-bind-ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
    ssl-default-bind-ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

ssl-default-bind-client-sigalgs <sigalgs>

ssl-default-bind-client-sigalgs <sigalgs>

Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature liés à l’authentification du client pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_client_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.

ssl-default-bind-curves <curves>

ssl-default-bind-curves <curves>

Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de courbes elliptiques (“suite de courbes”) négociés lors de l’échange SSL/TLS avec ECDHE. Le format de la chaîne est une liste séparée par des deux-points de noms de courbes. Veuillez consulter le mot-clé « bind » pour plus d’informations.

ssl-default-bind-options [<option>]...

ssl-default-bind-options [<option>]...

Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit les options SSL par défaut pour forcer leur activation sur toutes les lignes « bind ». Veuillez consulter le mot-clé « bind » pour consulter les options disponibles.

Exemple :

global
   ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets

ssl-default-bind-sigalgs <sigalgs>

ssl-default-bind-sigalgs <sigalgs>

Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature négociés pendant les échanges TLSv1.2 et TLSv1.3 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.

ssl-default-server-ciphers <ciphers>

ssl-default-server-ciphers <ciphers>

Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement négociés lors de l’échange SSL/TLS jusqu’à TLSv1.2 avec le serveur, pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL. Pour des informations complémentaires et des recommandations, consulter par exemple (https://wiki.mozilla.org/Security/Server_Side_TLS ) et (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Pour la configuration des algorithmes de chiffrement TLSv1.3, se référer à la directive « ssl-default-server-ciphersuites ». Voir également la directive « server » pour plus d’informations.

ssl-default-server-ciphersuites <ciphersuites>

ssl-default-server-ciphersuites <ciphersuites>

Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré et si OpenSSL 1.1.1 ou une version ultérieure a été utilisée pour compiler HAProxy. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement négociés lors de l’échange TLSv1.3 avec le serveur, pour toutes les lignes « server » qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL, dans la section « ciphersuites ». Pour la configuration des chiffrements TLSv1.2 et versions antérieures, veuillez consulter le mot-clé « ssl-default-server-ciphers ». Veuillez consulter le mot-clé « server » pour plus d’informations.

ssl-default-server-client-sigalgs <sigalgs>

ssl-default-server-client-sigalgs <sigalgs>

Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature liés à l’authentification du client pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_client_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.

ssl-default-server-curves <curves>

ssl-default-server-curves <curves>

Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de courbes elliptiques (“suite de courbes”) négociés lors de l’échange SSL/TLS avec ECDHE. Le format de la chaîne est une liste séparée par des deux-points de noms de courbes. Veuillez consulter le mot-clé « server » pour plus d’informations.

ssl-default-server-options [<option>]...

ssl-default-server-options [<option>]...

Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit les options SSL par défaut pour forcer l’activation sur toutes les lignes « server ». Veuillez consulter le mot-clé « server » pour connaître les options disponibles.

ssl-default-server-sigalgs <sigalgs>

ssl-default-server-sigalgs <sigalgs>

Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature négociés pendant les échanges TLSv1.2 et TLSv1.3 avec le serveur pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.

ssl-dh-param-file <file>

ssl-dh-param-file <file>

Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit les paramètres DH par défaut utilisés lors de l’échange de clés Diffie-Hellman éphémère (DHE) pendant la négociation SSL/TLS, pour toutes les lignes “bind” qui ne définissent pas explicitement leurs propres paramètres. Il sera remplacé par des paramètres DH personnalisés trouvés dans un fichier de certificat si présent. Si des paramètres DH personnalisés ne sont pas spécifiés, ni par l’option ssl-dh-param-file, ni en les définissant directement dans le fichier de certificat, les chiffres DHE ne seront pas utilisés, sauf si tune.ssl.default-dh-param est défini. Dans ce dernier cas, des paramètres DH prédéfinis de la taille spécifiée seront utilisés. L’utilisation de paramètres DH personnalisés est recommandée, car ils sont connus pour être plus sécurisés. Les paramètres DH personnalisés peuvent être générés à l’aide de la commande OpenSSL « openssl dhparam <size> », où la taille doit être d’au moins 2048, car les paramètres DH de 1024 bits ne doivent plus être considérés comme sécurisés.

ssl-passphrase-cmd <cmd> <args> ...

ssl-passphrase-cmd <cmd> <args> ...

Ce paramètre n’est disponible que si le support OpenSSL a été inclus lors de la compilation. Il permet de définir une ligne de commande complète appelée lors du chargement d’un certificat chiffré pendant l’initialisation. La commande peut être un script ou tout autre programme. Elle reçoit comme premier paramètre le chemin vers la clé privée chiffrée, puis les paramètres « args » définis par l’utilisateur, et doit écrire la phrase de passe permettant de déchiffrer la clé privée sur la sortie standard. À chaque chargement d’une nouvelle clé privée chiffrée durant l’initialisation, HAProxy tente d’abord chaque phrase de passe déjà connue, puis appelle à nouveau la commande de phrase de passe si aucune ne fonctionne.

ssl-propquery <query>

ssl-propquery <query>

Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de définir une chaîne de propriétés par défaut utilisée lors de la récupération des algorithmes dans les fournisseurs. Il se comporte de la même manière que l’option openssl propquery et suit la même syntaxe (décrite dans https://www.openssl.org/docs/man3.0/man7/property.html ). Par exemple, si deux fournisseurs sont chargés, celui nommé foo et le fournisseur par défaut, la chaîne propquery “?provider=foo” permet de sélectionner par défaut les implémentations d’algorithmes fournies par le fournisseur foo, et de revenir à celles du fournisseur par défaut en cas d’absence.

ssl-provider <name>

ssl-provider <name>

Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de charger un fournisseur lors de l’initialisation. Si le chargement réussit, les fonctionnalités fournies par le fournisseur chargé peuvent être utilisées par HAProxy. Plusieurs options ssl-provider peuvent être spécifiées dans un fichier de configuration. Les fournisseurs seront chargés dans l’ordre de leur apparition.

Veuillez noter qu’un chargement explicite d’un fournisseur empêche OpenSSL de charger automatiquement le fournisseur « default ». OpenSSL permet également de définir les fournisseurs à charger directement dans son fichier de configuration (par exemple OpenSSL.cnf), de sorte qu’il n’est pas nécessaire d’utiliser l’option « ssl-provider » pour charger des fournisseurs. La commande CLI « show ssl providers » peut être utilisée pour afficher tous les fournisseurs ayant été chargés avec succès.

Le chemin de recherche par défaut du fournisseur OpenSSL est indiqué dans la sortie de la commande « OpenSSL version -a ». Si le fournisseur se trouve dans un autre répertoire, vous pouvez définir la variable d’environnement OPENSSL_MODULES, qui précise le répertoire où se trouve votre fournisseur.

Voir également « ssl-propquery » et « ssl-provider-path ».

ssl-provider-path <path>

ssl-provider-path <path>

Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de spécifier le chemin de recherche utilisé par OpenSSL pour localiser les fournisseurs. Il se comporte de la même manière que la variable d’environnement OPENSSL_MODULES. Il sera utilisé pour toute option ‘ssl-provider’ ultérieure, jusqu’à ce qu’une nouvelle option ‘ssl-provider-path’ soit définie. Voir également « ssl-provider ».

ssl-load-extra-del-ext

ssl-load-extra-del-ext

Ce paramètre permet de configurer la manière dont HAProxy effectue la recherche des fichiers SSL supplémentaires. Par défaut, HAProxy ajoute une nouvelle extension au nom de fichier (par exemple, avec “foobar.crt” charge “foobar.crt.key”). Avec cette option activée, HAProxy supprime l’extension avant d’ajouter la nouvelle (par exemple, avec “foobar.crt” charge “foobar.key”).

Votre fichier crt doit porter une extension “.crt” pour que cette option fonctionne.

Cette option n’est pas compatible avec les extensions de bundle (.ecdsa, .rsa, .dsa) et ne tentera pas de les supprimer.

Cette option est désactivée par défaut. Voir également « ssl-load-extra-files ».

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

Ce paramètre modifie la manière dont HAProxy recherche les fichiers non spécifiés lors du chargement des certificats SSL. Cette option s’applique aux certificats associés aux lignes « bind » ainsi qu’aux lignes « server », mais certains fichiers supplémentaires n’auront aucun impact fonctionnel pour les certificats des lignes « server ».

Par défaut, HAProxy découvre automatiquement un grand nombre de fichiers non spécifiés dans la configuration, et vous pouvez souhaiter désactiver ce comportement afin d’optimiser le temps de démarrage.

“none” : charger uniquement les fichiers spécifiés dans la configuration. Ne pas essayer de charger un ensemble de certificats si le fichier n’existe pas. Dans le cas d’un répertoire, ne pas essayer de regrouper les certificats s’ils ont le même nom de base.

« all » : ce comportement est par défaut ; il tente de charger tout : les paquets, sctl, ocsp, l’émetteur, la clé.

“bundle” : Lorsqu’un fichier spécifié dans la configuration n’existe pas, HAProxy tentera de charger un « cert bundle ». Les bundles de certificats ne sont gérés qu’au niveau du frontal et ne fonctionnent pas pour les certificats du backend.

À compter de HAProxy 2.3, les bundles ne sont plus chargés dans le même magasin de certificats OpenSSL ; au lieu de cela, chaque certificat est chargé dans un magasin distinct, ce qui équivaut à déclarer plusieurs directives « crt ». OpenSSL 1.1.1 est requis pour cette fonctionnalité. Cela signifie que les bundles ne sont désormais utilisés qu’à des fins de compatibilité descendante et ne sont plus obligatoires pour configurer une liaison hybride RSA/ECC.

Pour associer ces fichiers PEM à un « bundle de certificats » reconnu par HAProxy, ils doivent être nommés selon la convention suivante : tous les fichiers PEM à regrouper doivent partager le même nom de base, accompagné d’un suffixe indiquant le type de clé. Actuellement, trois suffixes sont pris en charge : rsa, dsa et ecdsa. Par exemple, si www.example.com comporte deux fichiers PEM, un fichier RSA et un fichier ECDSA, ils doivent être nommés : “example.pem.rsa” et “example.pem.ecdsa”. La première partie du nom de fichier est arbitraire ; seul le suffixe est pertinent. Pour charger ce bundle dans HAProxy, indiquez uniquement le nom de base :

Exemple : bind:8443 ssl crt example.pem

Notez que le suffixe n’est pas fourni à HAProxy ; cela indique à HAProxy de rechercher un bundle de certificats.

HAProxy chargera tous les fichiers PEM du bundle comme s’ils étaient configurés séparément dans plusieurs directives « crt ».

Le chargement du bundle n’a plus d’impact sur le chargement du répertoire, puisque les fichiers sont chargés séparément.

En ligne de commande, les bundles sont considérés comme des fichiers distincts, et l’extension du bundle est obligatoire pour les valider.

Les fichiers OCSP (.ocsp), les fichiers émetteurs (.issuer), la transparence des certificats (.sctl) ainsi que les clés privées (.key) sont pris en charge avec le regroupement de plusieurs certificats.

sctl : Essayer de charger “<basename>.sctl” pour chaque mot-clé crt. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.

“ocsp”: Essayer de charger “<basename>.ocsp” pour chaque mot-clé crt. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.

“issuer”: Essayer de charger “<basename>.issuer” si l’émetteur du fichier OCSP n’est pas fourni dans le fichier PEM. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.

“key”: Si la clé privée n’a pas été fournie par le fichier PEM, essayez de charger un fichier “<basename>.key” contenant une clé privée.

Le comportement par défaut est « all ».

Exemple :

ssl-load-extra-files bundle sctl
ssl-load-extra-files sctl ocsp issuer
ssl-load-extra-files none

Voir aussi : « crt », section 5.1 concernant les options de liaison et section 5.2 concernant les options de serveur.

ssl-security-level <number>

ssl-security-level <number>

Ce directive permet de choisir le niveau de sécurité OpenSSL tel qu’il est décrit dans https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html . Le niveau de sécurité sera appliqué à chaque contexte SSL dans HAProxy. Seuls les valeurs comprises entre 0 et 5 sont prises en charge.

La valeur par défaut dépend de votre version d’OpenSSL, de votre distribution et de la manière dont la bibliothèque a été compilée.

Ce directive nécessite au moins OpenSSL 1.1.1.

ssl-server-verify [none|required]

ssl-server-verify [none|required]

Comportement par défaut de la vérification SSL côté serveur. Si défini sur « none », les certificats des serveurs ne sont pas vérifiés. La valeur par défaut est « required », sauf si elle est forcée via l’option en ligne de commande ‘-dV’.

ssl-skip-self-issued-ca

ssl-skip-self-issued-ca

Autorité de certification auto-délivrée, également appelée CA racine x509, constitue l’élément d’ancrage pour la validation de chaîne : en tant que serveur, elle est inutile à envoyer, le client doit la posséder. La configuration standard ne doit pas inclure une telle CA dans le fichier PEM. Cette option permet de conserver une telle CA dans le fichier PEM sans la transmettre au client. Cas d’utilisation : fournir l’émetteur pour OCSP sans nécessiter de fichier ‘.issuer’ et pouvoir le partager via ‘issuers-chain-path’. Cela concerne tous les certificats ne comportant pas de certificats intermédiaires. Cette option est inutile pour BoringSSL ; le champ .issuer est ignoré car les bits OCSP n’en ont pas besoin. Nécessite au moins OpenSSL 1.0.2.

stats calculate-max-counters [on|off]

stats calculate-max-counters [on|off]

Active ou désactive le calcul des compteurs max des statistiques. Si vous n’en avez pas besoin, les désactiver peut légèrement améliorer les performances. La valeur par défaut est activée.

stats maxconn <connections>

stats maxconn <connections>

Par défaut, la socket de statistiques est limitée à 10 connexions simultanées. Il est possible de modifier cette valeur en utilisant « stats maxconn ».

stats socket [<address:port>|<path>] [param*]

stats socket [<address:port>|<path>] [param*]

Lie un socket UNIX à <path> ou une adresse TCPv4/v6 à <address:port>. Les connexions à ce socket renvoient diverses sorties de statistiques et permettent même d’envoyer certains commandes afin de modifier certains paramètres en cours d’exécution. Veuillez consulter la section 9.3 « Commandes de socket Unix » du guide d’administration pour plus de détails.

Tous les paramètres pris en charge par les lignes « bind » sont pris en charge, par exemple pour restreindre l’accès à certains utilisateurs ou leurs droits d’accès. Veuillez consulter section 5.1 pour plus d’informations.

stats timeout <timeout, in milliseconds>

stats timeout <timeout, in milliseconds>

Le délai d’expiration par défaut sur la socket de statistiques est fixé à 10 secondes. Il est possible de modifier cette valeur à l’aide de « stats timeout ». La valeur doit être indiquée en millisecondes, ou être suivie d’une unité de temps parmi { us, ms, s, m, h, d }.

stats-file <path>

stats-file <path>

Chemin vers un fichier de statistiques HAProxy généré. Au démarrage, HAProxy charge les valeurs dans ses compteurs internes. Utilisez la commande en ligne de commande « dump stats-file » pour produire un tel fichier. Voir le manuel de gestion pour plus de détails.

stress-level <level>

stress-level <level>

Activez un code alternatif destiné à exercer une charge sur le binaire HAProxy. Le niveau est un entier compris entre 0 et 9. La valeur par défaut 0 désactive toute exécution de charge. Les niveaux de 1 à 9 augmentent progressivement la pression de charge appliquée au binaire HAProxy. Notez qu’utiliser un niveau positif peut fortement réduire les performances. Ce paramètre doit donc être activé uniquement à des fins de débogage et sur demande explicite d’un développeur.

strict-limits

strict-limits

Fait échouer le processus au démarrage en cas d’échec de setrlimit. HAProxy tente de définir la meilleure valeur setrlimit selon les calculs effectués. En cas d’échec, un avertissement est émis. Cette option garantit un échec explicite de HAProxy lorsque ces limites échouent. Elle est activée par défaut. Elle peut toutefois être désactivée de force en préfixant le mot-clé par « no ».

thread-group <group> [<thread-range>...]

thread-group <group> [<thread-range>...]

Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il définit la liste des threads qui composeront le groupe de threads <group>. Les numéros de thread et de groupe commencent à 1. Les plages de threads sont définies soit en indiquant un seul numéro de thread, soit en spécifiant les bornes inférieure et supérieure séparées par un trait d’union ‘-’ (par exemple, « 1-16 »). Les threads non affectés seront automatiquement affectés aux groupes de threads non affectés, et les groupes de threads définis avec cette directive ne recevront jamais plus de threads que ceux définis. Définir plusieurs fois le même groupe remplace les définitions précédentes par la nouvelle. Voir également « nbthread » et « thread-groups ».

thread-groups <number>

thread-groups <number>

Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il permet à HAProxy de répartir ses threads en <number> groupes indépendants. Actuellement, la valeur par défaut est 1. Les groupes de threads permettent de réduire le partage entre threads afin de limiter les conflits, au prix d’une configuration plus complexe. C’est également la seule manière d’utiliser plus de 64 threads, car jusqu’à 64 threads par groupe peuvent être configurés. Le nombre maximum de groupes est configuré au moment de la compilation et vaut 16 par défaut. Voir également « nbthread ».

thread-hard-limit <number>

thread-hard-limit <number>

Ce paramètre sert à imposer une limite au nombre de threads, qu’il s’agisse de threads détectés ou configurés. Il est particulièrement utile sur les systèmes d’exploitation où le nombre de threads est détecté automatiquement, lorsque l’on souhaite un nombre de threads inférieur au nombre de processeurs dans des configurations génériques et portables. En effet, bien que « nbthread » impose un nombre de threads qui entraîne un avertissement et de mauvaises performances si supérieur au nombre de processeurs disponibles, « thread-hard-limit » ne fait que limiter le maximum à cette valeur, en ajustant automatiquement le nombre de threads à une valeur inférieure ou égale à celle-ci, sans toutefois augmenter les valeurs inférieures. Si « nbthread » est forcé à une valeur supérieure, « thread-hard-limit » l’emporte, et un avertissement est émis afin que l’anomalie de configuration puisse être corrigée. Par défaut, aucune limite n’est appliquée. Voir également « nbthread ».

uid <number>

uid <number>

Change l’identifiant utilisateur du processus en <number>. Il est recommandé que cet identifiant utilisateur soit dédié à HAProxy ou à un petit ensemble de démons similaires. HAProxy doit être lancé avec des privilèges de superutilisateur afin de pouvoir basculer vers un autre identifiant. Voir également « gid » et « user ».

ulimit-n <number>

ulimit-n <number>

Définit le nombre maximal de descripteurs de fichiers par processus à <number>. Par défaut, il est calculé automatiquement, il est donc recommandé de ne pas utiliser cette option. Si l’objectif est uniquement de limiter le nombre de descripteurs de fichiers, il est préférable d’utiliser « fd-hard-limit » à la place.

Notez que les serveurs dynamiques ne sont pas pris en compte dans ce calcul automatique des ressources. Si vous utilisez un grand nombre de serveurs dynamiques, il peut être nécessaire de spécifier cette valeur manuellement.

Voir aussi : fd-hard-limit, maxconn

unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] [ group <group> ] [ gid <gid> ]

Fixe les paramètres courants pour les sockets UNIX déclarés dans les instructions « bind ». Cela sert principalement à simplifier la déclaration de ces sockets UNIX et à réduire le risque d’erreurs, car ces paramètres sont fréquemment requis mais sont également spécifiques au processus. Le paramètre <prefix> peut être utilisé pour forcer tous les chemins de socket à être relatifs à ce répertoire. Cela peut être nécessaire pour accéder à un composant situé dans un chroot. Notez que ces chemins sont résolus avant que HAProxy ne s’isole dans un chroot, donc ils sont absolus. Les paramètres <mode>, <user>, <uid>, <group> et <gid> ont tous la même signification que leurs homonymes utilisés dans l’instruction « bind ». Si les deux sont spécifiés, l’instruction « bind » a priorité, ce qui signifie que les paramètres « unix-bind » peuvent être considérés comme des paramètres par défaut au niveau du processus.

unsetenv [<name> ...]

unsetenv [<name> ...]

Supprime les variables d’environnement spécifiées dans les arguments. Cela peut être utile pour masquer certaines informations sensibles qui sont parfois héritées de l’environnement utilisateur lors de certaines opérations. Les variables n’existant pas sont ignorées sans avertissement, de sorte qu’après l’opération, il est certain qu’aucune de ces variables ne reste. Les modifications prennent effet immédiatement, de sorte que la ligne suivante du fichier de configuration ne verra plus ces variables. Voir également « setenv », « presetenv » et « resetenv ».

user <user name>

user <user name>

Similaire à « uid » mais utilise l’UID du nom d’utilisateur <user name> provenant de /etc/passwd.. Voir également « uid » et « group ».

node <name>

node <name>

Seuls les lettres, chiffres, traits d’union et traits de soulignement sont autorisés, comme dans les noms DNS.

Cette instruction est utile dans les configurations HA où deux ou plusieurs processus ou serveurs partagent la même adresse IP. En attribuant un nom de nœud différent à chaque nœud, il devient facile d’identifier instantanément quel serveur traite le trafic.

wurfl-cache-size <size>

wurfl-cache-size <size>

Définit la taille du cache des agents utilisateurs WURFL. Pour des recherches plus rapides, les agents utilisateurs déjà traités sont conservés dans un cache LRU :

• “0” : aucun cache n’est utilisé.
• <size> : taille du cache LRU en éléments.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.

wurfl-data-file <file path>

wurfl-data-file <file path>

Chemin du fichier de données WURFL à utiliser pour fournir les services de détection de périphérique. Le fichier doit être accessible par HAProxy, avec les autorisations appropriées.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.

wurfl-information-list [<capability>]*

wurfl-information-list [<capability>]*

Une liste séparée par des espaces de capacités WURFL, capacités virtuelles et noms de propriétés que nous prévoyons d’utiliser dans les en-têtes injectés. Une liste complète des noms de capacité et de capacité virtuelle est disponible sur le site web Scientiamobile :

https://www.scientiamobile.com/wurflCapability

Propriétés WURFL valides :

• wurfl_id Contient l’identifiant du périphérique correspondant.

• wurfl_root_id Contient l’identifiant racine du périphérique correspondant.

• wurfl_isdevroot Indique si le périphérique correspondant est un périphérique racine. Les valeurs possibles sont « TRUE » ou « FALSE ».

• wurfl_useragent L’agent utilisateur d’origine associé à cette requête web particulière.

• wurfl_api_version Contient une chaîne représentant la version actuellement utilisée de l’API Libwurfl.

• wurfl_info Chaîne contenant des informations sur le fichier wurfl.xml analysé et son chemin complet.

• wurfl_last_load_time Contient l’horodatage UNIX du dernier chargement réussi de WURFL.

• wurfl_normalized_useragent L’agent utilisateur normalisé.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.

wurfl-information-list-separator <char>

wurfl-information-list-separator <char>

Caractère utilisé pour séparer les valeurs dans un en-tête de réponse contenant les résultats WURFL. Si non défini, une virgule (’,’) sera utilisée par défaut.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.

wurfl-patch-file [<file path>]

wurfl-patch-file [<file path>]

Une liste des chemins des fichiers de correctifs WURFL. Notez que les correctifs sont chargés au démarrage, donc avant le chroot.

Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.

3.2. Optimisation des performances

busy-polling

busy-polling

Dans certaines situations, notamment lorsqu’il s’agit de faibles latences sur des processeurs à fréquence variable ou lorsqu’on exécute dans des machines virtuelles, chaque fois que le processus attend un I/O via le poller, le processeur retourne en veille ou est attribué à une autre machine virtuelle pendant une durée prolongée, ce qui entraîne des latences excessivement élevées. Cette option propose une solution consistant à empêcher le processeur de passer en veille en utilisant toujours un délai d’expiration nul sur les pollers. Cela permet une réduction significative de la latence (de 30 à 100 microsecondes observées), au prix d’un risque accru de surchauffe du processeur. Elle peut même être utilisée avec des threads, auquel cas des threads mal affectés peuvent provoquer de fortes conflits, entraînant une performance dégradée et des valeurs élevées pour les champs CPU stolen dans la sortie de la commande “show info”, indiquant les threads mal configurés. Il est important de ne pas faire exécuter le processus sur le même processeur que les interruptions réseau lorsque cette option est activée. Il est également préférable de ne pas l’utiliser sur plusieurs threads de processeur partageant le même cœur. Cette option est désactivée par défaut. Si elle a été activée, elle peut toutefois être fortement désactivée en la préfixant par le mot-clé “no”. Elle est ignorée par les pollers “select” et “poll”.

Cette option est automatiquement désactivée sur les anciens processus dans le cadre d’un redémarrage sans interruption ; elle évite des conflits CPU excessifs lorsque plusieurs processus persistent pendant un certain temps en attendant la fin de leurs connexions actuelles.

max-spread-checks <delay in milliseconds>

max-spread-checks <delay in milliseconds>

Par défaut, HAProxy tente de répartir le démarrage des contrôles d’état sur l’intervalle de contrôle d’état le plus petit de tous les serveurs d’une ferme. Le principe vise à éviter de surcharger les services exécutés sur le même serveur. Toutefois, lorsqu’on utilise des intervalles de contrôle importants (10 secondes ou plus), les derniers serveurs de la ferme mettent un certain temps avant de commencer à être testés, ce qui peut poser problème. Ce paramètre sert à imposer une limite supérieure au délai entre le premier et le dernier contrôle, même si les intervalles de contrôle des serveurs sont plus longs. Lorsque les serveurs fonctionnent avec des intervalles plus courts, leurs intervalles sont respectés toutefois.

maxcompcpuusage <number>

maxcompcpuusage <number>

Définit l’utilisation maximale du CPU que HAProxy peut atteindre avant de cesser la compression des nouvelles requêtes ou de réduire le niveau de compression des requêtes en cours. Fonctionne comme « maxcomprate », mais mesure l’utilisation du CPU au lieu du débit de données entrantes. La valeur est exprimée en pourcentage de CPU utilisé par HAProxy. Une valeur de 100 désactive la limite. La valeur par défaut est 100. Une valeur inférieure empêchera le traitement de compression de ralentir l’ensemble du processus et d’introduire des latences élevées.

maxcomprate <number>

maxcomprate <number>

Définit le taux maximal d’entrée de compression par processus à <number> kilo-octets par seconde. Pour chaque flux, si la limite est atteinte, le niveau de compression sera réduit pendant le flux. Si la limite est atteinte au début d’un flux, celui-ci ne sera pas compressé du tout. Si la limite n’est pas atteinte, le niveau de compression sera augmenté jusqu’à tune.comp.maxlevel. Une valeur nulle signifie qu’aucune limite n’est appliquée, ce qui est la valeur par défaut.

maxconn <number>

maxconn <number>

Définit le nombre maximal de connexions simultanées par processus vers <number>. Cela équivaut à l’argument en ligne de commande “-n”. La valeur fournie via l’argument en ligne de commande “-n” a priorité sur la valeur maxconn définie dans la section globale. Le processus HAProxy peut également être compilé avec la variable de compilation SYSTEM_MAXCONN, qui sert alors de limite maximale système pour maxconn. Encore une fois, l’argument en ligne de commande “-n” permet, à l’exécution, de contourner la limite définie par SYSTEM_MAXCONN, si elle est configurée. Les proxies cessent d’accepter de nouvelles connexions lorsque maxconn est atteint. La limite douce des descripteurs de fichiers du processus (obtenue avec la commande “ulimit -n”) est automatiquement ajustée en fonction de la valeur maxconn fournie. Voir également “ulimit-n”. Remarque : le poller “select” ne peut pas utiliser de manière fiable plus de 1024 descripteurs de fichiers sur certaines plates-formes. Si votre plate-forme ne prend en charge que “select” et affiche “select FAILED” au démarrage, vous devez réduire la valeur de maxconn jusqu’à ce qu’elle fonctionne (généralement légèrement inférieure à 500). Si la valeur de maxconn n’est pas définie, elle sera calculée automatiquement en fonction des limites actuelles des descripteurs de fichiers, telles que rapportées par la commande “ulimit -nH” (nous prenons la valeur maximale entre les limites dures et douces), puis cette valeur automatique peut être réduite par “fd-hard-limit” et par la limite mémoire, si celle-ci a été imposée via l’option en ligne de commande “-m”. La valeur automatique dépend également de la taille des tampons, de la mémoire allouée à la compression, de la taille du cache SSL, ainsi que de l’utilisation ou non de SSL et de la valeur correspondante maxsslconn (qui peut également être automatique).

Voir aussi : fd-hard-limit, ulimit-n

maxconnrate <number>

maxconnrate <number>

Définit le nombre maximal de connexions par seconde par processus pour <number>. Les proxies cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter la capacité globale, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car il n’y aura pas nécessairement une répartition équitable entre les frontaux lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. En outre, réduire tune.maxaccept peut améliorer la justesse de répartition.

maxpipes <number>

maxpipes <number>

Définit le nombre maximal de tubes par processus à <number>. Actuellement, les tubes ne sont utilisés que par le splice TCP basé sur le noyau. Étant donné qu’un tube contient deux descripteurs de fichiers, la valeur de « ulimit-n » sera augmentée en conséquence. La valeur par défaut est maxconn/4, qui semble suffisante pour la plupart des utilisations intensives. Le code de splice alloue et libère dynamiquement les tubes, et peut revenir à une copie standard, aussi une valeur trop faible peut-elle uniquement affecter les performances.

maxsessrate <number>

maxsessrate <number>

Définit le nombre maximal de sessions par processus et par seconde à <number>. Les proxies cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter la capacité globale, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car il n’y aura pas nécessairement une répartition équitable entre les frontaux lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. En outre, réduire tune.maxaccept peut améliorer la justesse de répartition.

maxsslconn <number>

maxsslconn <number>

Définit le nombre maximal de connexions SSL concurrentes par processus à <number>. Par défaut, aucune limite spécifique SSL n’est appliquée, ce qui signifie que le paramètre maxconn global s’applique à toutes les connexions. Définir cette limite évite que OpenSSL n’utilise trop de mémoire et ne plante lorsque malloc retourne NULL (car il ne vérifie pas de manière fiable ces conditions). Notez que la limite s’applique aussi bien aux connexions entrantes qu’aux sortantes, de sorte qu’une connexion qui est déchiffrée puis chiffrée compte pour 2 connexions SSL. Si cette valeur n’est pas définie, mais qu’une limite mémoire est imposée, cette valeur sera automatiquement calculée en fonction de la limite mémoire, de maxconn, de la taille du tampon, de la mémoire allouée à la compression, de la taille du cache SSL, et de l’utilisation de SSL dans les frontaux, les backends ou les deux. Si ni maxconn ni maxsslconn ne sont spécifiés alors qu’une limite mémoire est présente, HAProxy ajustera automatiquement ces valeurs afin que 100 % des connexions puissent être établies en SSL sans risque, et tiendra compte des côtés où SSL est activé (frontal, backend, les deux).

maxsslrate <number>

maxsslrate <number>

Définit le nombre maximal de sessions SSL par processus et par seconde à <number>. Les écouteurs SSL cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter l’utilisation globale du CPU SSL, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car les frontaux ne seront pas nécessairement équitablement partagés lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. Il est également important de noter que les sessions sont comptabilisées avant leur entrée dans la pile SSL, et non après, ce qui protège également la pile contre des échanges malformés. Réduire tune.maxaccept peut également améliorer l’équité.

maxzlibmem <number>

maxzlibmem <number>

Définit la quantité maximale de mémoire RAM en mégaoctets par processus utilisable par zlib. Lorsque cette quantité maximale est atteinte, les flux futurs ne seront pas compressés tant que de la mémoire ne sera pas disponible. Si la valeur est définie à 0, aucune limite n’est appliquée. La valeur par défaut est 0. Cette valeur est disponible en octets via le socket UNIX avec la commande « show info », sur la ligne « MaxZlibMemUsage » ; la mémoire utilisée par zlib est indiquée par « ZlibMemUsage » en octets.

no-memory-trimming

no-memory-trimming

Désactive le découpage de mémoire (“malloc_trim”) à certains moments où des tentatives sont effectuées pour récupérer une grande quantité de mémoire (en cas de pénurie de mémoire ou lors d’un rechargement). Le découpage de mémoire force l’allocateur du système à parcourir toutes les zones inutilisées et à les libérer. Cette opération est généralement considérée comme une bonne pratique, afin de laisser plus de mémoire disponible à un nouveau processus alors que l’ancien est peu susceptible d’en faire un usage significatif. Toutefois, certains systèmes gérant des dizaines à des centaines de milliers de connexions concurrentes peuvent subir une fragmentation mémoire importante, ce qui peut rendre cette opération de libération extrêmement longue. Pendant cette période, aucune nouvelle demande ne passe par le processus, les nouvelles connexions ne sont plus acceptées, certaines vérifications de santé peuvent échouer, et le superviseur peut même déclencher la mort du processus inactif, laissant une énorme image mémoire. Si cela se produit, il est conseillé d’utiliser cette option pour désactiver le découpage et cesser de tenter d’être bienveillant envers le nouveau processus. Notez que les allocateurs mémoire avancés ne souffrent généralement pas de ce problème.

noepoll

noepoll

Désactive l’utilisation du système de sondage d’événements « epoll » sous Linux. Équivalent à l’argument en ligne de commande « -de ». Le système de sondage suivant utilisé sera généralement « poll ». Voir également « nopoll ».

noevports

noevports

Désactive l’utilisation du système de sondage d’événements par ports sur les systèmes SunOS dérivés de Solaris 10 et versions ultérieures. Cela équivaut à l’argument en ligne de commande “-dv”. Le système de sondage suivant utilisé sera généralement “poll”. Voir également “nopoll”.

nogetaddrinfo

nogetaddrinfo

Désactive l’utilisation de getaddrinfo(3) pour la résolution de noms. Équivalent à l’argument en ligne de commande « -dG ». La fonction gethostbyname(3) dépréciée sera utilisée.

nokqueue

nokqueue

Désactive l’utilisation du système de sondage d’événements “kqueue” sur BSD. Équivalent à l’argument en ligne de commande “-dk”. Le système de sondage suivant utilisé sera généralement “poll”. Voir également “nopoll”.

noktls

noktls

Désactive l’utilisation de ktls. Cela équivaut à l’argument de ligne de commande “-dT”.

nopoll

nopoll

Désactive l’utilisation du système de sondage d’événements « poll ». Cela équivaut à l’argument en ligne de commande « -dp ». Le système de sondage suivant utilisé sera « select ». Il ne devrait jamais être nécessaire de désactiver « poll », car il est disponible sur toutes les plates-formes prises en charge par HAProxy. Voir également « nokqueue », « noepoll » et « noevports ».

noreuseport

noreuseport

Désactive l’utilisation de SO_REUSEPORT – voir socket(7). Cela équivaut à l’argument en ligne de commande « -dR ».

nosplice

nosplice

Désactive l’utilisation du splice TCP du noyau entre sockets sous Linux. Cela équivaut à l’argument en ligne de commande “-dS”. Les données seront alors copiées à l’aide d’appels recv/send conventionnels et plus portables. Le splice TCP du noyau est limité à certaines versions récentes du noyau 2.6. La plupart des versions comprises entre 2.6.25 et 2.6.28 présentent des bogues et transmettent des données corrompues, elles ne doivent donc pas être utilisées. Cette option facilite la désactivation globale du splice du noyau en cas de doute. Voir également « option splice-auto », « option splice-request » et « option splice-response ».

profiling.memory { on | off }

profiling.memory { on | off }

Active (‘on’) ou désactive (‘off’) le profilage mémoire par fonction. Cela permet de conserver des statistiques d’utilisation des appels à malloc/calloc/realloc/free dans tout le processus (y compris dans les bibliothèques), qui seront rapportées en ligne de commande via la commande « show profiling ». Cette fonction est principalement destinée à être utilisée lorsqu’une utilisation mémoire anormale est observée et qu’elle ne peut être expliquée par les pools ou d’autres informations disponibles. La perte de performance est généralement d’environ 1 %, peut-être un peu plus sur des machines fortement multithreadées, ce qui la rend normalement adaptée à une utilisation en production. Le même effet peut également être obtenu en temps réel en ligne de commande à l’aide de la commande « set profiling memory », consulter le manuel de gestion.

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

Active (‘on’) ou désactive (‘off’) le profilage CPU par tâche. Lorsque cette option est définie sur ‘auto’, le profilage s’active automatiquement sur un thread lorsqu’il commence à subir une latence moyenne de 1000 microsecondes ou plus, comme indiqué dans le champ d’activité “avg_loop_us”, et se désactive automatiquement lorsque la latence redescend en dessous de 990 microsecondes (valeur moyenne calculée sur les 1024 itérations précédentes, ce qui empêche toute variation rapide et atténue fortement les pics brusques). Il peut également se déclencher spontanément de temps à autre sur des systèmes surchargés, des conteneurs ou machines virtuelles, ou lorsque le système échange (ce qui doit absolument ne jamais se produire sur un répartiteur de charge).

Lorsque le profilage des tâches est activé, HAProxy peut également collecter le temps passé par chaque tâche avec un verrou détenu ou en attente d’un verrou, ainsi que le temps passé en attente d’une allocation mémoire réussie en cas de perte dans le cache de pool. Cela peut parfois aider à comprendre certaines causes de latence. Pour cela, les mots-clés supplémentaires « lock » (pour activer la collecte du temps passé avec un verrou), « no-lock » (pour la désactiver), « memory » (pour activer la collecte du temps d’allocation mémoire) ou « no-memory » (pour la désactiver) peuvent être utilisés. Par défaut, ils ne sont pas activés, car ils peuvent avoir un impact CPU non négligeable sur les systèmes fortement sollicités (3 à 10 %). Notez que la surcharge n’est prise en compte que lorsque le profilage est effectivement en cours d’exécution, de sorte qu’en mode « auto », elle n’apparaît que lorsque HAProxy décide de l’activer.

Le profilage CPU par tâche peut être très utile pour identifier où le temps est consommé et quelles requêtes ont quel effet sur d’autres requêtes. Activer cette fonctionnalité affecte généralement les performances globales de moins de 1 %, aussi est-il recommandé de la laisser sur la valeur par défaut « auto » afin qu’elle ne s’active que lorsqu’un problème est détecté. Cette fonctionnalité nécessite un système prenant en charge l’appel système clock_gettime(2) avec les identifiants d’horloge CLOCK_MONOTONIC et CLOCK_THREAD_CPUTIME_ID ; sinon, le temps rapporté sera nul. Cette option peut être modifiée en cours d’exécution à l’aide de la commande « set profiling » en ligne de commande.

spread-checks <0..50, in percent>

spread-checks <0..50, in percent>

Parfois, il est souhaitable d’éviter d’envoyer les agents et les contrôles d’état aux serveurs à des intervalles exacts, par exemple lorsque de nombreux serveurs logiques sont situés sur le même serveur physique. Grâce à ce paramètre, il devient possible d’ajouter une certaine aléatoire à l’intervalle de contrôle, compris entre 0 et +/- 50 %. Une valeur comprise entre 2 et 5 semble donner de bons résultats. La valeur par défaut reste à 0.

ssl-engine <name> [algo <comma-separated list of algorithms>]

ssl-engine <name> [algo <comma-separated list of algorithms>]

Définit le moteur OpenSSL à <name>. La liste des valeurs valides pour <name> peut être obtenue à l’aide de la commande « openssl engine ». Cette instruction peut être utilisée plusieurs fois ; elle active simplement plusieurs moteurs cryptographiques. Référencer un moteur non pris en charge empêchera HAProxy de démarrer. Notez que de nombreux moteurs entraînent une performance HTTPS inférieure à celle du logiciel pur avec les processeurs récents. L’option « algo » définit les algorithmes par défaut fournis par un ENGINE à l’aide de la fonction OPENSSL ENGINE_set_default_string(). Une valeur de « ALL » utilise le moteur pour toutes les opérations cryptographiques. Si aucune liste d’algorithmes n’est spécifiée, la valeur « ALL » est utilisée. Une liste séparée par des virgules d’algorithmes différents peut être indiquée, notamment : RSA, DSA, DH, EC, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. Ce format est identique à celui utilisé dans le fichier de configuration OpenSSL : https://www.openssl.org/docs/man1.0.2/apps/config.html

HAProxy version 2.6 a désactivé la prise en charge des moteurs dans la version par défaut. Cette option n’est disponible que si HAProxy a été compilé avec cette fonctionnalité. Si le moteur ssl est requis, HAProxy peut être recompilé avec le drapeau USE_ENGINE=1.

ssl-mode-async

ssl-mode-async

Ajoute le mode SSL_MODE_ASYNC au contexte SSL. Cela active les opérations TLS asynchrones I/O si des moteurs SSL capables de traitement asynchrone sont utilisés. L’implémentation actuelle prend en charge un maximum de 32 moteurs. L’API ASYNC d’OpenSSL ne prend pas en charge le déplacement des tampons read/write et n’est pas conforme à la gestion des tampons de HAProxy. Par conséquent, le mode asynchrone est désactivé pour les opérations read/write (il n’est activé que lors des échanges d’initialisation et de renégociation).

tune.applet.zero-copy-forwarding { on | off }

tune.applet.zero-copy-forwarding { on | off }

Active (« on ») ou désactive (« off ») le transfert zéro-copie des données pour les applets. Il est activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding.

tune.buffers.limit <number>

tune.buffers.limit <number>

Définit une limite rigide sur le nombre de tampons pouvant être alloués par processus. La valeur par défaut est zéro, ce qui signifie sans limite. La limite est automatiquement ajustée afin de respecter les tampons réservés en cas d’urgence, de sorte que l’utilisateur n’ait pas à effectuer des calculs complexes. Forcer cette valeur peut être particulièrement utile pour limiter la quantité de mémoire qu’un processus peut utiliser, tout en conservant un comportement raisonnable. Lorsque cette limite est atteinte, une tâche demandant un tampon attend qu’un autre soit libéré. En général, le temps d’attente est très court et imperceptible, à condition que les limites restent raisonnables. Toutefois, certaines limitations historiques ont affaibli ce mécanisme au fil des versions, et il est connu qu’en cas de pénurie prolongée, certaines tâches peuvent se bloquer jusqu’à expiration de leur délai d’expiration, il est donc préférable d’éviter d’utiliser cette option sauf si strictement nécessaire.

tune.buffers.reserve <number>

tune.buffers.reserve <number>

Définit le nombre de tampons par thread qui sont pré-alloués et réservés pour une utilisation exclusive en cas de pénurie de mémoire entraînant des échecs d’allocation. La valeur minimale est 0 et la valeur par défaut est 4. Aucune raison ne justifie qu’un utilisateur modifie cette valeur, sauf si un développeur principal le recommande pour une raison très spécifique.

tune.bufsize <size>

tune.bufsize <size>

Définit la taille de tampon à cette valeur (en octets). Des valeurs plus faibles permettent à plus de flux de coexister dans la même quantité de mémoire RAM, tandis que des valeurs plus élevées permettent à certaines applications avec des cookies très volumineux de fonctionner. La valeur par défaut est 16384 et peut être modifiée au moment de la compilation. Il est fortement recommandé de ne pas modifier cette valeur par défaut, car des valeurs trop basses peuvent interrompre certains services tels que les statistiques, et des valeurs supérieures à la taille par défaut augmentent l’utilisation de la mémoire, pouvant entraîner une exhaustion de la mémoire système. Il est nécessaire de diminuer au moins le paramètre global maxconn du même facteur que celui-ci est augmenté. En outre, l’utilisation de HTTP/2 impose que cette valeur soit au moins 16384. Si une requête HTTP est plus grande que (tune.bufsize - tune.maxrewrite), HAProxy renvoie une erreur HTTP 400 (Requête incorrecte). De même, si une réponse HTTP est plus grande que cette taille, HAProxy renvoie une erreur HTTP 502 (Bad Gateway). Notez que la valeur définie par ce paramètre est automatiquement arrondie à la multiple suivante de 8 sur les machines 32 bits et de 16 sur les machines 64 bits.

tune.bufsize.large <size>

tune.bufsize.large <size>

Définit la taille en octets des tampons volumineux. Par défaut, le support des tampons volumineux n’est pas activé ; il doit être activé explicitement en définissant cette valeur.

Ces tampons sont conçus pour être utilisés dans certains contextes spécifiques où une quantité de données supérieure doit être tamponnée sans modifier la taille des tampons réguliers. Les tampons volumineux ne sont pas utilisés implicitement.

Notez qu’en cas de configuration de grands tampons, trois tampons spéciaux de grande taille seront alloués pour chaque thread au démarrage, à usage interne.

tune.bufsize.small <size>

tune.bufsize.small <size>

Définit la taille en octets des tampons petits. La valeur par défaut est 1024.

Ces tampons sont conçus pour être utilisés dans certains contextes spécifiques où la consommation mémoire est limitée, mais où il semble inutile d’allouer un tampon complet. Si toutefois un petit tampon s’avère insuffisant, une réallocation est effectuée automatiquement afin de passer à un tampon de taille standard.

Pour l’instant, il est utilisé automatiquement uniquement par le protocole HTTP/3 pour émettre les en-têtes de réponse. Sinon, le support des petits tampons peut être activé pour des proxies spécifiques via l’option « use-small-buffers ».

Voir aussi : option use-small-buffers

tune.cli.max-payload-size <size>

tune.cli.max-payload-size <size>

Définit la taille maximale autorisée pour le chargement utile transmis à une commande en ligne de commande.

En ligne de commande, une ligne de commande est limitée par la taille de la mémoire tampon. Cela signifie que toutes les commandes et leurs arguments doivent tenir dans une mémoire tampon pour être traitées, à l’exclusion de la charge utile qui peut être transmise à la dernière commande de la ligne de commande. Cette charge utile peut être allouée dans une zone dédiée si nécessaire. Sa taille est limitée par ce paramètre. La valeur par défaut est 128 Ko.

Bien que cette valeur doive être suffisamment élevée pour la plupart des utilisations, si elle est modifiée, elle doit être choisie avec soin. Une valeur excessive peut avoir un impact sur les performances de HAProxy. Selon la commande utilisée, une charge importante peut nécessiter un traitement long et risquer de déclencher le watchdog.

Veuillez consulter le manuel de gestion pour obtenir les détails concernant l’interface en ligne de commande.

tune.comp.maxlevel <number>

tune.comp.maxlevel <number>

Définit le niveau de compression maximal. Le niveau de compression influence l’utilisation du processeur pendant la compression. Cette valeur affecte l’utilisation du processeur pendant la compression. Chaque flux utilisant la compression initialise l’algorithme de compression avec cette valeur. La valeur par défaut est 1.

tune.defaults.purge

tune.defaults.purge

Pour prendre en charge les backends dynamiques, toutes les sections de paramètres par défaut nommés sont désormais conservées en mémoire après analyse. Cela est nécessaire car les backends ajoutés en temps réel doivent être basés sur un ensemble de paramètres par défaut nommé pour leur configuration.

Cela peut consommer une quantité importante de mémoire si le nombre d’instances defaults est important. Dans ce cas, et si la fonctionnalité de backend dynamique n’est pas nécessaire, il est possible d’utiliser cette option pour forcer la suppression de la section defaults après son analyse. Il reste toutefois obligatoire de conserver la section defaults référencée, qui contient des paramètres ne pouvant pas être copiés par les proxies qui la référencent. Par exemple, c’est le cas si la section defaults définit des règles TCP/HTTP ou un jeu de règles tcpcheck.

tune.disable-fast-forward

tune.disable-fast-forward

Désactive le transfert accéléré des données. Il s’agit d’un mécanisme d’optimisation du transfert de données consistant à acheminer les données directement d’un côté à l’autre sans réveiller le flux. Grâce à cette directive, il est possible de désactiver cette optimisation. Notez qu’elle désactive également tout transfert par assemblage TCP noyau ainsi que le transfert sans copie. Cette commande n’est pas destinée à une utilisation régulière ; elle sera généralement proposée uniquement par les développeurs lors de sessions de débogage complexes.

tune.disable-zero-copy-forwarding

tune.disable-zero-copy-forwarding

Désactive globalement le transfert zéro-copie des données. Il s’agit d’un mécanisme d’optimisation du transfert rapide des données en évitant l’utilisation du tampon du canal. Grâce à cette directive, il est possible de désactiver cette optimisation. Notez qu’elle désactive également tout transfert direct TCP du noyau.

Voir aussi : tune.pt.zero-copy-forwarding, tune.applet.zero-copy-forwarding, tune.h1.zero-copy-fwd-recv, tune.h1.zero-copy-fwd-send, tune.h2.zero-copy-fwd-send, tune.quic.zero-copy-fwd-send

tune.epoll.mask-events <event[,...]>

tune.epoll.mask-events <event[,...]>

Au fil de l’histoire d’HAProxy, plusieurs problèmes complexes ont été rencontrés, dus à des bogues dans le mécanisme epoll du noyau Linux. Ces problèmes sont généralement très rares et impossibles à reproduire en dehors de l’environnement du rapporteur, et ne peuvent être contournés que par la désactivation d’epoll au profit de poll, ce qui n’est pas satisfaisant dans les environnements exigeant de hautes performances. Chaque fois, ces problèmes affectent uniquement des types d’événements très spécifiques (et rares), et la possibilité de masquer ces événements peut constituer une solution de contournement plus acceptable. Cette option permet cette possibilité en autorisant l’ignoration silencieuse de quelques événements peu courants, qu’elle remplace par une entrée (qui indique un événement entrant non spécifié). L’effet est d’éviter les chemins rapides de traitement des erreurs dans certaines parties du code, et de ne recourir qu’aux chemins communs. Cette option ne doit jamais être utilisée, sauf sur recommandation explicite d’un expert chargé de diagnostiquer ou de contourner un bogue du noyau.

L’option prend un seul argument, qui est une liste séparée par des virgules de mots, chacun désignant un événement à masquer. La liste des événements actuellement pris en charge est la suivante : - « err » : masque l’événement EPOLLERR - « hup » : masque les événements EPOLLHUP - « rdhup » : masque les événements EPOLLRDHUP

Exemple :

# mask all non-traffic epoll events:
tune.epoll.mask-events err,hup,rdhup

tune.events.max-events-at-once <number>

tune.events.max-events-at-once <number>

Définit le nombre d’événements pouvant être traités simultanément par un gestionnaire de tâche asynchrone (via l’API event_hdl). <number> doit être compris entre 1 et 10 000. Une valeur élevée peut entraîner une contention de threads en raison du traitement intensif de la tâche sans interruption, tandis qu’une valeur faible peut entraîner un réamorçage constant de la tâche, car elle ne parvient pas à consommer suffisamment d’événements par exécution et ne parvient pas à suivre le producteur d’événements. La valeur par défaut peut être imposée au moment de la compilation, sinon elle est définie par défaut à 100.

tune.fail-alloc

tune.fail-alloc

Si compilé avec DEBUG_FAIL_ALLOC ou démarré avec “-dMfail”, indique le pourcentage de chances qu’une tentative d’allocation échoue. Doit être compris entre 0 (aucun échec) et 100 (aucun succès). Cela est utile pour déboguer et s’assurer que les échecs de mémoire sont gérés correctement. Si non défini, le ratio est de 0. Toutefois, l’option en ligne de commande “-dMfail” le fixe automatiquement à un taux d’échec de 1 %, de sorte qu’il n’est pas nécessaire de modifier la configuration pour les tests.

tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]

tune.fd.edge-triggered { on | off }  [ EXPERIMENTAL ]

Active (‘on’) ou désactive (‘off’) le mode de sondage déclenché par bord pour les descripteurs de fichiers (FD) qui le supportent. Ce paramètre n’est actuellement pris en charge qu’avec epoll. Il peut réduire notablement le nombre d’appels à epoll_ctl() et améliorer légèrement les performances dans certains scénarios. Cette fonctionnalité reste expérimentale : elle peut entraîner des connexions bloquées en cas de bogues non corrigés, et est désactivée par défaut.

tune.glitches.kill.cpu-usage <number>

tune.glitches.kill.cpu-usage <number>

Définit le seuil minimal d’utilisation du CPU compris entre 0 et 100, au-delà duquel les connexions présentant trop de perturbations seront tuées. Cela s’applique aux connexions ayant atteint leur seuil de perturbations. Dans les environnements où des connexions très longues se comportent souvent mal sans avoir d’impact sur les performances, il peut être souhaitable de les conserver malgré leur mauvais comportement, à condition qu’elles n’entraînent pas de dégradation, et de ne commencer à les tuer uniquement lorsque l’utilisation du CPU devient élevée. Ce paramètre permet de spécifier qu’une connexion atteignant son seuil de perturbations sera activement tuée lorsque l’utilisation du CPU atteint ou dépasse ce niveau, mais jamais lorsqu’elle est inférieure. Notez que l’utilisation du CPU est mesurée par thread, de sorte qu’une seule connexion malveillante peut être tuée. La valeur par défaut est zéro, ce qui signifie qu’une connexion atteignant son seuil de perturbations sera automatiquement tuée. Une règle empirique consisterait à définir cette valeur à deux fois l’utilisation du CPU habituelle, ou à l’utilisation courante du CPU plus la moitié de l’utilisation en veille (par exemple, si le CPU atteint habituellement 60 %, une valeur de 80 peut être pertinente). Ce paramètre n’a aucun effet sans tune.h2.fe.glitches-threshold, tune.quic.fe.sec.glitches-threshold ou tune.h1.fe.glitches-threshold. Voir également les paramètres globaux “tune.h2.fe.glitches-threshold”, “tune.h1.fe.glitches-threshold” et “tune.quic.fe.sec.glitches-threshold”.

tune.h1.be.glitches-threshold <number>

tune.h1.be.glitches-threshold <number>

Définit le seuil du nombre d’anomalies sur une connexion backend HTTP/1, au-delà duquel cette connexion sera automatiquement fermée. Cela permet de fermer automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Les événements courants incluent des en-têtes mal formés qui ont toutefois été acceptés par “accept-unsafe-violations-in-http-response”. Une valeur non nulle doit généralement être placée dans les centaines ou les milliers pour être efficace sans affecter les serveurs légèrement défectueux. Il est également possible de ne fermer les connexions que lorsque la consommation CPU dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’une connexion légèrement défaillante cessera d’être utilisée après un certain temps sans risquer d’interrompre les transferts en cours.

Voir également : tune.h1.fe.glitches-threshold, bc_glitches et tune.glitches.kill.cpu-usage

tune.h1.fe.glitches-threshold <number>

tune.h1.fe.glitches-threshold <number>

Définit le seuil du nombre d’incidents sur une connexion frontale HTTP/1 au-delà duquel cette connexion sera automatiquement fermée. Cela permet de fermer automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Les événements courants incluent des en-têtes mal formés qui ont toutefois été acceptés par “accept-unsafe-violations-in-http-request”. Une valeur non nulle doit généralement être fixée à plusieurs centaines ou milliers pour être efficace sans affecter les clients légèrement erronés. Il est également possible de ne fermer les connexions que lorsque la consommation du processeur dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’un client légèrement non conforme aura l’opportunité de créer une nouvelle connexion et de continuer à fonctionner sans être affecté, sans jamais déclencher une fermeture brutale qui risquerait d’interrompre des transferts en cours.

Voir également : tune.h1.be.glitches-threshold, fc_glitches et tune.glitches.kill.cpu-usage

tune.h1.zero-copy-fwd-recv { on | off }

tune.h1.zero-copy-fwd-recv { on | off }

Active (« on ») ou désactive (« off ») les réceptions en copie zéro des données pour le multiplexeur H1. Activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-send

tune.h1.zero-copy-fwd-send { on | off }

tune.h1.zero-copy-fwd-send { on | off }

Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur H1. Il est activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-recv

tune.h2.be.glitches-threshold <number>

tune.h2.be.glitches-threshold <number>

Définit le seuil du nombre de glitchs sur une connexion backend, au-delà duquel cette connexion sera automatiquement interrompue. Cela permet d’interrompre automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Attention, certains serveurs H2 peuvent occasionnellement provoquer quelques glitchs sur des connexions longues, aussi toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les serveurs légèrement défaillants. Il est également possible de ne tuer les connexions qu’après dépassement d’un certain seuil d’utilisation du CPU, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’une connexion légèrement défaillante cessera d’être utilisée après un certain temps sans risquer d’interrompre les transferts en cours.

Voir également : tune.h2.fe.glitches-threshold, bc_glitches et tune.glitches.kill.cpu-usage

tune.h2.be.initial-window-size <number>

tune.h2.be.initial-window-size <number>

Définit la taille initiale de la fenêtre HTTP/2 pour les connexions sortantes, soit le nombre d’octets que le serveur peut envoyer avant d’attendre une confirmation de la part de HAProxy. Ce paramètre n’a d’effet que sur le contenu du payload, et non sur les en-têtes. En l’absence de réglage, la valeur par défaut commune définie par tune.h2.initial-window-size s’applique. Il peut être pertinent d’augmenter légèrement cette valeur afin d’accélérer les téléchargements ou de réduire la charge CPU sur les serveurs, au prix d’une injustice entre clients. Il est préférable d’utiliser tune.h2.be.rxbuf à la place, qui ne provoque aucune injustice. Ce paramètre n’affecte pas la consommation de ressources.

Voir également : tune.h2.initial-window-size.

tune.h2.be.max-concurrent-streams <number>

tune.h2.be.max-concurrent-streams <number>

Définit le nombre maximum de flux simultanés par connexion sortante (HTTP/2) (c’est-à-dire le nombre de requêtes en attente sur une connexion unique vers un serveur). Si ce paramètre n’est pas défini, la valeur par défaut définie par tune.h2.max-concurrent-streams s’applique. Une valeur inférieure à la valeur par défaut de 100 peut améliorer la réactivité d’un site au détriment de la maintenance de plus nombreuses connexions établies vers les serveurs. Lorsque l’option « http-reuse » est définie sur « always », il est recommandé de réduire cette valeur afin d’éviter de mélanger trop de clients différents sur la même connexion, car si un client est plus lent que les autres, un mécanisme connu sous le nom de « blocage en tête de file » a tendance à provoquer un effet en cascade sur la vitesse de téléchargement de tous les clients partageant une connexion (dans ce cas, il est conseillé de maintenir tune.h2.be.initial-window-size faible). Il est fortement recommandé de ne pas augmenter cette valeur ; certains pourraient trouver optimal de fonctionner avec des valeurs faibles (généralement 1 à 5).

tune.h2.be.max-frames-at-once <number>

tune.h2.be.max-frames-at-once <number>

Définit le nombre maximal de trames entrantes HTTP/2 traitées simultanément sur une connexion backend. Il peut être utile de le définir à une valeur faible (quelques dizaines à quelques centaines) lorsqu’on traite des tampons très volumineux, afin de maintenir une faible latence et une meilleure équité entre plusieurs connexions. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.

tune.h2.be.rxbuf <size>

tune.h2.be.rxbuf <size>

Définit la taille de la mémoire tampon de réception HTTP/2 pour les connexions sortantes, en octets. Cette taille sera arrondie au multiple suivant de tune.bufsize et sera partagée entre toutes les transmissions de données (cadres HEADERS et DATA). Dans tous les cas, une mémoire tampon sera toujours attribuée à chaque flux, et 7/8 des mémoires tampons non utilisées seront partagées entre les flux en téléchargement de charge utile, permettant d’améliorer significativement les performances de téléchargement et d’éviter le blocage par tête de file (HoL) sur les connexions backend partagées entre plusieurs clients lorsque http-reuse est défini sur « always ». La fenêtre par flux annoncée est automatiquement ajustée pour refléter l’espace disponible, de sorte qu’en pratique il ne sera pas nécessaire de modifier tune.h2.be.initial-window-size. Si la valeur définie est inférieure à celle requise pour gérer tous les flux, la valeur minimale sera utilisée. La valeur par défaut est d’environ 1600k (100 flux avec des tampons de 16ko chacun).

Voir aussi : tune.h2.be.initial-window-size, tune.h2.fe.rxbuf, http-reuse.

tune.h2.fe.glitches-threshold <number>

tune.h2.fe.glitches-threshold <number>

Définit le seuil du nombre de perturbations sur une connexion frontale, au-delà duquel cette connexion sera automatiquement interrompue. Cela permet d’interrompre automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Prenez garde que certains clients H2 peuvent occasionnellement provoquer quelques perturbations sur des connexions longues, aussi toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les clients légèrement défectueux. Il est également possible de n’interrompre les connexions qu’au-delà d’un certain seuil d’utilisation du processeur, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture correcte est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’un client légèrement non conforme aura l’opportunité de créer une nouvelle connexion et de continuer à fonctionner sans être affecté, sans jamais déclencher la fermeture brutale, ce qui risquerait d’interrompre les transferts en cours.

Voir également : tune.h2.be.glitches-threshold, fc_glitches et tune.glitches.kill.cpu-usage

tune.h2.fe.initial-window-size <number>

tune.h2.fe.initial-window-size <number>

Définit la taille initiale de fenêtre HTTP/2 pour les connexions entrantes, soit le nombre d’octets que le client peut envoyer avant d’attendre une confirmation de la part de HAProxy. Ce paramètre n’a d’effet que sur le contenu du corps (c’est-à-dire le corps des requêtes POST), et non sur les en-têtes. Si ce paramètre n’est pas défini, la valeur par défaut commune définie par tune.h2.initial-window-size s’applique. Il peut être pertinent d’augmenter cette valeur afin de permettre des téléchargements plus rapides. La valeur par défaut est égale à tune.bufsize (16384), ce qui permet au moins 1,25 Mbps de bande passante par flux avec un temps de ping de 100 ms, ou 125 Mbps avec un temps de ping de 1 ms. Ce paramètre n’affecte pas l’utilisation des ressources. Utiliser des valeurs trop élevées peut entraîner une perte de réactivité côté client si des pages sont chargées en parallèle avec de grands téléchargements. Il est préférable d’utiliser tune.h2.fe.rxbuf à la place, qui ne provoque aucune injustice.

Voir également : tune.h2.initial-window-size.

tune.h2.fe.max-concurrent-streams <number> [args...]

tune.h2.fe.max-concurrent-streams <number> [args...]

Définit le nombre maximum de flux simultanés par connexion entrante (HTTP/2) (c’est-à-dire le nombre de requêtes en attente sur une connexion unique depuis un client). Si ce paramètre n’est pas défini, la valeur par défaut définie par tune.h2.max-concurrent-streams s’applique. Une valeur plus élevée que la valeur par défaut de 100 peut parfois améliorer légèrement le temps de chargement des pages pour des sites complexes comportant de nombreux objets de petite taille sur des réseaux à forte latence, mais peut également entraîner une utilisation accrue de la mémoire en permettant au client d’allouer plus de ressources en même temps. La valeur par défaut de 100 est généralement appropriée, et il est recommandé de ne pas modifier cette valeur. Une concurrence plus élevée a également un impact sur la charge de traitement et la latence lors de la gestion d’un grand nombre de connexions qui utilisent elles-mêmes de nombreux flux, et peut réduire la barrière contre les attaques par déni de service. La commande prend en charge les arguments optionnels suivants après le nombre :

• rq-load { <number> | auto | ignore } :

The optional argument "rq-load" permits to dynamically adjust the
advertised concurrency based on the executing thread's run-queue load:
as long as the thread's load remains below the indicated threshold, the
configured streams limit will be advertised. When the thread's load
increases beyond the configured limit, the advertised streams limit will be
decreased proportionally to the square of the excess ratio. Target load
levels between 50 and 100 generally show very good moderation under heavy
loads. Alternately, instead of specifying an explicit number, the keyword
accepts "ignore", which is the default and means that the thread's
run-queue load will not be considered to moderate the advertised streams
limit, and "auto", which sets the limit to the "tune.runqueue-depth"
value, which generally provides good results without having to tweak
the configuration any further.

• min <number> :

This sets the minimum advertised concurrency level when rq-load is used,
even if this results in a higher load than the configured target. This
allows to maintain a good level of interactivity on a site under very
heavy load. The minimum and default value is 1, but values between 5
and 15 can improve user experience.

Exemple :

tune.h2.fe.max-concurrent-streams 100 rq-load auto min 15

tune.h2.fe.max-frames-at-once <number>

tune.h2.fe.max-frames-at-once <number>

Définit le nombre maximal de trames entrantes HTTP/2 traitées simultanément sur une connexion frontale. Il peut être utile de le définir à une valeur faible (quelques dizaines à quelques centaines) lors de la gestion de très grands tampons afin de maintenir une faible latence et une meilleure équité entre plusieurs connexions. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.

tune.h2.fe.max-rst-at-once <number>

tune.h2.fe.max-rst-at-once <number>

Définit le nombre maximal de HTTP/2 entrants RST_STREAM qui seront traités simultanément sur une connexion frontale. Dès réception du nombre spécifié de trames RST_STREAM, le gestionnaire de connexion sera placé dans une file d’attente à faible priorité et traité après toutes les autres tâches. Il peut être utile de le définir à une valeur très faible (1 ou quelques unités) afin de réduire significativement les impacts des inondations RST_STREAM. Les RST_STREAM se produisent effectivement lorsque l’utilisateur clique sur le bouton Arrêter dans son navigateur, mais les quelques millisecondes supplémentaires dues à ce ré-empilement sont généralement imperceptibles, tout en étant généralement efficaces pour réduire fortement la charge provoquée par de telles inondations. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.

tune.h2.fe.max-total-streams <number>

tune.h2.fe.max-total-streams <number>

Définit le nombre maximal de flux totaux traités par connexion entrante pour HTTP/2. Dès que cette limite est atteinte, HAProxy envoie un cadre GOAWAY gracieux informant le client qu’il fermera la connexion après la fermeture de tous les flux en cours. En pratique, les clients ferment généralement aussi rapidement que possible lorsqu’ils reçoivent ce cadre, puis établissent une nouvelle connexion pour les requêtes suivantes. Cette approche peut être utile et souhaitable dans des situations où les clients restent connectés très longtemps et provoquent un déséquilibre au sein d’une ferme. Par exemple, dans certains environnements hautement dynamiques, il est possible qu’un nouveau répartiteur de charge soit instancié en temps réel pour s’adapter à une augmentation de charge, et qu’une fois la charge redescendue, il doive être arrêté sans rompre les connexions établies. En définissant une limite ici, les connexions auront une durée de vie limitée et seront régulièrement renouvelées, certaines pouvant être établies vers d’autres nœuds, afin que les ressources existantes soient rapidement libérées.

Il est important de comprendre qu’il existe une relation implicite entre cette limite et “tune.h2.fe.max-concurrent-streams” ci-dessus. En effet, HAProxy acceptera toujours le traitement de toutes les connexions potentiellement en cours entre le client et le frontal, de sorte que la limite annoncée sera toujours automatiquement augmentée de la valeur configurée dans max-concurrent-streams, qui servira de limite stricte au-delà de laquelle une violation par un client non conforme entraînera la fermeture de la connexion. Ainsi, lors du comptage du nombre de requêtes par connexion à partir des journaux, tout nombre compris entre max-total-streams et (max-total-streams + max-concurrent-streams) peut être observé, selon la vitesse à laquelle les connexions sont créées par le client.

La valeur par défaut est zéro, ce qui impose aucune limite au-delà de celles implicites par le protocole (2^30 ≈ 1,07 milliard). Des valeurs autour de 1000 peuvent déjà entraîner une renouvellement fréquent des connexions sans provoquer de latence perceptible pour la plupart des clients. Définir cette valeur trop basse peut entraîner une augmentation de la charge CPU due aux reconnexions TLS fréquentes, ainsi qu’une augmentation du temps de chargement des pages. Veuillez noter que certains outils de test de charge ne prennent pas en charge les reconnexions et peuvent signaler des erreurs avec ce paramètre ; il peut donc être nécessaire de le désactiver lors de l’exécution de benchmarks de performance. Voir également “tune.h2.fe.max-concurrent-streams”.

tune.h2.fe.rxbuf <size>

tune.h2.fe.rxbuf <size>

Définit la taille de la mémoire tampon de réception HTTP/2 pour les connexions entrantes, en octets. Cette taille sera arrondie au multiple suivant de tune.bufsize et sera partagée entre toutes les transmissions de données (cadres HEADERS et DATA). Dans tous les cas, une mémoire tampon sera toujours attribuée à chaque flux, et 7/8 des mémoires tampons non utilisées seront partagées entre les flux transmettant des charges utiles, permettant d’améliorer significativement les performances de transmission. La fenêtre par flux annoncée est automatiquement ajustée pour refléter l’espace disponible, de sorte qu’en pratique il ne devrait pas être nécessaire de modifier tune.h2.fe.initial-window-size. Si la valeur définie est inférieure à celle requise pour gérer tous les flux, la valeur minimale sera utilisée. La valeur par défaut de 1600k (100 flux avec des tampons de 16 ko chacun) permet une vitesse de transmission d’environ 130 Mbps pour un client ayant un RTT de 100 ms.

Voir également : tune.h2.fe.initial-window-size et tune.h2.be.rxbuf.

tune.h2.header-table-size <number>

tune.h2.header-table-size <number>

Définit la taille du tableau dynamique d’en-têtes HTTP/2. La valeur par défaut est de 4096 octets et ne peut pas dépasser 65536 octets. Une valeur plus élevée peut aider certains clients à envoyer des requêtes plus compactes, selon leurs capacités. Cette quantité de mémoire est consommée pour chaque connexion HTTP/2. Il est recommandé de ne pas la modifier.

tune.h2.initial-window-size <number>

tune.h2.initial-window-size <number>

Définit la valeur par défaut de la taille initiale de la fenêtre HTTP/2, sur les connexions entrantes et sortantes. Cette valeur est utilisée pour les connexions entrantes lorsque tune.h2.fe.initial-window-size n’est pas définie, et pour les connexions sortantes lorsque tune.h2.be.initial-window-size n’est pas définie. Ce paramètre est utilisé à la fois comme valeur initiale et comme minimum par flux. La valeur par défaut est égale à 16384 (tune.bufsize), ce qui permet, pour les téléchargements, une bande passante d’au moins 1,25 Mbps par flux sur un réseau affichant un temps de ping de 100 ms, ou 125 Mbps sur un réseau local à 1 ms. Lorsque le nombre de tampons reçus est inférieur au maximum, dans les limites définies par tune.h2.be.rxbuf et tune.h2.fe.rxbuf, les tampons non utilisés sont partagés entre les flux en réception. En conséquence, il n’est normalement pas utile de modifier cette valeur par défaut. Étant donné qu’un changement de cette valeur par défaut augmente à la fois les vitesses de téléchargement et provoque une plus grande injustice entre les clients lors des téléchargements, il est recommandé d’utiliser plutôt les paramètres spécifiques aux côtés tune.h2.fe.initial-window-size et tune.h2.be.initial-window-size.

tune.h2.log-errors { none | connection | stream }

tune.h2.log-errors { none | connection | stream }

Définit le niveau d’erreurs dans le démultiplexeur H2 qui déclenchera une journalisation. La valeur par défaut est « stream », ce qui signifie que toute erreur de décodage rencontrée dans le démultiplexeur entraînera l’émission d’un journal. La valeur « connection » indique que seules les erreurs entraînant l’invalidation de la connexion produiront une journalisation. Enfin, « none » indique qu’aucune erreur de décodage ne produira de journal. Il est recommandé de définir au moins « connection » afin de détecter les anomalies protocolaires, même si cela implique de passer temporairement à « none » pendant les périodes difficiles.

tune.h2.max-concurrent-streams <number>

tune.h2.max-concurrent-streams <number>

Définit le nombre maximal par défaut de flux simultanés par connexion (HTTP/2) (c’est-à-dire le nombre de requêtes en cours sur une connexion unique). Cette valeur est utilisée pour les connexions entrantes lorsque tune.h2.fe.max-concurrent-streams n’est pas définie, et pour les connexions sortantes lorsque tune.h2.be.max-concurrent-streams n’est pas définie. La valeur par défaut est 100. L’impact varie selon le côté ; veuillez consulter les deux paramètres ci-dessus pour plus de détails. Il est recommandé de ne pas utiliser ce paramètre et de passer aux paramètres par côté à la place. Une valeur nulle désactive la limite, permettant à un client unique de créer autant de flux qu’autorisé par HAProxy. Il est fortement recommandé de ne pas modifier cette valeur.

tune.h2.max-frame-size <number>

tune.h2.max-frame-size <number>

Définit la taille maximale de trame HTTP/2 que HAProxy annonce être prêt à recevoir de ses pairs. La valeur par défaut est la plus grande entre 16384 et la taille de tampon (tune.bufsize). En tout état de cause, HAProxy n’annonce pas de prise en charge de tailles de trames supérieures à celles des tampons. Le principal objectif de ce paramètre est de permettre de limiter la taille maximale de trame lorsqu’on utilise des tampons de grande taille. Des tailles de trames trop importantes peuvent avoir un impact sur les performances ou provoquer un comportement anormal chez certains pairs. Il est fortement recommandé de ne pas modifier cette valeur.

tune.h2.zero-copy-fwd-send { on | off }

tune.h2.zero-copy-fwd-send { on | off }

Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur H2. Activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding

tune.http.cookielen <number>

tune.http.cookielen <number>

Définit la longueur maximale des cookies capturés. Il s’agit de la valeur maximale autorisée pour la directive « capture cookie xxx len yyy », toute valeur supérieure étant automatiquement tronquée à cette valeur. Il est important de ne pas définir une valeur trop élevée, car toutes les captures de cookies allouent toujours cette taille, quelle que soit leur valeur configurée (elles partagent un même pool). Cette valeur est par requête et par réponse, donc la mémoire allouée est deux fois cette valeur par connexion. Si non spécifié, la limite est fixée à 63 caractères. Il est recommandé de ne pas modifier cette valeur.

tune.http.logurilen <number>

tune.http.logurilen <number>

Définit la longueur maximale de l’URI de requête dans les journaux. Cela empêche le troncature des URI de requête longs contenant des chaînes de requête précieuses dans les lignes de journal. Ceci n’est pas lié aux limites syslog. Si vous augmentez cette limite, vous pouvez également augmenter le paramètre ’log … len yyy’. Votre démon syslog peut également nécessiter des directives de configuration spécifiques. La valeur par défaut est 1024.

tune.http.maxhdr <number>

tune.http.maxhdr <number>

Définit le nombre maximal d’en-têtes autorisés dans les messages HTTP reçus. Lorsqu’un message contient un nombre d’en-têtes supérieur à cette valeur (y compris la première ligne), il est rejeté avec un code d’état « 400 Bad Request » pour une requête, ou « 502 Bad Gateway » pour une réponse. La valeur par défaut est 101, suffisante pour toutes les utilisations, étant donné que le serveur Apache largement déployé utilise la même limite. Il peut être utile d’augmenter cette limite temporairement afin de permettre le fonctionnement d’une application défectueuse jusqu’à sa correction. La plage acceptée est 1..32767. Prenez en compte que chaque nouvel en-tête consomme 32 bits de mémoire par flux, n’augmentez donc pas cette limite de manière excessive.

Notez que HTTP/1.1 est un protocole texte, il n’existe donc aucune limite particulière lors de l’envoi du message. La limite appliquée lors de l’analyse du message est suffisante. HTTP/2 et HTTP/3 sont des protocoles binaires et nécessitent une étape de codage. Une limite est également définie lors du codage des en-têtes afin de respecter les contraintes imposées par les protocoles. Cette limite est suffisamment élevée, mais n’est pas documentée intentionnellement. La même limite s’applique aux premières étapes du décodage, pour la même raison.

tune.idle-pool.shared { full | on | off }

tune.idle-pool.shared { full | on | off }

Contrôle le partage des pools de connexions inactives entre les threads pour un même serveur. Il peut être activé pour tous les threads d’un même groupe de threads (‘on’), activé pour tous les threads (‘full’) ou désactivé (‘off’). La valeur par défaut consiste à partager les pools entre les threads du même groupe de threads (‘on’), afin de minimiser le nombre de connexions persistantes vers un serveur et d’optimiser le taux de réutilisation des connexions. Le partage avec des threads provenant d’autres groupes de threads peut avoir un impact sur les performances, et n’est pas activé par défaut, mais peut être utile si la réutilisation maximale des connexions est une priorité. Pour faciliter le débogage ou en cas de suspicion de bug dans HAProxy concernant la réutilisation des connexions, il peut être pratique de désactiver de force le partage des pools inactifs entre plusieurs threads, et de forcer cette option à « off ». Il est fortement déconseillé de désactiver cette option sans définir une valeur conservatrice sur « pool-low-conn » pour tous les serveurs qui dépendent de la réutilisation des connexions afin d’atteindre un haut niveau de performance, sinon les connexions pourraient être fermées très fréquemment à mesure que le nombre de threads augmente.

tune.idletimer <timeout>

tune.idletimer <timeout>

Définit la durée après laquelle HAProxy considère qu’un tampon vide est probablement associé à un flux inactif. Cela permet d’ajuster de manière optimale certaine taille de paquets lors du transfert de données importantes et petites de façon alternée. La décision d’utiliser splice() ou d’envoyer des tampons volumineux en SSL est influencée par ce paramètre. La valeur est exprimée en millisecondes, comprise entre 0 et 65535. Une valeur nulle signifie que HAProxy ne tentera pas de détecter les flux inactifs. La valeur par défaut est 1000, qui semble correctement détecter les pauses utilisateur (par exemple, lire une page avant de cliquer). Il n’y a aucune raison de modifier cette valeur. Veuillez consulter tune.ssl.maxrecord ci-dessous.

tune.listener.default-shards { by-process | by-thread | by-group }

tune.listener.default-shards { by-process | by-thread | by-group }

Par défaut, toutes les lignes « bind » créent une seule partition, c’est-à-dire un seul socket que tous les threads du processus écoutent. Avec un grand nombre de threads, cela n’est pas très efficace et peut même entraîner un surcroît important de charge dans le noyau pour mettre à jour l’état de surveillance ou distribuer les événements aux différents threads. Les systèmes d’exploitation modernes prennent en charge l’équilibrage des connexions entrantes, un mécanisme qui permet de lier plusieurs sockets à la même adresse et au même port, et de répartir uniformément toutes les connexions entrantes entre ces sockets afin que chaque thread ne voie que les connexions en attente dans le socket auquel il est lié. Cela réduit considérablement la charge côté noyau et améliore les performances dans le chemin des connexions entrantes. Ce mécanisme est généralement activé dans HAProxy à l’aide de l’option « shards » sur les lignes « bind », qui vaut 1 par défaut, ce qui signifie qu’un écouteur est unique par processus. Sur les systèmes disposant de nombreux processeurs, il peut être plus pratique de modifier ce paramètre par défaut en « by-thread » afin de toujours créer un socket d’écoute par thread, ou en « by-group » afin de toujours créer un socket d’écoute par groupe de threads. Faites attention à l’utilisation des descripteurs de fichiers avec « by-thread », car chaque écouteur nécessite autant de sockets qu’il y a de threads. Certains systèmes d’exploitation (par exemple FreeBSD) limitent à 256 le nombre de sockets sur une même adresse. Notez que « by-group » reste équivalent à « by-process » pour les configurations par défaut impliquant un seul groupe de threads, et revient à partager le même socket sur les systèmes qui ne prennent pas en charge ce mécanisme. La valeur par défaut est « by-group », avec un retour à « by-process » pour les systèmes ou familles de sockets qui ne prennent pas en charge les liaisons multiples.

tune.listener.multi-queue { on | fair | off }

tune.listener.multi-queue { on | fair | off }

Active (‘on’ / ‘fair’) ou désactive (‘off’) le mécanisme d’acceptation multi-file d’écouteur, qui répartit le trafic entrant sur tous les threads auxquels une directive « bind » est autorisée, plutôt que de les réserver à lui seul. Cela permet une répartition plus uniforme du trafic et une meilleure évolutivité, en particulier dans les environnements où les threads peuvent être déséquilibrés en charge en raison d’activités externes (par exemple, des interruptions réseau qui convergent sur un même thread). Le mode par défaut, « on », optimise le choix du thread en sélectionnant, parmi un échantillon, celui qui possède le moins de connexions. Il s’agit souvent du meilleur choix lorsque les connexions sont longues, car il parvient à maintenir tous les threads occupés. Un deuxième mode, « fair », parcourt tous les threads indépendamment de leur charge instantanée. Il peut être plus adapté aux connexions de courte durée, ou sur des machines disposant d’un très grand nombre de threads, où la probabilité de trouver le thread le moins chargé avec le mode « on » est faible. Enfin, il est possible de désactiver de force le mécanisme de redistribution en utilisant « off », notamment pour le dépannage, ou dans les cas où les connexions sont de courte durée et où l’on estime que le système d’exploitation assure déjà une répartition suffisamment efficace. La valeur par défaut est « on ».

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

Indiquez explicitement à HAProxy comment gérer les objets d’extraction d’échantillon lors de leur transmission à Lua. En effet, lors de l’utilisation des convertisseurs natifs, les extraits d’échantillons ou les variables provenant de scripts Lua (parmi d’autres) sont convertis du type interne smp en type Lua équivalent. En raison d’une implémentation historique, une ambiguïté existe concernant la gestion des booléens : lors de la conversion Lua → HAProxy smp, les booléens sont correctement conservés, mais lors de la conversion HAProxy smp → Lua, les booléens étaient par erreur convertis en entiers. Cela signifie qu’une extraction d’échantillon ou un convertisseur retournant un booléen renverrait un entier 0 ou 1 lorsqu’il est utilisé depuis Lua. Malheureusement, en Lua, les booléens et les entiers ne sont pas interchangeables. Ainsi, pour éviter toute ambiguïté, “tune.lua.bool-sample-conversion” doit être explicitement défini sur « normal » (ce qui signifie abandonner le comportement historique pour une meilleure cohérence) ou sur “pre-3.1-bug” (forcer le comportement historique afin de prévenir les dysfonctionnements des scripts existants). Si l’option n’est pas définie explicitement et qu’un script Lua est chargé à partir de la configuration, HAProxy émettra un avertissement, et l’option passera implicitement à “pre-3.1-bug” afin de conserver le comportement historique. Il est recommandé de définir cette option sur « normal » après avoir vérifié que les scripts Lua en cours d’utilisation gèrent correctement les échantillons HAProxy booléens comme des booléens.

Ce paramètre doit être défini avant toute directive « lua-load » ou « lua-load-per-thread » pour être pris en compte, sinon il est ignoré.

tune.lua.burst-timeout <timeout>

tune.lua.burst-timeout <timeout>

Le délai d’expiration « burst » s’applique à tout gestionnaire Lua. Si le gestionnaire ne parvient pas à se terminer ou à effectuer une suspension avant l’expiration du délai, il sera interrompu afin d’éviter les conflits de thread, d’empêcher le trafic de ne pas être servi trop longtemps, et d’empêcher finalement le processus de planter en raison de l’activation du watchdog. Contrairement aux autres délais d’expiration Lua, qui sont cumulatifs lors des suspensions, le délai d’expiration « burst » garantit que le temps passé dans une seule fenêtre d’exécution Lua ne dépasse pas le délai configuré.

Ici, « yield » signifie que l’exécution Lua est effectivement interrompue, soit par un appel explicite à une fonction de type lua-yielding, telle que core.(m)sleep() ou core.yield(), soit suite à une interruption forcée automatique (voir tune.lua.forced-yield), et qu’elle sera reprise ultérieurement lorsque la tâche associée sera remise en planification. Tous les gestionnaires Lua ne peuvent pas effectuer de yield : il convient de distinguer les gestionnaires pouvant effectuer un yield de ceux qui ne peuvent pas.

Pour les gestionnaires récupérables (tâches, actions…), atteindre le délai d’expiration signifie que “tune.lua.forced-yield” pourrait être trop élevé pour le système ; le réduire pourrait améliorer la situation, mais il pourrait aussi être pertinent de vérifier si l’ajout de rendus manuels à certains points clés au sein de la fonction Lua aide ou non. Cela peut également indiquer que le gestionnaire passe trop de temps dans une fonction spécifique de la bibliothèque Lua qui ne peut pas être interrompue.

Pour les gestionnaires intransigeants (convertisseurs Lua, extraits d’échantillon), cela peut simplement indiquer que le gestionnaire effectue trop de calculs, ce qui peut résulter d’une conception inappropriée, étant donné que ces gestionnaires, qui bloquent souvent le flux d’exécution de la requête, doivent se terminer rapidement afin de permettre la progression du traitement de la requête. Une approche courante de résolution consisterait à optimiser davantage la fonction Lua en termes de vitesse, car réduire “tune.lua.forced-yield” n’aiderait pas.

Ce délai d’expiration ne prend en compte que l’exécution pure du runtime Lua. Si Lua effectue un appel à core.sleep, le temps d’attente n’est pas pris en compte. Le délai d’expiration par défaut est de 1000 ms.

Note : si un cycle de ramasse-miettes Lua est initié depuis le gestionnaire (soit explicitement demandé, soit déclenché automatiquement par Lua après un certain temps), la durée de ce cycle sera également prise en compte.

En effet, il n’existe aucun moyen de déduire la durée du cycle de ramassage automatique (GC), ce qui peut entraîner certains faux positifs sur des systèmes saturés (où le GC peine à suivre et consomme la majeure partie du temps d’exécution disponible). Si tel était le cas, voici quelques pistes de résolution :

- vérification de la possibilité d'optimiser le script afin de réduire l'utilisation mémoire Lua
- ajustement des paramètres de GC Lua et/ou demande de cycles de GC manuels
  (voir : https://www.lua.org/manual/5.4/manual.html#pdf-collectgarbage)
- augmentation de tune.lua.burst-timeout

Définir la valeur à 0 désactive entièrement cette protection.

tune.lua.forced-yield <number>

tune.lua.forced-yield <number>

Ce directive force le moteur Lua à effectuer une suspension à chaque <number> d’instructions exécutées. Cela permet d’interrompre un script long et permet au planificateur HAProxy de traiter d’autres tâches, comme l’acceptation de connexions ou le transfert de trafic. La valeur par défaut est de 10 000 instructions pour les scripts chargés avec « lua-load-per-thread » et de MAX(500, 10 000 / nbthread) instructions pour les scripts chargés avec « lua-load » (valeur optimale pour les performances tout en évitant les conflits de thread dus à la concurrence pour le verrou global Lua).

Si HAProxy exécute fréquemment du code Lua mais que plus de réactivité est nécessaire, cette valeur peut être réduite. Si le code Lua est assez long et que son résultat est absolument nécessaire pour traiter les données, la valeur de <number> peut être augmentée, mais celle-ci doit être définie avec prudence, car dans un contexte multithreadé, elle pourrait accroître la contention.

tune.lua.log.loggers { on | off }

tune.lua.log.loggers { on | off }

Active (‘on’) ou désactive (‘off’) la journalisation de la sortie des scripts LUA via les journaux applicables au proxy actuel, le cas échéant.

Par défaut, ‘on’.

tune.lua.log.stderr { on | auto | off }

tune.lua.log.stderr { on | auto | off }

Active (‘on’) ou désactive (‘off’) la journalisation de la sortie des scripts LUA via stderr. Lorsqu’elle est définie sur ‘auto’, la journalisation via stderr est activée de manière conditionnelle si l’une des conditions suivantes est remplie :

- tune.lua.log.loggers est défini sur « off »
- le script est exécuté dans un contexte non proxy sans logger global
- le script est exécuté dans un contexte proxy sans logger attaché

Veuillez noter que, lorsqu’elle est activée, cette journalisation s’ajoute à la journalisation configurée via tune.lua.log.loggers.

Valeur par défaut : « auto ».

tune.lua.maxmem <number>

tune.lua.maxmem <number>

Définit la quantité maximale de mémoire RAM en mégaoctets par processus utilisable par Lua. Par défaut, elle est nulle, ce qui signifie sans limite. Il est important de définir une limite afin d’assurer qu’une erreur dans un script ne provoque pas l’épuisement de la mémoire du système.

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

Sélectionne les bibliothèques standard Lua à charger lors de l’initialisation de l’état Lua. L’argument est une liste séparée par des virgules de noms de bibliothèques provenant de l’ensemble suivant : table, io, os, string, math, utf8, package, debug. Les valeurs spéciales « all » et « none » peuvent être utilisées à la place d’une liste. « none » ne peut pas être combinée avec des noms de bibliothèques. La valeur par défaut est « all ».

Les bibliothèques base et coroutine sont toujours chargées, quelle que soit cette configuration : base fournit les fonctions Lua de base sur lesquelles HAProxy s’appuie, et coroutine est requise car HAProxy remplace coroutine.create() par une implémentation sécurisée propre à son environnement.

Notez que les appels à fork() et la création de nouveaux threads sont déjà bloqués par défaut dans HAProxy, quelle que soit cette configuration, et ne peuvent être réactivés qu’à l’aide de la directive globale « insecure-fork-wanted ». Restreindre l’ensemble des bibliothèques chargées réduit davantage la surface d’attaque exposée aux scripts Lua. En particulier : - l’omission de « os » empêche l’utilisation de os.execute() et os.exit() - l’omission de « io » empêche l’utilisation de io.open() et io.popen() - l’omission de « package » empêche le chargement de modules C natifs via require() - l’omission de « debug » empêche l’inspection interne de HAProxy via debug.getupvalue(), debug.getmetatable() ou debug.sethook()

Exemples :

tune.lua.openlibs none                    # only base + coroutine
tune.lua.openlibs string,math,table,utf8  # safe subset, no I/O or OS
tune.lua.openlibs all                     # default, load everything

Ce paramètre doit être défini avant toute directive « lua-load », « lua-load-per-thread » ou « lua-prepend-path », faute de quoi une erreur de parsing est renvoyée.

tune.lua.service-timeout <timeout>

tune.lua.service-timeout <timeout>

Ce délai d’expiration correspond à l’exécution des services Lua. Il est utile pour empêcher les boucles infinies ou des durées d’exécution trop longues en Lua. Ce délai ne prend en compte que le runtime pur Lua. Si le code Lua effectue une pause, celle-ci n’est pas prise en compte. La valeur par défaut est de 4 s.

tune.lua.session-timeout <timeout>

tune.lua.session-timeout <timeout>

Ce délai d’expiration correspond à l’exécution des sessions Lua. Il est utile pour empêcher les boucles infinies ou des durées d’exécution trop longues en Lua. Ce délai ne prend en compte que l’exécution réelle du runtime Lua. Si la session Lua effectue une pause, celle-ci n’est pas prise en compte. La valeur par défaut est de 4 s.

tune.lua.task-timeout <timeout>

tune.lua.task-timeout <timeout>

Le but est le même que “tune.lua.session-timeout”, mais ce délai d’expiration est dédié aux tâches. Par défaut, ce délai d’expiration n’est pas défini, car une tâche peut rester active pendant toute la durée de vie de HAProxy. Par exemple, une tâche utilisée pour vérifier les serveurs.

tune.max-checks-per-thread <number>

tune.max-checks-per-thread <number>

Définit le nombre de contrôles d’état actifs par thread au-delà duquel un thread tentera activement de rechercher un thread moins chargé pour exécuter le contrôle d’état, ou le mettra en file d’attente jusqu’à ce que le nombre de contrôles d’état actifs en cours d’exécution sur ce thread diminue. La valeur par défaut est zéro, ce qui signifie qu’aucune limite n’est définie. Ce paramètre peut être nécessaire dans certains environnements exécutant un très grand nombre de contrôles coûteux avec de nombreux threads lorsque la charge semble inégale, ce qui peut entraîner des délais d’expiration aléatoires des contrôles d’état au démarrage, notamment lors de l’utilisation d’OpenSSL 3.0, qui est environ 20 fois plus intensif en ressources CPU pour les contrôles d’état que les versions antérieures. Cela permettra de répartir équitablement le travail des contrôles d’état sur tous les threads. La grande majorité des configurations n’a pas besoin de modifier ce paramètre. Veuillez noter qu’une valeur trop faible peut considérablement ralentir les contrôles d’état si ces derniers sont lents à s’exécuter.

tune.maxaccept <number>

tune.maxaccept <number>

Définit le nombre maximal de connexions consécutives qu’un processus peut accepter d’affilée avant de passer à d’autres tâches. En mode mono-processus, des valeurs plus élevées permettaient d’obtenir de meilleures performances aux débits de connexion élevés, bien que cela ne soit plus pertinent avec la mise en file d’attente multiple. Cette valeur s’applique individuellement à chaque écouteur, de sorte que le nombre de processus auxquels un écouteur est lié est pris en compte. Sa valeur par défaut est 4, qui a montré les meilleurs résultats. Si une valeur nettement plus élevée a été héritée d’une configuration ancienne, il peut être utile de la supprimer, car cela améliore à la fois les performances et réduit le temps de réponse. En mode multi-processus, cette valeur est divisée par deux fois le nombre de processus auxquels l’écouteur est lié. Affecter la valeur -1 désactive complètement cette limitation. Il est normalement inutile de modifier cette valeur.

tune.maxpollevents <number>

tune.maxpollevents <number>

Définit le nombre maximal d’événements pouvant être traités simultanément lors d’un appel au système de sondage. La valeur par défaut est adaptée au système d’exploitation. Il a été observé qu’une réduction de cette valeur en dessous de 200 tend à diminuer légèrement la latence au détriment de la bande passante réseau, tandis qu’une augmentation au-dessus de 200 tend à échanger latence contre une bande passante légèrement accrue. La valeur configurée doit être inférieure ou égale à 1000000.

tune.maxrewrite <number>

tune.maxrewrite <number>

Définit l’espace mémoire réservé à cette taille en octets. Cet espace réservé est utilisé pour la réécriture ou l’ajout d’en-têtes. Les premières lectures sur les sockets ne rempliront jamais plus de bufsize-maxrewrite. Historiquement, cette valeur était définie par défaut à la moitié de bufsize, bien que cela n’ait pas beaucoup de sens puisqu’il est rare d’avoir un grand nombre d’en-têtes à ajouter. Une valeur trop élevée empêche le traitement des requêtes ou réponses volumineuses. Une valeur trop faible empêche l’ajout d’en-têtes supplémentaires aux requêtes déjà importantes ou aux requêtes POST. Il est généralement conseillé de la définir à environ 1024. Elle est automatiquement ajustée à la moitié de bufsize si elle est supérieure à cette valeur. Cela signifie que vous n’avez pas à vous soucier de cette option lors du changement de bufsize.

tune.max-rules-at-once <number>

tune.max-rules-at-once <number>

Définit le nombre maximum de règles pouvant être évaluées simultanément dans les fonctions d’évaluation de règlesets, à condition qu’elles prennent en charge la suspension. En effet, il n’est pas rare de rencontrer des configurations comportant un grand nombre de règles telles que « tcp-request content » ou « http-request ». Un grand nombre de règles combiné à des actions exigeant beaucoup de ressources processeur (par exemple, des actions agissant sur le contenu) peut entraîner une contention de thread, car toutes les règles d’un même règleset sont évaluées dans la même boucle d’interrogation si l’évaluation n’est pas interrompue. Cette option garantit qu’au plus <number> règles ne peuvent être exécutées dans la même boucle d’interrogation pour les règlesets orientés contenu (ceux qui prennent déjà en charge la suspension en raison de l’inspection du contenu). Elle force ainsi la fonction d’évaluation à suspendre, de manière à revenir dans la boucle d’interrogation suivante pour poursuivre l’évaluation.

Les jeux de règles affectés sont :

• “tcp-request content”
• “tcp-response content”
• “http-request”
• “http-response”

La valeur par défaut est 50.

tune.memory.hot-size <number>

tune.memory.hot-size <number>

Définit la quantité de mémoire par thread qui sera conservée en cache local et qui ne pourra jamais être récupérée par d’autres threads. L’accès à cette mémoire est très rapide (sans verrouillage), et en disposer d’une quantité suffisante est essentiel pour maintenir un bon niveau de performance en cas de forte contention de threads. La valeur est exprimée en octets, et sa valeur par défaut est configurée au moment de la compilation via CONFIG_HAP_POOL_CACHE_SIZE, qui vaut par défaut 524288 (512 ko). Une valeur plus élevée peut améliorer les performances dans certains scénarios d’utilisation, notamment lorsque les profils de performance indiquent une forte contrainte d’allocation mémoire. L’expérience montre qu’une valeur optimale se situe entre une et deux fois la taille du cache L2 par cœur processeur. Des valeurs trop élevées ont un impact négatif sur les performances en provoquant une utilisation inefficace des caches L3 des processeurs, et consomment davantage de mémoire. Il est recommandé de ne pas modifier cette valeur, ou de le faire par petites incréments. Pour désactiver complètement les caches CPU par thread, une valeur très faible pourrait fonctionner, mais il est préférable d’utiliser “-dMno-cache” en ligne de commande.

tune.notsent-lowat.client <size>

tune.notsent-lowat.client <size>
tune.notsent-lowat.server <size>

Ajuste le tamponage par socket du noyau afin de signaler que le côté émetteur d’une socket est plein dès que la quantité de données tamponnées atteint cette valeur augmentée de la taille de fenêtre mesurée. Le principe consiste à maintenir dans les tampons socket la quantité strictement nécessaire de données, plus une petite marge correspondant à ce qui serait envoyé au moment où haproxy tente de réémettre. Une valeur faible (généralement proche de tune.bufsize) permet de réduire significativement la consommation mémoire dans les tampons système et de diminuer la latence au niveau de l’application due au vidage des données tamponnées. Cette configuration est généralement plus efficace et plus précise que tune.sndbuf.client et tune.sndbuf.client sur les systèmes qui la supportent. Elle s’applique par connexion (connexion depuis un client ou connexion vers un serveur selon le paramètre) et n’est utilisée que pour les connexions TCP. La valeur par défaut est zéro, ce qui signifie sans limite. Cette option n’est disponible que sous Linux.

tune.pattern.cache-size <number>

tune.pattern.cache-size <number>

Définit la taille du cache de recherche de motifs à <number> entrées. Il s’agit d’un cache LRU qui conserve les recherches précédentes et leurs résultats. Ce cache est utilisé par les ACLs et les cartes lors de recherches de motifs lentes, à savoir celles utilisant les méthodes de correspondance « sub », « reg », « dir », « dom », « end », « bin », ainsi que les chaînes insensibles à la casse. Il s’applique aux expressions de motif, ce qui signifie qu’il peut mémoriser le résultat d’une recherche parmi tous les motifs spécifiés sur une ligne de configuration (y compris ceux chargés à partir de fichiers). Il invalide automatiquement les entrées mises à jour via des actions HTTP ou en ligne de commande. La taille par défaut du cache est fixée à 10 000 entrées, ce qui limite son empreinte à environ 5 Mo par process/thread sur les systèmes 32 bits et 8 Mo par process/thread sur les systèmes 64 bits, les caches étant thread/process locaux. Le risque de collision dans ce cache est très faible, de l’ordre de la taille du cache divisée par 2^64. En pratique, avec 10 000 requêtes par seconde et une taille de cache par défaut de 10 000 entrées, il y a 1 % de chance qu’une attaque par force brute provoque une collision unique après 60 ans, ou 0,1 % après 6 ans. Ce risque est considéré comme bien inférieur à celui d’une corruption mémoire causée par des composants vieillissants. Si ce niveau de risque n’est pas acceptable, le cache peut être désactivé en définissant ce paramètre à 0.

tune.peers.max-updates-at-once <number>

tune.peers.max-updates-at-once <number>

Définit le nombre maximal de mises à jour de table de persistance que HAProxy tentera de traiter en une seule fois lors de l’envoi de messages. Récupérer les données pour ces mises à jour nécessite des opérations de verrouillage qui peuvent être intensives en ressources CPU sur des machines fortement multithreadées si non limitées, et peuvent également augmenter la latence du trafic pendant le transfert initial par lots entre un processus plus ancien et un processus plus récent. À l’inverse, des valeurs faibles peuvent également entraîner un surcoût CPU plus élevé et prendre plus de temps à s’achever. La valeur par défaut est 200, et il est conseillé de ne pas la modifier.

tune.pipesize <size>

tune.pipesize <size>

Définit la taille de la mémoire tampon du noyau pour les tubes à cette taille (en octets). Par défaut, les tubes ont la taille par défaut du système. Toutefois, dans certains cas, notamment lors de l’utilisation du découpage TCP, il peut améliorer les performances d’augmenter la taille des tubes, en particulier si l’on soupçonne que les tubes ne sont pas pleins et que de nombreuses appels à splice() sont effectués. Cela a une incidence sur la taille mémoire du noyau, donc cette valeur ne doit pas être modifiée si les impacts ne sont pas compris.

tune.pool-high-fd-ratio <number>

tune.pool-high-fd-ratio <number>

Ce paramètre définit le nombre maximal de descripteurs de fichiers (en pourcentage) utilisés globalement par HAProxy par rapport au nombre maximal de descripteurs de fichiers que HAProxy peut utiliser avant de commencer à tuer les connexions inactives lorsque nous ne pouvons pas réutiliser une connexion et devons en créer une nouvelle. La valeur par défaut est 25 (un quart du nombre de descripteurs signifie qu’environ la moitié du nombre maximal de connexions frontales peut maintenir une connexion inactif derrière, tout au-delà de ce seuil ne semble généralement pas pertinent dans le cas général lorsqu’on cible la réutilisation des connexions).

tune.pool-low-fd-ratio <number>

tune.pool-low-fd-ratio <number>

Ce paramètre définit le nombre maximal de descripteurs de fichiers (en pourcentage) utilisés globalement par HAProxy par rapport au nombre maximal de descripteurs de fichiers que HAProxy peut utiliser avant de cesser de placer les connexions dans le pool inactif pour réutilisation. La valeur par défaut est 20.

tune.pt.zero-copy-forwarding { on | off }

tune.pt.zero-copy-forwarding { on | off }

Active (‘on’) ou désactive (‘off’) le transfert zéro-copie des données pour le multiplexeur en pass-through. À utiliser uniquement si le splice du noyau est également configuré. Activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding, option splice-auto, option splice-request et option splice-response

tune.quic.be.cc.cubic-min-losses <number>

tune.quic.be.cc.cubic-min-losses <number>
tune.quic.fe.cc.cubic-min-losses <number>

Définit le nombre de paquets perdus nécessaires pour que l’algorithme de contrôle de congestion Cubic considère réellement un événement de perte. En règle générale, tout événement de perte est considéré comme le résultat d’une congestion et suffisant pour que Cubic reparte d’une fenêtre plus petite. Toutefois, des expérimentations montrent qu’il existe diverses causes de pertes qui ne sont pas du tout dues à une congestion et qui peuvent simplement être qualifiées de pertes erronées, pour lesquelles l’ajustement de la fenêtre n’a aucun effet, sauf à ralentir la communication. Une mauvaise qualité du signal radio, une livraison hors ordre, une utilisation élevée du CPU par un client entraînant des délais aléatoires, ainsi que des imprécisions du timer système peuvent être parmi les causes courantes de ce phénomène. Ce paramètre permet de rendre Cubic un peu plus tolérant aux pertes erronées en modifiant le nombre minimum de pertes cumulées entre deux ACKs nécessaires pour considérer un événement de perte, qui est par défaut de 1. Des gains significatifs ont été observés expérimentalement, mais toujours accompagnés d’une augmentation de la bande passante gaspillée par les retransmissions et d’un risque accru de saturation des liens congestionnés. La valeur 2 peut être utilisée ponctuellement pour comparer certains métriques. N’allez jamais au-delà de 2 sans une analyse préalable par un expert. La valeur par défaut et minimale est 1. Utilisez toujours 1.

tune.quic.cc.cubic.min-losses <number> (deprecated)

tune.quic.cc.cubic.min-losses <number> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.cc.hystart { on | off }

tune.quic.be.cc.hystart { on | off }
tune.quic.fe.cc.hystart { on | off }

Active (‘on’) ou désactive (‘off’) l’algorithme HyStart++ (RFC 9406) pour les connexions QUIC, utilisé comme substitution à la phase de démarrage lent des algorithmes de contrôle de congestion, qui peut entraîner une perte élevée de paquets. Il est désactivé par défaut.

tune.quic.cc-hystart { on | off } (deprecated)

tune.quic.cc-hystart { on | off } (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.cc.max-frame-loss <number>

tune.quic.be.cc.max-frame-loss <number>
tune.quic.fe.cc.max-frame-loss <number>

Définit la limite à partir de laquelle un cadre QUIC unique peut être marqué comme perdu. Si cette limite est dépassée, la connexion est considérée comme défaillante et est fermée immédiatement.

La valeur par défaut est 10.

tune.quic.max-frame-loss <number> (deprecated)

tune.quic.max-frame-loss <number> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.cc.max-win-size <size>

tune.quic.be.cc.max-win-size <size>
tune.quic.fe.cc.max-win-size <size>

Définit la taille maximale par défaut de la fenêtre du contrôleur de congestion pour une connexion QUIC unique, côté frontal ou backend. La valeur doit être indiquée sous forme d’entier, éventuellement suivie d’un suffixe « k », « m » ou « g ». Elle doit être comprise entre 10k et 4g.

Le multiplexeur QUIC utilise également la taille actuelle de la fenêtre de congestion pour déterminer s’il peut allouer de nouveaux tampons de flux lors de l’émission de données. En conséquence, la taille maximale de la fenêtre de congestion sert également de limite à cet allocateur.

La valeur par défaut est de 480 ko.

Voir également les options de liaison et de serveur « quic-cc-algo ».

tune.quic.frontend.default-max-window-size <size> (deprecated)

tune.quic.frontend.default-max-window-size <size> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.cc.reorder-ratio <0..100, in percent>

tune.quic.be.cc.reorder-ratio <0..100, in percent>
tune.quic.fe.cc.reorder-ratio <0..100, in percent>

Le ratio appliqué au seuil de réordonnancement des paquets calculé. Il peut déclencher une détection de perte de paquets élevée lorsqu’il est trop petit.

La valeur par défaut est 50.

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.max-idle-timeout <timeout>

tune.quic.be.max-idle-timeout <timeout>
tune.quic.fe.max-idle-timeout <timeout>

Définit le paramètre de transport QUIC max_idle_timeout sur le côté frontal ou backend. Il suit le format de temps HAProxy et s’exprime en millisecondes. Ce paramètre détermine la durée après laquelle une connexion est fermée silencieusement si elle est restée inactif pendant une période effective. Les deux extrémités s’appuient sur la même valeur négociée : - le minimum des deux paramètres si les deux ne sont pas nuls, - le maximum si seulement l’un des deux n’est pas nul, - si les deux paramètres sont nuls, cette fonctionnalité est désactivée.

Valeur par défaut : 30 s.

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.sec.glitches-threshold <number>

tune.quic.be.sec.glitches-threshold <number>
tune.quic.fe.sec.glitches-threshold <number>

Définit le seuil du nombre de glitchs par connexion, côté frontal ou backend, au-delà duquel la connexion est automatiquement interrompue. Cela permet de tuer automatiquement les connexions défaillantes sans avoir à écrire de règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, donc aucune occurrence ne provoquera la fermeture d’une connexion. Attention, certains clients QUIC peuvent occasionnellement provoquer quelques glitchs sur des connexions longues, donc toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les clients légèrement défaillants. Il est également possible de ne tuer les connexions que lorsque la consommation du CPU dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”.

Voir aussi : fc_glitches, tune.glitches.kill.cpu-usage

tune.quic.frontend.glitches-threshold <number> (deprecated)

tune.quic.frontend.glitches-threshold <number> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.fe.sec.retry-threshold <number>

tune.quic.fe.sec.retry-threshold <number>

Active dynamiquement la fonctionnalité Retry pour tous les écouteurs QUIC configurés dès que ce nombre de connexions en demi-ouverture est atteint. Une connexion en demi-ouverture est une connexion dont la négociation n’a pas encore été correctement terminée ni échouée. Pour être fonctionnel, ce paramètre nécessite que le secret de cluster soit défini ; sinon, il sera ignoré silencieusement (voir le paramètre « cluster-secret »). Ce paramètre sera également ignoré silencieusement si l’utilisation du Retry QUIC a été forcée (voir le paramètre « quic-force-retry »).

La valeur par défaut est 100.

Consultez https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 pour plus d’informations sur la réessai QUIC.

tune.quic.retry-threshold <number> (deprecated)

tune.quic.retry-threshold <number> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.fe.sock-per-conn { default-on | force-off }

tune.quic.fe.sock-per-conn { default-on | force-off }

Spécifie globalement la manière dont les connexions frontend QUIC utiliseront le socket pour les opérations receive/send. Les connexions peuvent partager le socket de l’écouteur ou chacune peut allouer son propre socket.

Valeur par défaut : « default-on ». Cette option permet d’attribuer une socket dédiée à chaque connexion QUIC. Elle est recommandée pour obtenir les meilleurs performances avec un trafic QUIC important. Elle est également la seule manière d’assurer correctement l’arrêt doux sans perte de données pour les connexions QUIC, et de gérer efficacement les erreurs temporaires lors de l’opération sendto(). Toutefois, cette option dépend de fonctionnalités avancées du pilote réseau UDP. Si la plateforme est jugée incompatible, HAProxy basculera automatiquement en mode « force-off » au démarrage. Veuillez noter que les écouteurs QUIC sur des ports privilégiés peuvent nécessiter d’être exécutés en tant qu’uid 0, ou une configuration spécifique au système pour autoriser l’uid cible à lier ces ports, comme des capacités système. Voir également la directive globale « setcap ».

La valeur « force-off » indique que les transferts QUIC se produiront sur le socket d’écoute partagé. Cette option peut constituer un bon compromis pour un trafic faible, car elle permet de réduire la consommation de descripteurs de fichiers. Toutefois, les performances ne seront pas optimales en raison d’une utilisation accrue du CPU si les écouteurs sont partagés entre de nombreux threads ou si un grand nombre de connexions QUIC peuvent être utilisées simultanément.

Ce paramètre s’applique conjointement à chaque option de liaison « quic-socket ». Si le mode « default-on » est utilisé dans le réglage global, il est activé pour chaque écouteur, sauf pour ceux configurés avec « quic-socket listener ». En revanche, si « force-off » est utilisé globalement, il s’applique à chaque instance d’écouteur, indépendamment de leur configuration individuelle.

tune.quic.socket-owner { connection | listener } (deprecated)

tune.quic.socket-owner { connection | listener } (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. La nouvelle option s’appelle “tune.quic.fe.sock-per-conn”, avec la valeur héritée « connection » correspondant à « default-on » et « listener » à « force-off ».

tune.quic.be.stream.data-ratio <0..100, in percent>

tune.quic.be.stream.data-ratio <0..100, in percent>
tune.quic.fe.stream.data-ratio <0..100, in percent>

Ce paramètre permet de configurer la limite maximale du nombre d’octets de données en transit sur chaque flux. Il est exprimé en pourcentage par rapport au paramètre de connexion QUIC rxbuf du flux, le résultat étant arrondi vers le haut à bufsize.

La valeur par défaut est 90. Cette valeur convient à la plupart des scénarios web courants, où les téléchargements sont effectués uniquement pour un ou quelques flux, tandis que les autres sont utilisés uniquement pour les téléchargements. Si la limite de connexion rxbuf reste à un niveau raisonnable, cela garantit qu’uniquement une partie des flux ouverts peut atteindre sa capacité maximale.

Dans le cas d’une application utilisant de nombreux flux de téléchargement en parallèle et souffrant d’un manque d’équité entre ces flux, il peut être pertinent de réduire ce ratio, afin d’améliorer l’équité et de réduire la bande passante par flux.

Voir aussi : “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”

tune.quic.frontend.stream-data-ratio <0..100, in percent> (deprecated)

tune.quic.frontend.stream-data-ratio  <0..100, in percent> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.stream.max-concurrent <number>

tune.quic.be.stream.max-concurrent <number>
tune.quic.fe.stream.max-concurrent <number>

Du côté frontal, cette valeur est utilisée comme valeur du paramètre de transport initial_max_streams_bidi annoncé. Elle est imposée comme nombre maximal de flux bidirectionnels que le pair distant sera autorisé à ouvrir simultanément pendant la durée de vie de la connexion. Cela limite effectivement le nombre de requêtes clientes HTTP/3 simultanées.

Valeur par défaut : 100. Notez que si vous la réduisez, cela peut limiter les capacités de mise en mémoire tampon des flux en réception, ce qui entraînerait un débit de téléchargement médiocre. Cette situation peut être corrigée en augmentant le paramètre de connexion QUIC stream rxbuf.

Du côté backend, cela est appliqué localement par HAProxy afin de limiter le nombre de requêtes simultanées multiplexées sur une seule connexion. Ce paramètre peut être restreint davantage par le contrôle de flux du pair. Il peut être nécessaire de réduire la valeur par défaut de 100 afin d’améliorer la réactivité d’un site, au prix d’un nombre plus élevé de connexions backend ouvertes. De même que du côté frontal, ce paramètre influence directement la capacité de tamponnage en réception, mais cette fois-ci en limitant la capacité de téléchargement HTTP. La taille du tampon de réception des flux QUIC peut être augmentée lorsqu’on traite principalement des réponses HTTP dont la taille dépasse “tune.bufsize”.

Voir aussi : “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.fe.stream.max-total <number>

tune.quic.fe.stream.max-total <number>

Définit le nombre maximal de requêtes pouvant être traitées par une connexion QUIC unique. Dès que ce seuil est atteint, la connexion est fermée de manière propre. Dans HTTP/3, cela se traduit par un cadre GOAWAY. La connexion est définitivement fermée une fois toutes les transmissions restantes terminées.

Ce paramètre est appliqué comme une limite stricte sur la connexion via le mécanisme de contrôle de flux QUIC. Si un pair la violer, la connexion sera immédiatement fermée.

Ce paramètre peut être utilisé pour obliger les clients à ouvrir de nouvelles connexions de temps à autre afin de poursuivre l’émission de requêtes et éviter de maintenir des connexions trop longtemps. Toutefois, des valeurs faibles augmenteront la latence du côté client, ainsi que la consommation CPU des deux côtés en raison des échanges TLS.

La valeur par défaut est 0, ce qui signifie qu’aucune limite spécifique n’est appliquée, en dehors de la limitation imposée par le protocole QUIC (2^60, soit plus d’un milliard de milliards).

tune.quic.frontend.max-streams-bidi <number> (deprecated)

tune.quic.frontend.max-streams-bidi <number> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.stream.rxbuf <size>

tune.quic.be.stream.rxbuf <size>
tune.quic.fe.stream.rxbuf <size>

Ce paramètre constitue la limite maximale stricte du nombre d’octets de données en transit sur une connexion QUIC au niveau du frontal. Il est réutilisé comme valeur du paramètre de transport initial_max_data. Il influence directement le débit de téléchargement du pair, en fonction de la latence et de la consommation mémoire par connexion dans HAProxy.

Par défaut, la valeur est définie à 0, ce qui indique qu’elle doit être générée automatiquement comme le produit de max-concurrent et de bufsize. Cette valeur peut être augmentée, par exemple, si une application backend dépend de transferts massifs sur des réseaux à forte latence.

Voir aussi : “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.frontend.max-data-size <size> (deprecated)

tune.quic.frontend.max-data-size <size> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.tx.pacing { on | off }

tune.quic.be.tx.pacing { on | off }
tune.quic.fe.tx.pacing { on | off }

Active (‘on’) ou désactive (‘off’) le support du réglage du débit pour l’émission QUIC. Par défaut, il est activé. Le but du réglage du débit est de lisser l’émission des données afin de réduire les pertes réseau. Dans la plupart des scénarios, il améliore significativement le débit en évitant les retransmissions. Toutefois, il peut être utile de le désactiver sur des réseaux présentant des caractéristiques de latence très élevées bandwidth/low afin d’éviter des délais indésirables et de réduire la consommation CPU.

Voir également les options de liaison et de serveur « quic-cc-algo ».

tune.quic.disable-tx-pacing (deprecated)

tune.quic.disable-tx-pacing (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.be.tx.udp-gso { on | off }

tune.quic.be.tx.udp-gso { on | off }
tune.quic.fe.tx.udp-gso { on | off }

Active (‘on’) ou désactive (‘off’) la prise en charge du GSO UDP pour l’émission QUIC. Par défaut, cette fonctionnalité est activée. Ce mécanisme du noyau permet d’émettre plusieurs datagrammes en une seule appel système, ce qui est plus efficace pour les transferts volumineux. Il peut être utile de la désactiver sur recommandation d’un développeur lorsqu’une anomalie est suspectée lors de l’émission.

tune.quic.disable-udp-gso (deprecated)

tune.quic.disable-udp-gso (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.listen { on | off }

tune.quic.listen { on | off }

Désactive le protocole de transport QUIC du côté frontal. Tous les écouteurs QUIC seront toujours créés, mais ils n’écouteront pas les datagrammes entrants. Ainsi, aucun trafic QUIC ne sera traité par HAProxy du côté frontal.

Valeur par défaut : « on ». Si un problème est suspecté avec le trafic QUIC, cette option permet de basculer facilement les écouteurs QUIC sans modifier chaque ligne de configuration individuellement.

Voir également l’extraction d’échantillon “quic_enabled”.

tune.quic.mem.tx-max <size>

tune.quic.mem.tx-max <size>

Définit la quantité maximale de mémoire utilisable par la pile QUIC au niveau du transport pour l’émission. Cela sert à la fois de limite aux octets en vol et aux tampons de sortie du multiplexeur. Notez que, afin d’éviter les conflits entre threads, cette limite n’est pas strictement appliquée, ce qui permet qu’elle soit dépassée occasionnellement. En outre, chaque connexion pourra toujours utiliser une fenêtre d’au moins 2 datagrammes, aussi une valeur appropriée de maxconn doit-elle être utilisée en complément.

tune.quic.frontend.max-tx-mem <size> (deprecated)

tune.quic.frontend.max-tx-mem <size> (deprecated)

Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.

tune.quic.zero-copy-fwd-send { on | off }

tune.quic.zero-copy-fwd-send { on | off }

Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur QUIC. Il est activé par défaut.

Voir aussi : tune.disable-zero-copy-forwarding

tune.renice.runtime <number>

tune.renice.runtime <number>

Cette option de configuration prend une valeur comprise entre -20 et 19. Elle applique une priorité de planification telle que documentée dans man 2 setpriority. Cette priorité est appliquée après l’analyse de la configuration, ce qui signifie qu’elle ne s’applique qu’au processus worker ou au processus autonome. Elle est généralement configurée pour attribuer une priorité supérieure à celle d’un processus effectuant l’analyse de configuration (tune.renice.startup).

Voir aussi : tune.renice.startup

tune.renice.startup <number>

tune.renice.startup <number>

Cette option de configuration prend une valeur comprise entre -20 et 19. Elle applique une priorité de planification telle que documentée dans man 2 setpriority. Cette priorité est appliquée avant l’application du reste de la configuration, ce qui peut être utile si vous souhaitez réduire la priorité pendant l’analyse de la configuration. Cette priorité est appliquée au processus autonome ou au worker avant l’analyse de la configuration. Une fois la configuration analysée, la priorité précédente est restaurée, sauf si tune.renice.runtime est utilisé.

Voir aussi : tune.renice.runtime

tune.rcvbuf.backend <size>

tune.rcvbuf.backend  <size>
tune.rcvbuf.frontend <size>

Pour la taille du tampon de réception du socket noyau sur les sockets non connectés, jusqu’à cette taille. Cela peut être utilisé avec QUIC en mode écouteur et avec le transfert de journaux sur le frontal. Les tampons système par défaut peuvent parfois être trop petits pour les sockets recevant une forte charge de trafic agrégé, entraînant des pertes et éventuellement des retransmissions (dans le cas de QUIC), ce qui peut ralentir la mise en place des connexions sous une charge élevée. La valeur est exprimée en octets, appliquée à chaque socket. En mode écouteur, les sockets sont partagés entre toutes les connexions, et le nombre total de sockets dépend de la valeur « shards » de la ligne « bind ». Il n’existe pas de valeur optimale ; une bonne valeur correspond au produit de la taille attendue par connexion multipliée par le nombre attendu de connexions. Le noyau peut réduire les valeurs trop grandes. Voir également “tune.rcvbuf.client” et “tune.rcvbuf.server” pour leurs équivalents sur les sockets connectés, ainsi que “tune.sndbuf.backend” et “tune.sndbuf.frontend” pour le paramètre d’envoi.

tune.rcvbuf.client <size>

tune.rcvbuf.client <size>
tune.rcvbuf.server <size>

Force la taille du tampon de réception socket du noyau du côté client ou serveur à la valeur spécifiée, en octets. Cette valeur s’applique à tous les frontaux et backends TCP/HTTP. Elle devrait normalement jamais être définie, et la taille par défaut (0) permet au noyau d’ajuster automatiquement cette valeur en fonction de la mémoire disponible. Toutefois, il peut parfois être utile de la définir à des valeurs très faibles (par exemple 4096) afin de réduire l’utilisation de la mémoire noyau en empêchant celui-ci de tamponner des quantités trop importantes de données reçues. Des valeurs plus faibles augmentent toutefois significativement l’utilisation du CPU.

tune.recv_enough <size>

tune.recv_enough <size>

HAProxy utilise certains indicateurs pour détecter qu’une lecture courte indique la fin des tampons de socket. L’un d’eux est qu’une lecture retourne plus de <recv_enough> octets, valeur par défaut de 10136 (7 segments de 1448 chacun). Cette valeur par défaut peut être modifiée par ce paramètre afin de mieux gérer les charges de travail comportant de nombreuses messages courts, comme les sessions telnet ou SSH.

tune.ring.queues <number>

tune.ring.queues <number>

Définit le nombre de files d’écriture situées devant les tampons circulaires. Cela peut influer sur l’utilisation du CPU lors des sessions de débogage, et une valeur trop faible ou trop élevée peut avoir un impact important. La valeur optimale a été déterminée expérimentalement par les développeurs, et il n’y a aucune raison de la modifier sauf si explicitement indiqué afin de résoudre des problèmes spécifiques. Ce paramètre ne doit pas être conservé dans la configuration après une mise à jour de version, car sa valeur optimale peut évoluer au fil du temps.

tune.runqueue-depth <number>

tune.runqueue-depth <number>

Définit le nombre maximal de tâches pouvant être traitées simultanément lors de l’exécution des tâches. La valeur par défaut dépend du nombre de threads, mais se situe entre 35 et 280, des valeurs qui tendent à offrir les débits de requêtes les plus élevés et les latences les plus faibles. Augmenter cette valeur peut entraîner une augmentation de la latence lors du traitement de I/Os, tandis qu’une valeur trop faible peut engendrer un surcoût. Les nombres élevés de threads bénéficient de valeurs plus faibles. Lors de l’expérimentation avec des valeurs beaucoup plus élevées, il peut être utile d’activer également tune.sched.low-latency et éventuellement tune.fd.edge-triggered afin de limiter la latence maximale au niveau le plus bas possible.

tune.sched.low-latency { on | off }

tune.sched.low-latency { on | off }

Active (‘on’) ou désactive (‘off’) le planificateur de tâches à faible latence. Par défaut, HAProxy traite les tâches de plusieurs classes une classe à la fois, car c’est la méthode la plus efficace. Toutefois, lorsqu’on utilise de grandes valeurs pour tune.runqueue-depth, cela peut avoir un effet mesurable sur la latence des requêtes ou des connexions. Lorsque ce paramètre à faible latence est activé, les tâches des classes de priorité inférieure sont toujours exécutées avant les autres, si elles existent. Cela permet de réduire la latence maximale subie par de nouvelles requêtes ou connexions au milieu d’un trafic massif, au prix d’un impact plus élevé sur ce trafic important. Pour une utilisation régulière, il est préférable de le laisser désactivé. La valeur par défaut est off.

tune.sndbuf.backend <size>

tune.sndbuf.backend  <size>
tune.sndbuf.frontend <size>

Pour la taille de la mémoire tampon d’envoi du socket noyau sur les sockets non connectés, jusqu’à cette taille. Cela peut être utilisé pour la journalisation UNIX et UDP côté backend, ainsi que pour QUIC en mode écouteur côté frontal. Les tampons système par défaut peuvent parfois être trop petits pour les sockets partagés entre de nombreuses connexions (ou émetteurs de journaux), entraînant des pertes et éventuellement des retransmissions, ce qui ralentit la mise en place de nouvelles connexions sous fort trafic. La valeur est exprimée en octets, appliquée à chaque socket. En mode écouteur, les sockets sont partagés entre toutes les connexions, et le nombre total de sockets dépend de la valeur « shards » de la ligne « bind ». Il n’existe pas de valeur optimale ; une bonne valeur correspond au produit de la taille attendue par connexion multipliée par le nombre attendu de connexions. Le noyau peut réduire les valeurs trop grandes. Voir également “tune.sndbuf.client” et “tune.sndbuf.server” pour leurs équivalents sur les sockets connectés, ainsi que “tune.rcvbuf.backend” et “tune.rcvbuf.frontend” pour le paramètre de réception.

tune.sndbuf.client <size>

tune.sndbuf.client <size>
tune.sndbuf.server <size>

Force la taille du tampon d’envoi socket du noyau du côté client ou serveur à la valeur spécifiée en octets. Cette valeur s’applique à tous les frontaux et backends TCP/HTTP. Elle devrait normalement ne jamais être définie, et la taille par défaut (0) permet au noyau d’ajuster automatiquement cette valeur en fonction de la mémoire disponible. Toutefois, il peut parfois être utile de la définir à des valeurs très faibles (par exemple 4096) afin de réduire l’utilisation de la mémoire noyau en empêchant celui-ci de tamponner des quantités trop importantes de données reçues. Des valeurs plus faibles augmentent toutefois significativement l’utilisation du CPU. Un autre cas d’usage consiste à éviter les délais d’expiration d’écriture avec des clients extrêmement lents, en empêchant le noyau d’attendre qu’une grande partie du tampon soit lue avant de notifier à nouveau HAProxy. Voir également tune.notsent-lowat.client et tune.notsent-lowat.server pour des paramètres plus efficaces permettant de contrôler plus finement l’utilisation de la mémoire et la réactivité sous Linux sans nuire aux performances.

tune.ssl.cachesize <number>

tune.ssl.cachesize <number>

Définit la taille du cache global des sessions SSL, en nombre de blocs. Un bloc est suffisamment grand pour contenir une session encodée sans certificat de pair. Une session encodée avec certificat de pair est stockée dans plusieurs blocs, selon la taille du certificat de pair. Un bloc utilise environ 200 octets de mémoire (selon le calcul sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE utilisé pour la fonction shctx_init). La valeur par défaut peut être imposée au moment de la compilation, sinon elle vaut 20000. Lorsque le cache est plein, les entrées les moins utilisées sont supprimées et réaffectées. Des valeurs plus élevées réduisent la fréquence de cette suppression, donc le nombre de négociations SSL coûteuses en ressources CPU, en garantissant que toutes les utilisations conservent leur session aussi longtemps que possible. Toutes les entrées sont pré-allouées au démarrage. Définir cette valeur à 0 désactive le cache des sessions SSL.

tune.ssl.capture-buffer-size <number>

tune.ssl.capture-buffer-size <number>
tune.ssl.capture-cipherlist-size <number> (deprecated)

Définit la taille maximale de la mémoire tampon utilisée pour capturer la liste des chiffres du client hello, la liste des extensions, la liste des courbes elliptiques et les formats de points de courbe elliptique. Si la valeur est 0 (valeur par défaut), la capture est désactivée ; sinon, une mémoire tampon est allouée pour chaque connexion SSL/TLS.

tune.ssl.certificate-compression { auto | off }

tune.ssl.certificate-compression { auto | off }

Ce paramètre permet de configurer la prise en charge de la compression des certificats, une extension (RFC 8879) du TLS 1.3.

Lorsqu’il est défini sur « auto », la valeur par défaut de la bibliothèque TLS est utilisée.

Avec « off », HAProxy tente de désactiver explicitement le support de la fonctionnalité. HAProxy ne tentera plus d’envoyer des certificats compressés ni d’accepter des certificats compressés.

Configure les côtés backend et frontal.

Ce mot-clé est pris en charge par OpenSSL >= 3.2.0.

La valeur par défaut est auto.

tune.ssl.default-dh-param <number>

tune.ssl.default-dh-param <number>

Définit la taille maximale des paramètres de Diffie-Hellman utilisés pour générer la clé ephemeral/temporary en cas d’échange de clés DHE. La taille finale tentera de correspondre à la taille de la clé RSA (ou DSA) du serveur (par exemple, une clé DH temporaire de 2048 bits pour une clé RSA de 2048 bits), mais ne dépassera pas cette valeur maximale. Seules les valeurs égales ou supérieures à 1024 sont autorisées. Des valeurs plus élevées augmenteront la charge CPU, et les valeurs supérieures à 1024 bits ne sont pas prises en charge par les clients Java 7 et antérieurs. Cette valeur n’est pas utilisée si des paramètres de Diffie-Hellman statiques sont fournis directement dans le fichier de certificat ou à l’aide de la directive ssl-dh-param-file. Si ni default-dh-param ni ssl-dh-param-file n’est défini, et si le fichier PEM du serveur d’un frontal donné ne spécifie pas ses propres paramètres DH, alors les chiffres DHE seront indisponibles pour ce frontal.

tune.ssl.force-private-cache

tune.ssl.force-private-cache

Cette option désactive le partage du cache de session SSL entre tous les processus. Elle ne devrait normalement pas être utilisée, car elle entraîne de nombreuses renegotiations du fait que les clients accèdent à un processus aléatoire. Toutefois, elle peut être nécessaire sur certains systèmes d’exploitation où aucune méthode de synchronisation du cache SSL n’est disponible. Dans ce cas, l’ajout d’une première couche de répartition de charge basée sur un hachage avant la couche SSL peut limiter l’impact de l’absence de partage de session.

tune.ssl.hard-maxrecord <number>

tune.ssl.hard-maxrecord <number>

Définit le nombre maximal d’octets passés à SSL_write() à tout moment. La valeur par défaut 0 signifie qu’aucune limite n’est appliquée. Contrairement à tune.ssl.maxrecord, ce paramètre ne sera pas ajusté dynamiquement. Des enregistrements plus petits peuvent réduire le débit, mais peuvent être nécessaires lors de la gestion de clients à faible empreinte.

tune.ssl.keylog { on | off }

tune.ssl.keylog { on | off }

Cette option active la journalisation des clés TLS. Elle doit être utilisée avec précaution, car elle consomme davantage de mémoire par session SSL et peut réduire les performances. Elle est désactivée par défaut.

Ces extractions d’échantillon doivent être utilisées pour générer le fichier SSLKEYLOGFILE nécessaire pour décrypter le trafic avec Wireshark.

https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html

La variable SSLKEYLOG est une série de lignes formatées de cette manière :

<Label> <space> <ClientRandom> <space> <Secret>

Le ClientRandom est fourni par l’extraction d’échantillon %[ssl_fc_client_random,hex], le secret et l’étiquette peuvent être trouvés dans le tableau ci-dessous. Vous devez générer un fichier SSLKEYLOGFILE contenant toutes les étiquettes de ce tableau.

Les extraits d’échantillons suivants sont des chaînes hexadécimales et n’ont pas besoin d’être convertis.

  SSLKEYLOGFILE Label             |  Sample fetches for the Secrets
  --------------------------------|-----------------------------------------
  CLIENT_EARLY_TRAFFIC_SECRET     |  %[ssl_xx_client_early_traffic_secret]
  CLIENT_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_client_handshake_traffic_secret]
  SERVER_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_server_handshake_traffic_secret]
  CLIENT_TRAFFIC_SECRET_0         |  %[ssl_xx_client_traffic_secret_0]
  SERVER_TRAFFIC_SECRET_0         |  %[ssl_xx_server_traffic_secret_0]
  EXPORTER_SECRET                 |  %[ssl_xx_exporter_secret]
  EARLY_EXPORTER_SECRET           |  %[ssl_xx_early_exporter_secret]

Ces récupérations existent côté frontal (fc) ou côté backend (bc) ; remplacez « xx » par « fc » ou « bc » pour utiliser le bon côté.

Cela n’est disponible qu’avec OpenSSL 1.1.1, et est utile avec la session TLS1.3.

Si vous souhaitez générer le contenu d’un fichier SSLKEYLOGFILE avec TLS < 1.3, vous n’avez besoin que de cette ligne :

CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]

Une journalisation complète de clés pourrait être générée avec un format de journalisation de cette manière, même si cela n’est pas idéal pour syslog :

log-format "CLIENT_EARLY_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_early_traffic_secret]\n
            CLIENT_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_handshake_traffic_secret]\n
            SERVER_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_server_handshake_traffic_secret]\n
            CLIENT_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_client_traffic_secret_0]\n
            SERVER_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_server_traffic_secret_0]\n
            EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_exporter_secret]\n
            EARLY_EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_early_exporter_secret]"

HAProxy fournit également les formats ci-dessus sous forme de variables d’environnement prédéfinies, pouvant être utilisées directement dans une directive « log-format » :

$HAPROXY_KEYLOG_FC_LOG_FMT   frontend (client-facing) connection keys
$HAPROXY_KEYLOG_BC_LOG_FMT   backend (server-facing) connection keys

tune.ssl.keyupdate-rate-limit <limit>

tune.ssl.keyupdate-rate-limit <limit>

Limite la quantité de KeyUpdate par seconde que nous acceptons à <limit> avant de la considérer comme une inondation, et de tuer la connexion. Le traitement des KeyUpdate est coûteux en ressources CPU, et il n’y a peu de raisons de recevoir un grand nombre de ces messages. Une valeur de « 0 » désactive la limitation de débit. La valeur par défaut est 100.

tune.ssl.lifetime <timeout>

tune.ssl.lifetime <timeout>

Définit la durée pendant laquelle une session SSL mise en cache peut rester valide. Cette durée est exprimée en secondes et vaut 300 par défaut (5 minutes). Il est important de comprendre qu’elle ne garantit pas que les sessions resteront actives aussi longtemps, car si la mémoire tampon est pleine, les sessions inactives les plus anciennes seront supprimées, même si leur durée de vie configurée n’est pas atteinte. L’utilité réelle de ce paramètre est de prévenir l’utilisation de sessions trop longtemps.

tune.ssl.maxrecord <number>

tune.ssl.maxrecord <number>

Définit la quantité maximale d’octets transmis à SSL_write() au début du transfert de données. Valeur par défaut 0 signifie qu’aucune limite n’est appliquée. Au-delà de SSL/TLS, le client ne peut décrypter les données qu’une fois qu’il a reçu un enregistrement complet. Avec de grands enregistrements, cela signifie que les clients peuvent devoir télécharger jusqu’à 16 ko de données avant de commencer à les traiter. Limiter cette valeur peut améliorer les temps de chargement des pages sur les navigateurs situés sur des réseaux à haute latence ou à faible bande passante. Il est recommandé de trouver des valeurs optimales qui tiennent dans 1 ou 2 segments TCP (généralement 1448 octets sur Ethernet avec les horodatages TCP activés, ou 1460 lorsque les horodatages sont désactivés), en tenant compte de l’overhead ajouté par SSL/TLS. Des valeurs typiques de 1419 et 2859 ont donné de bons résultats lors des tests. Utilisez « strace -e trace=write » pour déterminer la meilleure valeur. HAProxy passera automatiquement à ce paramètre après avoir détecté une connexion inactif (voir tune.idletimer ci-dessus). Voir également tune.ssl.hard-maxrecord.

tune.ssl.ssl-ctx-cache-size <number>

tune.ssl.ssl-ctx-cache-size <number>

Définit la taille du cache utilisé pour stocker les certificats générés, sur <number> entrées. Il s’agit d’un cache LRU. Comme la génération dynamique d’un certificat SSL est coûteuse, ceux-ci sont mis en mémoire tampon. La taille du cache par défaut est fixée à 1000 entrées.

tune.streams-elasticity <number>

tune.streams-elasticity <number>

Définit un pourcentage cible de flux par connexion frontale par rapport au nombre maximum de connexions simultanées (maxconn) lorsque toutes les connexions sont établies. Ce métrique s’applique aux protocoles multiplexés comme HTTP/2 ou QUIC, où chaque connexion peut recevoir plusieurs flux. Au moins un flux est toujours garanti, donc le pourcentage doit être d’au moins 100 %. Pendant la mise en place de la connexion, HAProxy annonce dynamiquement des flux supplémentaires jusqu’à la limite configurée, tout en maintenant le rapport cible. À l’établissement de la connexion, chaque connexion frontale reçoit au moins un flux ; les flux supplémentaires sont attribués selon le pourcentage cible et les limites de flux configurées. Cela garantit une allocation de flux efficace dans des conditions de charge variables (plus de flux en cas de faible charge, moins de flux en cas de forte charge).

Les sites très dynamiques, avec de nombreux objets par page, bénéficient de ratios élevés, permettant un grand nombre de flux par connexion. Les sites utilisant en moyenne moins de flux (WebSocket, code d’application) peuvent préférer des ratios plus faibles, proches de 120 ou 150 (20 à 50 % de flux supplémentaires par rapport aux connexions), afin d’éviter un nombre excessif de flux sous charge soutenue.

La valeur par défaut est 0, ce qui signifie qu’aucune restriction n’est appliquée à ce niveau, de sorte que seules les configurations H2 et QUIC s’appliquent (avec le paramètre par défaut de 100 flux par connexion, ce qui correspond à 10000 %). Ce paramètre reste recommandé pour les déploiements de petite taille (maxconn d’environ mille). Les configurations de taille modérée (quelques milliers à dizaines de milliers de connexions) fixent généralement ce ratio entre 1000 et 5000, permettant 10 à 50 flux par connexion en charge maximale. Les déploiements à grande échelle (centaines de milliers à millions de connexions) peuvent utiliser des valeurs plus faibles (120 à 200) afin de supporter en moyenne 1,2 à 2 flux par connexion en charge maximale.

Contrairement à HTTP/2, QUIC est capable d’ajuster dynamiquement le nombre de flux simultanés pendant la durée de vie de la connexion. Toutefois, le contrôle de flux QUIC est plus strict que celui de HTTP/2, aussi est-il préférable, lors de son utilisation, de spécifier des valeurs suffisamment élevées pour éviter une latence supplémentaire sur la connexion. Il existe également une limitation pour les écouteurs QUIC avec 0-RTT activé. Dans ce cas, la valeur initiale annoncée au pair ignorera l’élasticité des flux et se fondera uniquement sur le paramètre “tune.quic.fe.stream.max-concurrent”. Toutefois, le principe d’élasticité des flux restera effectif au-delà de cette annonce initiale pendant la durée de vie de la connexion.

Surveiller le nombre total de flux actifs sur les backends, y compris les files d’attente, constitue un indicateur pratique de charge cible durable et aide à éviter le surdimensionnement.

tune.stick-counters <number>

tune.stick-counters <number>

Définit le nombre de compteurs de persistance pouvant être suivis simultanément par une connexion ou une requête via les actions “track-sc*” dans les règles “tcp-request” ou “http-request”. La valeur par défaut est définie au moment de la compilation par la macro MAX_SESS_STK_CTR, et vaut 3. Il est possible de modifier cette valeur et d’ignorer celle fournie au moment de la compilation, mais celle-ci ne peut pas dépasser 100. L’augmentation de cette valeur peut être nécessaire lors du portage de configurations complexes vers HAProxy, mais les utilisateurs sont avertis des coûts associés : chaque entrée consomme 16 octets par connexion et 16 octets par requête, toutes lesquelles doivent être allouées et initialisées à zéro pour toutes les requêtes, même lorsque non utilisées. Ainsi, une valeur de 10 entraîne une augmentation de la consommation mémoire par requête de 320 octets et provoque l’effacement de cette mémoire pour chaque requête, ce qui a un impact mesurable sur le processeur. À l’inverse, lorsque aucune règle “track-sc” n’est utilisée, la valeur peut être réduite (0 étant autorisé pour désactiver entièrement les compteurs de persistance).

tune.takeover-other-tg-connections <value>

tune.takeover-other-tg-connections <value>

Par défaut, nous n’essaierons pas d’utiliser des connexions inactives provenant d’autres groupes de threads. Ce comportement peut toutefois être modifié. Les valeurs valides pour <value> sont : « none », la valeur par défaut, si elle est utilisée, aucune tentative ne sera faite pour utiliser des connexions inactives provenant d’autres groupes de threads, « restricted », dans lequel nous n’essaierons de récupérer une connexion inactives d’un autre groupe de thread que si nous utilisons des protocoles ne pouvant pas créer de nouvelles connexions, tels que le HTTP inversé, ainsi qu’en cas d’utilisation de strict-maxconn, ou « full », dans lequel nous chercherons toujours dans les autres groupes de threads des connexions inactives. Notez que l’utilisation de connexions provenant d’autres groupes de threads peut entraîner des pertes de performance, donc cette option ne doit être utilisée que si nécessaire. Notez que ce comportement est désormais contrôlé par tune.idle-pool.shared, et ce mot-clé est conservé uniquement pour assurer la compatibilité avec les configurations anciennes, et sera déprécié.

tune.vars.global-max-size <size>

tune.vars.global-max-size <size>
tune.vars.proc-max-size <size>
tune.vars.reqres-max-size <size>
tune.vars.sess-max-size <size>
tune.vars.txn-max-size <size>

Ces cinq paramètres permettent de gérer la quantité maximale de mémoire utilisée par le système de variables. « global » limite la quantité totale de mémoire disponible pour toutes les portées. « proc » limite la mémoire pour la portée processus, « sess » pour la portée session, « txn » pour la portée transaction, et « reqres » pour la mémoire allouée à chaque traitement de requête ou réponse. La comptabilité mémoire est hiérarchique, ce qui signifie que les limites plus grossières incluent les limites plus fines : « proc » inclut « sess », « sess » inclut « txn », et « txn » inclut « reqres ».

Par exemple, lorsque “tune.vars.sess-max-size” est limité à 100, “tune.vars.txn-max-size” et “tune.vars.reqres-max-size” ne peuvent pas dépasser 100 non plus. Si nous créons une variable “txn.var” contenant 100 octets, tout l’espace disponible est utilisé. Notez qu’un dépassement des limites en temps d’exécution ne provoque pas de message d’erreur, mais les valeurs pourraient être tronquées ou corrompues. Veillez donc à prévoir avec précision la quantité d’espace nécessaire pour stocker toutes vos variables.

tune.zlib.memlevel <number>

tune.zlib.memlevel <number>

Définit le paramètre memLevel lors de l’initialisation de zlib pour chaque flux. Il détermine la quantité de mémoire à allouer pour l’état interne de compression. Une valeur de 1 utilise la mémoire minimale mais est lente et réduit le taux de compression, tandis qu’une valeur de 9 utilise la mémoire maximale pour une vitesse optimale. Peut être une valeur comprise entre 1 et 9. La valeur par défaut est 8.

tune.zlib.windowsize <number>

tune.zlib.windowsize <number>

Définit la taille de fenêtre (la taille de la mémoire tampon d’historique) en tant que paramètre d’initialisation de zlib pour chaque flux. Des valeurs plus élevées de ce paramètre entraînent une meilleure compression au détriment de l’utilisation mémoire. Peut être une valeur comprise entre 8 et 15. La valeur par défaut est 15.

3.3. Débogage

anonkey <key>

anonkey <key>

Cela définit la clé d’anonymisation globale à <key>, qui doit être un nombre de 32 bits compris entre 0 et 4294967295. Il s’agit de la clé utilisée par défaut par les commandes en ligne de commande lorsque le mode anonymisé est activé. Cette clé peut également être définie en temps réel à partir de la commande en ligne de commande « set anon global-key ». Voir également l’argument de ligne de commande “-dC” dans le manuel de gestion.

debug.counters { on | off }

debug.counters { on | off }

Active (‘on’) ou désactive (‘off’) la mise à jour des compteurs d’événements dans le code. Ces compteurs sont ceux rapportés sous le type “CNT” dans la commande CLI “debug counters”. Ces compteurs ne sont disponibles que si le code a été compilé avec DEBUG_COUNTERS défini à une valeur égale ou supérieure à 1. Avec la valeur 1, les compteurs ne sont pas mis à jour par défaut (“debug.counters off”), et avec la valeur 2, ils sont mis à jour par défaut (“debug.counters on”). Il n’existe normalement aucune raison de modifier ce paramètre, sauf si une demande est formulée par un développeur, ou si l’on soupçonne une consommation anormale de CPU (auquel cas, une remontée aux développeurs est nécessaire, accompagnée d’un dump des compteurs). Il est également possible de modifier cet état en temps réel à l’aide de la commande CLI “debug counters”. Veuillez consulter le manuel de gestion.

force-cfg-parser-pause <timeout>

force-cfg-parser-pause <timeout>

Cette commande met en pause le parseur de configuration pendant <timeout> millisecondes. Cela est utile en développement ou pour tester les délais d’expiration des scripts d’initialisation, notamment pour simuler un rechargement très long. Elle nécessite que l’option expose-experimental-directives soit activée.

<timeout> est la valeur de délai d’expiration spécifiée en millisecondes par défaut, mais peut être exprimée dans toute autre unité si le nombre est suivi de l’unité, comme expliqué en haut de ce document.

Exemple :

global
    expose-experimental-directives
    force-cfg-parser-pause 10s

quick-exit

quick-exit

Cela accélère la sortie du processus ancien lors d’un rechargement en ignorant la libération des objets mémoire et des écouteurs, puisque tous ces éléments sont récupérés par le système d’exploitation à la mort du processus. Les gains sont négligeables (de l’ordre de quelques centaines de millisecondes au maximum, pour des configurations très volumineuses). L’utilisation principale concerne en réalité le cas où un bug est détecté dans le code de deinit(), car cela permet de le contourner. Il est préférable de ne pas utiliser cette option sauf instruction explicite des développeurs.

quiet

quiet

N’affichez aucun message lors du démarrage. Cela équivaut à l’argument de ligne de commande “-q”.

warn-blocked-traffic-after <time>

warn-blocked-traffic-after <time>

Cela permet d’ajuster le délai après lequel une tâche bloquée, empêchant le trafic, déclenche l’envoi d’un avertissement sur la sortie d’erreur standard. Le délai est exprimé en millisecondes et vaut 100 ms par défaut. Les valeurs autorisées doivent être comprises entre 1 ms et 1000 ms inclus. Des valeurs plus faibles provoquent fréquemment des avertissements, tandis que des valeurs plus élevées les déclenchent rarement. Le watchdog tue quand même une tâche en erreur qui ne répond pas deux fois pendant une seconde, aussi un délai d’avertissement de 1000 ms ne déclenchera normalement aucun avertissement. Il est recommandé de garder des valeurs comprises entre 10 et 100 ms afin de détecter des anomalies de configuration pouvant dégrader l’expérience utilisateur, entraînant des temps de réponse longs ou des saccades lors des sessions interactives. Par exemple, une fonction Lua d’extraction mal conçue effectuant des calculs lourds, ou un fichier de carte map_reg ou map_regm très volumineux avec un coût d’évaluation élevé, peuvent provoquer de tels problèmes. Pour comparaison, une poignée de main TLS peut consommer entre un et deux millisecondes, et la compression d’un tampon de réponse HTTP de 16 ko est d’environ une milliseconde. La sortie contient un dump de thread de la tâche défaillante, avec un backtrace et certains contextes qui aident à identifier où le temps est consommé.

zero-warning

zero-warning

Lorsque cette option est définie, HAProxy refusera de démarrer si un avertissement a été émis lors du traitement de la configuration et de son application. Cela signifie que les avertissements concernant des combinaisons de paramètres incorrectes, les avertissements relatifs à des limites très élevées qui ne pouvaient pas être appliquées, etc., entraînent une sortie avec erreur au démarrage. Quelques avertissements tardifs au démarrage ne peuvent pas être détectés par cette option, tels que l’échec de suppression des groupes supplémentaires lors du changement d’ID de groupe en mode “daemon” ou “master-worker”, ou l’échec de marquer le processus comme dumpable après le fork(). Cette option ne détecte pas les avertissements émis en cours d’exécution. Il est fortement recommandé de définir cette option sur les configurations qui ne sont pas fréquemment modifiées, car elle aide à détecter des erreurs subtiles et à maintenir la configuration propre et compatible à long terme. Notez que “haproxy -c” signalera également des erreurs dans ce cas. Cette option est équivalente à l’argument en ligne de commande “-dW”.

3.4. Ajustement du client HTTP

HTTPClient est une bibliothèque HTTP interne, pouvant être utilisée par divers sous-systèmes, par exemple dans des scripts LUA. HTTPClient n’est pas utilisé dans le chemin de données, autrement dit, il n’a rien à voir avec le trafic HTTP passant par HAProxy.

httpclient.resolvers.disabled <on|off>

httpclient.resolvers.disabled <on|off>

Désactive la résolution DNS du httpclient. Empêche la création de la section « default » des résolveurs.

Valeur par défaut : désactivé.

httpclient.resolvers.id <resolvers id>

httpclient.resolvers.id <resolvers id>

Cette option définit la section resolvers avec laquelle le httpclient tentera de résoudre.

L’option par défaut est l’identifiant de résolveur « default ». Par défaut, si cette option n’est pas utilisée, la résolution est simplement désactivée si la section n’est pas trouvée.

Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée si elle échoue à charger.

httpclient.resolvers.prefer <ipv4|ipv6>

httpclient.resolvers.prefer <ipv4|ipv6>

Cette option permet de choisir la famille d’IP à utiliser lors de la résolution, ce qui est pratique lorsque IPv6 n’est pas disponible sur votre réseau. L’option par défaut est « ipv6 ».

httpclient.retries <number>

httpclient.retries <number>

Cette option permet de configurer le nombre d’essais de rétention du httpclient en cas d’échec d’une requête. Elle a le même effet que la directive « retries » dans un backend.

Valeur par défaut : 3.

httpclient.ssl.ca-file <cafile>

httpclient.ssl.ca-file <cafile>

Cette option définit le fichier ca à utiliser pour vérifier le certificat du serveur. Elle accepte les mêmes paramètres que l’option « ca-file » sur la ligne serveur.

Par défaut, et lorsque cette option n’est pas utilisée, la valeur est « @system-ca », qui tente de charger les certificats de la autorité de certification du système. En cas d’échec, le protocole SSL sera désactivé pour le httpclient.

Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée en cas d’échec.

httpclient.ssl.verify [none|required]

httpclient.ssl.verify [none|required]

Fonctionne de la même manière que l’option verify sur les lignes server. Si elle est définie sur « none », les certificats des serveurs ne sont pas vérifiés. L’option par défaut est « required ».

Par défaut, et lorsque cette option n’est pas utilisée, la valeur est « required ». Si l’échec se produit, le protocole SSL sera désactivé pour le httpclient.

Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée en cas d’échec.

httpclient.timeout.connect <timeout>

httpclient.timeout.connect <timeout>

Définir le délai maximal d’attente pour une tentative de connexion par défaut pour le client HTTP.

Arguments :

<timeout> is the timeout value specified in milliseconds by default, but
          can be in any other unit if the number is suffixed by the unit,
          as explained at the top of this document.

La valeur par défaut est de 5000 ms.

13 - 4. Proxies

La configuration du proxy peut être située dans un ensemble de sections :

• defaults [<name>] [ depuis <defaults_name> ]
• frontal <name> [ depuis <defaults_name> ]
• backend <name> [ depuis <defaults_name> ]
• écouter <name> [ depuis <defaults_name> ]

Une section « frontend » décrit un ensemble de sockets d’écoute acceptant les connexions clientes.

Une section « backend » décrit un ensemble de serveurs auxquels le proxy se connectera pour acheminer les connexions entrantes.

Une section « listen » définit un proxy complet comprenant ses parties frontale et arrière regroupées dans une même section. Elle est généralement utile pour le trafic TCP uniquement.

Une section « defaults » réinitialise toutes les paramètres aux valeurs documentées et définit de nouveaux paramètres utilisables par les sections ultérieures. Toutes les sections « frontend », « backend » et « listen » prennent toujours leurs paramètres initiaux à partir d’une section « defaults », par défaut la dernière apparaissant avant la section nouvellement créée. Il est possible de désigner explicitement une section « defaults » spécifique pour charger les paramètres initiaux en indiquant son nom sur la ligne de section après le mot-clé facultatif « from ». Bien que les sections « defaults » n’imposent pas de nom, il est recommandé de les nommer pour une meilleure lisibilité. C’est également la seule manière de désigner une section spécifique à utiliser à la place de la précédente par défaut. Étant donné que les noms de sections « defaults » sont facultatifs, une vérification très permissive est appliquée par défaut à leur nom, qui peut même se chevaucher. Toutefois, si une section « defaults » est référencée par une autre section, son nom doit respecter la syntaxe imposée aux noms de proxy, et ce nom doit être unique parmi les sections « defaults ». Veuillez noter qu’indépendamment de ce qui est actuellement autorisé, il est recommandé d’éviter les noms de section en double en général et de respecter la même syntaxe que pour les noms de proxy. Cette règle pourrait être imposée dans une version future. En outre, un avertissement est émis si une section « defaults » est utilisée explicitement par un proxy tout en étant également utilisée implicitement par un autre, car elle est la dernière définie. Il est fortement conseillé de ne pas mélanger ces deux modes d’utilisation, en utilisant toujours des références explicites ou en ajoutant une dernière section « defaults » commune réservée à toutes les utilisations implicites.

Notez qu’il est même possible qu’une section defaults prenne ses paramètres initiaux à partir d’une autre, et hérite ainsi des paramètres à travers plusieurs niveaux de sections defaults. Cela peut être pratique pour établir certains profils de configuration afin de regrouper des paramètres par défaut (par exemple, TCP contre HTTP ou délais courts contre délais longs), mais cela peut rapidement devenir difficile à suivre.

Par défaut, les sections defaults nommées sont conservées après l’analyse de la configuration. Cela permet de les réutiliser pour la création dynamique de backends. Ce comportement peut être modifié globalement via le mot-clé “tune.defaults.purge”.

Tous les noms de proxy doivent être composés de lettres majuscules et minuscules, de chiffres, de ‘-’ (tiret), ‘_’ (souligné), ‘.’ (point) et ‘:’ (deux-points). Les noms d’ACL sont sensibles à la casse, ce qui signifie que « www » et « WWW » représentent deux proxies différents.

Historiquement, tous les noms de proxy pouvaient se chevaucher sous certaines conditions (par exemple, lorsqu’ils ne possédaient pas les mêmes capacités frontend/backend), mais cela provoquait trop de problèmes dans les journaux ainsi que des ambiguïtés lors des opérations en ligne de commande, des noms de tables de persistance et de la récupération des statistiques. Il est désormais obligatoire que deux proxies aient des noms différents, quelle que soit leur capacité respective.

Actuellement, deux modes de proxy majeurs sont pris en charge : « tcp », également appelé couche 4, et « http », également appelé couche 7. En mode couche 4, HAProxy transfère simplement le trafic bidirectionnel entre deux extrémités. En mode couche 7, HAProxy analyse le protocole et peut interagir avec celui-ci en autorisant, bloquant, redirigeant, ajoutant, modifiant ou supprimant des contenus arbitraires dans les requêtes ou les réponses, selon des critères arbitraires.

En mode HTTP, le traitement appliqué aux requêtes et réponses transitées sur une connexion dépend de la combinaison des options HTTP du frontal et du backend. HAProxy prend en charge 3 modes de connexion :

• KAL : maintien de la connexion ouverte (« option http-keep-alive »), qui est le mode par défaut : toutes les requêtes et réponses sont traitées, et les connexions restent ouvertes mais inactives entre les réponses et les nouvelles requêtes.

• SCL : fermeture du serveur (“option http-server-close”) : la connexion orientée serveur est fermée après la réception de la fin de la réponse, mais la connexion orientée client reste ouverte.

• CLO : fermeture (“option httpclose”) : la connexion est fermée après la fin de la réponse, et l’en-tête “Connection: close” est ajouté dans les deux sens.

Le mode effectif appliqué à une connexion passant par un frontal et un backend peut être déterminé par les deux modes de proxy selon la matrice suivante, mais en résumé, les modes sont symétriques, keep-alive est l’option la plus faible et close est l’option la plus forte.

               Backend mode

                | KAL | SCL | CLO
            ----+-----+-----+----
            KAL | KAL | SCL | CLO
            ----+-----+-----+----
   mode     SCL | SCL | SCL | CLO
            ----+-----+-----+----
            CLO | CLO | CLO | CLO

Il est possible de chaîner un frontend TCP à un backend HTTP. Cette configuration est sans intérêt si seule la circulation HTTP est traitée. Toutefois, elle peut être utilisée pour gérer plusieurs protocoles au sein du même frontend. Dans ce cas, la connexion client est d’abord traitée comme une connexion TCP brute avant d’être mise à niveau vers HTTP. Avant la mise à niveau, les traitements de contenu sont effectués sur des données brutes. Une fois la mise à niveau effectuée, les données sont analysées et stockées à l’aide d’une représentation interne appelée HTX, et il n’est plus possible de s’appuyer sur la représentation brute. Il n’existe aucun moyen de revenir en arrière.

Il existe deux types de mises à jour : les mises à jour in situ et les mises à jour destructrices. La première implique une mise à jour TCP vers HTTP/1. Dans HTTP/1, le traitement des requêtes est sérialisé, de sorte que le flux applicatif peut être préservé. La seconde implique une mise à jour TCP vers HTTP/2. Étant donné qu’il s’agit d’un protocole multiplexé, le flux applicatif ne peut être associé à aucun flux HTTP/2 et est donc détruit. De nouveaux flux applicatifs sont ensuite créés lorsque HAProxy reçoit de nouveaux flux HTTP/2 au niveau inférieur, dans le multiplexeur H2. Il est important de comprendre cette différence, car elle change radicalement la manière de traiter les données. Lorsqu’une mise à jour HTTP/1 est effectuée, les traitements appliqués sur les données brutes ne sont ni perdus ni réexécutés, tandis qu’en cas de mise à jour HTTP/2, les flux applicatifs sont distincts et toutes les règles frontales sont systématiquement évaluées sur chacun. Comme indiqué, le premier flux, le flux TCP, est détruit, mais uniquement après l’évaluation des règles frontales.

Il existe un autre point important à comprendre lorsqu’un traitement HTTP est effectué à partir d’un proxy TCP. Bien que HAProxy soit capable d’analyser HTTP/1 en temps réel à l’aide des règles tcp-request, il n’est pas possible pour HTTP/2. Seul le préambule HTTP/2 peut être analysé. Il s’agit d’une limitation majeure concernant l’analyse du contenu HTTP en TCP. Concrètement, il n’est possible de déterminer qu’avec certitude si les données reçues sont au format HTTP. Par exemple, il n’est pas possible de choisir un backend en fonction de la valeur de l’en-tête Host, alors qu’il s’agit d’une opération triviale dans HTTP/1.. Heureusement, une solution existe pour atténuer cet inconvénient.

Il existe deux façons d’effectuer une mise à niveau HTTP. La première, méthode historique, consiste à sélectionner un backend HTTP. La mise à niveau a lieu lorsque le backend est défini. Ainsi, pour les mises à niveau in situ, seule la configuration du backend est prise en compte dans le traitement des données HTTP. Pour les mises à niveau destructrices, le flux applicatif est détruit, ce qui arrête son traitement. Avec cette méthode, les possibilités de choisir un backend avec une connexion HTTP/2 sont réellement limitées, comme mentionné ci-dessus, et un peu inutiles car le flux est détruit. La deuxième méthode consiste à effectuer la mise à niveau pendant l’évaluation des règles tcp-request content, grâce à l’action « switch-mode http ». Dans ce cas, la mise à niveau est effectuée dans le contexte du frontal et il est possible de définir des directives HTTP dans ce frontal. Pour les mises à niveau in situ, elle offre toute la puissance de l’analyse HTTP dès que possible. Elle n’est pas très éloignée d’un frontal HTTP. Pour les mises à niveau destructrices, cela ne change rien, sauf qu’il est inutile de choisir un backend sur une information limitée. Il s’agit bien sûr de la méthode recommandée. Ainsi, tester le protocole de la requête dans les règles tcp-request content pour effectuer une mise à niveau HTTP est suffisant. Toutes les manipulations HTTP restantes peuvent être déplacées vers le jeu de règles http-request du frontal. Mais gardez à l’esprit que les règles tcp-request content sont toujours évaluées sur chaque flux, ce qui ne peut pas être modifié.

4.1. Matrice des mots-clés proxy

La liste suivante de mots-clés est prise en charge. La plupart d’entre eux ne peuvent être utilisés que dans un ensemble limité de types de sections. Certains sont marqués comme « dépréciés » car ils sont hérités d’une ancienne syntaxe pouvant prêter à confusion ou être fonctionnellement limitée, et de nouveaux mots-clés recommandés ont été introduits pour les remplacer. Les mots-clés marqués par «(*)» peuvent être inversés de manière optionnelle en utilisant le préfixe « no », par exemple « no option contstats ». Cette fonctionnalité est utile lorsque l’option est activée par défaut et doit être désactivée pour une instance spécifique. Ces options peuvent également être préfixées par « default » afin de restaurer les paramètres par défaut, indépendamment de ce qui a été spécifié dans une section « defaults » précédente. Les mots-clés pris en charge dans les sections « defaults » marqués par «(!) » ne sont pris en charge que dans les sections « defaults » nommées, et non dans les sections anonymes.

Note : Certains directives dangereuses et non recommandées sont intentionnellement omises dans la matrice suivante. Cela est voulu. Ces directives sont documentées. Mais leur omission dans cette liste constitue une autre manière de dissuader toute personne souhaitant les utiliser.

 keyword                              defaults   frontend   listen    backend
------------------------------------+----------+----------+---------+---------
acl                                       X (!)      X         X         X
backlog                                   X          X         X         -
balance                                   X          -         X         X
be-unpublished                            -          -         X         X
bind                                      -          X         X         -
capture cookie                            -          X         X         -
capture request header                    -          X         X         -
capture response header                   -          X         X         -
clitcpka-cnt                              X          X         X         -
clitcpka-idle                             X          X         X         -
clitcpka-intvl                            X          X         X         -
compression                               X          X         X         X
cookie                                    X          -         X         X
crt                                       -          X         X         -
declare capture                           -          X         X         -
default-server                            X          -         X         X
default_backend                           X          X         X         -
description                               -          X         X         X
disabled                                  X          X         X         X
dispatch                    (deprecated)  -          -         X         X
email-alert from                          X          X         X         X
email-alert level                         X          X         X         X
email-alert mailers                       X          X         X         X
email-alert myhostname                    X          X         X         X
email-alert to                            X          X         X         X
enabled                                   X          X         X         X
errorfile                                 X          X         X         X
errorfiles                                X          X         X         X
errorloc                                  X          X         X         X
errorloc302                               X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
errorloc303                               X          X         X         X
error-log-format                          X          X         X         -
external-check command                    X          -         X         X
external-check path                       X          -         X         X
force-persist                             -          -         X         X
force-be-switch                           -          X         X         -
filter                                    -          X         X         X
filter-sequence                           -          X         X         X
fullconn                                  X          -         X         X
guid                                      -          X         X         X
hash-balance-factor                       X          -         X         X
hash-preserve-affinity                    X          -         X         X
hash-type                                 X          -         X         X
http-after-response                       X (!)      X         X         X
http-check comment                        X          -         X         X
http-check connect                        X          -         X         X
http-check disable-on-404                 X          -         X         X
http-check expect                         X          -         X         X
http-check send                           X          -         X         X
http-check send-state                     X          -         X         X
http-check set-var                        X          -         X         X
http-check unset-var                      X          -         X         X
http-error                                X          X         X         X
http-request                              X (!)      X         X         X
http-response                             X (!)      X         X         X
http-reuse                                X          -         X         X
http-send-name-header                     X          -         X         X
id                                        -          X         X         X
ignore-persist                            -          -         X         X
load-server-state-from-file               X          -         X         X
log                                  (*)  X          X         X         X
log-format                                X          X         X         -
log-format-sd                             X          X         X         -
log-tag                                   X          X         X         X
log-steps                                 X          X         X         -
max-keep-alive-queue                      X          -         X         X
max-session-srv-conns                     X          X         X         -
maxconn                                   X          X         X         -
mode                                      X          X         X         X
monitor fail                              -          X         X         -
monitor-uri                               X          X         X         -
option abortonclose                  (*)  X          X         X         X
option allbackups                    (*)  X          -         X         X
option checkcache                    (*)  X          -         X         X
option clitcpka                      (*)  X          X         X         -
option contstats                     (*)  X          X         X         -
option disable-h2-upgrade            (*)  X          X         X         -
option dontlog-normal                (*)  X          X         X         -
option dontlognull                   (*)  X          X         X         -
-- keyword -------------------------- defaults - frontend - listen -- backend -
option external-check                     X          -         X         X
option forwardfor                         X          X         X         X
option forwarded                     (*)  X          -         X         X
option h1-case-adjust-bogus-client   (*)  X          X         X         -
option h1-case-adjust-bogus-server   (*)  X          -         X         X
option http-buffer-request           (*)  X          X         X         X
option http-drop-request-trailers    (*)  X          -         -         X
option http-drop-response-trailers   (*)  X          -         X         -
option http-ignore-probes            (*)  X          X         X         -
option http-keep-alive               (*)  X          X         X         X
option http-no-delay                 (*)  X          X         X         X
option http-pretend-keepalive        (*)  X          -         X         X
option http-restrict-req-hdr-names        X          X         X         X
option http-server-close             (*)  X          X         X         X
option http-use-proxy-header         (*)  X          X         X         -
option httpchk                            X          -         X         X
option httpclose                     (*)  X          X         X         X
option httplog                            X          X         X         -
option httpslog                           X          X         X         -
option idle-close-on-response        (*)  X          X         X         -
option independent-streams           (*)  X          X         X         X
option ldap-check                         X          -         X         X
option log-health-checks             (*)  X          -         X         X
option log-separate-errors           (*)  X          X         X         -
option logasap                       (*)  X          X         X         -
option mysql-check                        X          -         X         X
option nolinger                      (*)  X          X         X         X
option originalto                         X          X         X         X
option persist                       (*)  X          -         X         X
option pgsql-check                        X          -         X         X
option prefer-last-server            (*)  X          -         X         X
option redispatch                    (*)  X          -         X         X
option redis-check                        X          -         X         X
option smtpchk                            X          -         X         X
option socket-stats                  (*)  X          X         X         -
option splice-auto                   (*)  X          X         X         X
option splice-request                (*)  X          X         X         X
option splice-response               (*)  X          X         X         X
option spop-check                         X          -         X         X
option srvtcpka                      (*)  X          -         X         X
option ssl-hello-chk                      X          -         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
option tcp-check                          X          -         X         X
option tcp-smart-accept              (*)  X          X         X         -
option tcp-smart-connect             (*)  X          -         X         X
option tcpka                              X          X         X         X
option tcplog                             X          X         X         -
option transparent      (deprecated) (*)  X          -         X         X
option use-small-buffers             (*)  X          -         X         X
persist rdp-cookie                        X          -         X         X
quic-initial                              X (!)      X         X         -
rate-limit sessions                       X          X         X         -
redirect                                  -          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
retries                                   X          -         X         X
retry-on                                  X          -         X         X
server                                    -          -         X         X
server-state-file-name                    X          -         X         X
server-template                           -          -         X         X
source                                    X          -         X         X
srvtcpka-cnt                              X          -         X         X
srvtcpka-idle                             X          -         X         X
srvtcpka-intvl                            X          -         X         X
stats admin                               -          X         X         X
stats auth                                X          X         X         X
stats enable                              X          X         X         X
stats hide-version                        X          X         X         X
stats http-request                        -          X         X         X
stats realm                               X          X         X         X
stats refresh                             X          X         X         X
stats scope                               X          X         X         X
stats show-desc                           X          X         X         X
stats show-legends                        X          X         X         X
stats show-node                           X          X         X         X
stats show-version                        X          X         X         X
stats uri                                 X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
stick match                               -          -         X         X
stick on                                  -          -         X         X
stick store-request                       -          -         X         X
stick store-response                      -          -         X         X
stick-table                               -          X         X         X
tcp-check comment                         X          -         X         X
tcp-check connect                         X          -         X         X
tcp-check expect                          X          -         X         X
tcp-check send                            X          -         X         X
tcp-check send-lf                         X          -         X         X
tcp-check send-binary                     X          -         X         X
tcp-check send-binary-lf                  X          -         X         X
tcp-check set-var                         X          -         X         X
tcp-check unset-var                       X          -         X         X
tcp-request connection                    X (!)      X         X         -
tcp-request content                       X (!)      X         X         X
tcp-request inspect-delay                 X (!)      X         X         X
tcp-request session                       X (!)      X         X         -
tcp-response content                      X (!)      -         X         X
tcp-response inspect-delay                X (!)      -         X         X
timeout check                             X          -         X         X
timeout client                            X          X         X         -
timeout client-fin                        X          X         X         -
timeout client-hs                         X          X         X         -
timeout connect                           X          -         X         X
timeout http-keep-alive                   X          X         X         X
timeout http-request                      X          X         X         X
timeout queue                             X          -         X         X
timeout server                            X          -         X         X
timeout server-fin                        X          -         X         X
timeout tarpit                            X          X         X         X
timeout tunnel                            X          -         X         X
transparent                 (deprecated)  X          -         X         X
unique-id-format                          X          X         X         X
unique-id-header                          X          X         X         -
use_backend                               -          X         X         -
use-fcgi-app                              -          -         X         X
use-server                                -          -         X         X
------------------------------------+----------+----------+---------+---------
 keyword                              defaults   frontend   listen    backend

4.2. Référence des mots-clés triés par ordre alphabétique

Cette section décrit chaque mot-clé et son utilisation.

acl <aclname> <criterion> [flags] [operator] <value> ...

acl <aclname> <criterion> [flags] [operator] <value> ...

Déclarer ou compléter une liste d’accès.

Peut être utilisé dans les contextes suivants : tcp, http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui

Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les ACL définies dans une section defaults ne sont pas visibles depuis d’autres sections qui l’utilisent.

Exemple :

acl invalid_src  src          0.0.0.0/7 224.0.0.0/3
acl invalid_src  src_port     0:1023
acl local_dst    hdr(host) -i localhost

Voir section 7 concernant l’utilisation des ACL.

backlog <conns>

backlog <conns>

Fournir des indications au système concernant la taille approximative du tampon d’écoute souhaitée

Peut être utilisé dans les contextes suivants : tcp, http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non

Arguments :

<conns>   is the number of pending connections. Depending on the operating
          system, it may represent the number of already acknowledged
          connections, of non-acknowledged ones, or both.

Cette option n’est significative que pour les écouteurs en mode flux, y compris ceux utilisant QUIC. Son comportement, toutefois, n’est pas identique à celui des instances QUIC.

Pour tous les écouteurs sauf QUIC, afin de se protéger contre les attaques par inondation SYN, une solution consiste à augmenter la taille de la file d’attente des SYN du système. Selon le système, cette valeur peut être ajustable via un paramètre système, ne pas être ajustable du tout, ou dépendre des indications fournies par l’application au moment de l’appel système listen(). Par défaut, HAProxy transmet la valeur maxconn du frontal à l’appel système listen(). Sur les systèmes pouvant utiliser cette valeur, il peut parfois être utile de pouvoir spécifier une valeur différente, d’où la présence de ce paramètre backlog.

Sous Linux 2.4, le paramètre est ignoré par le système. Sous Linux 2.6, il est utilisé comme indication et le système accepte au plus la plus petite puissance de deux supérieure, sans dépasser certaines limites (généralement 32768).

Pour les écouteurs QUIC, le paramètre backlog définit une limite partagée entre le nombre maximal de poignées d’établissement actives et le nombre de connexions en attente d’acceptation. La phase de poignée dépend principalement de la latence réseau avec le pair distant, tandis que la deuxième phase dépend uniquement de la charge de HAProxy. Lorsqu’une de ces limites est atteinte, haproxy commence à rejeter les paquets INITIAL, empêchant toute nouvelle allocation de connexion, jusqu’à ce que l’excédent de connexions commence à diminuer. Cette situation peut entraîner un passage silencieux des navigateurs vers des versions HTTP inférieures et le basculement vers TCP.

Voir également : « maxconn » et le guide d’ajustement du système d’exploitation cible.

balance <algorithm> [ <arguments> ]

balance <algorithm> [ <arguments> ]
balance url_param <param> [check_post]

Définir l’algorithme de répartition de charge à utiliser dans un backend.

Peut être utilisé dans les contextes suivants : tcp, http, log

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui

Arguments :

<algorithm> is the algorithm used to select a server when doing load
            balancing. This only applies when no persistence information
            is available, or when a connection is redispatched to another
            server. <algorithm> may be one of the following:

  roundrobin  Each server is used in turns, according to their weights.
              This is the smoothest and fairest algorithm when the server's
              processing time remains equally distributed. This algorithm
              is dynamic, which means that server weights may be adjusted
              on the fly for slow starts for instance. It is limited by
              design to 4095 active servers per backend. Note that in some
              large farms, when a server becomes up after having been down
              for a very short time, it may sometimes take a few hundreds
              requests for it to be re-integrated into the farm and start
              receiving traffic. This is normal, though very rare. It is
              indicated here in case you would have the chance to observe
              it, so that you don't worry. Note: weights are ignored for
              backends in LOG mode.

  static-rr   Each server is used in turns, according to their weights.
              This algorithm is as similar to roundrobin except that it is
              static, which means that changing a server's weight on the
              fly will have no effect. On the other hand, it has no design
              limitation on the number of servers, and when a server goes
              up, it is always immediately reintroduced into the farm, once
              the full map is recomputed. It also uses slightly less CPU to
              run (around -1%). This algorithm is not usable in LOG mode.

  leastconn   The server with the lowest number of connections receives the
              connection. Round-robin is performed within groups of servers
              of the same load to ensure that all servers will be used. Use
              of this algorithm is recommended where very long sessions are
              expected, such as LDAP, SQL, TSE, etc... but is not very well
              suited for protocols using short sessions such as HTTP. This
              algorithm is dynamic, which means that server weights may be
              adjusted on the fly for slow starts for instance. It will
              also consider the number of queued connections in addition to
              the established ones in order to minimize queuing. This
              algorithm is not usable in LOG mode.

  first       The first server with available connection slots receives the
              connection. The servers are chosen from the lowest numeric
              identifier to the highest (see server parameter "id"), which
              defaults to the server's position in the farm. Once a server
              reaches its maxconn value, the next server is used. It does
              not make sense to use this algorithm without setting maxconn.
              The purpose of this algorithm is to always use the smallest
              number of servers so that extra servers can be powered off
              during non-intensive hours. This algorithm ignores the server
              weight, and brings more benefit to long session such as RDP
              or IMAP than HTTP, though it can be useful there too. In
              order to use this algorithm efficiently, it is recommended
              that a cloud controller regularly checks server usage to turn
              them off when unused, and regularly checks backend queue to
              turn new servers on when the queue inflates. Alternatively,
              using "http-check send-state" may inform servers on the load.
              This algorithm is not usable in LOG mode.

  hash        Takes a regular sample expression in argument. The expression
              is evaluated for each request and hashed according to the
              configured hash-type. The result of the hash is divided by
              the total weight of the running servers to designate which
              server will receive the request. This can be used in place of
              "source", "uri", "hdr()", "url_param()", "rdp-cookie" to make
              use of a converter, refine the evaluation, or be used to
              extract data from local variables for example. When the data
              is not available, round robin will apply. This algorithm is
              static by default, which means that changing a server's
              weight on the fly will have no effect, but this can be
              changed using "hash-type". This algorithm is not usable for
              backends in LOG mode, please use "log-hash" instead.

  source      The source IP address is hashed and divided by the total
              weight of the running servers to designate which server will
              receive the request. This ensures that the same client IP
              address will always reach the same server as long as no
              server goes down or up. If the hash result changes due to the
              number of running servers changing, many clients will be
              directed to a different server. This algorithm is generally
              used in TCP mode where no cookie may be inserted. It may also
              be used on the Internet to provide a best-effort stickiness
              to clients which refuse session cookies. This algorithm is
              static by default, which means that changing a server's
              weight on the fly will have no effect, but this can be
              changed using "hash-type". See also the "hash" option above.
              This algorithm is not usable for backends in LOG mode.

  uri         This algorithm hashes either the left part of the URI (before
              the question mark) or the whole URI (if the "whole" parameter
              is present) and divides the hash value by the total weight of
              the running servers. The result designates which server will
              receive the request. This ensures that the same URI will
              always be directed to the same server as long as no server
              goes up or down. This is used with proxy caches and
              anti-virus proxies in order to maximize the cache hit rate.
              Note that this algorithm may only be used in an HTTP backend.
              This algorithm is static by default, which means that
              changing a server's weight on the fly will have no effect,
              but this can be changed using "hash-type".

              This algorithm supports two optional parameters "len" and
              "depth", both followed by a positive integer number. These
              options may be helpful when it is needed to balance servers
              based on the beginning of the URI only. The "len" parameter
              indicates that the algorithm should only consider that many
              characters at the beginning of the URI to compute the hash.
              Note that having "len" set to 1 rarely makes sense since most
              URIs start with a leading "/".

              The "depth" parameter indicates the maximum directory depth
              to be used to compute the hash. One level is counted for each
              slash in the request. If both parameters are specified, the
              evaluation stops when either is reached.

              A "path-only" parameter indicates that the hashing key starts
              at the first '/' of the path. This can be used to ignore the
              authority part of absolute URIs, and to make sure that HTTP/1
              and HTTP/2 URIs will provide the same hash. See also the
              "hash" option above.

  url_param   The URL parameter specified in argument will be looked up in
              the query string of each HTTP GET request.

              If the modifier "check_post" is used, then an HTTP POST
              request entity will be searched for the parameter argument,
              when it is not found in a query string after a question mark
              ('?') in the URL. The message body will only start to be
              analyzed once either the advertised amount of data has been
              received or the request buffer is full. In the unlikely event
              that chunked encoding is used, only the first chunk is
              scanned. Parameter values separated by a chunk boundary, may
              be randomly balanced if at all. This keyword used to support
              an optional <max_wait> parameter which is now ignored.

              If the parameter is found followed by an equal sign ('=') and
              a value, then the value is hashed and divided by the total
              weight of the running servers. The result designates which
              server will receive the request.

              This is used to track user identifiers in requests and ensure
              that a same user ID will always be sent to the same server as
              long as no server goes up or down. If no value is found or if
              the parameter is not found, then a round robin algorithm is
              applied. Note that this algorithm may only be used in an HTTP
              backend. This algorithm is static by default, which means
              that changing a server's weight on the fly will have no
              effect, but this can be changed using "hash-type". See also
              the "hash" option above.

  hdr(<name>) The HTTP header <name> will be looked up in each HTTP
              request. Just as with the equivalent ACL 'hdr()' function,
              the header name in parenthesis is not case sensitive. If the
              header is absent or if it does not contain any value, the
              roundrobin algorithm is applied instead.

              An optional 'use_domain_only' parameter is available, for
              reducing the hash algorithm to the main domain part with some
              specific headers such as 'Host'. For instance, in the Host
              value "haproxy.1wt.eu", only "1wt" will be considered.

              This algorithm is static by default, which means that
              changing a server's weight on the fly will have no effect,
              but this can be changed using "hash-type". See also the
              "hash" option above.

  random
  random(<draws>)
              A random number will be used as the key for the consistent
              hashing function. This means that the servers' weights are
              respected, dynamic weight changes immediately take effect, as
              well as new server additions. Random load balancing can be
              useful with large farms or when servers are frequently added
              or removed as it may avoid the hammering effect that could
              result from roundrobin or leastconn in this situation. The
              hash-balance-factor directive can be used to further improve
              fairness of the load balancing, especially in situations
              where servers show highly variable response times. When an
              argument <draws> is present, it must be an integer value one
              or greater, indicating the number of draws before selecting
              the least loaded of these servers. It was indeed demonstrated
              that picking the least loaded of two servers is enough to
              significantly improve the fairness of the algorithm, by
              always avoiding to pick the most loaded server within a farm
              and getting rid of any bias that could be induced by the
              unfair distribution of the consistent list. Higher values N
              will take away N-1 of the highest loaded servers at the
              expense of performance. With very high values, the algorithm
              will converge towards the leastconn's result but much slower.
              In addition, for large server farms with very low loads (or
              perfect balance), comparing loads will often lead to a tie,
              so in case of equal loads between all measured servers, their
              request rate over the last second are compared, which allows
              to better balance server usage over time in the same spirit
              as roundrobin does, and smooth consistent hash unfairness.
              The default value is 2, which generally shows very good
              distribution and performance. For large farms with low loads
              (less than a few requests per second per server), it may help
              to raise it to 3 or even 4. This algorithm is also known as
              the Power of Two Random Choices and is described here:
              http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf

              For backends in LOG mode, the number of draws is ignored and
              a single random is picked since there is no notion of server
              load. Random log balancing can be useful with large farms or
              when servers are frequently added or removed from the pool of
              available servers as it may avoid the hammering effect that
              could result from roundrobin in this situation.

  rdp-cookie
  rdp-cookie(<name>)
              The RDP cookie <name> (or "mstshash" if omitted) will be
              looked up and hashed for each incoming TCP request. Just as
              with the equivalent ACL 'req.rdp_cookie()' function, the name
              is not case-sensitive. This mechanism is useful as a degraded
              persistence mode, as it makes it possible to always send the
              same user (or the same session ID) to the same server. If the
              cookie is not found, the normal roundrobin algorithm is
              used instead.

              Note that for this to work, the frontend must ensure that an
              RDP cookie is already present in the request buffer. For this
              you must use 'tcp-request content accept' rule combined with
              a 'req.rdp_cookie_cnt' ACL.

              This algorithm is static by default, which means that
              changing a server's weight on the fly will have no effect,
              but this can be changed using "hash-type". See also the
              "hash" option above.

  log-hash    Takes a comma-delimited list of converters in argument. These
              converters are applied in sequence to the input log message,
              and the result will be cast as a string then hashed according
              to the configured hash-type. The resulting hash will be used
              to select the destination server among the ones declared in
              the log backend. The goal of this algorithm is to be able to
              extract a key within the final log message using string
              converters and then be able to stick to the same server thanks
              to the hash. Only "map-based" hashes are supported for now.
              This algorithm is only usable for backends in LOG mode, for
              others, please use "hash" instead.

  sticky      Tries to stick to the same server as much as possible. The
              first server in the list of available servers receives all
              the log messages. When the server goes DOWN, the next server
              in the list takes its place. When a previously DOWN server
              goes back UP it is added at the end of the list so that the
              sticky server doesn't change until it becomes DOWN.

<arguments> is an optional list of arguments which may be needed by some
            algorithms. Right now, only "url_param", "uri" and "log-hash"
            support an optional argument.

L’algorithme de répartition de charge d’un backend est défini sur « random » lorsque aucun autre algorithme, mode ni option n’a été défini. L’algorithme ne peut être défini qu’une seule fois pour chaque backend.

Avec les schémas d’authentification qui exigent la même connexion, comme NTLM, les algorithmes basés sur l’URI ne doivent pas être utilisés, car ils entraîneraient la redirection des requêtes ultérieures vers des serveurs backend différents, rompant ainsi les hypothèses non valides sur lesquelles repose NTLM.

TCP/HTTP Exemples :

balance roundrobin
balance url_param userid
balance url_param session_id check_post 64
balance hdr(User-Agent)
balance hdr(host)
balance hdr(Host) use_domain_only
balance hash req.cookie(clientid)
balance hash var(req.client_id)
balance hash req.hdr_ip(x-forwarded-for,-1),ipmask(24)

Exemples de backend de journalisation :

global
  log backend@mylog-rrb local0 # send all logs to mylog-rrb backend
  log backend@mylog-hash local0 # send all logs to mylog-hash backend

backend mylog-rrb
  mode log
  balance roundrobin

  server s1 udp@127.0.0.1:514 # will receive 50% of log messages
  server s2 udp@127.0.0.1:514

backend mylog-hash
  mode log

  # extract "METHOD URL PROTO" at the end of the log message,
  # and let haproxy hash it so that log messages generated from
  # similar requests get sent to the same syslog server:
  balance log-hash 'field(-2,\")'

  # server list here
  server s1 127.0.0.1:514
  #...

Remarque : les limitations et précautions suivantes relatives à l’utilisation de l’extension “check_post” avec “url_param” doivent être prises en compte :

- toutes les requêtes POST sont prises en compte, car il n'existe aucun moyen de déterminer si les paramètres se trouvent dans le corps ou dans l'entité, qui peut contenir des données binaires. Il peut donc être nécessaire d'utiliser une autre méthode pour limiter le traitement des requêtes POST ne comportant pas de paramètres URL dans le corps. (voir acl http_end)

-  utiliser une valeur `<max_wait>` supérieure à la taille du tampon de requête n'a pas de sens et est inutile. La taille du tampon est définie au moment de la compilation et vaut 16 ko par défaut.

- L'encodage de contenu n'est pas pris en charge, la recherche de paramètres échouera probablement ; la répartition de charge passera alors en mode Round Robin.

- Attendu : la directive 100-continue n'est pas prise en charge, la répartition de charge passera en mode Round Robin.

- Transfer-Encoding (RFC7230 3.3.1) n'est pris en charge que dans le premier morceau.
    Si la valeur entière du paramètre n'est pas présente dans le premier morceau, la sélection du serveur est indéfinie (en réalité, elle est déterminée par la quantité effectivement présente dans le premier morceau).

- Cette fonctionnalité ne prend pas en charge la génération d'une réponse 100, 411 ou 501.

- Dans certains cas, une requête "check_post" peut tenter de scanner tout le contenu du corps d’un message. La lecture se termine normalement lorsqu’un espace blanc linéaire ou un caractère de contrôle est détecté, indiquant la fin d’une éventuelle liste de paramètres d’URL. Ce comportement n’est probablement pas préoccupant pour les corps de message de type SGML.

Voir aussi : « dispatch », « cookie », « transparent », « hash-type ».

be-unpublished

be-unpublished

Instructe le backend à démarrer dans l’état non publié.

Peut être utilisé dans les contextes suivants : tcp, http, log

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui

En pratique, toutes les règles use_backend et default_backend provenant d’un autre proxy qui font référence au proxy actuel sont ignorées, et les règles de commutation de contenu suivantes sont évaluées. Cette comportement peut cependant être contourné à l’aide d’une règle « force-be-switch ».

Cet état est similaire à celui de désactivation, mais avec quelques différences. Premièrement, un backend non publié sera entièrement initialisé, y compris les contrôles d’état des serveurs, qui restent actifs. Enfin, un backend peut être rendu publiquement accessible via la commande « publish backend » sur la ligne de commande. Voir le manuel de gestion.

Voir aussi : « force-be-switch »

bind [<address>]:<port_range> [, ...] [param*]

bind [<address>]:<port_range> [, ...] [param*]
bind /<path> [, ...] [param*]

Définissez une ou plusieurs adresses d’écoute et/ou ports dans un frontal.

Peut être utilisé dans les contextes suivants : tcp, http

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non

Arguments :

<address>     is optional and can be a host name, an IPv4 address, an IPv6
              address, or '*'. It designates the address the frontend will
              listen on. If unset, all IPv4 addresses of the system will be
              listened on. The same will apply for '*' or the system's
              special address "0.0.0.0". The IPv6 equivalent is '::'. Note
              that for UDP, specific OS features are required when binding
              on multiple addresses to ensure the correct network interface
              and source address will be used on response. In other way,
              for QUIC listeners only bind on multiple addresses if running
              with a modern enough systems.

              Optionally, an address family prefix may be used before the
              address to force the family regardless of the address format,
              which can be useful to specify a path to a unix socket with
              no slash ('/'). Currently supported prefixes are:
                - 'ipv4@'  -> address is always IPv4
                - 'ipv6@'  -> address is always IPv6
                - 'udp@'   -> address is resolved as IPv4 or IPv6 and
                  protocol UDP is used. Currently those listeners are
                  supported only in log-forward sections.
                - 'udp4@'  -> address is always IPv4 and protocol UDP
                  is used. Currently those listeners are supported
                  only in log-forward sections.
                - 'udp6@'  -> address is always IPv6 and protocol UDP
                  is used. Currently those listeners are supported
                  only in log-forward sections.
                - 'unix@'  -> address is a path to a local unix socket
                - 'abns@'  -> address is in abstract namespace (Linux only).
                - 'abnsz@'  -> address is in abstract namespace (Linux only)
                   but it is explicitly zero-terminated. This means no \0
                   padding is used to complete sun_path. It is useful to
                   interconnect with programs that don't implement the
                   default abns naming logic that haproxy uses.
                - 'fd@<n>' -> use file descriptor <n> inherited from the
                  parent. The fd must be bound and may or may not already
                  be listening.
                - 'sockpair@<n>'-> like fd@ but you must use the fd of a
                  connected unix socket or of a socketpair. The bind waits
                  to receive a FD over the unix socket and uses it as if it
                  was the FD of an accept(). Should be used carefully.
                - 'quic4@' -> address is resolved as IPv4 and protocol UDP
                  is used. Note that to achieve the best performance with a
                  large traffic you should keep "tune.quic.fe.sock-per-conn
                  default-on". Else QUIC connections will be multiplexed
                  over the listener socket. Another alternative would be to
                  duplicate QUIC listener instances over several threads,
                  for example using "shards" keyword to at least reduce
                  thread contention.
                - 'quic6@' -> address is resolved as IPv6 and protocol UDP
                  is used. The performance note for QUIC over IPv4 applies
                  as well.
                - 'rhttp@' [ EXPERIMENTAL ] -> used for reverse HTTP.
                  Address must be a server with the format
                  '<backend>/<server>'. The server will be used to
                  instantiate connections to a remote address. The listener
                  will try to maintain "nbconn" connections. This is an
                  experimental features which requires
                  "expose-experimental-directives" on a line before this
                  bind.

              You may want to reference some environment variables in the
              address parameter, see section 2.3 about environment
              variables.

<port_range>  is either a unique TCP port, or a port range for which the
              proxy will accept connections for the IP address specified
              above. The port is mandatory for TCP listeners. Note that in
              the case of an IPv6 address, the port is always the number
              after the last colon (':'). A range can either be:
               - a numerical port (ex: '80')
               - a dash-delimited ports range explicitly stating the lower
                 and upper bounds (ex: '2000-2100') which are included in
                 the range.

              Particular care must be taken against port ranges, because
              every <address:port> couple consumes one socket (= a file
              descriptor), so it's easy to consume lots of descriptors
              with a simple range, and to run out of sockets. Also, each
              <address:port> couple must be used only once among all
              instances running on a same system. Please note that binding
              to ports lower than 1024 generally require particular
              privileges to start the program, which are independent of
              the 'uid' parameter.

<path>        is a UNIX socket path beginning with a slash ('/'). This is
              alternative to the TCP listening port. HAProxy will then
              receive UNIX connections on the socket located at this place.
              The path must begin with a slash and by default is absolute.
              It can be relative to the prefix defined by "unix-bind" in
              the global section. Note that the total length of the prefix
              followed by the socket path cannot exceed some system limits
              for UNIX sockets, which commonly are set to 107 characters.

<param*>      is a list of parameters common to all sockets declared on the
              same line. These numerous parameters depend on OS and build
              options and have a complete section dedicated to them. Please
              refer to section 5 to for more details.

Il est possible de spécifier une liste de combinaisons adresse:port séparées par des virgules. Le frontal écoutera alors sur toutes ces adresses. Il n’existe aucune limite fixe au nombre d’adresses et de ports sur lesquels un frontal peut écouter, ni aucune limite au nombre d’instructions « bind » dans un frontal.

Exemple :

listen http_proxy
    bind:80,:443
    bind 10.0.0.1:10080,10.0.0.1:10443
    bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy

listen http_https_proxy
    bind:80
    bind:443 ssl crt /etc/haproxy/site.pem

listen http_https_proxy_explicit
    bind ipv6@:80
    bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
    bind unix@ssl-frontend.sock user root mode 600 accept-proxy

listen external_bind_app1
    bind "fd@${FD_APP1}"

listen h3_quic_proxy
    bind quic4@10.0.0.1:8888 ssl crt /etc/mycrt

Note : En ce qui concerne les sockets de l’espace de noms abstrait sous Linux, les sockets HAProxy « abns » utilisent la longueur entière de sun_path pour la longueur de l’adresse. Certains autres programmes, comme socat, utilisent par défaut uniquement la longueur de chaîne. Passez l’option « ,unix-tightsocklen=0 » à toute définition de socket abstrait dans socat pour la rendre compatible avec celle de HAProxy, ou utilisez à la place la famille de sockets HAProxy « abnsz ».

Voir également : « source », « option forwardfor », « unix-bind » et la documentation du protocole PROXY, ainsi que section 5 concernant les options bind.

capture cookie <name> len <length>

capture cookie <name> len <length>

Capturez et enregistrez un cookie dans la requête et dans la réponse.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non

Arguments :

<name>    is the beginning of the name of the cookie to capture. In order
          to match the exact name, simply suffix the name with an equal
          sign ('='). The full name will appear in the logs, which is
          useful with application servers which adjust both the cookie name
          and value (e.g. ASPSESSIONXXX).

<length>  is the maximum number of characters to report in the logs, which
          include the cookie name, the equal sign and the value, all in the
          standard "name=value" form. The string will be truncated on the
          right if it exceeds <length>.

Seul le premier cookie est capturé. Les en-têtes de requête « cookie » et les en-têtes de réponse « set-cookie » sont surveillés. Cela est particulièrement utile pour détecter des bugs applicatifs provoquant une chevauchement ou un vol de session entre utilisateurs, car les cookies de l’utilisateur ne devraient normalement changer que sur une page de connexion.

Lorsqu’un cookie n’est pas fourni par le client, la colonne de journal associée indique « - ». Lorsqu’une requête ne provoque pas l’attribution d’un cookie par le serveur, une « - » est indiquée dans la colonne de réponse.

La capture est effectuée uniquement dans le frontend, car il est nécessaire que le format des journaux ne change pas pour un frontend donné en fonction des backends. Cela pourrait évoluer à l’avenir. Notez qu’il ne peut y avoir qu’une seule instruction « capture cookie » dans un frontend. La longueur maximale de capture est définie par le paramètre global “tune.http.cookielen” et vaut 63 caractères par défaut. Il n’est pas possible de spécifier une capture dans une section « defaults ».

Exemple :

capture cookie ASPSESSION len 32

Voir également : « capture d’en-tête de requête », « capture d’en-tête de réponse » ainsi que la section 8 concernant la journalisation.

capture request header <name> len <length>

capture request header <name> len <length>

Capturez et enregistrez la dernière occurrence de l’en-tête de requête spécifié.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non

Arguments :

<name>    is the name of the header to capture. The header names are not
          case-sensitive, but it is a common practice to write them as they
          appear in the requests, with the first letter of each word in
          upper case. The header name will not appear in the logs, only the
          value is reported, but the position in the logs is respected.

<length>  is the maximum number of characters to extract from the value and
          report in the logs. The string will be truncated on the right if
          it exceeds <length>.

La valeur complète de la dernière occurrence de l’en-tête est capturée. La valeur sera ajoutée aux journaux entre accolades (’{}’). Si plusieurs en-têtes sont capturés, ils seront séparés par une barre verticale (’|’) et apparaîtront dans le même ordre que leur déclaration dans la configuration. Les en-têtes inexistants seront journalisés sous forme de chaîne vide. Les utilisations courantes de la capture d’en-têtes de requête incluent le champ “Host” dans les environnements de hébergement virtuel, le champ “Content-length” lorsqu’un téléchargement est pris en charge, le champ “User-agent” pour distinguer rapidement les utilisateurs réels des robots, et le champ “X-Forwarded-For” dans les environnements proxy afin de déterminer l’origine de la requête.

Notez que lors de la capture d’en-têtes tels que « User-agent », certains espaces peuvent être enregistrés, ce qui complique l’analyse des journaux. Veillez donc à ce que vous enregistrez, si vous savez que votre analyseur de journaux n’est pas suffisamment intelligent pour s’appuyer sur les accolades.

Il n’y a aucune limite au nombre d’en-têtes de requête capturés ni à leur longueur, bien qu’il soit recommandé de les limiter afin de réduire l’utilisation mémoire par flux. Pour maintenir un format de journal cohérent pour un même frontal, les captures d’en-têtes ne peuvent être déclarées qu’au sein d’un frontend. Il n’est pas possible de spécifier une capture dans une section « defaults ».

Exemple :

capture request header Host len 15
capture request header X-Forwarded-For len 15
capture request header Referer len 15

Voir aussi : « capture cookie », « capture d’en-tête de réponse » ainsi que la section 8 concernant la journalisation.

capture response header <name> len <length>

capture response header <name> len <length>

Capturez et enregistrez la dernière occurrence de l’en-tête de réponse spécifié.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non

Arguments :

<name>    is the name of the header to capture. The header names are not
          case-sensitive, but it is a common practice to write them as they
          appear in the response, with the first letter of each word in
          upper case. The header name will not appear in the logs, only the
          value is reported, but the position in the logs is respected.

<length>  is the maximum number of characters to extract from the value and
          report in the logs. The string will be truncated on the right if
          it exceeds <length>.

La valeur complète de la dernière occurrence de l’en-tête est capturée. Le résultat sera ajouté aux journaux entre accolades (’{}’) après les en-têtes de requête capturés. Si plusieurs en-têtes sont capturés, ils seront séparés par une barre verticale (’|’) et apparaîtront dans le même ordre qu’ils ont été déclarés dans la configuration. Les en-têtes inexistants seront journalisés sous forme de chaîne vide. Les utilisations courantes des en-têtes de réponse capturés incluent l’en-tête “Content-length”, qui indique le nombre d’octets attendus en retour, et l’en-tête “Location” pour suivre les redirections.

Il n’y a aucune limite au nombre d’en-têtes de réponse capturés ni à leur longueur, bien qu’il soit recommandé de les garder faibles afin de limiter l’utilisation mémoire par flux. Pour maintenir un format de journal cohérent pour un même frontal, les captures d’en-têtes ne peuvent être déclarées qu’au niveau d’un frontal. Il n’est pas possible de spécifier une capture dans une section « defaults ».

Exemple :

capture response header Content-length len 9
capture response header Location len 15

Voir aussi : « capture cookie », « capture en-tête de requête », ainsi que la section 8 concernant la journalisation.

clitcpka-cnt <count>

clitcpka-cnt <count>

Définit le nombre maximal d’enquêtes keepalive TCP qui doivent être envoyées avant de fermer la connexion du côté client.

Peut être utilisé dans les contextes suivants : tcp, http, log

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non

Arguments :

<count>   is the maximum number of keepalive probes.

Ce mot-clé correspond à l’option de socket TCP_KEEPCNT. Si ce mot-clé n’est pas spécifié, le paramètre TCP système (tcp_keepalive_probes) est utilisé. La disponibilité de ce paramètre dépend du système d’exploitation. Il est connu pour fonctionner sous Linux.

Voir aussi : « option clitcpka », « clitcpka-idle », « clitcpka-intvl ».

clitcpka-idle <timeout>

clitcpka-idle <timeout>

Définit le délai pendant lequel la connexion doit rester inactif avant que TCP ne commence à envoyer des sondes de maintien de connexion, si activé, l’envoi des paquets TCP keepalive côté client.

Peut être utilisé dans les contextes suivants : tcp, http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non

Arguments :

<timeout> is the time the connection needs to remain idle before TCP starts
          sending keepalive probes. It is specified in seconds by default,
          but can be in any other unit if the number is suffixed by the
          unit, as explained at the top of this document.

Ce mot-clé correspond à l’option de socket TCP_KEEPIDLE. Si ce mot-clé n’est pas spécifié, le paramètre TCP système (tcp_keepalive_time) est utilisé. La disponibilité de ce paramètre dépend du système d’exploitation. Il est connu pour fonctionner sous Linux.

Voir aussi : « option clitcpka », « clitcpka-cnt », « clitcpka-intvl ».

clitcpka-intvl <timeout>

clitcpka-intvl <timeout>

Définit le délai entre les sondes keepalive individuelles du côté client.

Peut être utilisé dans les contextes suivants : tcp, http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non

Arguments :

<timeout> is the time between individual keepalive probes. It is specified
          in seconds by default, but can be in any other unit if the number
          is suffixed by the unit, as explained at the top of this
          document.

Ce mot-clé correspond à l’option de socket TCP_KEEPINTVL. Si ce mot-clé n’est pas spécifié, le paramètre TCP système (tcp_keepalive_intvl) est utilisé. La disponibilité de ce paramètre dépend du système d’exploitation. Il est connu pour fonctionner sous Linux.

Voir aussi : « option clitcpka », « clitcpka-cnt », « clitcpka-idle ».

compression algo <algorithm> ...

compression algo <algorithm> ...
compression algo-req <algorithm>
compression algo-res <algorithm>
compression type <mime type> ...

Activer la compression HTTP.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui

Arguments :

algo     is followed by the list of supported compression algorithms for
         responses (legacy keyword)
algo-req is followed by compression algorithm for request (only one is
  provided).
algo-res is followed by the list of supported compression algorithms for
         responses.
type     is followed by the list of MIME types that will be compressed for
         responses (legacy keyword).
type-req is followed by the list of MIME types that will be compressed for
         requests.
type-res is followed by the list of MIME types that will be compressed for
         responses.

Les algorithmes actuellement pris en charge sont :

identity     this is mostly for debugging, and it was useful for developing
             the compression feature. Identity does not apply any change on
             data.

gzip         applies gzip compression. This setting is only available when
             support for zlib or libslz was built in.

deflate      same as "gzip", but with deflate algorithm and zlib format.
             Note that this algorithm has ambiguous support on many
             browsers and no support at all from recent ones. It is
             strongly recommended not to use it for anything else than
             experimentation. This setting is only available when support
             for zlib or libslz was built in.

raw-deflate  same as "deflate" without the zlib wrapper, and used as an
             alternative when the browser wants "deflate". All major
             browsers understand it and despite violating the standards,
             it is known to work better than "deflate", at least on MSIE
             and some versions of Safari. Do not use it in conjunction
             with "deflate", use either one or the other since both react
             to the same Accept-Encoding token. This setting is only
             available when support for zlib or libslz was built in.

La compression sera activée en fonction de l’en-tête de requête Accept-Encoding. Avec la valeur identity, cet en-tête n’est pas pris en compte. Si les serveurs backend prennent en charge la compression HTTP, ces directives n’auront aucun effet : HAProxy détectera la réponse compressée et ne la comprimera pas à nouveau. Si les serveurs backend ne prennent pas en charge la compression HTTP et qu’un en-tête Accept-Encoding est présent dans la requête, HAProxy comprimera la réponse correspondante.

La compression est désactivée lorsque : - la requête ne déclare pas d’algorithme de compression pris en charge dans l’en-tête « Accept-Encoding » - le message de réponse n’est pas HTTP/1.1 ou supérieur - le code de statut HTTP n’est pas l’un des codes suivants : 200, 201, 202 ou 203 - la réponse ne contient ni l’en-tête « Content-Length » ni un en-tête « Transfer-Encoding » dont la dernière valeur est « chunked » - la réponse contient un en-tête « Content-Type » dont la première valeur commence par « multipart » - la réponse contient la valeur « no-transform » dans l’en-tête « Cache-control » - l’en-tête « User-Agent » correspond à « Mozilla/4 », sauf si c’est MSIE 6 sous XP SP2, ou MSIE 7 et versions ultérieures - la réponse contient un en-tête « Content-Encoding », indiquant que la réponse est déjà compressée (voir déchargement de compression) - la réponse contient un en-tête « ETag » invalide ou plusieurs en-têtes « ETag » - la taille du contenu est inférieure à la taille minimale (voir compression minsize-res)

Note : La compression n’émet pas l’en-tête Warning.

Exemples :

compression algo gzip
compression type text/html text/plain

Voir également : « compression offload », « compression direction », « compression minsize-req » et « compression minsize-res »

compression minsize-req <size>

compression minsize-req <size>
compression minsize-res <size>

Définit la taille minimale du contenu en octets pour la compression soit appliquée.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui

Les charges plus petites que cette taille ne seront pas compressées, évitant ainsi une surcharge CPU inutile pour des données qui ne bénéficieraient pas significativement de la compression. « minsize-req » s’applique aux requêtes et « minsize-res » aux réponses. La valeur par défaut est 0.

compression offload

compression offload

Fait fonctionner HAProxy en tant qu’accélérateur de compression uniquement.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui

L’option « offload » fait que HAProxy supprime l’en-tête Accept-Encoding afin d’empêcher les backends de compresser les réponses. Il est fortement recommandé de ne pas procéder ainsi, car cela implique que toute la charge de compression sera effectuée au niveau du seul point où HAProxy est installé. Toutefois, dans certains scénarios de déploiement, HAProxy peut être placé devant une passerelle défectueuse présentant une implémentation incorrecte de la compression HTTP, dont la désactivation n’est pas possible. Dans ce cas, HAProxy peut être utilisé pour empêcher cette passerelle d’émettre des charges utiles non valides. Dans ce contexte, supprimer simplement l’en-tête dans la configuration ne fonctionne pas, car cette opération s’applique avant l’analyse de l’en-tête, ce qui empêche HAProxy de procéder à la compression. L’option « offload » doit alors être utilisée pour de tels scénarios.

Si cette option est utilisée dans une section defaults, un avertissement est émis et l’option est ignorée.

Voir aussi : « compression type », « compression algo », « compression direction »

compression direction <direction> (deprecated)

compression direction <direction> (deprecated)

Permet à HAProxy de compresser à la fois les requêtes et les réponses. Les valeurs valides sont « request », pour compresser uniquement les requêtes, « response », pour compresser uniquement les réponses, ou « both », lorsque vous souhaitez compresser les deux. La valeur par défaut est « response ».

Cette directive n’est pertinente que lorsque la « compression filtre » ancienne était activée, car avec les filtres comp-req et comp-res, la direction de compression est redondante.

Peut être utilisé dans les contextes suivants : http

Voir aussi : « compression type », « compression algo », « compression offload »

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
              [ postonly ] [ preserve ] [ httponly ] [ secure ]
              [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
              [ dynamic ] [ attr <value> ]*

Activez la persistance basée sur les cookies dans un backend.

Peut être utilisé dans les contextes suivants : http

Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui

Arguments :

<name>    is the name of the cookie which will be monitored, modified or
          inserted in order to bring persistence. This cookie is sent to
          the client via a "Set-Cookie" header in the response, and is
          brought back by the client in a "Cookie" header in all requests.
          Special care should be taken to choose a name which does not
          conflict with any likely application cookie. Also, if the same
          backends are subject to be used by the same clients (e.g.
          HTTP/HTTPS), care should be taken to use different cookie names
          between all backends if persistence between them is not desired.

rewrite   This keyword indicates that the cookie will be provided by the
          server and that HAProxy will have to modify its value to set the
          server's identifier in it. This mode is handy when the management
          of complex combinations of "Set-cookie" and "Cache-control"
          headers is left to the application. The application can then
          decide whether or not it is appropriate to emit a persistence
          cookie. Since all responses should be monitored, this mode
          doesn't work in HTTP tunnel mode. Unless the application
          behavior is very complex and/or broken, it is advised not to
          start with this mode for new deployments. This keyword is
          incompatible with "insert" and "prefix".

insert    This keyword indicates that the persistence cookie will have to
          be inserted by HAProxy in server responses if the client did not

          already have a cookie that would have permitted it to access this
          server. When used without the "preserve" option, if the server
          emits a cookie with the same name, it will be removed before
          processing. For this reason, this mode can be used to upgrade
          existing configurations running in the "rewrite" mode. The cookie
          will only be a session cookie and will not be stored on the
          client's disk. By default, unless the "indirect" option is added,
          the server will see the cookies emitted by the client. Due to
          caching effects, it is generally wise to add the "nocache" or
          "postonly" keywords (see below). The "insert" keyword is not
          compatible with "rewrite" and "prefix".

prefix    This keyword indicates that instead of relying on a dedicated
          cookie for the persistence, an existing one will be completed.
          This may be needed in some specific environments where the client
          does not support more than one single cookie and the application
          already needs it. In this case, whenever the server sets a cookie
          named <name>, it will be prefixed with the server's identifier
          and a delimiter. The prefix will be removed from all client
          requests so that the server still finds the cookie it emitted.
          Since all requests and responses are subject to being modified,
          this mode doesn't work with tunnel mode. The "prefix" keyword is
          not compatible with "rewrite" and "insert". Note: it is highly
          recommended not to use "indirect" with "prefix", otherwise server
          cookie updates would not be sent to clients.

indirect  When this option is specified, no cookie will be emitted to a
          client which already has a valid one for the server which has
          processed the request. If the server sets such a cookie itself,
          it will be removed, unless the "preserve" option is also set. In
          "insert" mode, this will additionally remove cookies from the
          requests transmitted to the server, making the persistence
          mechanism totally transparent from an application point of view.
          Note: it is highly recommended not to use "indirect" with
          "prefix", otherwise server cookie updates would not be sent to
          clients.

nocache   This option is recommended in conjunction with the insert mode
          when there is a cache between the client and HAProxy, as it
          ensures that a cacheable response will be tagged non-cacheable if
          a cookie needs to be inserted. This is important because if all
          persistence cookies are added on a cacheable home page for
          instance, then all customers will then fetch the page from an
          outer cache and will all share the same persistence cookie,
          leading to one server receiving much more traffic than others.
          See also the "insert" and "postonly" options.

postonly  This option ensures that cookie insertion will only be performed
          on responses to POST requests. It is an alternative to the
          "nocache" option, because POST responses are not cacheable, so
          this ensures that the persistence cookie will never get cached.
          Since most sites do not need any sort of persistence before the
          first POST which generally is a login request, this is a very
          efficient method to optimize caching without risking to find a
          persistence cookie in the cache.
          See also the "insert" and "nocache" options.

preserve  This option may only be used with "insert" and/or "indirect". It
          allows the server to emit the persistence cookie itself. In this
          case, if a cookie is found in the response, HAProxy will leave it
          untouched. This is useful in order to end persistence after a
          logout request for instance. For this, the server just has to
          emit a cookie with an invalid value (e.g. empty) or with a date in
          the past. By combining this mechanism with the "disable-on-404"
          check option, it is possible to perform a completely graceful
          shutdown because users will definitely leave the server after
          they logout.

httponly  This option tells HAProxy to add an "HttpOnly" cookie attribute
          when a cookie is inserted. This attribute is used so that a
          user agent doesn't share the cookie with non-HTTP components.
          Please check RFC6265 for more information on this attribute.

secure    This option tells HAProxy to add a "Secure" cookie attribute when
          a cookie is inserted. This attribute is used so that a user agent
          never emits this cookie over non-secure channels, which means
          that a cookie learned with this flag will be presented only over
          SSL/TLS connections. Please check RFC6265 for more information on
          this attribute.

domain    This option allows to specify the domain at which a cookie is
          inserted. It requires exactly one parameter: a valid domain
          name. If the domain begins with a dot, the browser is allowed to
          use it for any host ending with that name. It is also possible to
          specify several domain names by invoking this option multiple
          times. Some browsers might have small limits on the number of
          domains, so be careful when doing that. For the record, sending
          10 domains to MSIE 6 or Firefox 2 works as expected.

maxidle   This option allows inserted cookies to be ignored after some idle
          time. It only works with insert-mode cookies. When a cookie is
          sent to the client, the date this cookie was emitted is sent too.
          Upon further presentations of this cookie, if the date is older
          than the delay indicated by the parameter (in seconds), it will
          be ignored. Otherwise, it will be refreshed if needed when the
          response is sent to the client. This is particularly useful to
          prevent users who never close their browsers from remaining for
          too long on the same server (e.g. after a farm size change). When
          this option is set and a cookie has no date, it is always
          accepted, but gets refreshed in the response. This maintains the
          ability for admins to access their sites. Cookies that have a
          date in the future further than 24 hours are ignored. Doing so
          lets admins fix timezone issues without risking kicking users off
          the site.

maxlife   This option allows inserted cookies to be ignored after some life
          time, whether they're in use or not. It only works with insert
          mode cookies. When a cookie is first sent to the client, the date
          this cookie was emitted is sent too. Upon further presentations
          of this cookie, if the date is older than the delay indicated by
          the parameter (in seconds), it will be ignored. If the cookie in
          the request has no date, it is accepted and a date will be set.
          Cookies that have a date in the future further than 24 hours are
          ignored. Doing so lets admins fix timezone issues without risking
          kicking users off the site. Contrary to maxidle, this value is
          not refreshed, only the first visit date counts. Both maxidle and
          maxlife may be used at the time. This is particularly useful to
          prevent users who never close their browsers from remaining for
          too long on the same server (e.g. after a farm size change). This
          is stronger than the maxidle method in that it forces a
          redispatch after some absolute delay.

dynamic   Activate dynamic cookies. When used, a session cookie is
          dynamically created for each server, based on the IP and port
          of the server, and a secret key, specified in the
          "dynamic-cookie-key" backend directive.
          The cookie will be regenerated each time the IP address change,
          and is only generated for IPv4/IPv6.

attr      This option tells HAProxy to add an extra attribute when a
          cookie is inserted. The attribute value can contain any
          characters except control ones or ";". This option may be
          repeated.