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
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.
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> ...
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 :
Voir section 7 concernant l’utilisation des ACL.
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 :
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> ]
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 :
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 :
Exemples de backend de journalisation :
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
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*]
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 :
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 :
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>
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 :
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 :
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>
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 :
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 :
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>
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 :
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 :
Voir aussi : « capture cookie », « capture en-tête de requête », ainsi que la section 8 concernant la journalisation.
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 :
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>
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 :
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>
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 :
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> ...
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 :
Les algorithmes actuellement pris en charge sont :
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 :
Voir également : « compression offload », « compression direction », « compression minsize-req » et « compression minsize-res »
compression minsize-req <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
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)
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 ]
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 :
Il ne peut y avoir qu’un seul cookie de persistance par backend HTTP, et celui-ci peut être déclaré dans une section defaults. La valeur du cookie sera la valeur indiquée après le mot-clé « cookie » dans une déclaration server. Si aucun cookie n’est déclaré pour un serveur donné, le cookie n’est pas défini.
Exemples :
Voir aussi : « balance source », « capture cookie », « server » et « ignore-persist ».
declare capture [ request | response ] len <length>
Déclare une plage de capture.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non
Arguments :
Cette déclaration n’est disponible que dans la section frontend ou listen, mais l’emplacement réservé peut être utilisé dans les backends. Le mot-clé « request » alloue une plage de capture destinée à être utilisée dans la requête, et le mot-clé « response » alloue une plage de capture destinée à être utilisée dans la réponse.
Voir aussi : « capture-req », « capture-res » (convertisseurs d’échantillon), “capture.req.hdr”, “capture.res.hdr” (extractions d’échantillon), « http-request capture » et « http-response capture ».
default-server [param*]
Modifier les options par défaut d’un serveur dans un backend
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Exemple :
Voir également : « server » et section 5 concernant les options du serveur
default_backend <backend>
Spécifiez le backend à utiliser lorsque aucune règle “use_backend” n’a été matché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 :
Lorsque l’on effectue un commutateur de contenu entre un frontal et des backends en utilisant le mot-clé “use_backend”, il est souvent utile d’indiquer quel backend sera utilisé lorsque aucune règle ne correspond. Il s’agit généralement du backend dynamique, qui intercepte toutes les requêtes non déterminées.
Si un backend est désactivé ou non publié, les règles default_backend qui le ciblent seront ignorées et le traitement des flux restera sur le proxy d’origine.
Exemple :
Voir également : “use_backend”
description <string>
Décrivez un écouteur, un frontal ou un backend.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Arguments : chaîne
Permet d’ajouter une phrase de description de l’objet lié dans la page de statistiques HTML de HAProxy. La description s’affichera à droite du nom de l’objet qu’elle décrit. Aucun besoin d’échapper les espaces dans les arguments <string>.
disabled
Désactivez un proxy, un frontal ou un backend.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Le mot-clé « disabled » est utilisé pour désactiver une instance, principalement afin de libérer un port d’écoute ou de désactiver temporairement un service. L’instance sera toujours créée et sa configuration vérifiée, mais elle sera initialisée dans l’état « arrêté » et apparaîtra ainsi dans les statistiques. Elle ne recevra aucune requête, ni ne transmettra de vérifications de santé ni de journaux. Il est possible de désactiver plusieurs instances en même temps en ajoutant le mot-clé « disabled » dans une section « defaults ».
Par défaut, un backend désactivé ne peut pas être sélectionné pour le commutateur de contenu. Toutefois, une partie du trafic peut ignorer cette règle lorsque force-be-switch est utilisé.
Voir aussi : « enabled », « force-be-switch »
dispatch <address>:<port> (deprecated)
Définir une adresse de serveur par défaut
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Le mot-clé « dispatch » désigne un serveur par défaut utilisé lorsque aucun autre serveur ne peut accepter la connexion. À l’origine, il était utilisé pour acheminer les connexions non persistantes vers un chargeur d’équilibre auxiliaire. En raison de sa syntaxe simple, il a également été utilisé pour des relais TCP simples. Il est recommandé de ne pas l’utiliser afin d’améliorer la clarté, et d’utiliser à la place la directive « server ».
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5 en raison de limitations internes (absence de prise en charge du SSL, des connexions inactives, etc.). Son utilisation génère un avertissement qui peut être supprimé en activant la directive « expose-deprecated-directives » dans la section globale.
La bonne manière de procéder sans cette directive consiste à déclarer simplement un serveur avec la même adresse et le même port. Si la directive « dispatch » est combinée à d’autres serveurs, ces derniers doivent être configurés avec un poids nul afin de ne jamais être sélectionnés par l’algorithme de répartition de charge.
Exemple :
Voir également : « server »
dynamic-cookie-key <string>
Définir la clé secrète dynamique pour 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 : La clé secrète à utiliser.
Lorsque les cookies dynamiques sont activés (voir la directive « dynamic » pour les cookies), un cookie dynamique est créé pour chaque serveur (sauf si un cookie est explicitement spécifié dans la ligne « server »), en utilisant un hachage de l’adresse IP du serveur, du port TCP et de la clé secrète. Ainsi, il est possible d’assurer la persistance de session à travers plusieurs équilibreurs de charge, même si les serveurs sont ajoutés ou supprimés dynamiquement.
enabled
Activez un proxy, un frontal ou un backend.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Le mot-clé « enabled » est utilisé pour activer explicitement une instance, lorsque les paramètres par défaut ont été définis sur « disabled ». Cette utilisation est très rare.
Voir aussi : « disabled »
errorfile <code> <file>
Renvoyer le contenu d’un fichier au lieu des erreurs générées par HAProxy
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Il est important de comprendre que ce mot-clé n’a pas pour but de réécrire les erreurs renvoyées par le serveur, mais les erreurs détectées et renvoyées par HAProxy. C’est pourquoi la liste des erreurs prises en charge est limitée à un ensemble réduit.
Le code 200 est émis en réponse aux requêtes correspondant à une règle « monitor-uri ».
Les fichiers sont analysés au démarrage de HAProxy et doivent être valides selon la spécification HTTP. Ils ne doivent pas dépasser la taille de tampon configurée (BUFSIZE), qui est généralement de 16 ko, faute de quoi une erreur interne sera renvoyée. Il est également recommandé de ne pas référencer de contenus locaux (par exemple des images) afin d’éviter les boucles entre le client et HAProxy lorsque tous les serveurs sont hors service, ce qui provoquerait une erreur au lieu d’une image. Enfin, la réponse ne peut pas dépasser (tune.bufsize - tune.maxrewrite) afin que les règles « http-after-response » puissent encore fonctionner (voir “tune.maxrewrite”).
Les fichiers sont lus en même temps que la configuration et conservés en mémoire. Pour cette raison, les erreurs sont toujours renvoyées, même lorsque le processus est chrooté, et aucune modification de fichier n’est prise en compte pendant l’exécution du processus. Une méthode simple pour développer ces fichiers consiste à les associer au code d’état 403 et à interroger une URL bloquée.
Voir aussi : « http-error », « errorloc », « errorloc302 », « errorloc303 »
Exemple :
errorfiles <name> [<code> ...]
Importez, en totalité ou en partie, les fichiers d’erreur définis dans la section <name> http-errors.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Les erreurs définies dans la section http-errors sous le nom <name> sont importées dans le proxy actuel.
Si aucun code d’état n’est spécifié, tous les fichiers d’erreur de la section http-errors sont importés. Sinon,
seuls les fichiers d’erreur associés aux codes d’état indiqués sont importés. Ces fichiers d’erreur remplacent
les erreurs personnalisées déjà définies pour le proxy. Ils peuvent être remplacés par des fichiers ultérieurs.
Fonctionnellement, cela revient exactement à déclarer tous les fichiers d’erreur manuellement à l’aide des directives “errorfile”.
Voir également : « http-error », « errorfile », « errorloc », « errorloc302 », « errorloc303 » et section 12.4 concernant les erreurs HTTP.
Exemple :
errorloc <code> <url>
Renvoyer une redirection HTTP vers une URL au lieu des erreurs générées par HAProxy
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Il est important de comprendre que ce mot-clé n’a pas pour but de réécrire les erreurs renvoyées par le serveur, mais les erreurs détectées et renvoyées par HAProxy. C’est pourquoi la liste des erreurs prises en charge est limitée à un ensemble réduit.
Le code 200 est émis en réponse aux requêtes correspondant à une règle « monitor-uri ».
Notez que les deux mots-clés renvoient le code d’état HTTP 302, qui indique au client de récupérer l’URL désignée en utilisant la même méthode HTTP. Cela peut poser des problèmes importants en cas de méthodes autres que GET, comme POST, car l’URL envoyée au client pourrait ne pas être autorisée pour une requête autre que GET. Pour contourner ce problème, utilisez plutôt « errorloc303 », qui envoie le code d’état HTTP 303, indiquant au client que l’URL doit être récupérée à l’aide d’une requête GET.
Voir aussi : « http-error », « errorfile », « errorloc303 »
errorloc303 <code> <url>
Renvoyer une redirection HTTP vers une URL au lieu des erreurs générées par HAProxy
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Il est important de comprendre que ce mot-clé n’a pas pour but de réécrire les erreurs renvoyées par le serveur, mais les erreurs détectées et renvoyées par HAProxy. C’est pourquoi la liste des erreurs prises en charge est limitée à un ensemble réduit.
Le code 200 est émis en réponse aux requêtes correspondant à une règle « monitor-uri ».
Notez que les deux mots-clés renvoient le code d’état HTTP 303, qui indique au client de récupérer l’URL désignée en utilisant la méthode HTTP GET. Cela résout les problèmes habituels liés à « errorloc » et au code 302. Il est possible que certains navigateurs très anciens, conçus avant HTTP/1.1, ne le supportent pas, mais aucun problème de ce type n’a été signalé à ce jour.
Voir aussi : « http-error », « errorfile », « errorloc », « errorloc302 »
email-alert from <emailaddr>
Déclare l’adresse email à utiliser à la fois dans l’enveloppe et l’en-tête des alertes par courriel. Il s’agit de l’adresse depuis laquelle les alertes par courriel sont envoyées.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Exige également que les paramètres « email-alert mailers » et « email-alert to » soient définis, et, le cas échéant, active l’envoi d’alertes par courriel pour le proxy.
Voir aussi : « email-alert level », « email-alert mailers », « email-alert myhostname », « email-alert to », section 12.3 concernant les serveurs de messagerie.
email-alert level <level>
Déclare le niveau maximal de journalisation des messages pour lesquels des alertes par courriel seront envoyées. Cela agit comme un filtre sur l’envoi des alertes par courriel.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Par défaut, le niveau est alert
Exige également que les paramètres « email-alert from », « email-alert mailers » et « email-alert to » soient définis ; si c’est le cas, l’envoi d’alertes par courriel est activé pour le proxy.
Les alertes sont envoyées lorsque :
- Un serveur non mis en pause est marqué comme hors service lorsque
<level>est à l’état d’alerte ou inférieur - Un serveur mis en pause est marqué comme hors service lorsque
<level>est à l’état d’information ou inférieur - Un serveur est marqué comme opérationnel ou passe en état de vidage lorsque
<level>est à l’état d’information ou inférieur - L’option log-health-checks est activée,
<level>est à l’état d’information ou inférieur, et une mise à jour de l’état du contrôle d’état a lieu
Voir aussi : « email-alert from », « email-alert mailers », « email-alert myhostname », « email-alert to », section 12.3 concernant les serveurs de messagerie.
email-alert mailers <mailersect>
Déclare les serveurs de messagerie à utiliser lors de l’envoi d’alertes par courrier électronique
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Exige également que les paramètres « email-alert from » et « email-alert to » soient définis ; si c’est le cas, l’envoi d’alertes par courriel est activé pour le proxy.
Voir également : « email-alert from », « email-alert level », « email-alert myhostname », « email-alert to », section 12.3 concernant les serveurs de messagerie.
email-alert myhostname <hostname>
Déclare l’adresse du nom d’hôte à utiliser lors de la communication avec les serveurs de messagerie.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Par défaut, le nom d’hôte du système est utilisé.
Exige également que les paramètres « email-alert from », « email-alert mailers » et « email-alert to » soient définis ; si c’est le cas, l’envoi d’alertes par courriel est activé pour le proxy.
Voir également : « email-alert from », « email-alert level », « email-alert mailers », « email-alert to », section 12.3 concernant les serveurs de messagerie.
email-alert to <emailaddr>
Déclarez à la fois l’adresse du destinataire dans l’enveloppe et l’adresse de destination dans l’en-tête des alertes par courriel. C’est l’adresse à laquelle les alertes par courriel sont envoyées.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Exige également que les paramètres « email-alert mailers » et « email-alert to » soient définis, et, le cas échéant, active l’envoi d’alertes par courriel pour le proxy.
Voir aussi : « email-alert from », « email-alert level », « email-alert mailers », « email-alert myhostname », section 12.3 concernant les serveurs de messagerie.
error-log-format <fmt>
Spécifie la chaîne de format de journalisation à utiliser en cas d’erreur de connexion du côté frontal.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Ce directive spécifie la chaîne de format de journalisation utilisée pour les journaux contenant des informations relatives aux erreurs, aux délais d’expiration, aux réessais, aux redirigements ou aux codes d’état HTTP 5xx. Ce format sera brièvement utilisé pour chaque ligne de journal concernée par l’option « log-separate-errors », y compris les erreurs de connexion décrites dans la section 8.2.5 .
Si la directive est utilisée dans une section defaults, tous les frontaux ultérieurs utiliseront le même format de journalisation. Veuillez consulter section 8.2.6 qui traite en détail la chaîne de format de journalisation personnalisée.
La directive « error-log-format » remplace les directives « error-log-format » précédentes.
force-persist { if | unless } <condition>
Déclare une condition pour forcer la persistance sur les serveurs inaccessibles
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Par défaut, les requêtes ne sont pas acheminées vers les serveurs hors service. Il est possible de forcer ce comportement en utilisant « option persist », mais cette option est inconditionnelle et redirige vers un serveur valide si « option redispatch » est activée. Cela laisse très peu de possibilités pour forcer certaines requêtes à atteindre un serveur artificiellement marqué comme hors service lors d’opérations de maintenance.
L’instruction « force-persist » permet de déclarer diverses conditions basées sur des ACL qui, lorsqu’elles sont remplies, font en sorte qu’une requête ignore l’état « hors service » d’un serveur et tente tout de même de s’y connecter. Cela permet de démarrer un serveur, qui continue de renvoyer une erreur aux contrôles d’état, tout en permettant d’exécuter un navigateur spécialement configuré pour tester le service. Parmi les méthodes pratiques, on peut utiliser une adresse IP source spécifique, ou un cookie spécifique. Le cookie présente l’avantage de pouvoir être facilement added/removed depuis le navigateur à partir d’une page de test. Une fois le service validé, il devient possible d’ouvrir le service au monde entier en renvoyant une réponse valide aux contrôles d’état.
La persistance forcée est activée lorsque la condition « if » est remplie, ou sauf si la condition « unless » est remplie. Le réacheminement final est toujours désactivé lors de son utilisation.
Voir aussi : « option redispatch », « ignore-persist », « persist » et section 7 concernant l’utilisation des ACL.
external-check command <command>
Exécutable à exécuter lors d’un contrôle externe
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 :
Les arguments passés à la commande sont :
<proxy_address> <proxy_port> <server_address> <server_port>
Les <proxy_address> et <proxy_port> sont dérivés de la première écouteur qui est soit IPv4, soit IPv6, soit une socket UNIX. Dans le cas d’un écouteur de socket UNIX, le proxy_address sera le chemin de la socket et <proxy_port> sera la chaîne “NOT_USED”. Dans une section backend, il n’est pas possible de déterminer un écouteur, et les deux valeurs <proxy_address> et <proxy_port> auront pour valeur la chaîne “NOT_USED”.
Certains valeurs sont également fournies via des variables d’environnement.
Variables d’environnement :
Si la commande exécutée se termine avec un statut zéro, le contrôle est considéré comme réussi ; sinon, le contrôle est considéré comme échoué.
Exemple :
Voir aussi : « external-check », « option external-check », « external-check path »
external-check path <path>
Valeur de la variable d’environnement PATH utilisée lors de l’exécution d’un contrôle externe
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 :
Le chemin par défaut est “”.
Exemple :
Voir aussi : « external-check », « option external-check », « external-check command »
force-be-switch { if | unless } <condition>
Permet le choix d’une instance backend, même si elle est désactivée ou non publiée, lors du commutateur de contenu. Cette règle peut être utilisée par les administrateurs pour tester le trafic vers des services avant de les exposer au monde extérieur.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non
Voir aussi : « be-unpublished », « disabled »
filter <name> [param*]
Ajoutez le filtre <name> à la liste des filtres associée au proxy.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Arguments :
Plusieurs occurrences de la ligne de filtre peuvent être utilisées pour le même proxy. Le même filtre peut être référencé plusieurs fois si nécessaire.
Exemple :
Voir aussi : section 9 , « filter-sequence »
filter-sequence { requête | réponse } <filter_list>
Spécifie l’ordre d’exécution des filtres déclarés sur le proxy.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Liste séparée par des virgules de noms de filtres (<filter_list>) pour spécifier l’ordre d’exécution des filtres déclarés sur le proxy, respectivement pour le chemin de la requête ou de la réponse.
Lorsque filter-sequence n’est pas spécifié pour un chemin donné (par exemple : requête vs réponse), l’ordre dans lequel les filtres sont déclarés sur le proxy est utilisé.
Si la séquence de filtres omet certains filtres déclarés sur le proxy, ceux-ci ne seront pas exécutés. Ceci constitue une méthode efficace pour désactiver temporairement un filtre sans le supprimer de la configuration.
Exemple :
Voir aussi : « filter »
fullconn <conns>
Spécifiez à quelle charge du backend les serveurs atteindront leur maxconn
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Lorsqu’un serveur dispose d’un paramètre « maxconn » défini, cela signifie que son nombre de connexions simultanées ne dépassera jamais cette valeur. En outre, si un paramètre « minconn » est également défini, cela indique une limite dynamique qui suit la charge du backend. Le serveur acceptera alors toujours au moins <minconn> connexions, jamais plus de <maxconn>, et la limite sera ajustée progressivement entre ces deux valeurs lorsque le backend dispose de moins de <conns> connexions simultanées. Cela permet de limiter la charge sur les serveurs en conditions normales, tout en permettant de la pousser davantage en cas de charges importantes, sans surcharger les serveurs en cas de charges exceptionnelles.
Étant donné qu’il est difficile d’obtenir cette valeur correcte, HAProxy la définit automatiquement à 10 % de la somme des maxconns de tous les frontaux pouvant rediriger vers ce backend (selon les règles “use_backend” et “default_backend”). Ainsi, il est sans risque de la laisser non définie. Toutefois, les règles “use_backend” impliquant des noms dynamiques ne sont pas prises en compte, car il n’existe aucun moyen de savoir si elles pourraient correspondre ou non.
Exemple :
Voir aussi : « maxconn », « server »
guid <string>
Spécifiez un identifiant global unique sensible à la casse pour ce proxy.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
<string> doit être unique dans l’ensemble de la configuration haproxy, pour tous les types d’objets. Le format n’est pas spécifié afin de permettre à l’utilisateur de choisir sa politique d’affectation de noms. La seule restriction est sa longueur, qui ne peut pas dépasser 127 caractères. Toutes les valeurs alphanumériques ainsi que les caractères ‘.’, ‘:’, ‘-’ et ‘_’ sont autorisés. Voir également « shm-stats-file ».
hash-balance-factor <factor>
Spécifiez le facteur de répartition pour le hachage cohérent à charge bornée
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | non | oui
Arguments :
Spécifier un « hash-balance-factor » pour un serveur avec « hash-type consistent » active un algorithme qui empêche qu’un serveur reçoive trop de requêtes en même temps, même si certaines buckets de hachage reçoivent beaucoup plus de requêtes que d’autres. La mise à <factor> de 0 (valeur par défaut) désactive cette fonctionnalité. Sinon, <factor> est un pourcentage supérieur à 100. Par exemple, si <factor> est égal à 150, aucun serveur ne pourra avoir une charge supérieure à 1,5 fois la charge moyenne. Si des poids de serveurs sont utilisés, ceux-ci seront respectés.
Si le serveur de première choix est déclaré inapte, l’algorithme sélectionne un autre serveur en fonction du hachage de la requête, jusqu’à trouver un serveur disposant de capacité supplémentaire. Une valeur plus élevée de <factor> autorise un déséquilibre plus important entre les serveurs, tandis qu’une valeur plus faible de <factor> signifie qu’en moyenne, plus de serveurs seront examinés, ce qui impacte les performances. Des valeurs raisonnables se situent entre 125 et 200.
Ce paramètre est également utilisé par « balance random », qui repose en interne sur le mécanisme de hachage cohérent.
Voir également : « balance » et « hash-type ».
hash-preserve-affinity { always | maxconn | maxqueue }
Spécifiez une méthode d’affectation des flux aux serveurs avec la répartition de charge par hachage lorsque les serveurs sont saturés ou ont une file d’attente pleine.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Les valeurs suivantes peuvent être spécifiées :
- "always" : il s'agit de la stratégie par défaut. Un flux est affecté à un serveur en fonction d'un hachage, indépendamment du fait que le serveur soit actuellement surchargé.
- "maxconn" : lorsque sélectionné, les serveurs ayant la valeur "maxconn" définie et actuellement saturés sont ignorés. Un autre serveur est sélectionné en suivant l'anneau de hachage. Cela n'a aucun effet sur les serveurs qui n'ont pas défini "maxconn". Si tous les serveurs sont saturés, la requête est mise en file d'attente sur le dernier serveur de l'anneau de hachage situé avant le serveur initialement sélectionné.
- "maxqueue" : lorsque sélectionné, les serveurs ayant la valeur "maxconn" définie, ainsi que "maxqueue" définie sur une valeur non nulle (taille de file limitée) et dont la file est actuellement pleine sont ignorés. Un autre serveur est sélectionné en suivant l'anneau de hachage. Cette option n'a aucun effet sur les serveurs qui ne définissent pas à la fois "maxconn" et "maxqueue".
Voir aussi : « maxconn », « maxqueue », « hash-balance-factor »
hash-type <method> <function> <modifier>
Spécifiez une méthode à utiliser pour mapper les hachages sur les serveurs
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 :
Le type de hachage par défaut est « map-based » et est recommandé pour la plupart des utilisations. La fonction par défaut est « sdbm ». Le choix d’une fonction doit être fondé sur la plage des valeurs à hacher.
Voir aussi : « balance », « hash-balance-factor », « hash-preserve-affinity », « server »
http-after-response <action> <options...> [ { if | unless } <condition> ]
Contrôle d’accès pour toutes les réponses au niveau 7 (serveur, applet/service et internes).
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui
L’instruction http-after-response définit un ensemble de règles applicables au traitement au niveau couche 7. Ces règles sont évaluées dans l’ordre de leur déclaration lorsqu’elles sont rencontrées dans une section frontend, listen ou backend. Comme ces règles s’appliquent aux réponses, les règles du backend sont évaluées en premier, suivies par celles du frontend. Toute règle peut éventuellement être suivie d’une condition basée sur une ACL, auquel cas elle n’est évaluée que si la condition est vraie.
Contrairement aux règles http-response, celles-ci s’appliquent à toutes les réponses, tant aux réponses du serveur qu’aux réponses générées par HAProxy. Ces règles sont évaluées à la fin de l’analyse des réponses, avant la phase de transfert des données.
La condition est évaluée juste avant l’exécution de l’action, et celle-ci est exécutée exactement une fois. Il n’y a donc aucun problème si une action modifie un élément vérifié dans le cadre de la condition. Cela signifie également que plusieurs actions peuvent s’appuyer sur la même condition, de sorte que la première action qui modifie l’évaluation de la condition suffit à désactiver implicitement les actions restantes. Cette approche est utilisée, par exemple, lorsqu’il s’agit d’attribuer une valeur à une variable à partir de différentes sources lorsque celle-ci est vide. Il n’y a aucune limite au nombre d’instructions « http-after-response » par instance.
Le premier mot-clé après « http-after-response » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour cette action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « HTTP Aft »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Note : Les erreurs émises en phase précoce de l’analyse de la requête sont gérées par le multiplexeur à un niveau inférieur, avant toute analyse HTTP. Ainsi, aucun jeu de règles http-after-response n’est évalué sur ces erreurs.
Exemple :
http-check comment <string>
Définit un commentaire pour la règle http-check suivante, signalé dans les journaux en cas d’échec.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Il ne fonctionne qu’avec les règles connect, send et expect. Il est utile pour produire des rapports d’erreurs conviviaux.
Voir également : « option httpchk », « http-check connect », « http-check send » et « http-check expect ».
http-check connect [default] [port <expr>] [addr <ip>] [send-proxy]
Ouvre une nouvelle connexion pour effectuer un contrôle d’état HTTP
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Tout comme les contrôles d’état tcp-check, il est possible de configurer la connexion à utiliser pour effectuer un contrôle d’état HTTP. Cette directive doit également être utilisée pour décrire un scénario impliquant plusieurs échanges request/response, éventuellement sur des ports différents ou avec des serveurs distincts.
Lorsqu’aucun port TCP n’est configuré dans la ligne server ni dans la directive server port, le premier étape de la séquence http-check doit consister à préciser le port à l’aide de la directive « http-check connect ».
Dans un ensemble de règles http-check, une directive « connect » est obligatoire ; il est également obligatoire de commencer l’ensemble de règles par une règle « connect ». L’objectif est de garantir que l’administrateur sait ce qu’il fait.
Lorsqu’une connexion doit démarrer le jeu de règles, elle peut encore être précédée par des règles set-var, unset-var ou comment.
Exemples :
Voir également : « option httpchk », « http-check send », « http-check expect »
http-check disable-on-404
Activer un mode maintenance en cas de réponse HTTP/404 aux vérifications de santé
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsque cette option est activée, un serveur renvoyant un code HTTP 404 est exclu du chargement de la répartition, mais continue de recevoir les connexions persistantes. Cette fonctionnalité offre une méthode très pratique aux administrateurs Web pour effectuer un arrêt progressif de leurs serveurs. Il est également important de noter qu’un serveur détecté comme défaillant pendant qu’il était en ce mode ne déclenche pas d’alerte, uniquement un avis. Si le serveur répond à nouveau avec un code 2xx ou 3xx, il est immédiatement réintégré dans la ferme. L’état affiché sur la page de statistiques indique « NOLB » pour un serveur en ce mode. Il est essentiel de noter que cette option ne fonctionne qu’en conjonction avec l’option « httpchk ». Si cette option est utilisée avec « http-check expect », elle a priorité sur celle-ci, de sorte que les réponses 404 sont toujours considérées comme une interruption douce. Notez également qu’un serveur arrêté reste arrêté même s’il répond avec un code 404. Cette option n’est évaluée que pour les serveurs en cours d’exécution.
Voir également : « option httpchk » et « http-check expect ».
http-check expect [min-recv <int>] [comment <msg>]
Effectuez des contrôles d’état HTTP en tenant compte du contenu de la réponse ou de codes d’état spécifiques
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Par défaut, l’option « option httpchk » considère que les codes de réponse 2xx et 3xx sont valides, et que les autres sont invalides. Lorsque « http-check expect » est utilisé, il définit ce qui est considéré comme valide ou invalide. Une seule instruction « http-check » est autorisée dans un backend. Si un serveur ne répond pas ou expiré, le contrôle échoue évidemment. Les correspondances disponibles sont :
Il est important de noter que les réponses seront limitées à une taille définie par l’option globale “tune.bufsize”, qui vaut par défaut 16384 octets. Ainsi, les réponses trop grandes peuvent ne pas contenir le motif obligatoire lors de l’utilisation de « string » ou de « rstring ». Si une réponse de grande taille est absolument nécessaire, il est possible de modifier la taille maximale par défaut en définissant la variable globale. Toutefois, il convient de garder à l’esprit que l’analyse de réponses très grandes peut consommer des cycles CPU, notamment lors de l’utilisation d’expressions régulières, et qu’il est toujours préférable de cibler les vérifications sur des ressources plus petites.
Dans un jeu de règles http-check, la dernière règle expect peut être implicite. Si aucune règle expect n’est spécifiée après le dernier « http-check send », une règle expect implicite est définie pour correspondre aux codes d’état 2xx ou 3xx. Cela signifie que cette règle est également définie lorsque aucune règle « http-check » n’est présente du tout, à condition que seule l’option « option httpchk » soit définie.
Enfin, si « http-check expect » est combiné avec « http-check disable-on-404 », alors ce dernier a la priorité lorsque le serveur répond avec le code 404.
Exemples :
Voir également : « option httpchk », « http-check connect », « http-check disable-on-404 » et « http-check send ».
http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
Ajoutez une liste éventuelle d’en-têtes et/ou un corps à la requête envoyée lors des contrôles d’état HTTP.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
En plus de la ligne de requête définie par la directive « option httpchk », cette méthode est la façon valide d’ajouter des en-têtes et éventuellement un corps à la requête envoyée lors des contrôles d’état HTTP. Si un corps est défini, l’en-tête « Content-Length » associé est automatiquement ajouté. Par conséquent, cet en-tête ou l’en-tête « Transfer-encoding » ne doit pas être présent dans la requête fournie par « http-check send ». S’ils sont présents, ils seront ignorés. La méthode ancienne consistant à ajouter des en-têtes après la chaîne de version sur la ligne « option httpchk » est désormais obsolète.
De plus, « http-check send » ne prend pas en charge la persistance de connexion HTTP. Veillez à ce qu’un en-tête « Connection: close » soit automatiquement ajouté, sauf si un en-tête Connection a déjà été configuré via une entrée hdr.
Notez que l’en-tête Host et l’autorité de requête, lorsqu’ils sont tous deux définis, sont automatiquement synchronisés. Cela signifie que, lorsque la requête HTTP est envoyée, l’insertion d’un en-tête Host entraîne une mise à jour correspondante de l’autorité de requête. Par conséquent, ne vous étonnez pas si la valeur de l’en-tête Host remplace l’autorité de requête configurée.
Notez également que, pour l’instant, aucun en-tête Host n’est ajouté automatiquement dans les requêtes HTTP/1.1 ou ultérieures. Vous devez l’ajouter explicitement.
Voir également : « option httpchk », « http-check send-state » et « http-check expect ».
http-check send-state
Activer l’émission d’un en-tête d’état avec les contrôles d’état HTTP
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsque cette option est activée, HAProxy enverra systématiquement un en-tête spécial « X-HAProxy-Server-State » contenant une liste de paramètres indiquant à chaque serveur la manière dont HAProxy le perçoit. Cette fonctionnalité peut être utilisée, par exemple, lorsque un serveur est manipulé sans accès à HAProxy et que l’opérateur doit savoir si HAProxy le considère toujours comme actif ou non, ou s’il s’agit du dernier serveur d’une ferme.
L’en-tête est composé de champs séparés par des points-virgules, le premier étant un mot (“UP”, “DOWN”, “NOLB”), éventuellement suivi d’un nombre de vérifications valides avant la transition, tel qu’il apparaît dans l’interface de statistiques. Les en-têtes suivants sont au format “<variable>=<value>”, indiquant, dans un ordre quelconque, certaines valeurs disponibles dans l’interface de statistiques : - une variable “address”, contenant l’adresse du backend. Cela correspond au champ <address> dans la déclaration du serveur. Pour les sockets Unix, cela affichera “unix”.
- une variable "port", contenant le port du serveur backend. Cela correspond au champ `<port>` dans la déclaration du serveur. Pour les sockets Unix, la valeur sera "unix".
- une variable "name", contenant le nom du backend suivi d'un slash ("/") puis le nom du serveur. Cette variable peut être utilisée lorsque serveur est vérifié dans plusieurs backends.
- une variable "node" contenant le nom du nœud HAProxy, tel qu'indiqué dans la variable globale "node", sinon le nom d'hôte du système si non spécifié.
- une variable "weight" indiquant le poids du serveur, un slash ("/") et le poids total de la ferme (en ne comptant que les serveurs utilisables). Cela permet de savoir si d'autres serveurs sont disponibles pour prendre en charge la charge en cas de défaillance de celui-ci.
- une variable "scur" indiquant le nombre actuel de connexions simultanées sur le serveur, suivie d'une barre oblique ("/") puis du nombre total de connexions sur tous les serveurs du même backend.
- une variable "qcur" indiquant le nombre actuel de requêtes dans la file d'attente du serveur.
Exemple d’un en-tête reçu par le serveur d’application :
Voir également : « option httpchk », « http-check disable-on-404 » et « http-check send ».
http-check set-var(<var-name>[,<cond>...]) <expr>
Cette opération définit le contenu d’une variable. La variable est déclarée en inline.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Exemples :
http-check unset-var(<var-name>)
Libère une référence à une variable dans son contexte.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Exemples :
http-error status <code> [content-type <type>]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Définit un message d’erreur personnalisé à utiliser à la place des erreurs générées par HAProxy.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Ce directive peut être utilisée à la place de « errorfile » pour définir un message d’erreur personnalisé. Comme la directive « errorfile », elle est utilisée pour les erreurs détectées et renvoyées par HAProxy. Si un fichier d’erreur est défini, il est analysé au démarrage de HAProxy et doit être conforme aux normes HTTP. La réponse générée ne doit pas dépasser la taille de tampon configurée (BUFFSIZE), sinon une erreur interne sera renvoyée. Enfin, si vous envisagez d’utiliser des règles http-after-response pour réécrire ces erreurs, l’espace de tampon réservé doit être disponible (voir “tune.maxrewrite”).
Les fichiers sont lus en même temps que la configuration et conservés en mémoire. Pour cette raison, les erreurs sont toujours renvoyées, même lorsque le processus est chrooté, et aucune modification de fichier n’est prise en compte pendant l’exécution du processus.
Note : les erreurs 400/408/500 émises en phase précoce de l’analyse de la requête sont gérées par le multiplexeur à un niveau inférieur. Aucune mise en forme personnalisée n’est prise en charge à ce niveau. Seules les messages d’erreur statiques, définis avec la directive « errorfile », sont prises en charge. Toutefois, cette limitation n’existe que pendant l’analyse des en-têtes de la requête ou entre deux transactions.
Voir aussi : « errorfile », « errorfiles », « errorloc », « errorloc302 », « errorloc303 » et section 12.4 concernant les erreurs HTTP.
http-request <action> [options...] [ { if | unless } <condition> ]
Contrôle d’accès pour les requêtes au niveau 7
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui
L’instruction http-request définit un ensemble de règles applicables au traitement au niveau 7. Ces règles sont évaluées dans l’ordre de leur déclaration lorsqu’elles sont rencontrées dans une section frontend, listen ou backend. Chaque règle peut éventuellement être suivie d’une condition basée sur une ACL, auquel cas elle n’est évaluée que si la condition se traduit par une valeur vraie.
La condition est évaluée juste avant l’exécution de l’action, et celle-ci est exécutée exactement une fois. Il n’y a donc aucun problème si une action modifie un élément vérifié dans le cadre de la condition. Cela signifie également que plusieurs actions peuvent s’appuyer sur la même condition, de sorte que la première action qui modifie l’évaluation de la condition suffit à désactiver implicitement les actions restantes. Cette approche est utilisée, par exemple, lorsqu’il s’agit d’attribuer une valeur à une variable provenant de différentes sources lorsque celle-ci est vide. Il n’y a aucune limite au nombre d’instructions « http-request » par instance.
Le premier mot-clé après « http-request » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour cette action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « HTTP Req »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Exemple :
Exemple :
Exemple :
Voir aussi : « stats http-request », section 12.2 sur les listes d’utilisateurs et section 7 sur l’utilisation des ACL.
http-response <action> <options...> [ { if | unless } <condition> ]
Contrôle d’accès pour les réponses au niveau 7
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui
L’instruction http-response définit un ensemble de règles applicables au traitement au niveau couche 7. Ces règles sont évaluées dans l’ordre de leur déclaration lorsqu’elles sont rencontrées dans une section frontend, listen ou backend. Comme ces règles s’appliquent aux réponses, les règles du backend sont évaluées en premier, suivies par celles du frontend. Une règle peut éventuellement être suivie d’une condition basée sur une ACL, auquel cas elle n’est évaluée que si la condition est vraie.
La condition est évaluée juste avant l’exécution de l’action, et celle-ci est exécutée exactement une fois. Il n’y a donc aucun problème si une action modifie un élément vérifié dans le cadre de la condition. Cela signifie également que plusieurs actions peuvent s’appuyer sur la même condition, de sorte que la première action qui modifie l’évaluation de la condition suffit à désactiver implicitement les actions restantes. Cette approche est utilisée, par exemple, lorsqu’il s’agit d’attribuer une valeur à une variable provenant de différentes sources lorsque celle-ci est vide. Il n’y a aucune limite au nombre d’instructions « http-response » par instance.
Le premier mot-clé après « http-response » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour cette action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « HTTP Res »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Exemple :
Exemple :
Voir également : « http-request », section 12.2 sur les listes d’utilisateurs et section 7 sur l’utilisation des ACL.
http-reuse { never | safe | aggressive | always }
Déclare la manière dont les connexions HTTP inactives peuvent être partagées entre les requêtes
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Afin d’éviter le coût lié à la mise en place de nouvelles connexions vers les serveurs backend pour chaque requête HTTP, HAProxy tente de maintenir ces connexions inactives ouvertes après leur utilisation. Ces connexions sont spécifiques à un serveur et sont stockées dans une liste appelée pool, regroupées selon un ensemble de propriétés clés communes. Les requêtes HTTP ultérieures provoquent une recherche d’une connexion compatible partageant les mêmes propriétés dans le pool associé, ce qui permet de réutiliser cette connexion au lieu d’en établir une nouvelle.
Une limite sur le nombre de connexions inactives à maintenir sur un serveur peut être spécifiée à l’aide du mot-clé de configuration pool-max-conn pour le serveur. Les connexions inutilisées sont purgées périodiquement selon l’intervalle pool-purge-delay.
Les propriétés de connexion suivantes sont utilisées pour déterminer si une connexion inactif est éligible à la réutilisation pour une requête donnée :
- adresses source et destination
- protocole proxy
- options de socket TOS et mark
- nom de connexion, déterminé soit par le résultat de l’évaluation de l’expression « pool-conn-name » si présente, soit par l’expression « sni », qui par défaut vaut « req.hdr(host),field(1,:) », c’est-à-dire utilise le champ d’en-tête « Host » de la requête entrante sans deux-points ni numéro de port.
Dans certains cas, la recherche ou la réutilisation de connexion n’est pas effectuée en raison de restrictions supplémentaires. Cela est déterminé par la stratégie de réutilisation spécifiée via l’argument mot-clé :
- "never" : les connexions inactives ne sont jamais partagées entre les sessions. Ce mode peut être imposé pour annuler une stratégie différente héritée d'une section defaults ou dans un contexte de dépannage. Par exemple, si une ancienne application erronée considère que plusieurs requêtes effectuées sur la même connexion proviennent du même client, et qu'il n'est pas possible de corriger l'application, il peut être souhaitable de désactiver le partage des connexions pour un seul backend. Un exemple d'une telle application pourrait être une ancienne version d'HAProxy utilisant l'insertion de cookies en mode tunnel sans vérifier aucune requête après la première.
- "safe" : il s'agit de la stratégie par défaut et recommandée. La première requête d'une session est toujours envoyée via sa propre connexion, et seules les requêtes ultérieures peuvent être acheminées par d'autres connexions existantes. Cela garantit que, si le serveur ferme la connexion pendant l'envoi de la requête, le navigateur peut décider de la renvoyer silencieusement. Étant donné qu'il s'agit d'une configuration strictement équivalente à la mise en mémoire tampon régulière, aucune conséquence secondaire n'est à craindre. Une gestion spéciale est également appliquée aux connexions utilisant des protocoles sujets au blocage en tête de file (backend avec h2 ou fcgi). Dans ce cas, dès qu'au moins un flux est traité, la connexion utilisée est réservée pour gérer les flux de la même session. Dès lors que plus aucun flux n'est traité, la connexion est libérée et peut être réutilisée.
- "aggressive" : ce mode peut être utile dans les environnements de services web où tous les serveurs ne sont pas nécessairement connus, et où il serait avantageux de traiter la plupart des premières requêtes sur des connexions existantes. Dans ce cas, les premières requêtes ne sont envoyées que sur des connexions existantes ayant déjà été réutilisées au moins une fois, ce qui prouve que le serveur prend correctement en charge la réutilisation des connexions. Ce mode ne doit être utilisé que lorsque l'on est certain que le client peut réessayer une requête en échec de temps en temps, et où l'avantage de la réutilisation agressive des connexions dépasse nettement les inconvénients liés aux rares échecs de connexion.
- "always" : ce mode est recommandé uniquement lorsque le chemin vers le serveur est connu pour ne jamais interrompre les connexions existantes rapidement après les avoir libérées. Il permet d'envoyer la première requête d'une session vers une connexion existante. Cela peut offrir une amélioration de performance significative par rapport à la stratégie "safe" lorsque le backend est une ferme de cache, car ces composants présentent généralement un comportement constant et bénéficient du partage de connexion. Il est recommandé de maintenir le délai d'expiration "http-keep-alive" faible dans ce mode afin qu'aucune connexion morte ne reste utilisable. Dans la plupart des cas, cela entraîne les mêmes gains de performance que le mode "aggressive", mais avec des risques plus élevés. Ce mode ne doit être utilisé que lorsqu'il améliore la situation par rapport à "aggressive".
Notez également que les connexions utilisant des mécanismes d’authentification frauduleux (reliés à la connexion), tels que NTLM, sont marquées comme privées si possible et jamais partagées. Cela ne s’applique toutefois pas lors de l’utilisation d’un protocole à capacité de multiplexage et d’un mode de réutilisation dont la valeur est supérieure à la stratégie par défaut « sûre », car dans ce cas, rien n’empêche la connexion d’être déjà partagée.
Les règles déterminant si une connexion inactif doit être conservée ou fermée après traitement sont également régies par les paramètres “tune.pool-low-fd-ratio” (valeur par défaut : 20 %) et “tune.pool-high-fd-ratio” (valeur par défaut : 25 %). Ces valeurs correspondent au pourcentage total des descripteurs de fichiers utilisés par des connexions inactives au-delà duquel HAProxy va respectivement éviter de conserver une connexion ouverte après une réponse, et tuer activement les connexions inactives. Certains environnements utilisant un taux très élevé de connexions inactives, soit en raison d’une valeur globale “maxconn” trop faible, soit en raison d’un grand nombre de connexions HTTP/2 ou HTTP/3 sur le frontal (peu de connexions) mais de nombreuses connexions HTTP/1 sur le backend, peuvent observer un taux de réutilisation plus faible car trop peu de connexions sont conservées ouvertes. Dans ce cas, il peut être souhaitable de modifier ces seuils ou simplement d’augmenter la valeur globale de “maxconn”.
Dans certains cas rares, lorsque le nom d’hôte est utilisé pour distinguer les connexions TLS sortantes (par exemple, dans un proxy inverse), où la plupart des requêtes ciblent des hôtes différents, le taux de réutilisation sera très faible, et l’éviction automatique des connexions peu utilisées interviendra avant que les connexions n’aient eu la possibilité d’être réutilisées, car le mécanisme mesure continuellement le nombre moyen de connexions nécessaires pour assurer le service sans épuiser les ressources. Dans de tels cas, définir « pool-low-conn » à une valeur proche du nombre moyen attendu de connexions inactives peut aider à préserver davantage de connexions en incitant les threads à en établir eux-mêmes au lieu de tenter de choisir celles d’autres threads, réduisant ainsi la taille du pool de connexions disponibles.
Si un serveur hébergé localement utilise un seul certificat (avec plusieurs noms d’hôte ou des caractères génériques) et gère plusieurs sites, il peut être plus efficace d’utiliser simplement « no-sni-auto » sur la ligne « server » afin d’éviter de réserver une connexion à un nom d’hôte unique. Cela augmente considérablement le taux de réutilisation. Certains serveurs peuvent toutefois effectuer des vérifications excessives entre le nom d’hôte et le SNI, entraînant le rejet des requêtes ultérieures ; cette option nécessite donc une validation préalable. Le comportement par défaut (“sni-auto”) vise à garantir la sécurité même avec de tels serveurs.
Lorsque les groupes de threads sont activés explicitement, il est important de comprendre que les connexions inactives ne sont utilisables qu’entre les threads d’un même groupe. Il peut donc arriver qu’un déséquilibre de charge entre les groupes entraîne un besoin accru de connexions inactives, réduisant ainsi le taux de réutilisation. La même solution peut alors être appliquée (augmenter la valeur globale de « maxconn » ou augmenter les ratios de pool).
Voir aussi : « option http-keep-alive », « pool-conn-name », « pool-max-conn », « pool-purge-delay », « server maxconn », « sni », « thread-groups », “tune.pool-high-fd-ratio”, “tune.pool-low-fd-ratio”
http-send-name-header [<header>]
Ajoutez le nom du serveur à une requête. Utilisez la chaîne d’en-tête fournie par <header>
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
L’instruction « http-send-name-header » fait que le champ d’en-tête nommé <header> est défini au nom du serveur cible au moment où la requête est sur le point d’être envoyée sur le réseau. Toutes les occurrences existantes de cet en-tête sont supprimées. Lors de réessais ou de redirigements, le champ d’en-tête est mis à jour afin de refléter toujours le serveur auquel une tentative de connexion est effectuée. Étant donné que cet en-tête est modifié très tard dans la phase de configuration de la connexion, il peut avoir des effets imprévus sur des en-têtes déjà modifiés. Par exemple, son utilisation avec des en-têtes au niveau du transport, tels que connection, content-length, transfer-encoding, etc., risque fortement de provoquer l’envoi de requêtes non valides au serveur. C’est pourquoi les noms d’en-tête suivants sont interdits : host, content-length, transfer-encoding et connection.
Voir également : « server »
id <value>
Définir un identifiant persistant pour un proxy.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Arguments : aucun
Définir un identifiant persistant pour le proxy. Cet identifiant doit être unique et positif. Un identifiant non utilisé sera automatiquement attribué s’il n’est pas défini. En raison d’un comportement historique, la valeur 1 n’est pas utilisée à moins d’être explicitement définie. Par conséquent, la plus petite valeur automatiquement attribuée sera 2. Cet identifiant est actuellement retourné uniquement dans les statistiques.
ignore-persist { if | unless } <condition>
Déclarer une condition pour ignorer la persistance
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Par défaut, lorsque la persistance des cookies est activée, toutes les requêtes contenant le cookie sont persistantes sans condition (à condition que le serveur cible soit en fonctionnement).
L’instruction « ignore-persist » permet de déclarer diverses conditions basées sur des ACL qui, lorsqu’elles sont remplies, entraînent l’ignorance de la persistance pour une requête. Cela peut être utile pour équilibrer la charge des requêtes de fichiers statiques, qui n’ont souvent pas besoin de persistance. Cela peut également servir à désactiver entièrement la persistance pour un User-Agent spécifique (par exemple, certains robots de navigation web).
La persistance est ignorée lorsque la condition « if » est remplie, ou sauf si la condition « unless » est remplie.
Exemple :
Voir aussi : « force-persist », « cookie » et section 7 concernant l’utilisation des ACL.
load-server-state-from-file { global | local | none }
Permettre le rechargement sans interruption de HAProxy
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Ce directive indique à HAProxy le chemin vers un fichier dans lequel l’état des serveurs du processus précédent a été sauvegardé. Ainsi, au démarrage, avant de traiter le trafic, le nouveau processus peut appliquer les anciens états aux serveurs exactement comme s’il n’y avait pas eu de rechargement. L’objectif de la directive « load-server-state-from-file » est de préciser à HAProxy le fichier à utiliser. Pour l’instant, deux arguments permettent soit d’empêcher le chargement de l’état, soit de charger les états à partir d’un fichier contenant tous les backends et serveurs. Ce fichier d’état peut être généré en exécutant la commande « show servers state » sur le socket de statistiques et en redirigeant la sortie.
Le format du fichier est versionné et très spécifique. Pour le comprendre, veuillez lire la documentation de la commande « show servers state » (chapitre 9.3 du Guide d’administration).
Arguments :
Notes : - l’adresse IP du serveur est conservée entre les rechargements par défaut, mais son ordre peut être modifié grâce au paramètre « init-addr » du serveur. Cela signifie qu’un changement d’adresse IP effectué en ligne de commande en cours d’exécution sera conservé, et qu’une modification du résolveur local (par exemple /etc/hosts) pourra ne pas avoir d’effet si un fichier d’état est utilisé.
- Le poids du serveur est appliqué à partir du processus précédent, sauf s'il a changé entre les fichiers de configuration précédent et nouveau.
Exemple : Configuration minimale
global
stats socket /tmp/socket
server-state-file /tmp/server_state
defaults
load-server-state-from-file global
backend bk
server s1 127.0.0.1:22 check weight 11
server s2 127.0.0.1:22 check weight 12
Ensuite, on peut exécuter :
Contenu du fichier /tmp/server_state serait le suivant :
Exemple : Configuration minimale
global
stats socket /tmp/socket
server-state-base /etc/haproxy/states
defaults
load-server-state-from-file local
backend bk
server s1 127.0.0.1:22 check weight 11
server s2 127.0.0.1:22 check weight 12
Ensuite, on peut exécuter :
Contenu du fichier /etc/haproxy/states/bk serait le suivant :
Voir également : « server-state-file », « server-state-file-name » et « show servers state »
log global
Activez la journalisation par instance des événements et du trafic.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Préfixe :
Arguments :
Il est important de garder à l’esprit que ce sont les paramètres du frontal qui déterminent ce qui doit être journalisé pour une connexion, et que, en cas de commutation de contenu, les entrées de journal du backend seront ignorées. Les connexions sont journalisées au niveau « info ».
Toutefois, la déclaration de journalisation des backends définit la manière et l’emplacement où les changements d’état des serveurs seront journalisés. Le niveau « notice » sera utilisé pour indiquer un serveur qui passe à l’état actif, le niveau « warning » pour les signaux de terminaison et les arrêts définitifs du service, et le niveau « alert » pour les cas où un serveur tombe.
Note : Selon RFC3164, les messages sont tronqués à 1024 octets avant d’être émis.
Exemple :
log-format <fmt>
Spécifie la chaîne de format personnalisé à utiliser pour les journaux de trafic
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Ce directive spécifie la chaîne de format de journalisation utilisée pour tous les journaux issus du trafic passant par le frontal utilisant cette ligne. Si la directive est utilisée dans une section defaults, tous les frontaux ultérieurs utiliseront le même format de journalisation. Veuillez consulter section 8.2.6 qui traite en détail la chaîne de format de journalisation personnalisée.
Un format de journal spécifique, utilisé uniquement en cas d’erreur de connexion, peut également être défini, voir l’option « error-log-format ».
La directive « log-format » remplace les directives précédentes « option tcplog », « log-format », « option httplog » et « option httpslog ».
log-format-sd <fmt>
Spécifie la chaîne de format de journal personnalisé utilisée pour produire des données structurées RFC5424
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Cette directive spécifie la chaîne de format de journalisation structurée RFC5424 qui sera utilisée pour tous les journaux issus du trafic passant par le frontal utilisant cette ligne. Si la directive est utilisée dans une section defaults, tous les frontaux ultérieurs utiliseront le même format de journalisation. Voir la section 8.2.6 qui traite en détail la chaîne de format de journalisation.
Consultez https://tools.ietf.org/html/rfc5424#section-6.3 pour en savoir plus sur la partie données structurées de RFC5424.
Note : cette chaîne de format de journal sera utilisée uniquement par les journaux ayant défini le format de journalisation sur « rfc5424 ».
Exemple :
log-steps <steps>
Spécifie à quels stades du traitement des transactions les journaux doivent être générés.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Pendant le traitement des transactions tcp/http, HAProxy peut produire des journaux à différentes étapes du traitement (par exemple : accepter, se connecter, requête, réponse, fermer).
Par défaut, HAProxy émet une seule ligne de journal par transaction, une fois que toutes les composantes utilisées dans l’expression logformat ont pu être satisfaites. Cela signifie qu’en pratique, le journal est généralement émis à la fin de la transaction (après la fin de la réponse pour HTTP ou la fin de la connexion pour TCP), sauf si l’option logasap est utilisée.
La directive « log-steps » permet de préciser les instants exacts auxquels les journaux seront émis, et même de générer plusieurs journaux pour une même transaction. La valeur spéciale « all » peut être utilisée pour activer toutes les origines de journalisation disponibles, permettant ainsi de suivre une transaction de l’acceptation à la fermeture. Les origines de journalisation individuelles peuvent également être spécifiées en indiquant leurs noms séparés par des virgules, afin d’activer sélectivement la production des journaux.
Les origines de journalisation courantes sont : accept, connect, request, response, close.
Exemple :
Les origines de journalisation spécifiées sous forme de « étapes de journalisation » (comme accept, close) peuvent être utilisées telles quelles dans les profils de journalisation (après la directive « on »). Combiner les « étapes de journalisation » avec les profils de journalisation est particulièrement intéressant pour exercer un contrôle fin sur les journaux générés automatiquement par HAProxy lors du traitement des transactions.
Ce paramètre n’est pertinent que sur les frontaux ; il est ignoré sur les backends.
Voir aussi : « log-profile »
log-tag <string>
Spécifie l’étiquette de journalisation à utiliser pour tous les journaux sortants
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Définit le champ tag dans l’en-tête syslog à cette chaîne. La valeur par défaut est le log-tag défini dans la section global, sinon 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, ou de distinguer des instances clientes s’exécutant dans le même processus. Dans le backend, les journaux concernant les serveurs up/down utiliseront cette étiquette. À titre indicatif, il peut être pratique de définir un log-tag lié à un client hébergé dans une section defaults, puis d’ajouter tous les frontaux et backends de ce client, avant de commencer une autre instance cliente dans une nouvelle section defaults. Voir également la directive global « log-tag ».
max-keep-alive-queue <value>
Définir la taille maximale de la file d’attente du serveur pour la maintenance des connexions keep-alive
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
La réutilisation de la connexion serveur via HTTP keep-alive tente de réutiliser la même connexion serveur dès que possible, mais cela peut parfois s’avérer contre-productif, par exemple si un serveur possède un grand nombre de connexions tandis que d’autres sont inactives. Cela est particulièrement vrai pour les serveurs statiques.
Ce paramètre permet de définir un seuil sur le nombre de connexions en attente au-delà duquel HAProxy cesse de tenter de réutiliser le même serveur et privilégie la recherche d’un autre. La valeur par défaut, -1, signifie qu’aucune limite n’est appliquée. Une valeur nulle signifie que les requêtes keep-alive ne seront jamais mises en attente. Pour des serveurs très proches, accessibles avec une faible latence et peu sensibles à la rupture des connexions keep-alive, une valeur faible est recommandée (par exemple, un serveur local statique peut utiliser une valeur de 10 ou moins). Pour des serveurs distants souffrant d’une forte latence, des valeurs plus élevées peuvent être nécessaires afin de compenser la latence et/ou le coût associé au choix d’un autre serveur.
Notez que cela n’a aucune incidence sur les réponses qui sont conservées sur le même serveur consécutivement à une réponse 401. Elles continueront à être acheminées vers le même serveur, même si elles doivent être mises en file d’attente.
Voir également : « option http-server-close », « option prefer-last-server », la directive « maxconn » du serveur et la persistance des cookies.
max-session-srv-conns <nb>
Définir le nombre maximal de connexions sortantes que l’on peut maintenir en veille pour une session cliente donnée. La valeur par défaut est 5 (elle correspond exactement à MAX_SRV_LIST, définie au moment de la compilation).
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
maxconn <conns>
Corriger le nombre maximum de connexions simultanées sur un frontal
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Si le système le permet, il peut être utile, sur de grands sites, d’augmenter fortement cette limite afin que HAProxy gère les files d’attente de connexions, plutôt que de laisser les clients avec des tentatives de connexion non répondues. Cette valeur ne doit pas dépasser maxconn global. Gardez à l’esprit qu’une connexion consomme environ 33 ko de mémoire RAM, incluant deux tampons de taille tune.bufsize (16 ko par défaut) ainsi que d’autres données. Cela signifie qu’un système moyen doté de 1 Go de mémoire vive peut supporter environ 20 000 à 25 000 connexions simultanées, si correctement configuré.
En outre, lorsque <conns> est défini avec des valeurs élevées, il se peut que les serveurs ne soient pas dimensionnés pour supporter de telles charges ; il est donc généralement conseillé de leur attribuer des limites de connexion raisonnables.
Lorsque cette valeur est définie à zéro, ce qui est la valeur par défaut, la valeur globale « maxconn » est utilisée.
Voir également : « server », section « global » et son paramètre « maxconn », « fullconn »
mode { tcp|http|log|spop }
Définir le mode d’exécution ou le protocole de l’instance. Peut être utilisé dans les sections : defaults | frontal | listen | backend. oui | oui | oui | oui
Arguments :
Lors de la commutation de contenu, il est obligatoire que le frontal et le backend soient dans le même mode (généralement HTTP), faute de quoi la configuration sera refusée.
Exemple :
monitor fail { if | unless } <condition>
Ajoutez une condition pour signaler un échec à une requête HTTP de surveillance.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non
Arguments :
Cette instruction ajoute une condition qui peut forcer la réponse à une requête de surveillance à signaler une erreur. Par défaut, lorsque un composant externe interroge l’URI dédié à la surveillance, une réponse 200 est renvoyée. Lorsqu’une des conditions ci-dessus est remplie, HAProxy renvoie 503 au lieu de 200. Cela est très utile pour signaler une panne du site à un composant externe qui pourrait baser ses annonces de routage entre plusieurs sites sur la disponibilité signalée par HAProxy. Dans ce cas, on s’appuierait sur une ACL impliquant le critère « nbsrv ». Notez que « monitor fail » ne fonctionne qu’en mode HTTP. Les deux messages d’état peuvent être ajustés à l’aide de « errorfile » ou « errorloc » si nécessaire.
Exemple :
Voir aussi : « monitor-uri », « errorfile », « errorloc »
monitor-uri <uri>
Intercepte une URI utilisée par les requêtes de surveillance des composants externes
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Lorsqu’une requête HTTP faisant référence à <uri> sera reçue sur un frontal, HAProxy ne la transmettra ni ne la journalisera, mais renverra soit “HTTP/1.0 200 OK” soit “HTTP/1.0 503 Service unavailable”, selon les conditions d’échec définies avec “monitor fail”. Cela suffit généralement à toute sonde HTTP frontale pour détecter que le service est actif et en fonctionnement, sans transmettre la requête à un serveur backend. Notez que la méthode HTTP, la version et tous les en-têtes sont ignorés, mais la requête doit être au moins valide au niveau HTTP. Ce mot-clé ne peut être utilisé qu’avec un frontal en mode HTTP.
Les requêtes de surveillance sont traitées très tôt, juste après l’analyse de la requête, et même avant toute directive « http-request ». Seules les règles tcp-request sont appliquées avant celles-ci. Elles ne peuvent pas non plus être journalisées, ce qui est le comportement attendu. Une seule URI peut être configurée pour la surveillance ; lorsque plusieurs directives « monitor-uri » sont présentes, celle qui est définie en dernier détermine l’URI utilisée. Elles ne sont utilisées que pour signaler l’état de santé de HAProxy à un composant supérieur, rien de plus. Toutefois, il est possible d’ajouter un nombre quelconque de conditions à l’aide de « monitor fail » et des ACLs afin d’ajuster le résultat selon n’importe quelle vérification imaginable (le plus souvent, le nombre de serveurs disponibles dans un backend).
Note : si <uri> commence par une barre oblique (’/’), la correspondance est effectuée sur le chemin de la requête plutôt que sur l’URI de la requête. Il s’agit d’un contournement permettant aux requêtes HTTP/2 de correspondre à l’URI de surveillance. En effet, dans HTTP/2, les clients sont encouragés à n’envoyer que des URIs absolus.
Exemple :
Voir aussi : « monitor fail »
option abortonclose
Activer ou désactiver l’abandon anticipé du traitement non démarré lorsque le client se ferme
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
La prise en charge des connexions TCP permet la fermeture indépendante dans chaque direction, et une connexion dont une seule direction est fermée est souvent qualifiée de « demi-fermée ». À l’origine, lorsque l’écosystème HTTP était principalement basé sur le mode « fermeture », avec une seule requête et une seule réponse par connexion avant la fermeture, il était fréquent de voir des clients scriptés envoyer leur requête, fermer le côté envoi, attendre la réponse, recevoir l’indication de fermeture et terminer ainsi la connexion. Mais avec l’arrivée du keep-alive et de protocoles plus avancés, cette pratique a pratiquement disparu, et les seuls cas où un client ferme la connexion avant de recevoir sa réponse sont essentiellement ceux où l’utilisateur souhaite interrompre un transfert, ou lorsque le délai d’expiration est atteint et que la connexion est fermée.
Ces deux situations (demi-fermeture vs interruption) sont indiscernables du côté serveur (ici, l’écouteur HAProxy). Cela pose problème, car laisser la connexion ouverte et continuer à traiter une requête lorsque le client interrompt peut consommer beaucoup de ressources, notamment si la fermeture résulte d’un utilisateur cliquant sur le bouton « actualiser », ce qui signifie que de nouvelles requêtes sont en file d’attente sans que les précédentes soient interrompues. Inversement, interrompre systématiquement en cas de situation de demi-fermeture briserait un certain nombre d’applications TCP, ainsi que certaines applications HTTP sur les réseaux internes interagissant avec des agents hérités.
L’option « abortonclose » permet de choisir le comportement souhaité : - lorsqu’elle est présente dans un frontend, elle empêche le traitement des échanges TLS en attente sur une connexion demi-fermée. Cela peut résulter d’un utilisateur qui clique sur « actualiser » pendant une requête HTTPS sous une charge élevée, par exemple lors d’un basculement VRRP entre un nœud HAProxy actif et son sauvegarde : tous les clients se reconnectent en même temps au nouveau nœud, et chacun doit effectuer une main-handshake TLS coûteuse et complète. Si cette opération prend plus de quelques secondes, il est probable que certains utilisateurs abandonnent, et il est inutile de gaspiller des cycles CPU sur leurs échanges. Étant donné le coût CPU des échanges TLS, il est recommandé de laisser cette option activée sur les frontaux exposés à Internet. C’est le comportement par défaut pour les connexions TLS entrantes.
- quand présent dans un backend, il provoque l'abandon d'une requête qui n'a pas encore été envoyée au serveur (c'est-à-dire lorsqu'elle est en attente dans la file ou lors de la tentative de connexion). Si la requête est déjà en cours de traitement par un serveur, la connexion vers ce serveur est elle-même passée en demi-fermeture pour indiquer la même condition au serveur, qui décidera alors de la suite à donner. Ceci est la valeur par défaut pour les backends en mode HTTP.
Il est recommandé d’activer cette option sur les points de terminaison TLS exposés à Internet et sur les services HTTP, et de la désactiver pour les services TCP purs ainsi que pour les environnements hérités non exposés. Elle est activée par défaut dans les backends HTTP et peut être désactivée de force en préfixant le mot-clé par « no », soit dans la section backend elle-même, soit dans la section « defaults » dont elle hérite. Elle est également activée par défaut pour les écouteurs TLS et peut être désactivée de force en spécifiant « no option abortonclose » dans le frontend ou dans la section « defaults » dont il hérite.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « délai d’expiration de file d’attente » et les paramètres serveur « maxconn » et « maxqueue »
option accept-invalid-http-request (deprecated)
Activer ou désactiver la relaxation de l’analyse des requêtes HTTP
Le mot-clé « accept-invalid-http-request » est obsolète ; utilisez plutôt « option accept-unsafe-violations-in-http-request ».
option accept-invalid-http-response (deprecated)
Activer ou désactiver la relaxation de l’analyse des réponses HTTP
Le mot-clé « accept-invalid-http-response » est obsolète ; utilisez plutôt « option accept-unsafe-violations-in-http-response ».
option accept-unsafe-violations-in-http-request
Activer ou désactiver la relaxation de l’analyse des requêtes HTTP
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Par défaut, HAProxy respecte les différentes RFC HTTP en matière d’analyse des messages. Cela signifie que l’analyse des messages est assez stricte et provoque une erreur renvoyée au client pour les messages malformés. Ce comportement est souhaité, car de tels messages malformés sont essentiellement utilisés pour construire des attaques exploitant des faiblesses du serveur ou contourner les filtres de sécurité. Parfois, un navigateur défectueux ne respecte pas ces RFCs pour une raison quelconque (configuration, implémentation…) et le problème n’est pas immédiatement corrigé. Dans un tel cas, il est possible de relâcher le parseur HAProxy pour accepter certaines requêtes non valides en spécifiant cette option. La plupart des règles concernent l’analyse H1 pour des raisons historiques. Les versions plus récentes de HTTP ont tendance à être plus propres et les applications suivent plus strictement ces protocoles.
Lorsque cette option est définie, les règles suivantes s’appliquent :
* Dans H1 uniquement, les caractères non valides, y compris le caractère NULL, dans le nom d’en-tête ne seront pas rejetés ; toutefois, l’en-tête sera supprimé.
* Dans H1 uniquement, un caractère NULL dans une valeur d’en-tête sera accepté ;
* Dans H1 uniquement, les caractères dont la valeur est supérieure à 127 dans l'URI seront acceptés. La liste des caractères autorisés dans un URI est strictement définie par RFC3986. Les caractères 0 à 31, 32 (espace), 34 (« " »), 60 (« < »), 62 (« > »), 92 (« \ »), 94 (« ^ »), 96 (« ` »), 123 (« { »), 124 (« | »), 125 (« } »), 127 (suppression) et tous ceux dont la valeur est supérieure ne sont normalement pas autorisés. Dans H1, tous les caractères dont la valeur est comprise entre 0 et 32 ainsi que 127 seront systématiquement bloqués. Tous les caractères dont la valeur est supérieure à 127 (exclu) seront également bloqués, sauf lorsque cette option est activée. Les autres caractères (33 à 126) ne seront pas vérifiés du tout.
* Dans H1 et H2, les URL contenant des références de fragment ('#' après le chemin) seront acceptées ;
* En H1 uniquement, aucune vérification n'est effectuée sur l'autorité pour les requêtes CONNECT ;
* Dans H1 uniquement, aucune vérification ne sera effectuée contre la valeur de l'en-tête authority et de l'en-tête Host.
* Dans H1 uniquement, les contrôles de la version HTTP seront assouplis. Les requêtes GET HTTP/0.9 pourront ainsi être transmises sans version spécifiée, tout comme les requêtes utilisant d'autres noms de protocole, par exemple RTSP, ou plusieurs chiffres pour les versions majeure et mineure.
* Dans H1 uniquement, les requêtes WebSocket (RFC6455) ne présentant pas de champ d'en-tête "Sec-Websocket-Key" valide seront acceptées.
Cette option ne doit jamais être activée par défaut, car elle masque les bugs applicatifs et expose des failles de sécurité. Elle ne doit être déployée qu’après confirmation d’un problème.
Lorsque cette option est activée, les requêtes H1 invalides mais acceptées sont capturées afin de permettre une analyse ultérieure à l’aide de la requête « show errors » sur le socket de statistiques UNIX. Cette action permet également de confirmer que le problème a été résolu.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option accept-unsafe-violations-in-http-response » et « show errors » sur la socket de statistiques.
option accept-unsafe-violations-in-http-response
Activer ou désactiver la relaxation de l’analyse des réponses HTTP
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
De même que « option accept-unsafe-violations-in-http-request », cette option peut être utilisée pour assouplir les règles de parsing des réponses HTTP. Elle ne doit être activée que pour des serveurs hérités de confiance, afin d’accepter certaines réponses non conformes. La plupart de ces règles concernent le parsing H1 pour des raisons historiques. Les versions plus récentes de HTTP ont tendance à être plus rigoureuses, et les applications suivent désormais ces protocoles de manière plus stricte.
Lorsque cette option est définie, les règles suivantes s’appliquent :
* Dans H1 uniquement, les codes d’état de plus de 3 chiffres mais dont la valeur tient dans 16 bits ne sont pas rejetés.
* Dans H1 uniquement, les caractères non valides, y compris le caractère NULL, dans le nom d’en-tête ne seront pas rejetés ; toutefois, l’en-tête sera supprimé.
* Dans H1 uniquement, un caractère NULL dans une valeur d’en-tête sera accepté ;
* Dans H1 uniquement, les valeurs vides ou plusieurs occurrences de valeurs « chunked » pour l’en-tête Transfer-Encoding seront acceptées ;
* Dans H1 uniquement, aucune vérification ne sera effectuée contre la valeur de l'en-tête authority et de l'en-tête Host.
* Dans H1 uniquement, les tests sur la version HTTP seront assouplis. Cela permettra des noms de protocole différents (par exemple RTSP) ainsi que des chiffres multiples pour les versions majeure et mineure.
* Dans H1 uniquement, les réponses WebSocket (RFC6455) qui ne présentent pas un champ d'en-tête "Sec-Websocket-Accept" valide seront acceptées.
Cette option ne doit jamais être activée par défaut, car elle masque les bugs applicatifs et expose des failles de sécurité. Elle ne doit être déployée qu’après confirmation d’un problème.
Lorsque cette option est activée, les noms d’en-tête erronés seront toujours acceptés dans les réponses, mais la réponse complète sera capturée afin de permettre une analyse ultérieure à l’aide de la requête « show errors » sur le socket de statistiques UNIX. Cette action permet également de confirmer que le problème a été résolu.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option accept-unsafe-violations-in-http-request » et « show errors » sur la socket de statistiques.
option allbackups
Utilisez soit tous les serveurs de sauvegarde en même temps, soit uniquement le premier.
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 : aucun
Par défaut, le premier serveur de secours opérationnel reçoit tout le trafic lorsque tous les serveurs normaux sont hors service. Parfois, il peut être préférable d’utiliser plusieurs serveurs de secours simultanément, car un seul ne serait pas suffisant. Lorsque l’option allbackups est activée, la répartition de charge est effectuée entre tous les serveurs de secours lorsque tous les serveurs normaux sont indisponibles. Le même algorithme de répartition de charge est utilisé et les poids des serveurs sont respectés. Ainsi, il n’y a plus d’ordre de priorité entre les serveurs de secours.
Cette option est principalement utilisée avec des fermes de serveurs statiques destinées à renvoyer une page « désolé » lorsque l’application est complètement hors ligne.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
option checkcache
Analysez toutes les réponses des serveurs et bloquez les réponses comportant des cookies pouvant être mis en cache
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Certains frameworks de haut niveau définissent des cookies d’application partout et ne permettent pas toujours au développeur un contrôle suffisant sur la manière dont les réponses doivent être mises en cache. Lorsqu’un cookie de session est renvoyé pour un objet pouvant être mis en cache, le risque de croisement ou de vol de session entre utilisateurs empruntant les mêmes caches est élevé. Dans certaines situations, il est préférable de bloquer la réponse que de laisser des informations sensibles de session circuler librement.
L’option « checkcache » active une inspection approfondie de toutes les réponses des serveurs afin de garantir une conformité stricte à la spécification HTTP en matière de cacheabilité. Elle vérifie soigneusement les en-têtes « Cache-control », « Pragma » et « Set-cookie » dans la réponse du serveur afin de détecter tout risque de mise en cache d’un cookie par un proxy côté client. Lorsque cette option est activée, les seules réponses pouvant être transmises au client sont : - toutes celles qui ne contiennent pas d’en-tête « Set-Cookie » ; - toutes celles dont le code de retour est différent de 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501, à condition que le serveur n’ait pas défini un champ d’en-tête « Cache-control: public » ; - toutes celles résultant d’une requête utilisant une méthode autre que GET, HEAD, OPTIONS, TRACE, à condition que le serveur n’ait pas défini un champ d’en-tête « Cache-Control: public » ; - celles comportant un en-tête « Pragma: no-cache » ; - celles comportant un en-tête « Cache-control: private » ; - celles comportant un en-tête « Cache-control: no-store » ; - celles comportant un en-tête « Cache-control: max-age=0 » ; - celles comportant un en-tête « Cache-control: s-maxage=0 » ; - celles comportant un en-tête « Cache-control: no-cache » ; - celles comportant un en-tête « Cache-control: no-cache=“set-cookie” » ; - celles comportant un en-tête « Cache-control: no-cache=“set-cookie, » (permettant d’autres champs après « set-cookie »).
Si une réponse ne respecte pas ces exigences, elle sera bloquée comme si elle provenait d’une règle « http-response deny », avec une réponse « HTTP 502 bad gateway ». L’état de session affiche « PH– », ce qui signifie que le proxy a bloqué la réponse durant le traitement des en-têtes. En outre, une alerte sera envoyée dans les journaux afin d’informer les administrateurs qu’une correction est nécessaire.
En raison de l’impact élevé sur l’application, celle-ci doit être testée de manière approfondie avec l’option activée avant de passer en production. Il est également recommandé d’activer toujours cette option lors des tests, même si elle n’est pas utilisée en production, car elle signale les comportements potentiellement dangereux de l’application.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
option clitcpka
Activer ou désactiver l’envoi de paquets TCP keepalive 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 : aucun
Lorsqu’un pare-feu ou tout composant sensible à la session se trouve entre un client et un serveur, et que le protocole implique des sessions très longues avec des périodes d’inactivité prolongées (par exemple, les bureaux distants), il existe un risque que l’un des composants intermédiaires décide d’expirer une session restée inactif trop longtemps.
Activer les keep-alives TCP au niveau du socket fait que le système envoie régulièrement des paquets à l’autre extrémité de la connexion, la maintenant active. Le délai entre les sondes de keep-alive est contrôlé uniquement par le système et dépend à la fois du système d’exploitation et de ses paramètres de réglage.
Il est important de comprendre que les paquets keep-alive ne sont ni émis ni reçus au niveau de l’application. Seuls les piles réseau les perçoivent. Pour cette raison, même si l’une des extrémités du proxy utilise déjà des keep-alive pour maintenir sa connexion active, ces paquets keep-alive ne seront pas transférés à l’autre extrémité du proxy.
Veuillez noter que cela n’a rien à voir avec le keep-alive HTTP.
L’option « clitcpka » active l’envoi de sondes TCP keep-alive côté client d’une connexion, ce qui devrait aider à détecter les expiration de session entre HAProxy et un client.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option srvtcpka », « option tcpka »
option contstats
Activer la mise à jour continue des statistiques de trafic
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Par défaut, les compteurs utilisés pour le calcul des statistiques ne sont incrémentés qu’au moment où un flux se termine. Cela fonctionne assez bien lors de la mise à disposition d’objets de petite taille, mais avec des objets volumineux (par exemple des images ou archives importantes) ou lors du streaming A/V, le graphique généré à partir des compteurs HAProxy ressemble à un hérisson. Lorsque cette option est activée, les compteurs sont incrémentés fréquemment tout au long du flux, généralement toutes les 5 secondes, ce qui est souvent suffisant pour produire des graphiques nets. Le recalcule touche directement un chemin critique, aussi n’est-il pas activé par défaut, car il peut entraîner de nombreux réveils pour un très grand nombre de sessions et provoquer une légère baisse de performance.
option disable-h2-upgrade
Active ou désactive la mise à jour implicite HTTP/2 à partir d’une connexion client HTTP/1.x.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Par défaut, HAProxy est capable de mettre implicitement à jour une connexion client HTTP/1.x en connexion HTTP/2 si la première requête qu’il reçoit sur une connexion HTTP donnée correspond à l’introduction de connexion HTTP/2 (c’est-à-dire la chaîne « PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n »). Ainsi, il est possible de prendre en charge des clients HTTP/1.x et HTTP/2 sur des connexions non chiffrées. Cette option doit être utilisée pour désactiver la mise à jour implicite. Notez que cette mise à jour implicite n’est prise en charge que pour les proxies HTTP, ce qui s’applique également à cette option. Notez également qu’il est possible de forcer le HTTP/2 sur des connexions claires en spécifiant « proto h2 » dans la directive bind. Enfin, cette option s’applique à toutes les directives bind. Pour désactiver les mises à jour implicites de HTTP/2 pour une directive bind spécifique, il est possible d’utiliser « proto h1 ».
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
option dontlog-normal
Activer ou désactiver la journalisation des connexions normales et réussies
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Il existe des sites très volumineux traitant plusieurs milliers de connexions par seconde, pour lesquels la journalisation constitue un problème majeur. Certains sont même contraints de désactiver les journaux et ne peuvent pas déboguer les problèmes en production. L’activation de cette option garantit que les connexions normales, celles qui ne rencontrent aucune erreur, aucun délai d’expiration, aucune tentative de reconnexion ni aucun réacheminement, ne seront pas journalisées. Cela libère de l’espace disque pour les anomalies. En mode HTTP, le code d’état de la réponse est vérifié et les codes de retour 5xx seront toujours journalisés.
Il est fortement déconseillé d’utiliser cette option, car la plupart du temps, la clé des problèmes complexes se trouve dans les journaux normaux, qui ne seront pas journalisés ici. Si vous devez séparer les journaux, utilisez plutôt l’option « log-separate-errors ».
Voir aussi : « log », « dontlognull », « log-separate-errors » et section 8 concernant la journalisation.
option dontlognull
Activer ou désactiver la journalisation des connexions nulles
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Dans certains environnements, des composants se connectent régulièrement à divers systèmes afin de vérifier qu’ils sont toujours actifs. Cela peut provenir d’un autre répartiteur de charge ou de systèmes de surveillance. Par défaut, même une simple vérification de port ou un balayage génère une entrée dans les journaux. Si ces connexions polluent trop les journaux, il est possible d’activer l’option « dontlognull » pour indiquer qu’une connexion sur laquelle aucune donnée n’a été transférée ne sera pas journalisée, ce qui correspond généralement à ces sondes. Notez que les erreurs seront toutefois renvoyées au client et prises en compte dans les statistiques. Si ce n’est pas le comportement souhaité, l’option « http-ignore-probes » peut être utilisée à la place.
Il est généralement recommandé de ne pas utiliser cette option dans des environnements non contrôlés (par exemple, Internet), faute de quoi les scans et autres activités malveillantes ne seraient pas journalisés.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « log », « http-ignore-probes », « monitor-uri », et la section 8 concernant la journalisation.
option external-check
Utilisez des processus externes pour les contrôles d’état des serveurs
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Il est possible de tester l’état de santé d’un serveur à l’aide d’une commande externe. Cela est réalisé en exécutant l’exécutable défini par la directive « external-check command ».
Exige que l’option globale « external-check » soit définie.
Voir aussi : « external-check », « external-check command », « external-check path »
option forwarded [ proto ]
Activer l’insertion de l’en-tête forwarded défini par le RFC 7239 dans les requêtes envoyées aux serveurs
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Étant donné que HAProxy fonctionne en mode proxy inverse, les serveurs perdent une partie du contexte de la requête (origine de la requête : adresse IP du client, protocole utilisé…).
Une manière courante de contourner cette limitation consiste à utiliser les en-têtes bien connus x-forward-for et x-forward-* pour exposer une partie de ce contexte au niveau du servers/applications. sous-jacent. Bien que cette approche fonctionnait autrefois et soit largement déployée, elle n’est pas officiellement prise en charge par l’IETF et peut être à l’origine de problèmes d’interopérabilité ainsi que de failles de sécurité.
Pour résoudre ce problème, une nouvelle extension HTTP a été définie par l’IETF : l’en-tête forwarded (RFC7239). Plus d’informations ici : https://www.rfc-editor.org/rfc/rfc7239.html
L’utilisation de cet en-tête unique permet de transmettre de nombreuses informations au sein du même en-tête, et surtout, résout le problème de chaînage de proxy. (La RFC autorise plusieurs proxies en chaîne à ajouter leurs propres valeurs à un en-tête déjà existant).
Cette option peut être spécifiée dans les sections defaults, listen ou backend, mais sera ignorée dans les sections frontend.
Définir l’option forwarded sans argument entraîne l’utilisation du comportement implicite par défaut. Ce comportement par défaut active le paramètre proto et injecte l’adresse IP du client d’origine.
La configuration équivalente explicit/manual serait :
Le mot-clé « by » est utilisé pour activer le paramètre « by » (« nodename ») dans l’en-tête transféré. Il permet d’insérer des informations sur le proxy de la requête. La valeur de « by » sera définie sur l’adresse IP du proxy (adresse de destination) si disponible. Sinon (par exemple, avec un écouteur UNIX), « by » sera définie sur « unknown ».
Le mot-clé « by-expr » est utilisé pour activer le paramètre « by » (“nodename”) dans l’en-tête transféré. Il permet d’incorporer des informations sur le proxy de la requête. La valeur de « by » sera définie par le résultat de l’expression d’échantillonnage <by_expr>, si elle est valide, sinon elle sera définie à « unknown ».
Le mot-clé « for » est utilisé pour activer le paramètre « for » (« nodename ») dans l’en-tête transféré. Il permet d’incorporer des informations sur le client de la requête. La valeur de « for » sera définie sur l’adresse IP du client (adresse source) si disponible. Sinon (par exemple, avec un écouteur UNIX), « for » sera définie sur « unknown ».
Le mot-clé « for-expr » est utilisé pour activer le paramètre « for » (« nodename ») dans l’en-tête transféré. Il permet d’insérer des informations sur le client de la requête. La valeur de « for » sera définie sur le résultat de l’expression d’échantillonnage <for_expr>, si elle est valide, sinon elle sera définie sur « unknown ».
Le mot-clé ‘by_port’ est utilisé pour fournir les informations « nodeport » au paramètre « by ». ‘by_port’ exige que « by » ou « by-expr » soit défini, sinon il sera ignoré. Le champ « nodeport » sera défini sur le port du proxy (destination) s’il est disponible, sinon il sera ignoré.
Le mot-clé ‘by_port-expr’ est utilisé pour fournir les informations « nodeport » au paramètre « by ». ‘by_port-expr’ exige que « by » ou « by-expr » soit défini, sinon il sera ignoré. Le champ « nodeport » sera défini avec le résultat de l’expression d’échantillonnage <by_port_expr>, si celle-ci est valide, sinon il sera ignoré.
Le mot-clé ‘for_port’ est utilisé pour fournir les informations « nodeport » au paramètre « for ». ‘for_port’ exige que « for » ou « for-expr » soit défini, sinon il sera ignoré. Le « nodeport » sera défini sur le port client (source) s’il est disponible, sinon il sera ignoré.
Le mot-clé ‘for_port-expr’ est utilisé pour fournir les informations « nodeport » au paramètre « for ». ‘for_port-expr’ exige que « for » ou « for-expr » soit défini, sinon il sera ignoré. Le champ « nodeport » sera défini avec le résultat de l’expression d’échantillonnage <for_port_expr>, si celle-ci est valide, sinon il sera ignoré.
Exemples :
Voir aussi : « option forwardfor », « option originalto »
option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Activer l’insertion de l’en-tête X-Forwarded-For dans les requêtes envoyées aux serveurs
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Étant donné que HAProxy fonctionne en mode proxy inverse, les serveurs voient son adresse IP comme celle du client. Cela peut parfois être problématique lorsque l’adresse IP du client est attendue dans les journaux du serveur. Pour résoudre ce problème, HAProxy peut ajouter l’en-tête HTTP bien connu « X-Forwarded-For » à toutes les requêtes envoyées au serveur. Cet en-tête contient une valeur représentant l’adresse IP du client. Étant donné que cet en-tête est toujours ajouté à la fin de la liste d’en-têtes existante, le serveur doit être configuré pour ne jamais utiliser que la dernière occurrence de cet en-tête. Consultez le manuel du serveur pour savoir comment activer l’utilisation de cet en-tête standard. Notez que seule la dernière occurrence de l’en-tête doit être utilisée, car il est effectivement possible que le client ait déjà fourni cet en-tête.
Le mot-clé « header » peut être utilisé pour spécifier un nom d’en-tête différent afin de remplacer le nom par défaut « X-Forwarded-For ». Cela peut être utile lorsque vous avez déjà un en-tête « X-Forwarded-For » provenant d’une autre application (par exemple, stunnel) et que vous devez le préserver. De même, si votre backend ne utilise pas l’en-tête « X-Forwarded-For » et nécessite un autre en-tête (par exemple, les serveurs Web Zeus exigent « X-Cluster-Client-IP »).
Parfois, une même instance HAProxy peut être partagée entre un accès direct depuis un client et un accès via un proxy inverse (par exemple, lorsqu’un proxy inverse SSL est utilisé pour déchiffrer le trafic HTTPS). Il est possible de désactiver l’ajout de l’en-tête pour une adresse ou un réseau connu en ajoutant le mot-clé « except » suivi de l’adresse réseau. Dans ce cas, toute adresse IP source correspondant au réseau ne déclenchera pas l’ajout de cet en-tête. Les utilisations les plus courantes concernent les réseaux privés ou 127.0.0.1. Les versions IPv4 et IPv6 sont toutes deux prises en charge.
Autrement, le mot-clé « if-none » indique que l’en-tête ne sera ajouté que s’il est absent. Cela ne doit être utilisé que dans un environnement entièrement fiable, car cela pourrait entraîner une faille de sécurité si les en-têtes parvenant à HAProxy sont contrôlés par l’utilisateur final.
Cette option peut être spécifiée soit dans le frontal, soit dans le backend. Si au moins l’un d’eux l’utilise, l’en-tête sera ajouté. Notez que le paramètre d’en-tête défini dans le backend a priorité sur celui défini dans le frontal si les deux sont configurés. Dans le cas de l’argument « if-none », si au moins l’un du frontal ou du backend ne le précise pas, il impose que l’ajout soit obligatoire, et donc l’emporte.
Exemple :
Voir également : « option httpclose », « option http-server-close », « option http-keep-alive »
option h1-case-adjust-bogus-client
Activer ou désactiver le réglage de la casse des en-têtes HTTP/1 envoyés aux clients malveillants
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
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.
Lorsqu’HAProxy reçoit une réponse HTTP/1, ses noms d’en-têtes sont convertis en minuscules, manipulés et envoyés ainsi aux clients. Si un client est connu pour violer les normes HTTP et échouer à traiter une réponse provenant d’HAProxy, il est possible de transformer les noms d’en-têtes en minuscules vers un format différent lors de la mise en forme et de l’envoi de la réponse au client, en activant cette option et en précisant la liste des en-têtes à reformater à l’aide des directives globales « h1-case-adjust » ou « h1-case-adjust-file ». Ceci ne doit être qu’une solution de contournement temporaire, le temps que le client soit corrigé, car les clients nécessitant de telles solutions de contournement pourraient être vulnérables aux attaques d’envoi de contenu masqué et doivent être absolument corrigés.
Veuillez noter que cette option n’affecte pas les clients conformes aux normes.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option h1-case-adjust-bogus-server », « h1-case-adjust », « h1-case-adjust-file ».
option h1-case-adjust-bogus-server
Activer ou désactiver le traitement de la casse des en-têtes HTTP/1 envoyés aux serveurs malveillants
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
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.
Lorsqu’HAProxy reçoit une requête HTTP/1, les noms d’en-têtes sont convertis en minuscules, manipulés et envoyés de cette manière aux serveurs. Si un serveur est connu pour violer les normes HTTP et échouer à traiter une requête provenant d’HAProxy, il est possible de transformer les noms d’en-têtes en minuscules vers un format différent lors de la mise en forme et de l’envoi de la requête au serveur, en activant cette option et en précisant la liste des en-têtes à reformater à l’aide des directives globales « h1-case-adjust » ou « h1-case-adjust-file ». Ceci ne doit être qu’une solution de contournement temporaire, le temps que le serveur soit corrigé, car les serveurs nécessitant de telles solutions de contournement pourraient être vulnérables aux attaques d’envoi de contenu masqué et doivent absolument être corrigés.
Veuillez noter que cette option n’affecte pas les serveurs conformes aux normes.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option h1-case-adjust-bogus-client », « h1-case-adjust », « h1-case-adjust-file ».
option http-buffer-request
Activer ou désactiver l’attente de la totalité du corps de la requête HTTP avant de poursuivre
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Il peut parfois être souhaitable d’attendre la réception du corps d’une requête HTTP avant de prendre une décision. C’est précisément ce que fait « balance url_param », par exemple. Le premier cas d’utilisation consiste à tamponner les requêtes provenant de clients lents avant de se connecter au serveur. Un autre cas d’utilisation consiste à prendre la décision de routage en fonction du contenu du corps de la requête. Cette option, placée dans un frontal ou un backend, force le traitement HTTP à attendre jusqu’à réception intégrale du corps ou remplissage complet du tampon de requête. Elle peut entraîner des effets indésirables avec certaines applications qui abuse de HTTP en s’attendant à des transmissions non tamponnées entre le frontal et le backend ; elle ne doit donc certainement pas être utilisée par défaut.
Voir aussi : « option http-no-delay », « timeout http-request », « http-request wait-for-body »
option http-drop-request-trailers
Supprimer les traînées HTTP de la requête lors de son envoi au serveur
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | non | oui
Arguments : aucun
Lorsque cette option est activée, tous les trailers HTTP trouvés dans une requête sont supprimés avant d’être envoyés au serveur.
RFC9110#section-6.5.1 indique que les champs de bout de message peuvent être fusionnés avec les champs d’en-tête. Cette opération doit être effectuée intentionnellement, mais elle peut poser problème pour certaines applications, notamment si des clients malveillants masquent des champs d’en-tête sensibles dans la partie des champs de bout de message et que certains intermédiaires les fusionnent avec les en-têtes sans vérification spécifique. Dans ce cas, cette option peut être activée sur le backend afin de supprimer tout champ de bout de message détecté dans les requêtes avant leur envoi au serveur.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option http-drop-response-trailers »
option http-drop-response-trailers
Supprimer les traînées HTTP de la réponse lors de son envoi au client
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Cette option est similaire à « option http-drop-request-trailers », mais elle doit être utilisée pour supprimer les champs de bout de réponse avant de les envoyer aux clients.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option http-drop-request-trailers »
option http-ignore-probes
Activez ou désactivez la journalisation des connexions nulles et des délais d’expiration des requêtes
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Récemment, certains navigateurs ont commencé à implémenter une fonctionnalité de « pré-connexion », consistant à établir une connexion en avance à certains sites web récemment visités, au cas où l’utilisateur souhaiterait les visiter. Cela entraîne la création de nombreuses connexions vers des sites web, qui aboutissent à un code 408 Délai d’expiration de la requête si le délai d’expiration est atteint en premier, ou à un code 400 Requête incorrecte lorsque le navigateur décide de les fermer en premier. Ces événements polluent les journaux et alimentent les compteurs d’erreurs. Une option « option dontlognull » existait déjà, mais elle est insuffisante dans ce cas. À la place, cette option effectue les actions suivantes : - empêche l’envoi de tout message 400/408 au client si rien n’a été reçu sur une connexion avant sa fermeture ; - empêche l’émission de tout message de journalisation dans cette situation ; - empêche l’incrémentation de tout compteur d’erreur
Ainsi, la connexion vide est ignorée silencieusement. Notez qu’il est préférable de ne pas utiliser cette option sauf si son utilité est claire, car elle masque des problèmes réels. La raison la plus courante d’une requête non reçue accompagnée d’un code 408 provient d’une incohérence de MTU entre le client et un élément intermédiaire tel qu’un VPN, qui bloque les paquets trop volumineux. Ces problèmes sont généralement observés avec les requêtes POST ainsi qu’avec les requêtes GET comportant de grandes cookies. Les journaux sont souvent la seule manière de les détecter.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « log », « dontlognull », « errorfile » et la section 8 sur la journalisation.
option http-keep-alive
Activer ou désactiver la persistance HTTP du client vers le serveur pour les connexions HTTP/1.x
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Par défaut, HAProxy fonctionne en mode keep-alive pour les connexions persistantes HTTP/1.x : pour chaque connexion, il traite chaque requête et réponse, puis laisse la connexion inactif des deux côtés. Ce mode peut être modifié par plusieurs options, telles que « option http-server-close » ou « option httpclose ». Cette option permet de rétablir le mode keep-alive, ce qui peut être utile lorsque un autre mode a été utilisé dans une section « defaults ».
Paramètre « option http-keep-alive » active le mode keep-alive HTTP côté client et côté serveur. Cela permet d’obtenir la latence la plus faible côté client (réseau lent) et la réutilisation de session la plus rapide côté serveur, au prix de la maintenance de connexions inactives vers les serveurs. En général, il est possible, avec cette option, d’atteindre environ le double du débit de requêtes que l’option « http-server-close » permet sur des objets de petite taille. Deux situations principales rendent cette option utile :
- lorsque le serveur n'est pas conforme à HTTP et authentifie la connexion
au lieu des requêtes (par exemple, authentification NTLM)
- lorsque le coût de l'établissement de la connexion au serveur est important par rapport au coût de récupération de l'objet associé depuis le serveur.
Ce dernier cas peut survenir lorsque le serveur est un serveur statique rapide ou un cache.
Actuellement, les journaux ne préciseront pas si les requêtes proviennent de la même session. La date d’acceptation indiquée dans les journaux correspond à la fin de la requête précédente, et le temps de requête correspond au temps passé en attente d’une nouvelle requête. Le délai d’expiration de la requête keep-alive reste lié au délai d’expiration défini par « timeout http-keep-alive » ou « timeout http-request », si ce dernier n’est pas configuré.
Cette option désactive et remplace toute option précédente « option httpclose » ou « option http-server-close ».
Voir également : « option httpclose », « option http-server-close », « option prefer-last-server » et « option http-pretend-keepalive ».
option http-no-delay
Instructez le système à privilégier les délais d’interaction faibles par rapport aux performances en HTTP
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
En HTTP, chaque charge utile est unidirectionnelle et ne comporte aucune notion d’interactivité. Tout agent doit être capable de mettre en file d’attente les données de manière à garantir un délai raisonnablement faible. Certains rares cas d’applications serveur-à-serveur abuse du protocole HTTP et s’attendent à ce que la phase de charge utile soit hautement interactive, avec de nombreuses tranches de données entrelacées dans les deux sens au sein d’une même requête. Cela n’est absolument pas pris en charge par la spécification HTTP et ne fonctionnera pas à travers la plupart des proxies ou serveurs. Lorsque de telles applications tentent de procéder ainsi via HAProxy, cela fonctionne, mais elles subiront des délais élevés dus aux optimisations réseau qui favorisent les performances en incitant le système à attendre que suffisamment de données soient disponibles afin d’envoyer uniquement des paquets complets. Les délais typiques s’élèvent à environ 200 ms par aller-retour. Notez qu’un tel comportement ne se produit qu’en cas d’utilisation anormale. Les utilisations normales, telles que les requêtes CONNECT ou les WebSockets, ne sont pas affectées.
Lorsque l’option http-no-delay est présente dans le frontend ou le backend utilisé par une connexion, toutes ces optimisations sont désactivées afin de rendre les échanges aussi rapides que possible. Bien entendu, cela ne garantit en rien la fonctionnalité, car cela peut provoquer des dysfonctionnements ailleurs. Toutefois, si cela fonctionne via HAProxy, il fonctionnera à la vitesse maximale. Cette option ne doit jamais être utilisée par défaut, et ne doit jamais être utilisée du tout sauf si une application défectueuse est identifiée. L’usage de cette option entraîne une augmentation de la consommation de bande passante et de la charge CPU, ce qui peut réduire significativement les performances dans les environnements à forte latence.
Voir également : « option http-buffer-request »
option http-pretend-keepalive
Définir si HAProxy doit annoncer keepalive pour la connexion HTTP/1.x au serveur ou non
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsqu’il est exécuté avec l’option « option http-server-close » ou « option httpclose », HAProxy ajoute un en-tête « Connection: close » à la requête HTTP/1.x transmise au serveur. Malheureusement, certains serveurs, lorsqu’ils détectent cet en-tête, renoncent automatiquement à utiliser l’encodage par tronçons pour les réponses de longueur inconnue, ce qui est totalement sans rapport. Le résultat est qu’un client ou un cache pourrait recevoir une réponse incomplète sans s’en rendre compte, et considérer la réponse comme complète.
En définissant « option http-pretend-keepalive », HAProxy fait croire au serveur qu’il maintiendra la connexion ouverte. Le serveur ne basculera alors pas vers le comportement anormal indésirable décrit ci-dessus. Une fois que HAProxy a reçu toute la réponse, il ferme la connexion avec le serveur exactement comme il le ferait avec « option httpclose ». Ainsi, le client reçoit une réponse normale et la connexion est correctement fermée côté serveur.
Il est recommandé de ne pas activer cette option par défaut, car la plupart des serveurs ferment la connexion eux-mêmes de manière plus efficace après le dernier paquet, et libèrent leurs tampons légèrement plus tôt. En outre, le paquet supplémentaire sur le réseau pourrait réduire légèrement les performances maximales globales. Toutefois, il convient de noter qu’en activant cette option, HAProxy aura un travail légèrement moindre à accomplir. Ainsi, si HAProxy constitue le goulot d’étranglement de l’ensemble de l’architecture, l’activation de cette option pourrait économiser quelques cycles CPU.
Cette option peut être définie dans les sections backend et listen. Son utilisation dans une section frontend sera ignorée, et un avertissement sera signalé au démarrage. Il s’agit d’une option liée au backend, aussi n’y a-t-il aucune raison réelle de la définir dans un frontend.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option httpclose », « option http-server-close » et « option http-keep-alive »
option http-restrict-req-hdr-names { preserve | delete | reject }
Définir la politique HAProxy concernant les noms d’en-tête de requête HTTP contenant des caractères en dehors de l’ensemble “[a-zA-Z0-9-]”
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Cette option peut être utilisée pour restreindre les noms d’en-tête de requête aux caractères alphanumériques et au trait d’union ([A-Za-z0-9-]). Cela peut être obligatoire pour assurer l’interopérabilité avec des serveurs non conformes à HTTP qui échouent à traiter certains caractères dans les noms d’en-tête. Elle peut également être obligatoire pour les applications FastCGI, car tous les caractères non alphanumériques dans les noms d’en-tête sont remplacés par un trait de soulignement (’_’). Il devient ainsi facile de confondre des noms d’en-tête et de contourner certaines règles. Par exemple, les en-têtes « X-Forwarded-For » et “X_Forwarded-For” sont tous deux convertis en “HTTP_X_FORWARDED_FOR” en FastCGI.
Notez que cette option est évaluée par proxy et après l’évaluation des règles http-request.
option http-server-close
Activer ou désactiver la fermeture de la connexion HTTP/1.x côté serveur
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Par défaut, HAProxy fonctionne en mode keep-alive pour les connexions persistantes HTTP/1.x : pour chaque connexion, il traite chaque requête et réponse, puis laisse la connexion inactif des deux côtés. Ce mode peut être modifié par plusieurs options, telles que « option http-server-close » ou « option httpclose ». L’activation de « option http-server-close » active le mode de fermeture de connexion HTTP côté serveur tout en conservant la capacité à supporter le keep-alive HTTP et le pipelining côté client. Cela permet d’obtenir la plus faible latence côté client (réseau lent) et la réutilisation de session la plus rapide côté serveur, afin de préserver les ressources serveur, de manière similaire à « option httpclose ». Cela permet également de servir des serveurs non capables de keep-alive en mode keep-alive aux clients, à condition qu’ils respectent les exigences de RFC7230. Veuillez noter que certains serveurs ne respectent pas toujours ces exigences lorsqu’ils reçoivent « Connection: close » dans la requête. Le résultat est qu’aucune connexion keep-alive ne sera utilisée. Une solution de contournement consiste à activer « option http-pretend-keepalive ».
Actuellement, les journaux ne préciseront pas si les requêtes proviennent de la même session. La date d’acceptation indiquée dans les journaux correspond à la fin de la requête précédente, et le temps de requête correspond au temps passé en attente d’une nouvelle requête. Le délai d’expiration de la requête keep-alive reste lié au délai d’expiration défini par « timeout http-keep-alive » ou « timeout http-request », si ce dernier n’est pas configuré.
Cette option peut être définie aussi bien dans un frontend que dans un backend. Elle est activée si au moins l’un des deux — frontend ou backend — qui gère une connexion l’a activée. Elle désactive et remplace toute option précédente « option httpclose » ou « option http-keep-alive ». Veuillez consulter la section 4 (“Proxies”) pour comprendre comment cette option s’combine avec les autres lorsque les options frontend et backend diffèrent.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option httpclose », « option http-pretend-keepalive » et « option http-keep-alive ».
option http-use-proxy-header
Utilisez l’en-tête Proxy-Connection non standard à la place de Connection
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Bien que RFC7230 indique explicitement que les agents HTTP/1.1 doivent utiliser l’en-tête Connection pour indiquer leur préférence concernant les connexions persistantes ou non persistantes, les navigateurs et les proxies ignorent cet en-tête pour les connexions proxyées et utilisent à la place l’en-tête Proxy-Connection, non documenté et non standard. Le problème survient lorsqu’on cherche à placer un répartiteur de charge entre les navigateurs et de tels proxies, car il y aura une différence entre ce que HAProxy comprend et ce que le client et le proxy ont convenu.
En définissant cette option dans un frontal, HAProxy peut automatiquement passer à l’utilisation de cet en-tête non standard s’il détecte des requêtes proxyées. Une requête proxyée est définie ici comme une requête dont l’URI ne commence ni par ‘/’ ni par ‘*’. Cette option est incompatible avec le mode tunnel HTTP. Notez que cette option ne peut être spécifiée que dans un frontal et affecte la requête tout au long de sa durée de vie.
En outre, lorsque cette option est définie, une requête nécessitant une authentification passe automatiquement à l’utilisation des en-têtes d’authentification du proxy si elle est elle-même une requête proxyée. Cela permet de vérifier ou d’imposer l’authentification devant un proxy existant.
Cette option doit normalement ne jamais être utilisée, sauf devant un proxy.
Voir également : « option httpclose », et « option http-server-close ».
option httpchk
Active le protocole HTTP pour vérifier l’état de santé des serveurs
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Par défaut, les contrôles d’état des serveurs se limitent à la tentative d’établissement d’une connexion TCP. Lorsque l’option « option httpchk » est spécifiée, une requête HTTP complète est envoyée une fois la connexion TCP établie, et les réponses 2xx et 3xx sont considérées comme valides, tandis que toutes les autres indiquent une défaillance du serveur, y compris l’absence de réponse.
Associé aux directives « http-check », il est possible de personnaliser la requête envoyée lors des contrôles d’état HTTP ou les règles de correspondance sur la réponse. Il est également possible de configurer une séquence send/expect, tout comme avec la directive « tcp-check » pour les contrôles d’état TCP.
La configuration du serveur est utilisée par défaut pour ouvrir des connexions afin d’effectuer des contrôles d’état HTTP. Il est également possible de remplacer les paramètres du serveur à l’aide de règles « http-check connect ».
L’option « httpchk » n’exige pas nécessairement un backend HTTP ; elle fonctionne également avec des backends TCP brut. Cela est particulièrement utile pour vérifier des scripts simples liés à des ports dédiés via le démon inetd. Toutefois, elle s’appuie toujours internement sur un multiplexeur HTX. Cela implique que la mise en forme des requêtes et l’analyse des réponses seront strictes.
Exemples :
Voir également : « option ssl-hello-chk », « option smtpchk », « option mysql-check », « option pgsql-check », « http-check » et les options serveur « check », « port » et « inter ».
option httpclose
Activer ou désactiver la fermeture de la connexion HTTP/1.x
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Par défaut, HAProxy fonctionne en mode keep-alive concernant les connexions persistantes HTTP/1.x : pour chaque connexion, il traite chaque requête et réponse, puis laisse la connexion inactif des deux côtés. Ce mode peut être modifié par plusieurs options, telles que « option http-server-close » ou « option httpclose ».
Si l’option « option httpclose » est définie, HAProxy fermera la connexion client ou serveur, selon l’emplacement où l’option est configurée. Le frontal est considéré pour les connexions client, tandis que le backend est considéré pour les connexions serveur. Si l’option est définie sur un écouteur, elle s’applique aux connexions client et serveur. Elle vérifiera si un en-tête « Connection: close » est déjà présent dans chaque sens, et l’ajoutera si nécessaire.
Cette option peut également être combinée avec « option http-pretend-keepalive », ce qui empêche l’envoi de l’en-tête de requête « Connection: close », mais entraîne tout de même la fermeture de la connexion une fois la réponse entière reçue.
Il désactive et remplace toute option précédente « option http-server-close » ou « option http-keep-alive ».
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option http-server-close ».
option httplog [ clf ]
Activer la journalisation des requêtes HTTP, de l’état du flux et des minuteries
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Par défaut, le format de sortie des journaux est très limité, ne comportant que les adresses source et destination, ainsi que le nom de l’instance. En spécifiant « option httplog », chaque ligne de journalisation adopte un format bien plus riche, incluant, sans s’y limiter, la requête HTTP, les temporisateurs de connexion, l’état du flux, le nombre de connexions, les en-têtes et cookies capturés, le nom du frontal, du backend et du serveur, ainsi que bien entendu l’adresse source et les ports.
Spécifier uniquement « option httplog » efface automatiquement le mode « clf » s’il était défini par défaut.
L’option httplog remplace toute directive log-format précédemment définie.
Voir également : section 8 concernant la journalisation.
option httpslog
Activer la journalisation des requêtes HTTPS, de l’état du flux et des compteurs
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Par défaut, le format de sortie des journaux est très limité, ne comportant que les adresses source et destination, ainsi que le nom de l’instance. En spécifiant « option httpslog », chaque ligne de journalisation adopte un format bien plus riche, incluant, sans s’y limiter, la requête HTTP, les temporisateurs de connexion, l’état du flux, le nombre de connexions, les en-têtes et cookies capturés, le nom du frontal, du backend et du serveur, les états de vérification du certificat SSL et de la négociation SSL, ainsi que bien entendu l’adresse source et les ports.
L’option httpslog remplace toute directive log-format précédemment définie.
Voir également : section 8 concernant la journalisation.
option idle-close-on-response
Éviter de fermer les connexions frontend inactives si une interruption douce est en cours
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Par défaut, les connexions inactives seront fermées lors d’un arrêt doux. Dans certains environnements, un client communiquant avec le proxy peut avoir préparé certaines connexions inactives afin d’envoyer des requêtes ultérieurement. Si aucune tentative de nouvelle tentative en cas d’erreur d’écriture n’est effectuée, cela peut entraîner des erreurs pendant le rechargement de haproxy. Même si une implémentation correcte devrait réessayer en cas d’erreurs connection/write, cette option a été introduite afin de maintenir la compatibilité descendante avec les versions de HAProxy antérieures à la 2.4. En effet, avant la version 2.4, HAProxy attendait une dernière requête et réponse pour ajouter un en-tête « connection: close » avant de fermer la connexion, informant ainsi le client que la connexion ne serait pas réutilisable.
Dans un exemple concret, ce comportement a été observé sur AWS en utilisant un ALB devant un HAProxy. Le résultat final était un code 502 envoyé par l’ALB lors des rechargements du HAProxy.
Les utilisateurs sont avertis qu’utiliser cette option peut augmenter le nombre de processus anciens si les connexions restent inactives trop longtemps. Il se peut qu’il soit nécessaire d’ajuster les délais d’expiration client et/ou le paramètre « hard-stop-after » en cas de rechargements fréquents.
Voir également : « timeout client », « timeout client-fin », « timeout http-request », « hard-stop-after »
option independent-streams
Activer ou désactiver le traitement indépendant des délais d’expiration dans les deux sens
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Par défaut, lorsque des données sont envoyées via une socket, le délai d’expiration d’écriture et le délai d’expiration de lecture de cette socket sont actualisés, car nous considérons qu’il y a une activité sur cette socket, et nous ne disposons d’aucun autre moyen de deviner si nous devrions recevoir des données ou non.
Bien que ce comportement par défaut soit souhaitable pour presque toutes les applications, il existe une situation où il est préférable de le désactiver, et de ne mettre à jour le délai d’expiration de lecture que si des données entrantes sont reçues. Cela se produit dans les flux avec des délais d’expiration élevés et de faibles quantités de données échangées, comme les sessions telnet. Si le serveur disparaît soudainement, les données de sortie s’accumulent dans les tampons de socket du système, les deux délais d’expiration sont correctement mis à jour, et il n’existe aucun moyen de savoir que le serveur ne les reçoit pas, aussi ne déclenchons-nous pas de délai d’expiration. Toutefois, lorsque le protocole sous-jacent échoe toujours les données envoyées, il suffirait à lui seul de détecter le problème en utilisant le délai d’expiration de lecture. Notez que ce problème ne se produit pas avec des protocoles plus verbeux, car les données ne s’accumulent pas longtemps dans les tampons de socket.
Lorsque cette option est définie sur le frontal, elle désactive les mises à jour du délai d’expiration en lecture pour les données envoyées au client. Ce cas est probablement peu utile. Lorsqu’elle est définie sur le backend, elle désactive les mises à jour du délai d’expiration en lecture pour les données envoyées au serveur. Cette action risque généralement de rompre les grandes requêtes HTTP provenant de lignes lentes, utilisez-la donc avec précaution.
Voir également : « timeout client », « timeout server » et « timeout tunnel »
option ldap-check
Utilisez les contrôles d’état LDAPv3 pour le test des serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Il est possible de vérifier que le serveur communique correctement en LDAPv3, et non seulement de tester qu’il accepte la connexion TCP. Lorsque cette option est activée, un message de liaison simple anonyme LDAPv3 est envoyé au serveur, et la réponse est analysée afin de détecter un message de réponse de liaison LDAPv3.
Le serveur est considéré comme valide uniquement lorsque la réponse LDAP contient un resultCode success (http://tools.ietf.org/html/rfc4511#section-4.1.9 ).
La journalisation des requêtes de liaison dépend du serveur ; consultez la documentation correspondante pour savoir comment la configurer.
Exemple :
Voir aussi : « option httpchk »
option log-health-checks
Activer ou désactiver la journalisation des mises à jour d’état des contrôles d’état
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 : aucun
Par défaut, les échecs de contrôle d’état sont journalisés si le serveur est UP et les contrôles d’état réussis sont journalisés si le serveur est DOWN, de sorte que la quantité d’informations supplémentaires est limitée.
Lorsque cette option est activée, tout changement d’état du contrôle d’état ou de la santé du serveur est journalisé, ce qui permet de savoir qu’un serveur a échoué à des contrôles d’état ponctuels avant de planter, ou précisément quand il a cessé de répondre avec un statut HTTP valide, puis quand le port a commencé à rejeter les connexions, enfin quand le serveur a cessé toute réponse.
Notez que les changements d’état non provoqués par les contrôles d’état (par exemple, enable/disable en ligne de commande) ne sont pas intentionnellement journalisés par cette option.
Voir aussi : « option httpchk », « option ldap-check », « option mysql-check », « option pgsql-check », « option redis-check », « option smtpchk », « option tcp-check », « log » et la section 8 sur la journalisation.
option log-separate-errors
Modifier le niveau de journalisation pour les connexions non entièrement réussies
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Parfois, il n’est pas facile de repérer les erreurs dans les journaux. Cette option permet à HAProxy d’augmenter le niveau des journaux contenant potentiellement des informations intéressantes, telles que les erreurs, les délais d’expiration, les tentatives de reconnexion, les redirigements, ou les codes d’état HTTP 5xx. Le niveau passe de « info » à « err ». Cela permet de les journaliser séparément dans un fichier différent avec la plupart des démons syslog. Prenez garde à ne pas les supprimer du fichier d’origine, sinon vous perdriez l’ordre des événements, qui fournit des informations très importantes.
Avec cette option, les grands sites traitant plusieurs milliers de connexions par seconde peuvent journaliser le trafic normal dans un tampon tournant et ne sauvegarder que les journaux d’erreurs plus petits.
Voir aussi : « log », « dontlognull », « dontlog-normal » et section 8 concernant la journalisation.
option logasap
Active ou désactive la journalisation précoce.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Par défaut, les journaux sont émis lorsque tous les alias de format de journal et les extraits d’échantillon utilisés dans la définition de la chaîne de format de journal renvoient une valeur, ou lorsque le flux est terminé. Cela permet aux chaînes de format de journal intégrées de tenir compte du temps de transfert ou du nombre d’octets dans les messages de journal.
Lors de la gestion de connexions longues, telles que les transferts de fichiers volumineux ou RDP, il peut s’écouler un certain temps avant que la requête ou la connexion n’apparaisse dans les journaux. En utilisant « option logasap », le message de journalisation est généré dès que la connexion au serveur est établie en mode tcp, ou dès que le serveur envoie l’intégralité des en-têtes en mode http. Les informations manquantes dans les journaux seront le nombre total d’octets, qui ne reflétera que la quantité de données transférées avant la création du message, et le temps total, qui ne tiendra pas compte de la durée restante de la connexion ou du temps de transfert. Pour le cas HTTP, il est bon de capturer l’en-tête de réponse Content-Length afin que les journaux indiquent au moins le nombre d’octets attendus lors du transfert.
Exemples :
Voir également : « option httplog », « capture réponse en-tête » et section 8 concernant la journalisation.
option mysql-check [ user <username> [ { post-41 | pre-41 | post-80 } ] ]
Utilisez les contrôles d’état MySQL pour tester les serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Si vous spécifiez un nom d’utilisateur, le test consiste à envoyer deux paquets MySQL : un paquet d’authentification client, puis un paquet QUIT pour fermer correctement la session MySQL. Nous analysons ensuite le paquet d’initialisation d’échange MySQL et/ou le paquet d’erreur. Il s’agit d’un test basique mais utile, qui ne génère ni erreur ni connexion interrompue côté serveur. Toutefois, il nécessite un utilisateur autorisé non verrouillé, sans mot de passe. Pour créer un utilisateur basique limité dans MySQL, avec des limites de ressources facultatives :
Si vous ne spécifiez pas de nom d’utilisateur (cela est obsolète et non recommandé), le contrôle se limite à l’analyse du paquet d’initialisation de handshake MySQL ou du paquet d’erreur ; aucun paquet n’est envoyé en ce mode. Il a été signalé qu’il peut provoquer un verrouillage si le contrôle est trop fréquent et/ou s’il y a une trafic insuffisant. En réalité, vous devez, dans ce cas, vérifier la valeur de MySQL “max_connect_errors” comme si une connexion était établie avec succès en moins de “max_connect_errors” tentatives après une interruption précédente de connexion, auquel cas le compteur d’erreurs pour l’hôte est réinitialisé à zéro. Si le serveur HAProxy est bloqué, la commande « FLUSH HOSTS » est la seule manière de le débloquer.
N’oubliez pas que cela ne vérifie ni la présence de la base de données ni sa cohérence. Pour effectuer cette vérification, vous pouvez utiliser une vérification externe avec xinetd, par exemple.
La vérification nécessite MySQL >=3.22 ; pour les versions plus anciennes, utilisez la vérification TCP.
Souvent, un serveur MySQL entrant doit voir l’adresse IP du client pour diverses raisons, notamment le contrôle des privilèges par IP et la journalisation des connexions. Lorsqu’il est possible de le faire, il est souvent judicieux de masquer l’adresse IP du client lors de la connexion au serveur en utilisant l’argument « usesrc » du mot-clé « source », ce qui nécessite que la fonctionnalité de proxy transparent soit compilée, ainsi qu’un serveur MySQL qui achemine le client via la machine hébergeant HAProxy.
Voir aussi : « option httpchk »
option nolinger
Activer ou désactiver le nettoyage immédiat des ressources de session après fermeture
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Lorsque les clients ou les serveurs interrompent les connexions de manière inappropriée (par exemple, en étant physiquement déconnectés), les délais d’expiration de session sont déclenchés et la session est fermée. Toutefois, elle reste dans l’état FIN_WAIT1 pendant une certaine durée dans le système, consommant des ressources et pouvant limiter la capacité à établir de nouvelles connexions.
Lorsque cela se produit, il est possible d’activer l’option nolinger, qui force le système à supprimer immédiatement les données en attente sur une socket lors de sa fermeture. Ainsi, un paquet TCP RST est émis, les données en attente sont tronquées, et la session est instantanément supprimée des tables du système. L’effet généralement observable par un client est que les réponses sont tronquées si la fermeture intervient avec le dernier bloc de données (par exemple, dans une réponse de redirection ou d’erreur). Du côté serveur, cela peut aider à libérer immédiatement les ports sources lors du transfert quand un client interrompt une connexion en tunnel. Dans les deux cas, des réinitialisations TCP sont émises, et comme la session est détruite instantanément, aucune retransmission ne sera tentée. Sur un réseau bruyant, cela peut aggraver les problèmes, notamment lorsqu’un pare-feu est présent du côté bruyant, car le pare-feu pourrait détecter et traiter la réinitialisation (et supprimer ainsi sa session), puis bloquer tout trafic ultérieur pour cette session, y compris les retransmissions provenant de l’autre côté. Ainsi, si l’autre côté ne reçoit pas cette réinitialisation, il ne recevra jamais de nouveau RST, et le pare-feu pourrait enregistrer de nombreux paquets bloqués.
Pour toutes ces raisons, il est fortement recommandé de ne pas utiliser cette option, sauf si absolument nécessaire en dernier recours. Dans la plupart des cas, l’utilisation des délais « client-fin » ou « server-fin » permet d’obtenir des résultats similaires avec un comportement plus fiable. Sur Linux, il est également possible d’utiliser la configuration bind ou server « tcp-ut ».
Cette option peut être utilisée aussi bien sur les frontaux que sur les backends, selon le côté où elle est requise. Utilisez-la sur le frontal pour les clients, et sur le backend pour les serveurs. Bien que cette option soit techniquement prise en charge dans les sections « defaults », elle ne doit en aucun cas être utilisée là-bas, car elle risque de se propager accidentellement à des sections qui ne doivent pas l’utiliser, provoquant ainsi des problèmes.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « timeout client-fin », « timeout server-fin », mots-clés bind ou server « tcp-ut ».
option originalto [ except <network> ] [ header <name> ]
Activer l’insertion de l’en-tête X-Original-To dans les requêtes envoyées aux serveurs
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Étant donné qu’HAProxy peut fonctionner en mode transparent, chaque requête provenant d’un client peut être redirigée vers le proxy, et HAProxy lui-même peut acheminer chaque requête vers un environnement SQUID complexe, ce qui fait perdre l’hôte de destination provenant de SO_ORIGINAL_DST. Cela est problématique lorsque l’on souhaite appliquer des règles d’accès basées sur les adresses IP de destination. Pour résoudre ce problème, HAProxy peut ajouter un nouvel en-tête HTTP « X-Original-To » à toutes les requêtes envoyées au serveur. Cet en-tête contient une valeur représentant l’adresse IP de destination d’origine. Cette fonctionnalité doit être configurée de manière à ne jamais utiliser que la dernière occurrence de cet en-tête. Notez qu’il ne faut utiliser que la dernière occurrence de cet en-tête, car il est effectivement possible que le client ait déjà fourni un tel en-tête.
Le mot-clé « header » peut être utilisé pour spécifier un nom d’en-tête différent afin de remplacer le nom par défaut « X-Original-To ». Cela peut être utile lorsque vous avez déjà un en-tête « X-Original-To » provenant d’une autre application et que vous devez le préserver. De même, si votre serveur backend ne utilise pas l’en-tête « X-Original-To » et nécessite un autre en-tête.
Parfois, une même instance HAProxy peut être partagée entre un accès direct depuis un client et un accès via un proxy inverse (par exemple lorsqu’un proxy inverse SSL est utilisé pour déchiffrer le trafic HTTPS). Il est possible de désactiver l’ajout de l’en-tête pour une adresse ou un réseau cible connus en ajoutant le mot-clé « except » suivi de l’adresse réseau. Dans ce cas, toute adresse IP de destination correspondant au réseau ne déclenchera pas l’ajout de cet en-tête. Les utilisations les plus courantes concernent les réseaux privés ou 127.0.0.1. Les versions IPv4 et IPv6 sont toutes deux prises en charge.
Cette option peut être spécifiée soit dans le frontal, soit dans le backend. Si au moins l’un d’eux l’utilise, l’en-tête sera ajouté. Notez que le paramètre d’en-tête défini dans le backend a priorité sur celui défini dans le frontal si les deux sont configurés.
Exemples :
Voir également : « option httpclose », « option http-server-close ».
option persist
Activer ou désactiver la persistance forcée sur les serveurs inaccessibles
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsqu’une requête HTTP atteint un backend avec un cookie faisant référence à un serveur inactif, elle est, par défaut, redirigée vers un autre serveur. Il est possible de forcer la requête à être envoyée en premier au serveur inactif en utilisant « option persist », si cela est absolument nécessaire. Un cas d’utilisation courant est lorsque les serveurs sont sous une charge extrême et passent leur temps à basculer. Dans ce cas, les utilisateurs continuent d’être dirigés vers le serveur sur lequel ils ont ouvert la session, dans l’espoir qu’ils soient correctement servis. Il est recommandé d’utiliser « option redispatch » en conjonction avec cette option afin que, dans le cas où il serait impossible de se connecter au serveur (serveur définitivement inactif), le client soit finalement redirigé vers un autre serveur valide.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option redispatch », « retries », « force-persist »
option pgsql-check user <username>
Utilisez les contrôles d’état PostgreSQL pour le test des serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
La vérification envoie un message StartupMessage PostgreSQL et attend soit un message de demande d’authentification, soit un message d’erreur. Il s’agit d’un test basique mais utile qui ne génère ni erreur ni connexion interrompue sur le serveur. Cette vérification est identique à celle de « mysql-check ».
Voir aussi : « option httpchk »
option prefer-last-server
Permettre à plusieurs requêtes équilibrées de rester sur le même serveur
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsque l’algorithme de répartition de charge utilisé n’est pas déterministe, et qu’une requête précédente a été envoyée à un serveur auquel HAProxy maintient encore une connexion, il peut être souhaitable que les requêtes ultérieures d’une même session soient dirigées vers le même serveur autant que possible. Notez que cela diffère de la persistance, car nous ne faisons qu’indiquer une préférence que HAProxy tente d’appliquer sans aucune garantie. L’utilisation réelle concerne les connexions keep-alive envoyées aux serveurs. Lorsque cette option est utilisée, HAProxy tentera de réutiliser la même connexion attachée au serveur au lieu de répartir la charge vers un autre serveur, ce qui provoquerait la fermeture de la connexion. Cela peut avoir un sens pour les serveurs de fichiers statiques. Il ne convient pas d’utiliser cette option en combinaison avec des algorithmes basés sur le hachage. Notez qu’HAProxy tente déjà automatiquement de rester attaché à un serveur qui renvoie un code 401 ou à un proxy qui renvoie un code 407 (authentification requise), lorsque l’algorithme de répartition de charge n’est pas déterministe. Cette fonctionnalité est obligatoire pour l’utilisation avec le défi d’authentification NTLM défectueux, et aide considérablement au dépannage de certaines applications défaillantes. L’option prefer-last-server peut également être souhaitable dans ces environnements afin d’éviter de redistribuer le trafic après chaque réponse.
Il peut être utile de préciser ici quels algorithmes de répartition de charge sont considérés comme déterministes. Les algorithmes déterministes sélectionnent toujours le même serveur pour des données clientes données, à condition que l’ensemble des serveurs disponibles n’ait pas changé. En général, les algorithmes déterministes impliquent un hachage ou une recherche dans les requêtes entrantes pour choisir le serveur cible. Toutefois, ce n’est pas toujours le cas ; par exemple, « static-rr » peut également être considéré comme déterministe, car le choix du serveur repose sur le poids statique du serveur, rendant la sélection prévisible. L’algorithme « sticky » assure une routage déterministe pour les clients revenant.
En ce qui concerne les algorithmes non déterministes, ces algorithmes choisissent un serveur en fonction de l’état dynamique du serveur ou d’une rotation simple, si bien que deux requêtes consécutives ne sont pas garanties d’être acheminées vers le même serveur. L’option prefer-last-server est spécifiquement conçue pour de tels cas. roundrobin et leastconn en sont des exemples.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option http-keep-alive »
option redispatch
Activer ou désactiver la redistribution de session en cas d’échec de connexion
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
En mode HTTP, si un serveur désigné par un cookie est hors service, les clients peuvent effectivement rester attachés à ce serveur, par exemple lors de l’utilisation de « option persist » ou de « force-persist », car ils ne peuvent pas supprimer le cookie, ce qui les empêche de nouveau d’accéder au service.
Spécifier « option redispatch » permet au proxy de rompre la persistance basée sur les cookies ou le hachage constant, et de redistribuer les connexions vers un serveur fonctionnel.
Les serveurs actifs sont sélectionnés à partir d’un sous-ensemble de la liste des serveurs disponibles. Les serveurs actifs qui ne sont ni hors service ni en maintenance (c’est-à-dire dont l’état n’est pas vérifié ou qui ont été vérifiés comme « up ») sont sélectionnés dans l’ordre suivant :
Lorsqu’une nouvelle tentative est effectuée, HAProxy tente de sélectionner un serveur différent du dernier utilisé. Le nouveau serveur est sélectionné à partir de la liste actuelle des serveurs.
Parfois, si la liste est mise à jour entre deux tentatives (par exemple, si un grand nombre de tentatives ont lieu et que la durée est supérieure au temps nécessaire pour vérifier qu’un serveur est hors service, le supprimer de la liste et basculer sur la liste des serveurs de secours), les connexions peuvent être redirigées vers un serveur de secours, toutefois.
Il permet également de réessayer la connexion à un autre serveur en cas d’échecs multiples. Bien entendu, cela nécessite que « retries » soit défini à une valeur non nulle.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option persist », « force-persist », « retries »
option redis-check
Utilisez les contrôles d’état Redis pour tester les serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Il est possible de vérifier que le serveur communique correctement selon le protocole REDIS, et non seulement qu’il accepte la connexion TCP. Lorsque cette option est activée, une commande PING REDIS est envoyée au serveur, et la réponse est analysée afin de détecter le message de réponse “+PONG”.
Exemple :
Voir également : « option httpchk », « option tcp-check », « tcp-check expect »
option smtpchk
Utilisez les contrôles d’état SMTP pour tester les serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Lorsque l’option smtpchk est activée, les contrôles d’état consistent en une connexion TCP suivie d’une commande SMTP. Par défaut, cette commande est « HELO localhost ». Le code de réponse du serveur est analysé, et seuls les codes de réponse commençant par un « 2 » sont considérés comme valides. Toutes les autres réponses, ainsi qu’une absence de réponse, constituent une erreur et indiquent un serveur hors service.
Ce test est destiné à être utilisé avec des serveurs ou relais SMTP. Selon la requête, il se peut que certains serveurs ne journalisent pas chaque tentative de connexion, vous devrez donc peut-être expérimenter pour améliorer le comportement. Utiliser telnet sur le port 25 est souvent plus simple que de modifier la configuration.
Souvent, un serveur SMTP entrant doit voir l’adresse IP du client pour diverses raisons, notamment le filtrage du spam, la prévention de la falsification d’adresse et la journalisation. Lorsqu’il est possible de le faire, il est souvent judicieux de masquer l’adresse IP du client lors de la connexion au serveur en utilisant l’argument « usesrc » du mot-clé « source », ce qui nécessite que la fonctionnalité de proxy transparent soit compilée.
Exemple :
Voir aussi : « option httpchk », « source »
option socket-stats non option socket-stats
Activer ou désactiver la collecte et la fourniture de statistiques séparées pour chaque socket.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
option splice-auto
Activer ou désactiver l’accélération matérielle du noyau sur les sockets dans les deux sens
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Lorsque cette option est activée, soit sur un frontal, soit sur un backend, HAProxy évalue automatiquement la possibilité d’utiliser le splice TCP du noyau pour transférer les données entre le client et le serveur, dans les deux sens. HAProxy utilise des heuristiques pour estimer si le splice du noyau pourrait améliorer les performances ou non. Les deux sens sont gérés indépendamment. Notez que les heuristiques utilisées ne sont pas très agressives afin de limiter une utilisation excessive du splice. Cette option nécessite que le splice soit activé au moment de la compilation et peut être désactivée globalement à l’aide de l’option « nosplice ». Étant donné que le splice utilise des tubes, son utilisation suppose qu’il y ait suffisamment de tubes disponibles.
Note importante : la fusion TCP basée sur le noyau est une fonctionnalité spécifique à Linux, apparue pour la première fois dans le noyau 2.6.25. Elle permet d’accélérer le transfert de données entre sockets au niveau du noyau, sans copier ces données en espace utilisateur, offrant ainsi des gains de performance et des économies de cycles CPU significatifs. Étant donné que de nombreuses implémentations anciennes sont défectueuses, susceptibles de corrompre les données ou de fonctionner de manière inefficace, cette fonctionnalité n’est pas activée par défaut et doit être utilisée avec une extrême prudence. Bien qu’il ne soit pas possible de détecter la correction d’une implémentation, la version 2.6.29 est la première à proposer une implémentation correctement fonctionnelle. En cas de doute, la fusion peut être désactivée globalement à l’aide du mot-clé global « nosplice ».
Exemple :
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option splice-request », « option splice-response » et les options globales « nosplice » et « maxpipes »
option splice-request
Activer ou désactiver l’accélération automatique du noyau sur les sockets pour les requêtes
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Lorsque cette option est activée, soit sur un frontal, soit sur un backend, HAProxy utilisera le transfert direct du noyau (tcp splicing) chaque fois que possible pour acheminer les données allant du client vers le serveur. Il peut toutefois recourir au schéma recv/send si aucun canal libre n’est disponible. Cette option nécessite que le transfert direct soit activé lors de la compilation et peut être désactivée globalement via l’option « nosplice ». Étant donné que le transfert direct utilise des canaux, son utilisation suppose la disponibilité de suffisamment de canaux libres.
Remarque importante : consultez « option splice-auto » pour les limitations d’utilisation.
Exemple :
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option splice-auto », « option splice-response » et les options globales « nosplice » et « maxpipes »
option splice-response
Active ou désactive l’accélération automatique du noyau sur les sockets pour les réponses
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Lorsque cette option est activée, soit sur un frontal, soit sur un backend, HAProxy utilisera le transfert direct du noyau (tcp splicing) chaque fois que possible pour acheminer les données allant du serveur vers le client. Il peut toutefois recourir au schéma recv/send si aucun canal libre n’est disponible. Cette option nécessite que le transfert direct soit activé lors de la compilation et peut être désactivée globalement via l’option « nosplice ». Étant donné que le transfert direct utilise des canaux, son utilisation suppose la disponibilité de suffisamment de canaux libres.
Remarque importante : consultez « option splice-auto » pour les limitations d’utilisation.
Exemple :
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir également : « option splice-auto », « option splice-request » et les options globales « nosplice » et « maxpipes »
option spop-check
Utilisez les contrôles d’état SPOP pour tester les serveurs
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Il est possible de vérifier que le serveur communique correctement selon le protocole SPOP, et non seulement qu’il accepte la connexion TCP. Lorsque cette option est activée, une négociation HELLO est établie entre HAProxy et le serveur, et la réponse est analysée afin de vérifier qu’aucune erreur n’est signalée.
Exemple :
Voir aussi : « option httpchk »
option srvtcpka
Activer ou désactiver l’envoi de paquets TCP keepalive côté serveur
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 : aucun
Lorsqu’un pare-feu ou tout composant sensible à la session se trouve entre un client et un serveur, et que le protocole implique des sessions très longues avec des périodes d’inactivité prolongées (par exemple, les bureaux distants), il existe un risque que l’un des composants intermédiaires décide d’expirer une session restée inactif trop longtemps.
Activer les keep-alives TCP au niveau du socket fait que le système envoie régulièrement des paquets à l’autre extrémité de la connexion, la maintenant active. Le délai entre les sondes de keep-alive est contrôlé uniquement par le système et dépend à la fois du système d’exploitation et de ses paramètres de réglage.
Il est important de comprendre que les paquets keep-alive ne sont ni émis ni reçus au niveau de l’application. Seuls les piles réseau les perçoivent. Pour cette raison, même si l’une des extrémités du proxy utilise déjà des keep-alive pour maintenir sa connexion active, ces paquets keep-alive ne seront pas transférés à l’autre extrémité du proxy.
Veuillez noter que cela n’a rien à voir avec le keep-alive HTTP.
L’option « srvtcpka » active l’envoi de sondes TCP keep-alive du côté serveur d’une connexion, ce qui devrait aider à détecter les expiration de session entre HAProxy et un serveur.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option clitcpka », « option tcpka »
option ssl-hello-chk
Utilisez les contrôles d’état client hello SSLv3 pour tester les serveurs
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Lorsque certains protocoles basés sur SSL sont relayés en mode TCP via HAProxy, il est possible de vérifier que le serveur communique correctement en SSL, et non seulement qu’il accepte la connexion TCP. Lorsque l’option ssl-hello-chk est activée, un message client hello SSLv3 pur est envoyé une fois la connexion établie avec le serveur, puis la réponse est analysée afin de détecter un message server hello SSL. Le serveur est considéré comme valide uniquement si la réponse contient ce message server hello.
Tous les serveurs ont été testés afin de s’assurer qu’ils répondent correctement aux messages de hello SSLv3, et la plupart des serveurs ne journalisent même pas les requêtes ne contenant que des messages hello, ce qui est appréciable.
Notez que ce contrôle fonctionne même lorsque le support SSL n’a pas été inclus dans HAProxy, car il forge le message SSL. Lorsque le support SSL est disponible, il est préférable d’utiliser les contrôles d’état SSL natifs plutôt que celui-ci.
Voir aussi : « option httpchk », « check-ssl »
option tcp-check
Effectuez les contrôles d’état à l’aide des séquences tcp-check send/expect
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Cette méthode de contrôle d’état est destinée à être combinée avec des listes de commandes « tcp-check » afin de prendre en charge des séquences de contrôle d’état de type send/expect.
Les contrôles TCP prennent actuellement en charge 4 modes de fonctionnement : - absence de directive « tcp-check » : le contrôle d’état se limite à une tentative de connexion, ce qui constitue le mode par défaut.
- « tcp-check send » ou « tcp-check send-binary » est indiqué : cela permet d'envoyer une chaîne lors de l'ouverture d'une connexion. Avec certains protocoles, cela permet d'envoyer un message « QUIT », par exemple, ce qui empêche le serveur de noter une erreur de connexion pour chaque contrôle d'état. Le résultat du contrôle reste fondé uniquement sur la capacité à ouvrir la connexion.
- "tcp-check expect" est uniquement mentionné : il sert à tester une bannière.
La connexion est établie et HAProxy attend que le serveur présente un contenu qui doit respecter certaines règles. Le résultat de la vérification repose sur la correspondance entre le contenu reçu et les règles définies. Cette fonctionnalité convient aux protocoles POP, IMAP, SMTP, FTP, SSH et TELNET.
- à la fois « tcp-check send » et « tcp-check expect » sont mentionnés : cela permet de tester un protocole de type hello. HAProxy envoie un message, le serveur répond et la réponse est analysée. Le résultat de la vérification repose sur la correspondance entre le contenu de la réponse et les règles définies. Cette approche convient souvent aux protocoles qui nécessitent une liaison ou un request/response modèle.
LDAP, MySQL, Redis et SSL sont des exemples de tels protocoles, bien qu’ils disposent déjà chacun de leurs vérifications dédiées, qui comprennent une compréhension plus poussée du protocole respectif.
En ce mode, plusieurs questions peuvent être envoyées et plusieurs réponses peuvent être analysées.
Un cinquième mode peut être utilisé pour insérer des commentaires à différentes étapes du script.
Pour chaque règle tcp-check que vous créez, vous pouvez ajouter une directive « comment », suivie d’une chaîne. Cette chaîne sera rapportée dans les journaux et sur stderr en mode débogage. Elle est utile pour faciliter la génération de rapports d’erreurs conviviaux. La directive « comment » est bien entendu facultative.
Pendant l’exécution d’un contrôle d’état, une portée de variables est mise à disposition pour stocker des échantillons de données, à l’aide de l’opération « tcp-check set-var ». La libération de ces variables est possible à l’aide de « tcp-check unset-var ».
Exemples :
Voir également : « tcp-check connect », « tcp-check expect » et « tcp-check send ».
option tcp-smart-accept
Activer ou désactiver l’enregistrement d’un paquet ACK pendant la séquence d’acceptation
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments : aucun
Lorsqu’une requête de connexion HTTP arrive, le système l’acquitte en lieu et place de HAProxy, puis le client envoie immédiatement sa requête, que le système acquitte également tout en informant HAProxy de la nouvelle connexion. HAProxy lit ensuite la requête et envoie une réponse. Cela signifie que le système envoie une acknowledgement TCP inutile, car la requête aurait pu être acquittée par HAProxy lorsqu’il envoie sa réponse.
Pour cette raison, en mode HTTP, HAProxy demande automatiquement au système d’éviter d’envoyer cet ACK inutile sur les plates-formes qui le supportent (actuellement au moins Linux). Cela ne devrait causer aucun problème, car le système l’envoie quand même après 40 ms si la réponse met plus de temps que prévu à arriver.
Lors de sessions de dépannage réseau complexes, il peut être souhaitable de désactiver cette optimisation, car les accusés de réception différés peuvent compliquer le dépannage lorsqu’il s’agit d’identifier où les paquets sont retardés. Il est alors possible de revenir au comportement normal en spécifiant « no option tcp-smart-accept ».
Il est également possible de forcer ce comportement pour les proxies non HTTP en spécifiant simplement « option tcp-smart-accept ». Par exemple, cela peut avoir un sens avec certains services tels que SMTP, où le serveur parle en premier.
Il est recommandé d’éviter de forcer cette option dans une section defaults. En cas de doute, envisagez de la réinitialiser aux valeurs automatiques en préfixant l’option par le mot-clé default, ou de la désactiver en utilisant le mot-clé no.
Voir également : « option tcp-smart-connect »
option tcp-smart-connect
Activer ou désactiver la sauvegarde d’un paquet ACK pendant la séquence de connexion
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Sur certains systèmes (au moins Linux), HAProxy peut demander au noyau de ne pas envoyer immédiatement une accusé de réception vide lors d’une requête de connexion, mais de transmettre directement la requête de tampon à la place. Cela permet d’économiser un paquet sur le réseau et améliore ainsi les performances. Cette fonctionnalité peut également être utile pour certains serveurs, car ils reçoivent immédiatement la requête accompagnant la connexion entrante.
Cette fonctionnalité est activée lorsque « option tcp-smart-connect » est définie dans un backend. Elle n’est pas activée par défaut car elle complique le dépannage réseau.
Il n’a de sens d’activer cette fonctionnalité que pour les protocoles où le client parle en premier, comme HTTP. Dans les autres cas, si aucune donnée ne peut être envoyée à la place de l’ACK, un ACK normal est transmis.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : « option tcp-smart-accept »
option tcpka
Activer ou désactiver l’envoi de paquets TCP keepalive des deux côtés
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Lorsqu’un pare-feu ou tout composant sensible à la session se trouve entre un client et un serveur, et que le protocole implique des sessions très longues avec des périodes d’inactivité prolongées (par exemple, les bureaux distants), il existe un risque que l’un des composants intermédiaires décide d’expirer une session restée inactif trop longtemps.
Activer les keep-alives TCP au niveau du socket fait que le système envoie régulièrement des paquets à l’autre extrémité de la connexion, la maintenant active. Le délai entre les sondes de keep-alive est contrôlé uniquement par le système et dépend à la fois du système d’exploitation et de ses paramètres de réglage.
Il est important de comprendre que les paquets keep-alive ne sont ni émis ni reçus au niveau de l’application. Seuls les piles réseau les perçoivent. Pour cette raison, même si l’une des extrémités du proxy utilise déjà des keep-alive pour maintenir sa connexion active, ces paquets keep-alive ne seront pas transférés à l’autre extrémité du proxy.
Veuillez noter que cela n’a rien à voir avec le keep-alive HTTP.
L’option « tcpka » active l’envoi de sondes TCP keep-alive côté client et côté serveur d’une connexion. Notez que cette option n’a de sens que dans les sections « defaults » ou « listen ». Si cette option est utilisée dans un frontend, seuls les clients recevront des keep-alives ; si elle est utilisée dans un backend, seuls les serveurs recevront des keep-alives. Pour cette raison, il est fortement recommandé d’utiliser explicitement les options « option clitcpka » et « option srvtcpka » lorsque la configuration est répartie entre frontends et backends.
Voir aussi : « option clitcpka », « option srvtcpka »
option tcplog [clf]
Activer la journalisation avancée des connexions TCP avec l’état du flux et les compteurs
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Par défaut, le format de sortie des journaux est très pauvre, ne contenant que les adresses source et destination, ainsi que le nom de l’instance. En spécifiant « option tcplog », chaque ligne de journal devient beaucoup plus riche, incluant, sans s’y limiter, les compteurs de connexion, l’état du flux, le nombre de connexions, le nom du frontal, du backend et du serveur, ainsi que l’adresse source et les ports. Cette option est utile pour les proxies TCP purs afin de déterminer si c’est le client ou le serveur qui se déconnecte ou expiré. Pour les proxies HTTP normaux, il est préférable d’utiliser « option httplog », qui est encore plus complet.
L’option tcplog remplace toute directive précédente log-format.
Voir également : « option httplog », et section 8 concernant la journalisation.
option transparent (deprecated)
Activer le proxy transparent côté client
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Cette option a été introduite afin de permettre une persistance au niveau 7 aux répartiteurs de charge au niveau 3. L’idée consiste à utiliser la capacité du système d’exploitation à rediriger une connexion entrante provenant d’une adresse distante vers un processus local (ici HAProxy), et à faire en sorte que ce processus connaisse l’adresse initialement demandée. Lorsque cette option est utilisée, les sessions sans cookies seront acheminées vers l’adresse IP d’origine de la requête entrante (qui doit correspondre à celle d’un autre équipement), tandis que les requêtes avec cookies seront toujours acheminées vers le serveur approprié.
Notez qu’en dépit d’une croyance répandue, cette option ne fait pas que HAProxy présente l’adresse IP du client au serveur lors de l’établissement de la connexion.
À compter de la version 3.3, cette option est désormais obsolète car elle était sujet à plusieurs limitations techniques internes. Son utilisation génère un avertissement, qui peut être évité si nécessaire via le mot-clé global « expose-deprecated-directives ».
L’approche correcte consiste à déclarer un serveur sur l’adresse 0.0.0.0, qui s’occupera de la connexion à l’adresse cible attendue. Un serveur gérera également correctement les connexions inactives vers les serveurs cibles.
Exemple :
Voir également : l’argument « usesrc » du mot-clé « source », et l’option « transparent » du mot-clé « bind ».
option use-small-buffers [ queue | l7-retries | check ]*
Activer la prise en charge des tampons de petite taille pour les catégories données.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Cette option peut être utilisée pour activer le support des petits tampons à divers emplacements afin de réduire la consommation de mémoire. Par défaut, sans paramètre, les petits tampons sont utilisés autant que possible à tous les emplacements possibles. Sinon, il est possible de les limiter aux emplacements suivants :
- queue : Lorsqu’il est défini, des tampons de petite taille seront utilisés pour stocker les requêtes, si elles sont suffisamment petites, lorsque la connexion est mise en file d’attente.
- l7-retries : Lorsqu’il est défini, des tampons de petite taille seront utilisés pour sauvegarder les requêtes lorsque les réessais L7 sont activés.
- check : Lorsqu’il est défini, des tampons de petite taille seront utilisés pour les requêtes de vérification de santé.
Lorsqu’il est activé, des tampons de petite taille sont utilisés, mais uniquement si cela est possible. Sinon, lorsque les données sont trop grandes, un tampon régulier est automatiquement utilisé. La taille des tampons de petite taille est configurable via le paramètre global “tune.bufsize.small”.
Si cette option a été activée dans une section « defaults », elle peut être désactivée dans une instance spécifique en préfixant son nom par le mot-clé « no ».
Voir aussi : tune.bufsize.small
persist rdp-cookie
Activer la persistance basée sur les cookies RDP
Peut être utilisé dans les contextes suivants : tcp
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Cette instruction active la persistance basée sur un cookie RDP. Le cookie RDP contient toutes les informations nécessaires pour identifier le serveur dans la liste des serveurs connus. Ainsi, lorsque cette option est configurée dans le backend, la requête est analysée ; si un cookie RDP est détecté, il est décodé. Si ce cookie correspond à un serveur connu qui est toujours actif (ou si l’option persist est définie), la connexion est acheminée vers ce serveur.
Notez que cela n’a de sens que dans un backend TCP, mais pour que cela fonctionne, le frontal doit avoir attendu suffisamment longtemps pour garantir la présence d’un cookie RDP dans le tampon de la requête. Il s’agit de la même exigence que pour la méthode de répartition de charge « rdp-cookie ». Il est donc fortement recommandé de regrouper toutes les directives dans une seule section « listen ».
En outre, il est important de comprendre que le serveur terminal émettra ce cookie RDP uniquement s’il est configuré en mode « redirection de jeton », ce qui signifie que l’option « redirection de l’adresse IP » est désactivée.
Exemple :
Voir également : « balance rdp-cookie », « tcp-request » et l’ACL “req.rdp_cookie”.
quic-initial <action> [ { if | unless } <condition> ]
Effectuer une action sur un paquet Initial QUIC entrant. Contrairement à « tcp-request connection », cette directive est exécutée avant toute instanciation d’élément de connexion, avant le démarrage et la finalisation de l’échange SSL, ce qui est plus efficace lorsqu’il s’agit de rejeter des tentatives de connexion.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | non
Arguments :
Cette action est exécutée tôt lors de l’analyse des paquets QUIC. En conséquence, seule une liste minimale d’actions est prise en charge : - accept - dgram-drop - reject - send-retry
rate-limit sessions <rate>
Fixez une limite au nombre de nouvelles sessions acceptées par seconde sur un frontal
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Lorsque le frontal atteint le nombre spécifié de nouvelles sessions par seconde, il cesse d’accepter de nouvelles connexions jusqu’à ce que le taux redescende en dessous de la limite. Pendant cette période, les sessions en attente seront conservées dans la file d’attente du socket (dans les tampons système), et HAProxy ne sera même pas au courant de l’existence de ces sessions en attente. Lorsqu’on applique une limite très faible sur un service fortement sollicité, il peut être pertinent d’augmenter la taille de la file d’attente du socket en utilisant le mot-clé « backlog ».
Cette fonctionnalité est particulièrement efficace pour bloquer les attaques basées sur les connexions ou l’abus de service sur des serveurs sensibles. Comme le taux de session est mesuré toutes les millisecondes, il est extrêmement précis. De plus, la limite s’applique immédiatement, aucune attente n’est nécessaire pour détecter le seuil.
Exemple : limiter le débit des connexions SMTP à 10 par seconde au maximum écoute smtp mode tcp bind :25 taux-limité sessions 10 serveur smtp1 127.0.0.1:1025
Note : lorsque le débit maximal est atteint, l’état du frontal n’est pas modifié, mais ses sockets apparaissent comme « EN ATTENTE » dans les statistiques si l’option « socket-stats » est activée.
Voir également : le mot-clé « backlog » et le critère ACL “fe_sess_rate”.
redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
Rediriger HTTP vers if/unless si une condition est remplie
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
If/unless la condition est remplie, la requête HTTP entraîne une réponse de redirection. Si aucune condition n’est spécifiée, la redirection s’applique sans condition.
Arguments :
Exemple : déplacer uniquement l’URL de connexion vers HTTPS. acl clear dst_port 80 acl secure dst_port 8080 acl login_page url_beg /login acl logout url_beg /logout acl uid_given url_reg /login?userid=[^&]+ acl cookie_set hdr_sub(cookie) SEEN=1
rediriger préfixe https://mysite.com set-cookie SEEN=1 si !cookie_set
rediriger préfixe https://mysite.com si page_connexion !secure
rediriger préfixe http://mysite.com supprimer-requête si page_connexion !uid_fourni
rediriger localisation http://mysite.com/ si !page_connexion secure
rediriger localisation / supprimer-cookie USERID= si déconnexion
Exemple : envoyer des redirections pour les requêtes vers des articles sans « / ». acl missing_slash path_reg ^/article/[^/]$ redirect code 301 prefix / drop-query append-slash if missing_slash
Exemple : rediriger tout le trafic HTTP vers HTTPS lorsque le chiffrement SSL est géré par HAProxy. redirect scheme https if !{ ssl_fc }
Exemple : ajouter le préfixe ‘www.’ devant tous les hôtes ne le comportant pas http-request redirect code 301 location \ http://www.%[hdr(host)]%[capture.req.uri] \ sauf si { hdr_beg(host) -i www }
Exemple : rediriger définitivement uniquement les anciens URL vers les nouveaux http-request redirect code 301 location \ %[path,map_str(old-blog-articles.map)] ignore-empty
Voir section 7 concernant l’utilisation des ACL.
retries <value>
Définir le nombre de tentatives à effectuer sur un serveur après un échec
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Par défaut, les tentatives de nouvelle connexion sont les seules concernées par les réessais. Toutefois, lorsque la directive « retry-on » est utilisée, d’autres conditions peuvent déclencher un réessai (par exemple, une réponse vide, un code d’état indésirable), et chacune d’elles sera comptée comme une tentative. Lorsque le nombre total de tentatives atteint la valeur indiquée ici, une erreur sera renvoyée.
Afin d’éviter une nouvelle connexion immédiate à un serveur qui redémarre, un minuteur de retour de min(“timeout connect”, une seconde) est appliqué avant toute nouvelle tentative sur le même serveur.
Lorsque l’option redispatch est activée, certaines tentatives peuvent être effectuées sur un autre serveur, même si un cookie référence un serveur différent. Par défaut, cela ne concerne que la dernière tentative, sauf si un argument est fourni à l’option redispatch.
Voir également : « option redispatch »
retry-on [space-delimited list of keywords]
Spécifiez quand tenter de réessayer automatiquement une requête échouée. Ce paramètre n’est valable que lorsque « mode » est défini sur http et est ignoré silencieusement dans les autres cas.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
L’utilisation de cette directive remplace tout paramètre précédent par les nouveaux ; elle n’est pas cumulée.
Veuillez noter qu’utiliser une valeur autre que « none » ou « conn-failure » impose d’allouer un tampon et de copier intégralement la requête dans celui-ci, ce qui a des impacts mémoire et en performance. Les requêtes qui ne tiennent pas dans un seul tampon ne seront jamais réessayées (voir le paramètre global tune.bufsize).
Vous devez vous assurer que l’application dispose d’un mécanisme de protection contre le rebond, tel qu’un identifiant de transaction unique transmis dans les requêtes, ou que le rebond de la même requête n’a aucune conséquence, ou qu’il est très dangereux d’utiliser une valeur de réessai autre que « conn-failure » ou « none ». Les serveurs de fichiers statiques et les caches sont généralement considérés comme sûrs contre tout type de réessai. Utiliser un code d’état peut être utile pour quitter rapidement un serveur présentant un comportement anormal (mémoire insuffisante, problèmes du système de fichiers, etc.), mais dans ce cas, il peut être judicieux de rediriger immédiatement la connexion vers un autre serveur (voir « option redispatch » à ce sujet). Enfin, il est important de comprendre que la plupart des causes d’échecs proviennent des requêtes elles-mêmes, et que réessayer une requête provoquant un comportement anormal du serveur aggrave souvent la situation pour ce serveur, ou pour l’ensemble du service en cas de redirige.
Sauf si vous connaissez exactement la manière dont l’application gère les requêtes répétées, vous ne devez pas utiliser cette directive.
La valeur par défaut est « conn-failure ».
Exemple :
Voir aussi : « retries », « option redispatch », “tune.bufsize”
server <name> <address>[:[port]] [param*]
Déclarer un serveur dans un backend
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Exemples :
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 : « default-server », « http-send-name-header » et la section 5 à propos des options de serveur
server-state-file-name [ { use-backend-name | <file> } ]
Définissez le fichier d’état du serveur en lecture, chargez-le et appliquez-le aux serveurs disponibles dans ce backend.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Il ne s’applique que lorsque la directive « load-server-state-from-file » est définie sur « local ». Si <file> n’est pas fourni, et si « use-backend-name » est utilisé ou si cette directive n’est pas définie, alors le nom de backend est utilisé. Si <file> commence par une barre oblique « / », il est considéré comme un chemin absolu. Sinon, <file> est concaténé à la directive globale « server-state-base ».
Exemple : la configuration minimale ci-dessous ferait que HAProxy chercherait le fichier d’état serveur ‘/etc/haproxy/states/bk’ :
global
server-state-file-base /etc/haproxy/states
backend bk
load-server-state-from-file
Voir également : « server-state-base », « load-server-state-from-file » et « show servers state »
server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
Définissez un modèle pour initialiser les serveurs avec des paramètres partagés. Les noms de ces serveurs sont construits à partir des paramètres <prefix> et <num | range>.
Peut être utilisé dans les contextes suivants : tcp, http, log
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Exemples :
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Définir l’adresse source pour les connexions sortantes
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Le mot-clé « source » est utile dans les environnements complexes où une adresse spécifique est autorisée à se connecter aux serveurs. Il peut être nécessaire lorsqu’une adresse privée doit être utilisée via une passerelle publique, par exemple, et qu’il est connu que le système ne peut pas déterminer par lui-même l’adresse source appropriée.
Une extension disponible sur certains noyaux Linux patchés peut être utilisée via le mot-clé facultatif « usesrc ». Elle permet de se connecter aux serveurs à l’aide d’une adresse IP qui n’appartient pas au système lui-même. Ce mode est appelé « mode de proxy entièrement transparent ». Pour que cela fonctionne, les serveurs de destination doivent acheminer leur trafic de retour vers cette adresse via la machine exécutant HAProxy, et le transfert IP doit généralement être activé sur cette machine.
En mode « proxy transparent complet », il est possible de forcer l’affichage d’une adresse IP spécifique aux serveurs. Cette fonctionnalité est en réalité peu utilisée. Une utilisation plus courante consiste à demander à HAProxy de présenter l’adresse IP du client. Pour cela, deux méthodes sont disponibles :
- présentent l'adresse IP et le numéro de port du client. Il s'agit du mode le plus transparent, mais il peut poser des problèmes lorsque le suivi des connexions IP est activé sur la machine, car une même connexion peut être vue deux fois avec des états différents. Toutefois, cette solution présente l'avantage majeur de ne pas limiter le système aux 64 000 couples adresse+port sortants, car toutes les plages clientes peuvent être utilisées.
- présente uniquement l'adresse IP du client et sélectionne un port libre. Cette solution reste élégante, mais légèrement moins transparente (les journaux des pare-feu en aval ne correspondront pas à ceux en amont). Elle présente également l'inconvénient de limiter le nombre de connexions simultanées au nombre habituel de ports 64 k. Toutefois, comme les ports en amont et en aval sont différents, le suivi des connexions locales par adresse IP sur la machine ne sera pas perturbé par la réutilisation de la même session.
Cette option définit la source par défaut pour tous les serveurs du backend. Elle peut également être spécifiée dans une section « defaults ». Une spécification plus fine de l’adresse source est possible au niveau du serveur en utilisant l’option de serveur « source ». Pour en savoir plus, reportez-vous à la section 5 .
Pour fonctionner, l’option « usesrc » nécessite des privilèges root, ou, sur les systèmes pris en charge, la capacité “cap_net_raw”. Voir également la directive globale « setcap ».
Exemples :
Voir également : l’option de serveur « source » dans la section 5 , les correctifs Tproxy pour le noyau Linux sur www.balabit.com , le mot-clé « bind ».
srvtcpka-cnt <count>
Définit le nombre maximal d’enquêtes keepalive TCP qui doivent être envoyées avant de fermer la connexion côté serveur.
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 :
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 également : « option srvtcpka », « srvtcpka-idle », « srvtcpka-intvl ».
srvtcpka-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 de maintien de connexion TCP côté serveur.
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 :
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 également : « option srvtcpka », « srvtcpka-cnt », « srvtcpka-intvl ».
srvtcpka-intvl <timeout>
Définit le délai entre les sondes keepalive individuelles du côté serveur.
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 :
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 également : « option srvtcpka », « srvtcpka-cnt », « srvtcpka-idle ».
stats admin { if | unless } <cond>
Activer le niveau d’administration des statistiques if/unless si une condition est remplie
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Cette instruction active le niveau d’administration des statistiques if/unless si une condition est remplie.
Le niveau administrateur permet de enable/disable des serveurs depuis l’interface web. Par défaut, la page de statistiques est en lecture seule pour des raisons de sécurité. Si des directives « stats scope » sont définies dans la section, seuls les proxies désignés par ces directives accepteront les modifications d’état ; l’accès aux autres sera refusé.
Actuellement, la requête POST est limitée à la taille de tampon moins l’espace tampon réservé, ce qui signifie qu’en cas de liste de serveurs trop longue, la requête ne sera pas traitée. Il est recommandé de modifier un petit nombre de serveurs à la fois.
Les requêtes POST d’administration sont sujettes aux attaques CSRF. Cet risque est partiellement atténué en vérifiant que l’en-tête Origin (ou Referer si Origin est absent) correspond à l’en-tête Host, mais cette mesure ne suffit pas à empêcher complètement l’attaque. Il n’existe aucun moyen de se protéger entièrement contre ces attaques. Il est recommandé de ne pas exposer cette fonctionnalité sur une interface publique, et de limiter l’accès à ceux qui en ont besoin.
Exemple :
Exemple :
Exemple :
Voir aussi : « stats enable », « stats auth », « stats http-request », « stats scope », section 12.2 sur les listes d’utilisateurs et section 7 sur l’utilisation des ACL.
ssl-f-use [<sslbindconf> ...]*
Attribuez un certificat au frontal actuel.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non
Arguments :
Attribuez un certificat <crtname> à une liste de certificats créée automatiquement avec le nom du frontal et préfixée par @ (par exemple : ‘@frontend1’).
Cette liste de certificats implicite sera affectée à chaque ligne « ssl » de liaison dans le frontal actuel.
Les commandes crt-list issues de la socket de statistiques sont effectives avec cette liste de certificats, on peut donc la remplacer, supprimer ou ajouter des certificats et des options SSL à celle-ci.
Exemple :
Voir également : « crt-list » et « crt ».
stats auth <user>:<passwd>
Activer les statistiques avec authentification et accorder l’accès à un compte
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Cette instruction active les statistiques avec les paramètres par défaut et restreint l’accès aux utilisateurs déclarés uniquement. Elle peut être répétée autant de fois que nécessaire pour autoriser autant d’utilisateurs que souhaité. Lorsqu’un utilisateur tente d’accéder aux statistiques sans compte valide, une réponse « 401 Forbidden » sera renvoyée, ce qui amène le navigateur à demander un utilisateur et un mot de passe valides. Le domaine affiché au navigateur est configurable à l’aide de « stats realm ».
Étant donné que la méthode d’authentification est l’authentification HTTP Basic, les mots de passe circulent en clair sur le réseau. Il a donc été décidé que le fichier de configuration utiliserait également des mots de passe en clair afin de rappeler aux utilisateurs qu’ils ne doivent pas être sensibles et ne doivent pas être partagés avec d’autres comptes.
Il est également possible de réduire la portée des proxies affichés dans le rapport à l’aide de « stats scope ».
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir aussi : « stats enable », « stats realm », « stats scope », « stats uri »
stats enable
Activer le rapport de statistiques avec les paramètres par défaut
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Cette instruction active le rapport de statistiques avec les paramètres par défaut définis au moment de la compilation. Sauf indication contraire, ces paramètres sont utilisés : - uri des statistiques : /haproxy?stats - realm des statistiques : « HAProxy Statistics » - authentification des statistiques : non activée - portée des statistiques : aucune restriction
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir aussi : « stats auth », « stats realm », « stats uri »
stats hide-version
Activer les statistiques et masquer le rapport de version HAProxy
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
La page de statistiques peut rapporter certaines informations utiles sur l’état, ainsi que les statistiques. Parmi celles-ci figure la version d’HAProxy. Toutefois, il est généralement considéré comme dangereux de divulguer la version précise à quiconque, car cela peut aider à cibler des vulnérabilités connues par des attaques spécifiques. L’instruction « stats hide-version » supprime la version du rapport de statistiques. Cela est recommandé pour les sites publics ou tout site présentant une faiblesse login/password, et constitue la valeur par défaut.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir aussi : « stats auth », « stats enable », « stats realm », « stats uri », « stats show-version »
stats http-request { allow | deny | auth [realm <realm>] }
Contrôle d’accès aux statistiques
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Comme « http-request », ces options permettent un contrôle fin de l’accès aux statistiques. Chaque option peut être suivie de if/unless et d’une ACL. La première option dont la condition est satisfaite (ou l’option sans condition) détermine le résultat final. Pour « deny », une erreur 403 est renvoyée ; pour « allow », le traitement normal est effectué ; pour « auth », un code d’erreur 401/407 est renvoyé afin que le client soit invité à saisir un nom d’utilisateur et un mot de passe.
Il n’existe aucune limite fixe au nombre d’instructions http-request par instance.
Voir également : « http-request », section 12.2 sur les listes d’utilisateurs et section 7 sur l’utilisation des ACL.
stats realm <realm>
Activer les statistiques et définir le domaine d’authentification
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Le domaine est lu comme un mot unique, de sorte que tout espace qu’il contient doit être échappé à l’aide d’une barre oblique inverse (\).
Cette instruction n’est utile que conjointement avec « stats auth », car elle ne concerne que l’authentification.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir également : « stats auth », « stats enable », « stats uri »
stats refresh <delay>
Activer les statistiques avec actualisation automatique
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Cette instruction est utile sur les affichages de surveillance dotés d’une page permanente affichant l’activité du répartiteur de charge. Lorsqu’elle est activée, la page de rapport HTML inclura un lien « actualiser » / « arrêter l’actualisation » permettant à l’utilisateur de choisir s’il souhaite ou non l’actualisation automatique de la page.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir aussi : « stats auth », « stats enable », « stats realm », « stats uri »
stats scope { <name> | "." }
Activer les statistiques et limiter la portée d’accès
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Lorsque cette instruction est spécifiée, seules les sections énumérées par cette instruction apparaissent dans le rapport. Toutes les autres sont masquées, et toute tentative de modifier leur état en mode administrateur est rejetée. Cette instruction peut être utilisée autant de fois que nécessaire si plusieurs sections doivent être rapportées. Veuillez noter que la vérification des noms se fait par comparaison de chaînes de caractères simple, et qu’il n’est jamais vérifié qu’un nom de section donné existe réellement.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir également : « stats auth », « stats enable », « stats realm », « stats uri » et « stats admin »
stats show-desc [ <desc> ]
Activer le rapport d’une description sur la page de statistiques.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
`<desc>` est une description facultative à rapporter. Si non spécifiée, la description provenant de la section globale est automatiquement utilisée à la place.
Cette instruction est utile pour les utilisateurs qui proposent des services partagés à leurs clients, où le nœud ou la description doit être différent pour chaque client.
Bien que cette instruction seule suffise à activer le rapport des statistiques, il est recommandé de définir toutes les autres options afin d’éviter de dépendre de paramètres par défaut peu évidents. Par défaut, la description n’est pas affichée.
Exemple :
Voir également : « show-node », « stats enable », « stats uri » et « description » dans la section globale.
stats show-legends
Activer le rapport d’informations supplémentaires sur la page de statistiques
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
Activer le rapport d’informations supplémentaires sur la page de statistiques : - cap : fonctionnalités (proxy) - mode : l’un des suivants : tcp, http ou health (proxy) - id : identifiant SNMP (proxy, socket, serveur) - IP (socket, serveur) - cookie (backend, serveur)
Bien que cette instruction seule suffise à activer le rapport des statistiques, il est recommandé de définir toutes les autres options afin d’éviter de dépendre de paramètres par défaut peu évidents. Le comportement par défaut consiste à ne pas afficher ces informations.
Voir également : « stats enable », « stats uri ».
stats show-modules
Activer l’affichage du module de statistiques supplémentaires sur la page de statistiques
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
De nouvelles colonnes sont ajoutées à la fin de la ligne contenant les valeurs supplémentaires de statistiques, affichées comme un infobulle.
Bien que cette instruction seule suffise à activer le rapport des statistiques, il est recommandé de définir toutes les autres options afin d’éviter de dépendre de paramètres par défaut peu évidents. Le comportement par défaut consiste à ne pas afficher ces informations.
Voir également : « stats enable », « stats uri ».
stats show-node [ <name> ]
Activer le rapport du nom d’hôte sur la page de statistiques.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Cette instruction est utile pour les utilisateurs qui proposent des services partagés à leurs clients, où le nœud ou la description peut varier sur une page de statistiques fournie à chaque client. Le comportement par défaut consiste à ne pas afficher le nom d’hôte.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir également : « show-desc », « stats enable », « stats uri » et « node » dans la section globale.
stats show-version
Activer les statistiques et la rapport de version HAProxy
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments : aucun
La page de statistiques peut rapporter certaines informations d’état utiles en plus des statistiques. Parmi celles-ci figure la version d’HAProxy. Toutefois, il est généralement considéré comme dangereux de divulguer la version précise à quiconque, car cela peut aider à cibler des vulnérabilités connues par des attaques spécifiques, et cette fonctionnalité est donc désactivée par défaut. L’option « stats show-version » permet d’activer l’affichage de ces informations. Cette fonctionnalité n’est pas recommandée pour les sites publics ou tout site présentant une faiblesse login/password.
Voir également : « stats auth », « stats enable », « stats realm », « stats uri », « stats hide-version »
stats uri <prefix>
Activer les statistiques et définir le préfixe d’URI pour y accéder
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
L’URI des statistiques est intercepté dans le trafic relais, de sorte qu’il apparaît comme une page au sein de l’application normale. Il est fortement conseillé de s’assurer que l’URI sélectionné n’apparaîtra jamais dans l’application, faute de quoi il sera impossible de l’atteindre depuis l’application.
L’URI par défaut intégré dans HAProxy est “/haproxy?stats”, mais celui-ci peut être modifié au moment de la compilation, il est donc préférable de toujours le spécifier explicitement ici. Il est généralement recommandé d’inclure un point d’interrogation dans l’URI afin que les proxies intermédiaires évitent de mettre en cache les résultats. En outre, comme toute chaîne commençant par ce préfixe sera acceptée comme une requête de statistiques, le point d’interrogation aide à garantir qu’aucune URI valide ne commence par les mêmes mots.
Il peut parfois être très pratique d’utiliser « / » comme préfixe d’URI, et de placer cette déclaration dans une instance « listen » à part. Cela facilite la dédication d’une adresse ou d’un port aux statistiques uniquement.
Bien que cette instruction seule suffise à activer la génération de statistiques, il est recommandé de définir tous les autres paramètres afin d’éviter de dépendre de paramètres par défaut non évidents.
Exemple :
Voir aussi : « stats auth », « stats enable », « stats realm »
stick match <pattern> [table <table>] [{if | unless} <cond>]
Définir une condition de correspondance de modèle de requête pour associer un utilisateur à un serveur
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Certains protocoles ou applications nécessitent des règles de persistance complexes et ne peuvent pas toujours se fier uniquement aux cookies ni au hachage. L’instruction « stick match » décrit une règle permettant d’extraire le critère de persistance à partir d’une requête ou d’une connexion entrante. Consultez section 7 pour obtenir la liste complète des modèles et règles de transformation possibles.
Le tableau doit être déclaré à l’aide de l’instruction « stick-table ». Il doit être de type compatible avec le motif. Par défaut, il s’agit de celui présent dans le même backend. Il est possible de partager un tableau avec d’autres backends en le référençant à l’aide du mot-clé « table ». Si un autre tableau est référencé, les identifiants de serveur présents dans les backends sont utilisés. Par défaut, tous les identifiants de serveur commencent à 1 dans chaque backend, de sorte que l’ordre des serveurs suffit. Toutefois, en cas de doute, il est fortement recommandé de définir explicitement les identifiants de serveur à l’aide de leur paramètre « id ».
Il est possible de restreindre les conditions dans lesquelles une directive « stick match » s’applique, en utilisant « if » ou « unless » suivis d’une condition. Voir section 7 pour des conditions basées sur les listes de contrôle d’accès.
Il n’y a aucune limite au nombre d’instructions « stick match ». La première qui s’applique et correspond entraîne la redirection de la requête vers le même serveur que celui utilisé pour la requête qui a créé l’entrée. Ainsi, plusieurs correspondances peuvent être utilisées comme mécanisme de secours.
Les règles stick sont vérifiées après les cookies de persistance, elles n’ont donc pas d’effet sur la persistance si un cookie a déjà été utilisé pour sélectionner un serveur. Ainsi, il devient très simple d’insérer des cookies et de les associer à des adresses IP afin de maintenir la persistance entre HTTP et HTTPS.
Exemple :
Voir également : « stick-table », « stick on », section 11 sur les tables de persistance, et section 7 sur les listes de contrôle d’accès et la récupération d’échantillons.
stick on <pattern> [table <table>] [{if | unless} <condition>]
Définir un modèle de requête pour associer un utilisateur à un serveur
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Note : Cette forme est exactement équivalente à « stick match » suivie de « stick store-request », avec les mêmes arguments. Veuillez vous référer aux deux mots-clés pour plus de détails. Elle est fournie uniquement à titre de commodité pour écrire des configurations plus maintenables.
Exemples :
Voir aussi : « stick match », « stick store-request » et section 11 sur les tables de persistance.
stick store-request <pattern> [table <table>] [{if | unless} <condition>]
Définir un modèle de requête utilisé pour créer une entrée dans une table de persistance
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Certains protocoles ou applications nécessitent des règles de persistance complexes et ne peuvent pas toujours se fier simplement aux cookies ni au hachage. L’instruction « stick store-request » décrit une règle indiquant quoi extraire de la requête et quand le faire, afin de le stocker dans une table de persistance pour permettre à des requêtes ultérieures de la correspondre à l’aide de l’instruction « stick match ». Évidemment, la partie extraite doit avoir un sens et avoir une chance d’être correspondante dans une requête ultérieure. Le stockage de l’adresse IP du client, par exemple, a souvent un sens. Le stockage d’un identifiant trouvé dans un paramètre d’URL a également un sens. Le stockage d’un port source n’a presque jamais de sens, car il sera presque toujours aléatoirement correspondant. Voir section 7 pour la liste complète des modèles possibles et des règles de transformation.
Le tableau doit être déclaré à l’aide de l’instruction « stick-table ». Il doit être de type compatible avec le motif. Par défaut, il s’agit de celui présent dans le même backend. Il est possible de partager un tableau avec d’autres backends en le référençant à l’aide du mot-clé « table ». Si un autre tableau est référencé, les identifiants de serveur présents dans les backends sont utilisés. Par défaut, tous les identifiants de serveur commencent à 1 dans chaque backend, de sorte que l’ordre des serveurs suffit. Toutefois, en cas de doute, il est fortement recommandé de définir explicitement les identifiants de serveur à l’aide de leur paramètre « id ».
Il est possible de restreindre les conditions dans lesquelles une directive « stick store-request » s’applique, en utilisant « if » ou « unless » suivi d’une condition. Cette condition est évaluée lors de l’analyse de la requête, de sorte que toute critère peut être utilisé. Voir section 7 pour des conditions basées sur les ACL.
Il n’y a aucune limite au nombre d’instructions « stick store-request », mais il existe une limite de 8 stockages simultanés par requête ou réponse. Cela permet de stocker jusqu’à 8 critères, extraits indifféremment de la requête ou de la réponse, quelle que soit la quantité de règles. Seuls les 8 premiers critères correspondants seront conservés. Grâce à cela, il est possible de remplir plusieurs tables en même temps dans l’espoir d’améliorer les chances de reconnaître un utilisateur via un autre protocole ou une autre méthode d’accès. Il est possible d’utiliser plusieurs règles store-request sur la même table, ce qui peut servir à déterminer le meilleur critère à privilégier en organisant les règles par ordre de préférence décroissante. Seul le premier critère extrait pour une table donnée sera stocké. Toutes les règles store-request ultérieures faisant référence à la même table seront ignorées, et leurs ACLs ne seront pas évaluées.
Les règles « store-request » sont évaluées une fois la connexion au serveur établie, afin que le tableau contienne le serveur réel ayant traité la requête.
Exemple :
Voir également : « stick-table », « stick on », section 11 sur les tables de persistance, et section 7 sur les listes de contrôle d’accès et l’extraction d’échantillon.
stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Définir un modèle de réponse utilisé pour créer une entrée dans une table de persistance
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Certains protocoles ou applications nécessitent des règles de persistance complexes et ne peuvent pas toujours se fier simplement aux cookies ni au hachage. L’instruction « stick store-response » décrit une règle indiquant quoi extraire de la réponse et quand le faire, afin de le stocker dans une table de persistance pour permettre à des requêtes ultérieures de la correspondre à l’aide de l’instruction « stick match ». Évidemment, la partie extraite doit avoir un sens et avoir une chance d’être correspondante dans une requête ultérieure. Stocker un identifiant trouvé dans un en-tête de réponse a un sens. Voir section 7 pour la liste complète des modèles et règles de transformation possibles.
Le tableau doit être déclaré à l’aide de l’instruction « stick-table ». Il doit être de type compatible avec le motif. Par défaut, il s’agit de celui présent dans le même backend. Il est possible de partager un tableau avec d’autres backends en le référençant à l’aide du mot-clé « table ». Si un autre tableau est référencé, les identifiants de serveur présents dans les backends sont utilisés. Par défaut, tous les identifiants de serveur commencent à 1 dans chaque backend, de sorte que l’ordre des serveurs suffit. Toutefois, en cas de doute, il est fortement recommandé de définir explicitement les identifiants de serveur à l’aide de leur paramètre « id ».
Il est possible de restreindre les conditions dans lesquelles une directive « stick store-response » s’applique, en utilisant « if » ou « unless » suivi d’une condition. Cette condition est évaluée pendant l’analyse de la réponse, de sorte que toute critère puisse être utilisé. Voir section 7 pour des conditions basées sur des ACL.
Il n’y a aucune limite au nombre d’instructions « stick store-response », mais un plafond de 8 stockages simultanés par requête ou réponse. Cela permet de stocker jusqu’à 8 critères, extraits indifféremment de la requête ou de la réponse, quel que soit le nombre de règles. Seuls les 8 premiers critères correspondants seront conservés. Grâce à cela, il est possible de remplir plusieurs tables en même temps dans l’espoir d’améliorer les chances de reconnaître un utilisateur via un autre protocole ou une autre méthode d’accès. Il est possible d’utiliser plusieurs règles store-response sur la même table, ce qui peut servir à déterminer le meilleur critère à privilégier en classant les règles par ordre de préférence décroissante. Uniquement le premier critère extrait pour une table donnée sera stocké. Toutes les règles store-response ultérieures faisant référence à la même table seront ignorées, et leurs ACLs ne seront pas évaluées. Toutefois, même si une règle store-request fait référence à une table, une règle store-response peut également utiliser la même table. Cela signifie qu’une table peut apprendre exactement un élément provenant de la requête et un élément provenant de la réponse en même temps.
La table contiendra le serveur réel ayant traité la requête.
Exemple :
Voir également : « stick-table », « stick on », section 11 sur les tables de persistance, et section 7 sur les listes de contrôle d’accès et l’extraction de modèles.
stick-table type <type> size <size> [expire <expire>] [args...]
Configurez le tableau de persistance pour la section courante
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | oui
Cela sert à déclarer et configurer une table de persistance. Veuillez vous référer à la section 11.1 pour obtenir tous les détails et la liste des arguments pris en charge. Seuls le type et la taille sont obligatoires.
tcp-check comment <string>
Définit un commentaire pour la règle tcp-check suivante, signalé dans les journaux en cas d’échec.
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 :
Il ne fonctionne qu’avec les règles connect, send et expect. Il est utile pour produire des rapports d’erreurs conviviaux.
Voir également : « option tcp-check », « tcp-check connect », « tcp-check send » et « tcp-check expect ».
tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
Ouvre une nouvelle connexion
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 :
Lorsqu’une application est hébergée sur plusieurs ports TCP ou lorsqu’HAProxy effectue la répartition de charge de plusieurs services au sein d’un même backend, il est pertinent de vérifier chaque service individuellement avant de considérer un serveur comme opérationnel.
Lorsqu’aucun port TCP n’est configuré dans la ligne server ni dans la directive server port, alors la commande
’tcp-check connect port <port>’ doit être la première étape de la séquence.
Dans un ensemble de règles tcp-check, une règle « connect » est obligatoire ; il est également obligatoire de commencer l’ensemble de règles par une règle « connect ». Cette exigence vise à garantir que l’administrateur sait exactement ce qu’il fait.
Lorsqu’une connexion doit démarrer le jeu de règles, elle peut encore être précédée par des règles set-var, unset-var ou comment.
Exemples :
Voir aussi : « option tcp-check », « tcp-check send », « tcp-check expect »
tcp-check expect [min-recv <int>] [comment <msg>]
Spécifiez les données à collecter et à analyser lors d’un contrôle d’état générique
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 :
Les correspondances disponibles sont intentionnellement similaires à celles de leurs homologues http-check :
Il est important de noter que les réponses seront limitées à une taille définie par l’option globale “tune.bufsize”, qui vaut par défaut 16384 octets. Ainsi, les réponses trop grandes peuvent ne pas contenir le motif obligatoire lors de l’utilisation de « string », « rstring » ou binaire. Si une réponse de grande taille est absolument nécessaire, il est possible de modifier la taille maximale par défaut en définissant la variable globale. Toutefois, il convient de garder à l’esprit que l’analyse de réponses très grandes peut consommer des cycles CPU, notamment lors de l’utilisation d’expressions régulières, et qu’il est toujours préférable de cibler les vérifications sur des ressources plus petites. En outre, dans son état actuel, la vérification ne détectera aucun texte ni expression régulière au-delà d’un caractère nul dans la réponse. De même, il n’est pas possible de demander une correspondance avec le caractère nul.
Exemples :
Voir aussi : « option tcp-check », « tcp-check connect », « tcp-check send », « tcp-check send-binary », « http-check expect », tune.bufsize
tcp-check send <data> [comment <msg>]
Spécifiez une chaîne ou un format de journal personnalisé à envoyer en tant que question lors d’un contrôle d’état générique
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 :
Exemples :
Voir aussi : « option tcp-check », « tcp-check connect », « tcp-check expect », « tcp-check send-binary », tune.bufsize
tcp-check send-binary <hexstring> [comment <msg>]
Spécifiez une chaîne de chiffres hexadécimaux ou un format de journal personnalisé en hexadécimal à envoyer sous forme de question binaire lors d’un contrôle d’état TCP brut
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 :
Exemples :
Voir aussi : « option tcp-check », « tcp-check connect », « tcp-check expect », « tcp-check send », tune.bufsize
tcp-check set-var(<var-name>[,<cond>...]) <expr>
Cette opération définit le contenu d’une variable. La variable est déclarée en inline.
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 :
Exemples :
tcp-check unset-var(<var-name>)
Libère une référence à une variable dans son contexte.
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 :
Exemples :
tcp-request connection <action> <options...> [ { if | unless } <condition> ]
Effectuer une action sur une connexion entrante en fonction d’une condition au niveau couche 4
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | non
Arguments :
Immédiatement après l’acceptation d’une nouvelle connexion entrante, il est possible d’évaluer certaines conditions afin de décider si cette connexion doit être acceptée, rejetée ou si ses compteurs doivent être suivis. Ces conditions ne peuvent pas utiliser les contenus de données, car la connexion n’a pas encore été lue, et les tampons ne sont pas encore alloués. Cette fonctionnalité permet d’accepter ou de rejeter sélectivement et très rapidement des connexions provenant de diverses sources, avec une surcharge minimale. Si des contenus doivent être inspectés pour prendre la décision, il faut utiliser à la place les instructions « tcp-request content ».
Les règles « tcp-request connection » sont évaluées dans l’ordre exact de leur déclaration. Si aucune règle ne correspond ou s’il n’y a aucune règle, l’action par défaut consiste à accepter la connexion entrante. Il n’existe aucune limite spécifique au nombre de règles pouvant être insérées. Une règle peut éventuellement être suivie d’une condition basée sur une ACL, auquel cas elle n’est évaluée que si la condition est vraie.
La condition est évaluée juste avant l’exécution de l’action, et celle-ci est exécutée exactement une fois. Il n’y a donc aucun problème si une action modifie un élément vérifié dans le cadre de la condition. Cela signifie également que plusieurs actions peuvent dépendre de la même condition, de sorte que la première action qui modifie l’évaluation de la condition suffit à désactiver implicitement les actions restantes. Cette approche est utilisée, par exemple, lorsqu’il s’agit d’attribuer une valeur à une variable à partir de différentes sources lorsque celle-ci est vide.
Le premier mot-clé après « tcp-request connection » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour l’action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « TCP RqCon »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Notez que la condition “if/unless” est facultative. Si aucune condition n’est définie sur l’action, celle-ci est simplement exécutée sans condition. Cela peut être utile pour les actions “track-sc*” ainsi que pour modifier l’action par défaut en rejet.
Exemple : accepter toutes les connexions provenant d’hôtes listés blancs, rejeter les connexions trop rapides sans les compter, et suivre les connexions acceptées. Cela permet de limiter le débit des connexions provenant de sources abusives.
tcp-request connection accepte si { src -f /etc/haproxy/whitelist.lst }
tcp-request connection rejette si { src_conn_rate gt 10 }
tcp-request connection track-sc0 src
Exemple : accepter toutes les connexions provenant d’hôtes autorisés, compter toutes les autres connexions et rejeter celles qui sont trop rapides. Cela entraîne le blocage des connexions abusives tant qu’elles ne ralentissent pas.
tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
tcp-request connection track-sc0 src
tcp-request connection reject if { sc0_conn_rate gt 10 }
Exemple : activer le protocole PROXY pour le trafic provenant de tous les proxies connus.
tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
Voir section 7 concernant l’utilisation des ACL.
Voir aussi : « tcp-request session », « tcp-request content », « stick-table »
tcp-request content <action> [{if | unless} <condition>]
Effectuer une action sur une nouvelle session en fonction d’une condition au niveau couche 4 à 7
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui
Arguments :
Le contenu d’une requête peut être analysé à un stade précoce du traitement des requêtes appelé « inspection du contenu TCP ». Pendant ce stade, les règles basées sur les ACL sont évaluées à chaque mise à jour du contenu de la requête, jusqu’à ce qu’une règle « accept », « reject » ou « switch-mode » corresponde, ou que le délai d’inspection de la requête TCP expire sans règle correspondante.
La première différence entre ces règles et les règles « tcp-request connection » est que les règles « tcp-request content » peuvent utiliser le contenu pour prendre une décision. Le plus souvent, ces décisions portent sur une reconnaissance ou une validité de protocole. La deuxième différence est que les règles basées sur le contenu peuvent être utilisées aussi bien dans les frontaux que dans les backends. En cas de maintien de connexion HTTP avec le client, toutes les règles « tcp-request content » sont réévaluées, de sorte qu’HAProxy conserve une trace des compteurs persistants attribués par une règle « tcp-request connection » par rapport à une règle « tcp-request content », et vide tous les compteurs liés au contenu après le traitement d’une requête, afin qu’ils puissent être réévalués par les règles lors de la prochaine requête. Ceci est particulièrement important lorsque la règle suit certaines informations L7 ou lorsqu’elle est conditionnée par une ACL basée sur L7, car le suivi peut varier entre les requêtes.
Les règles basées sur le contenu sont évaluées dans l’ordre exact de leur déclaration. Si aucune règle ne correspond ou s’il n’y a aucune règle, l’action par défaut consiste à accepter les contenus. Aucune limite spécifique n’est imposée au nombre de règles pouvant être insérées.
Bien qu’il ne soit pas obligatoire, il est recommandé d’utiliser track-sc0 dans les règles « tcp-request connection », track-sc1 pour les règles « tcp-request content » dans le frontal, et track-sc2 pour les règles « tcp-request content » dans le backend, car cela rend la configuration plus lisible et plus facile à dépanner, mais il s’agit simplement d’une recommandation et tous les compteurs peuvent être utilisés partout.
Le premier mot-clé après « tcp-request content » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour l’action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « TCP RqCnt »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Notez que la condition “if/unless” est facultative. Si aucune condition n’est définie sur l’action, celle-ci est simplement exécutée sans condition. Cela peut être utile pour les actions “track-sc*” ainsi que pour modifier l’action par défaut en rejet.
Notez également qu’il est recommandé d’utiliser une règle « tcp-request session » pour suivre les informations qui ne dépendent pas du contenu au niveau 7, en particulier pour les frontaux HTTP. Certaines opérations HTTP sont effectuées au niveau de la session et peuvent entraîner un rejet prématuré des requêtes. Le suivi au niveau du contenu peut alors être perturbé dans de tels cas. Un avertissement est émis au démarrage afin, dans la mesure du possible, d’éviter une utilisation défaillante.
Il est tout à fait possible de correspondre au contenu au niveau 7 à l’aide de règles « tcp-request content » depuis un proxy TCP, car les correspondances ACL spécifiques à HTTP sont capables de parser préalablement le contenu d’un tampon avant d’extraire les données requises. Si le contenu tamponné ne se parse pas comme un message HTTP valide, alors l’ACL ne correspond pas. Le parseur utilisé à cet effet est exactement le même que celui utilisé pour tout autre traitement HTTP, si bien qu’il n’y a aucun risque de parser différemment. Dans un frontend HTTP ou un backend HTTP, il est garanti que le contenu HTTP sera toujours immédiatement disponible au moment de l’évaluation de la règle, car l’analyse HTTP est effectuée en phase précoce du traitement de la connexion, au niveau de la session. Toutefois, pour de tels proxies, l’utilisation de règles « http-request » est bien plus naturelle et recommandée.
Le suivi des informations layer7 est également possible, à condition que ces informations soient disponibles au moment du traitement de la règle. Le moteur de traitement des règles est capable d’attendre jusqu’à l’expiration du délai d’inspection lorsque les données à suivre ne sont pas encore disponibles.
Exemple :
Exemple :
Exemple :
Exemple :
Exemple :
Exemple :
Exemple : suivre les compteurs par frontal et par backend, bloquer les abusateurs au niveau du frontal lorsque le backend détecte un abus (et signale GPC0).
frontend http
# Utiliser le compteur généralisé 0 dans SC0 comme compteur global d'abus
# protégeant tous nos sites
stick-table type ip size 1m expire 5m store gpc0
tcp-request connection track-sc0 src
tcp-request connection reject if { sc0_get_gpc0 gt 0 }
...
use_backend http_dynamic if { path_end .php }
backend http_dynamic
# si une source effectue trop de requêtes trop rapidement vers ce site dynamique (suivi par SC1), bloquer cette source globalement au niveau du frontal.
stick-table type ip size 1m expire 5m store http_req_rate(10s)
acl click_too_fast sc1_http_req_rate gt 10
acl mark_as_abuser sc0_inc_gpc0(http) gt 0
tcp-request content track-sc1 src
tcp-request content reject if click_too_fast mark_as_abuser
Voir section 7 concernant l’utilisation des ACL.
Voir également : « tcp-request connection », « tcp-request session », « tcp-request inspect-delay » et « http-request ».
tcp-request inspect-delay <timeout>
Définir le délai maximal autorisé d’attente des données lors de l’inspection du contenu
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | oui
Arguments :
Les utilisateurs qui utilisent principalement HAProxy comme relais TCP s’inquiètent souvent du risque de transmettre tout type de protocole à un serveur sans analyse. Pour pouvoir analyser le contenu des requêtes, il est nécessaire de retarder temporairement les données, puis de les analyser. Cette directive permet simplement de retarder les données pendant au plus la durée spécifiée.
L’inspection du contenu TCP s’applique très tôt, lorsque la connexion atteint un frontal, puis très tôt lorsque la connexion est acheminée vers un backend. Cela signifie qu’une connexion peut subir un premier délai au niveau du frontal et un second délai au niveau du backend si les deux disposent de règles tcp-request.
Notez que, lors de l’inspection du contenu, HAProxy évaluera toutes les règles pour chaque nouveau morceau entrant, en tenant compte du fait que ces données sont partielles. Si aucune règle ne correspond avant le délai mentionné, une dernière vérification est effectuée à l’expiration, cette fois-ci en considérant que les contenus sont définitifs. Si aucun délai n’est défini, HAProxy ne patientera pas du tout et appliquera immédiatement un jugement fondé sur les informations disponibles. Évidemment, cela est peu susceptible d’être très utile et pourrait même être sujet à des conditions de course, aussi de telles configurations ne sont pas recommandées.
Notez que le délai d’inspection est raccourci en cas d’erreur de connexion ou d’arrêt, ou si le tampon de requête semble plein.
Dès qu’une règle correspond, la requête est libérée et poursuit son cours normalement. Si le délai d’expiration est atteint et qu’aucune règle ne correspond, la politique par défaut consiste à la laisser passer sans modification.
Pour la plupart des protocoles, il suffit de le définir à quelques secondes, car la plupart des clients envoient intégralement leur requête immédiatement après la connexion. Ajoutez 3 secondes ou plus pour couvrir les retransmissions TCP, mais pas davantage. Pour certains protocoles, il peut être pertinent d’utiliser des valeurs élevées, par exemple pour garantir que le client ne communique jamais avant le serveur (par exemple, SMTP), ou pour attendre que le client émette une communication avant de transmettre des données au serveur (par exemple, SSL). Notez que le délai d’expiration du client doit couvrir au moins le délai d’inspection, sinon il expirera en premier. Si le client ferme la connexion ou si la mémoire tampon est pleine, le délai expire immédiatement, car les contenus ne pourront plus évoluer.
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les proxies héritent cette valeur de leur section defaults.
Voir aussi : « tcp-request content accept », « tcp-request content reject », « timeout client ».
tcp-request session <action> [{if | unless} <condition>]
Effectuer une action sur une session validée en fonction d’une condition au niveau 5
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | oui | oui | non
Arguments :
Une fois une session validée (c’est-à-dire après la fin de toutes les négociations), il est possible d’évaluer certaines conditions afin de décider si cette session doit être acceptée, rejetée ou si ses compteurs doivent être suivis. Ces conditions ne peuvent pas utiliser les contenus de données, car aucun tampon n’a encore été alloué et le traitement ne peut pas attendre à ce stade. Le cas d’usage principal consiste à copier certaines informations précoces dans des variables (puisqu’il est possible d’accéder aux variables au niveau de la session), ou à suivre certaines informations collectées après la négociation, telles que des éléments au niveau SSL (SNI, chiffres, CN du certificat client) ou des informations provenant de l’en-tête du protocole PROXY (par exemple, suivre une source transmise de cette manière). Les informations extraites peuvent ainsi être copiées dans une variable ou suivies à l’aide de règles « track-sc ». Bien entendu, il est également possible de décider de accept/reject comme pour les autres jeux de règles. La plupart des opérations effectuées ici pourraient également être réalisées dans des règles « tcp-request content », à ceci près que, en HTTP, ces règles sont évaluées pour chaque nouvelle requête, ce qui n’est pas toujours acceptable. Par exemple, une règle pourrait incrémenter un compteur à chaque évaluation. Il serait également possible qu’un pays soit déterminé par géolocalisation à partir de l’adresse IP source, affecté à une variable au niveau de la session, puis que l’adresse source soit réécrite à partir d’un en-tête HTTP pour toutes les requêtes. Si certaines données doivent être inspectées afin de prendre la décision, il convient alors d’utiliser les instructions « tcp-request content » à la place.
Les règles « tcp-request session » sont évaluées dans l’ordre exact de leur déclaration. Si aucune règle ne correspond ou s’il n’y a aucune règle, l’action par défaut consiste à accepter la session entrante. Il n’existe aucune limite spécifique au nombre de règles pouvant être insérées.
Le premier mot-clé après « tcp-request session » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour l’action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées de « TCP RqSes »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Notez que la condition “if/unless” est facultative. Si aucune condition n’est définie sur l’action, celle-ci est simplement exécutée sans condition. Cela peut être utile pour les actions “track-sc*” ainsi que pour modifier l’action par défaut en rejet.
Exemple : suivre l’adresse source d’origine par défaut, ou celle annoncée dans l’en-tête PROXY pour les connexions provenant des proxies locaux. La première règle au niveau de la connexion permet la réception du protocole PROXY pour ces dernières, la deuxième règle suit l’adresse que nous décidons de conserver après décodage éventuel.
tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
tcp-request session track-sc0 src
Exemple : accepter toutes les sessions provenant d’hôtes listés blancs, rejeter les sessions trop rapides sans les compter, et suivre les sessions acceptées. Cela permet de limiter le débit des sessions provenant de sources abusives.
tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
tcp-request session reject if { src_sess_rate gt 10 }
tcp-request session track-sc0 src
Exemple : accepter toutes les sessions provenant d’hôtes listés blancs, compter toutes les autres sessions et rejeter celles qui sont trop rapides. Cela entraîne le blocage des connexions abusives tant qu’elles ne ralentissent pas.
tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
tcp-request session track-sc0 src
tcp-request session reject if { sc0_sess_rate gt 10 }
Voir section 7 concernant l’utilisation des ACL.
Voir aussi : « tcp-request connection », « tcp-request content », « stick-table »
tcp-response content <action> [{if | unless} <condition>]
Effectuer une action sur une réponse de session en fonction d’une condition au niveau couche 4-7
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | non | oui | oui
Arguments :
Le contenu de la réponse peut être analysé à un stade précoce du traitement de la réponse, appelé « inspection du contenu TCP ». Pendant cette phase, les règles basées sur les ACL sont évaluées à chaque mise à jour du contenu de la réponse, jusqu’à ce qu’une règle finale corresponde, ou qu’une durée d’attente pour l’inspection du contenu TCP soit définie et expire sans qu’aucune règle ne corresponde.
Souvent, ces décisions tiennent compte de la reconnaissance ou de la validité d’un protocole.
Les règles basées sur le contenu sont évaluées dans l’ordre exact de leur déclaration. Si aucune règle ne correspond ou s’il n’y a aucune règle, l’action par défaut consiste à accepter les contenus. Aucune limite spécifique n’est imposée au nombre de règles pouvant être insérées.
Le premier mot-clé après « tcp-response content » dans la syntaxe est l’action de la règle, éventuellement suivi d’un nombre variable d’arguments pour cette action. Les actions prises en charge ainsi que leurs syntaxes respectives sont énumérées dans section 4.3 « Actions » (rechercher les actions marquées par « TCP RsCnt »).
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les règles définies dans la section defaults sont évaluées avant celles de la section proxy associée. Pour éviter les ambigüités, dans ce cas, une même section defaults ne peut pas être utilisée par des proxies possédant la capacité frontend et par des proxies possédant la capacité backend. Cela signifie qu’une section listen ne peut pas utiliser une section defaults définissant de telles règles.
Notez que la condition “if/unless” est facultative. Si aucune condition n’est définie sur l’action, celle-ci est simplement exécutée sans condition. Cela peut être utile pour modifier l’action par défaut en rejet.
Plusieurs types d’actions sont pris en charge :
Il est tout à fait possible de correspondre au contenu au niveau 7 à l’aide des règles « tcp-response content », mais il est alors essentiel de s’assurer qu’une réponse complète a été mise en mémoire tampon, faute de quoi aucun contenu ne correspondra. Pour y parvenir, la meilleure solution consiste à détecter le protocole HTTP pendant la période d’inspection.
Voir section 7 concernant l’utilisation des ACL.
Voir également : « tcp-request content », « tcp-response inspect-delay »
tcp-response inspect-delay <timeout>
Définir le délai maximal autorisé d’attente d’une réponse lors de l’inspection du contenu
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui(!) | non | oui | oui
Arguments :
Cette directive n’est disponible que dans les sections defaults nommées, et non dans les sections anonymes. Les proxies héritent cette valeur de leur section defaults.
Voir également : « tcp-response content », « tcp-request inspect-delay ».
timeout check <timeout>
Définir un délai d’expiration supplémentaire pour la vérification, mais uniquement après qu’une connexion a déjà été établie.
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 :
Si défini, HAProxy utilise min(“délai d’expiration connect”, “inter”) comme délai d’expiration de connexion pour les vérifications et “délai d’expiration vérification” comme délai d’expiration de lecture supplémentaire. La fonction min est utilisée afin que les utilisateurs configurés avec des délais d’expiration de connexion très longs (par exemple, ceux qui en avaient besoin en raison de la file d’attente ou du tarpit) ne ralentissent pas leurs vérifications. (Veuillez noter qu’il n’existe aucune raison valable de définir des délais d’expiration de connexion aussi longs, car “délai d’expiration file d’attente” et “délai d’expiration tarpit” peuvent toujours être utilisés pour éviter cela).
Si « timeout check » n’est pas défini, HAProxy utilise « inter » pour le délai d’expiration complet de la vérification (connexion + lecture), exactement comme toutes les versions <1.3.15.
Dans la plupart des cas, le traitement de la requête de vérification est bien plus simple et rapide que celui des requêtes normales, et les utilisateurs souhaitent souvent éliminer les serveurs en retard ; ce délai d’expiration doit donc être inférieur à « timeout server ».
Ce paramètre est spécifique aux backends, mais peut être défini une fois pour tous dans les sections « defaults ». Il s’agit en réalité l’une des solutions les plus simples pour ne pas l’oublier.
Voir également : « timeout connect », « timeout queue », « timeout server », « timeout tarpit ».
timeout client <timeout>
Définir le délai maximal d’inactivité 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 :
Le délai d’expiration inactif s’applique lorsque le client est censé confirmer ou envoyer des données. En mode HTTP, ce délai est particulièrement important à prendre en compte pendant la première phase, lorsque le client envoie la requête, ainsi que pendant la réponse, lorsqu’il lit les données envoyées par le serveur. Toutefois, pour la première phase, il est préférable de définir « timeout http-request » afin de mieux protéger HAProxy contre les attaques du type Slowloris. La valeur est 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 indiqué en haut de ce document. En mode TCP (et dans une moindre mesure en mode HTTP), il est fortement recommandé que le délai d’expiration client reste égal au délai d’expiration serveur afin d’éviter des situations complexes à déboguer. Il est bon de prévoir une couverture d’une ou plusieurs pertes de paquets TCP en définissant des délais légèrement supérieurs à des multiples de 3 secondes (par exemple 4 ou 5 secondes). Si des flux longs coexistent avec des flux courts (par exemple WebSocket et HTTP), il peut être pertinent de considérer « timeout tunnel », qui remplace « timeout client » et « timeout server » pour les tunnels, ainsi que « timeout client-fin » pour les connexions demi-fermées.
Ce paramètre est spécifique aux frontaux, mais peut être défini une fois pour tous dans les sections « defaults ». Il s’agit en réalité l’une des solutions les plus simples pour ne pas l’oublier. Un délai d’expiration non spécifié entraîne un délai d’expiration infini, ce qui n’est pas recommandé. Une telle utilisation est acceptée et fonctionne, mais provoque un avertissement au démarrage, car elle peut entraîner un accumulation de sessions expirées dans le système si les délais d’expiration du système ne sont pas configurés non plus.
Voir également : « timeout server », « timeout tunnel », « timeout http-request ».
timeout client-fin <timeout>
Définir le délai d’expiration d’inactivité du côté client pour les connexions demi-fermées.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Le délai d’expiration d’inactivité s’applique lorsque le client est censé confirmer ou envoyer des données alors qu’une direction est déjà fermée. Ce délai diffère de « timeout client » car il ne s’applique qu’aux connexions dont une direction est fermée. Cette fonction est particulièrement utile pour éviter de maintenir les connexions dans l’état FIN_WAIT trop longtemps lorsque les clients ne se déconnectent pas correctement. Ce problème est particulièrement fréquent avec des connexions longues, telles que RDP ou WebSocket. Notez que ce délai peut remplacer « timeout tunnel » lorsque la connexion est fermée dans une seule direction. Il s’applique aux connexions HTTP/2 inactives une fois qu’un cadre GOAWAY a été envoyé, ce qui indique souvent une attente de fermeture rapide de la connexion.
Ce paramètre est spécifique aux frontaux, mais peut être défini une fois pour tous dans les sections « defaults ». Par défaut, il n’est pas défini, de sorte que les connexions demi-ouvertes utilisent les autres délais d’expiration (timeout.client ou timeout.tunnel).
Voir également : « timeout client », « timeout server-fin » et « timeout tunnel ».
timeout client-hs <timeout>
Définir le délai maximal d’attente pour la finalisation de la négociation TLS du client. Cette option est utilisable pour les connexions TCP et QUIC.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Si ce délai d’expiration de handshake n’est pas défini, il s’agit du délai d’expiration client utilisé à la place.
timeout connect <timeout>
Définir le temps maximal d’attente pour qu’une tentative de connexion à un serveur aboutisse.
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 :
Si le serveur est situé sur le même LAN que HAProxy, la connexion doit être immédiate (moins de quelques millisecondes). En tout état de cause, il est recommandé de prévoir un délai d’expiration légèrement supérieur à un ou plusieurs multiples de 3 secondes (par exemple 4 ou 5 secondes) afin de couvrir une ou plusieurs pertes de paquets TCP. Par défaut, le délai d’expiration de connexion préconfigure également les délais d’expiration de file d’attente et de tarpit à la même valeur, si ces derniers n’ont pas été spécifiés.
Ce paramètre est spécifique aux backends, mais peut être défini une fois pour tous dans les sections « defaults ». Il s’agit en réalité l’une des solutions les plus simples pour ne pas l’oublier. Un délai d’expiration non spécifié entraîne un délai d’expiration infini, ce qui n’est pas recommandé. Une telle utilisation est acceptée et fonctionne, mais provoque un avertissement au démarrage, car elle peut entraîner un accumulation de sessions défaillantes dans le système si les délais d’expiration du système ne sont pas configurés non plus.
Voir également : « timeout check », « timeout queue », « timeout server », « timeout tarpit ».
timeout http-keep-alive <timeout>
Définir le délai maximal autorisé d’attente pour la venue d’une nouvelle requête HTTP
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Par défaut, le délai d’expiration d’attente d’une nouvelle requête en cas de maintien de la connexion (keep-alive) est défini par « timeout http-request ». Toutefois, cela n’est pas toujours pratique, car certaines personnes souhaitent des délais d’expiration très courts pour libérer les connexions plus rapidement, tandis que d’autres préfèrent des délais plus longs, mais souhaitent tout de même des délais courts une fois la requête en cours.
Le délai d’expiration « http-keep-alive » répond à ces besoins. Il détermine la durée d’attente d’une nouvelle requête HTTP après l’envoi d’une réponse. Dès que le premier octet de la requête est détecté, le délai d’expiration « http-request » est utilisé pour attendre la réception complète de la requête. Notez que les lignes vides précédant une nouvelle requête ne réinitialisent pas le délai d’expiration et ne sont pas comptées comme une nouvelle requête.
Il existe également une autre différence entre les deux délais d’expiration : lorsque la connexion expire pendant le délai d’expiration http-keep-alive, aucune erreur n’est renvoyée, la connexion se ferme simplement. Si la connexion expire pendant le délai d’expiration “http-request” en attendant la fin d’une requête, une erreur HTTP 408 est renvoyée au client avant la fermeture de la connexion, sauf si l’option “option http-ignore-probes” est définie dans le frontal.
En général, « timeout http-keep-alive » doit être utilisé pour empêcher les clients de maintenir une connexion inactif trop longtemps sur des sites recevant un grand nombre de connexions courtes. Cela peut être réalisé en définissant la valeur à quelques dizaines à plusieurs centaines de millisecondes dans HTTP/1.1.. Cela fermera la connexion après que le client ait demandé une page, sans avoir à la maintenir ouverte pour attendre une nouvelle activité du client. Dans ce scénario, une nouvelle activité du navigateur entraînera une nouvelle négociation au niveau TCP et/ou SSL. Un cas d’utilisation courant est celui des sites HTTP qui ne servent qu’une redirection vers la page HTTPS. Ces connexions ne doivent pas rester inactives trop longtemps, car elles ne seront pas réutilisées, sauf peut-être pour télécharger une favicon.
Un autre cas d’utilisation est l’exact opposé : certaines sites souhaitent autoriser les clients à réutiliser des connexions inactives pendant une longue durée (par exemple 30 secondes à une minute), mais ne veulent pas attendre aussi longtemps pour la première requête, afin d’éviter une vector d’attaque très peu coûteux. Dans ce cas, le délai d’expiration http-keep-alive serait défini sur une valeur élevée, mais le délai d’expiration http-request resterait faible (quelques secondes).
Lorsqu’il est défini à une valeur très faible, les requêtes supplémentaires qui ne sont pas en pipeline risquent d’être traitées sur une autre connexion, sauf si les requêtes sont véritablement en pipeline, ce qui est très rare avec HTTP/1.1 (les requêtes envoyées bout à bout sans attendre de réponse). La plupart des implémentations de HTTP/1.1 envoient une requête, attendent la réponse, puis envoient une autre requête. Une valeur faible ici pour HTTP/1.1 peut être avantageuse pour réduire l’utilisation de mémoire et de sockets sur des sites comptant des centaines de milliers de clients, au prix d’une augmentation des coûts de calcul liés à l’établissement de connexion.
Une attention particulière doit être portée aux valeurs faibles lors de la gestion de HTTP/2.. La nature de HTTP/2 consiste à multiplexer les requêtes sur une connexion afin de réduire les surcoûts liés à la reconnexion au niveau des couches TCP et/ou SSL. Le protocole utilise également des trames de contrôle qui réagissent mal à la fermeture prématurée des connexions TCP, situation extrêmement rare pouvant entraîner des réponses tronquées lorsque les données sont perdues en transit après avoir quitté HAProxy (ce qui empêche même la journalisation d’une erreur). Une valeur basse suggérée pour HTTP/2 serait d’environ 4 secondes. Cela empêche la plupart des implémentations modernes de keep-alive de maintenir inutilement des connexions obsolètes, tout en permettant aux requêtes ultérieures de réutiliser la connexion. Toutefois, cette valeur doit être ajustée selon les besoins et ne constitue qu’un point de départ.
Si ce paramètre n’est pas défini, le délai d’expiration « http-request » s’applique ; si les deux ne sont pas définis, le délai d’expiration « timeout client » s’applique tout de même au niveau inférieur. Il doit être défini dans le frontal pour prendre effet, sauf si le frontal est en mode TCP, auquel cas le délai d’expiration du backend HTTP sera utilisé.
Voir également : « timeout http-request », « timeout client ».
timeout http-request <timeout>
Définir le délai maximal autorisé d’attente pour une requête HTTP complète
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Afin d’offrir une protection contre les attaques DoS, il peut être nécessaire de réduire le délai d’expiration maximal accepté pour recevoir une requête HTTP complète, sans affecter le délai d’expiration client. Cela permet de se protéger contre les connexions établies sur lesquelles aucune donnée n’est transmise. Le délai d’expiration client ne peut offrir une protection efficace contre ce type d’abus, car il s’agit d’un délai d’inactivité, ce qui signifie qu’une attaque consistant à envoyer un caractère de temps à autre ne déclenchera pas le délai. Grâce au délai d’expiration de requête HTTP, quelle que soit la vitesse à laquelle le client tape, la requête sera interrompue si elle n’est pas complète dans les délais. Lorsque le délai expire, une réponse HTTP 408 est envoyée au client pour l’informer du problème, puis la connexion est fermée. Les journaux rapporteront des codes de terminaison « cR ». Certains navigateurs récents rencontrent des problèmes avec ce comportement standard et bien documenté, il peut donc être nécessaire de masquer le code 408 en utilisant « option http-ignore-probes » ou « errorfile 408 /dev/null ». Pour plus de détails, consulter les explications concernant le code de terminaison « cR » dans la section 8.5 de .
Par défaut, ce délai d’expiration s’applique uniquement à la partie en-tête de la requête, et non aux données. Dès que la ligne vide est reçue, ce délai d’expiration n’est plus utilisé. Lorsqu’il est combiné avec « option http-buffer-request », ce délai d’expiration s’applique également au corps de la requête. Il est réutilisé sur les connexions keep-alive pour attendre une deuxième requête si « timeout http-keep-alive » n’est pas défini.
En général, il suffit de le définir à quelques secondes, car la plupart des clients envoient entièrement la requête immédiatement après la connexion. Ajoutez 3 secondes ou plus pour couvrir les retransmissions TCP, mais pas davantage. Une valeur très faible (par exemple 50 ms) fonctionne généralement sur les réseaux locaux, à condition qu’il n’y ait pas de perte de paquets. Cela empêche les utilisateurs d’envoyer des requêtes HTTP brutes via telnet.
Si ce paramètre n’est pas défini, le délai d’expiration client s’applique toujours entre chaque tranche de la requête entrante. Il doit être configuré dans le frontal pour prendre effet, sauf si le frontal est en mode TCP, auquel cas le délai d’expiration du backend HTTP sera utilisé.
Voir également : « errorfile », « http-ignore-probes », « timeout http-keep-alive » et « timeout client », « option http-buffer-request ».
timeout queue <timeout>
Définir le temps maximal d’attente dans la file d’attente pour qu’un slot de connexion devienne disponible
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Lorsque la limite maxconn d’un serveur est atteinte, les connexions sont placées en attente dans une file d’attente, qui peut être spécifique au serveur ou globale au backend. Afin de ne pas attendre indéfiniment, un délai d’expiration est appliqué aux requêtes en attente dans la file. Si ce délai d’expiration est atteint, la requête est considérée comme quasi impossible à traiter, elle est donc abandonnée et un code d’erreur 503 est renvoyé au client.
L’instruction « timeout queue » permet de définir le délai d’expiration maximal autorisé pour une requête en attente dans une file d’attente. Si non spécifié, la même valeur que le délai d’expiration de connexion du backend (« timeout connect ») est utilisée, afin de maintenir la compatibilité descendante avec les versions antérieures ne disposant pas de paramètre « timeout queue ».
Voir également : « timeout connect ».
timeout server <timeout>
Définir le délai maximal d’inactivité du côté serveur.
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 :
Le délai d’expiration d’inactivité s’applique lorsque le serveur est censé reconnaître une requête ou envoyer des données. En mode HTTP, ce délai est particulièrement important à prendre en compte pendant la première phase de la réponse du serveur, lorsqu’il doit envoyer les en-têtes, car il représente directement le temps de traitement du serveur pour la requête. Pour déterminer quelle valeur utiliser, il est souvent pertinent de commencer par définir les délais de réponse jugés inacceptables, puis de consulter les journaux pour observer la répartition des temps de réponse, et d’ajuster la valeur en conséquence.
La valeur est 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 indiqué en haut de ce document. En mode TCP (et, dans une moindre mesure, en mode HTTP), il est fortement recommandé que le délai d’expiration client reste égal au délai d’expiration serveur afin d’éviter des situations complexes à déboguer. Quelle que soit la durée de réponse attendue du serveur, il est bon de prévoir au moins une ou plusieurs pertes de paquets TCP en définissant des délais d’expiration légèrement supérieurs à des multiples de 3 secondes (par exemple, au moins 4 ou 5 secondes). Si des flux longs coexistent avec des flux courts (par exemple, WebSocket et HTTP), il peut être pertinent de considérer « timeout tunnel », qui remplace « timeout client » et « timeout server » pour les tunnels.
Ce paramètre est spécifique aux backends, mais peut être défini une fois pour tous dans les sections « defaults ». Il s’agit en réalité l’une des solutions les plus simples pour ne pas l’oublier. Un délai d’expiration non spécifié entraîne un délai d’expiration infini, ce qui n’est pas recommandé. Une telle utilisation est acceptée et fonctionne, mais provoque un avertissement au démarrage, car elle peut entraîner un accumulation de sessions expirées dans le système si les délais d’expiration du système ne sont pas configurés non plus.
Voir également : « timeout client » et « timeout tunnel ».
timeout server-fin <timeout>
Définir le délai d’expiration d’inactivité du côté serveur pour les connexions demi-fermées.
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 :
Le délai d’expiration d’inactivité s’applique lorsque le serveur est censé reconnaître ou envoyer des données alors qu’une direction de la connexion est déjà fermée. Ce délai diffère de « timeout server » car il ne s’applique qu’aux connexions dont une direction est fermée. Cette fonction est particulièrement utile pour éviter de maintenir les connexions dans l’état FIN_WAIT trop longtemps lorsque le serveur distant ne se déconnecte pas correctement. Ce problème est particulièrement fréquent avec des connexions longues telles que RDP ou WebSocket. Notez que ce délai peut remplacer « timeout tunnel » lorsque la connexion se ferme dans une seule direction. Ce paramètre a été ajouté pour complétude, mais dans la plupart des cas, il ne devrait pas être nécessaire.
Ce paramètre est spécifique aux backends, mais peut être défini une fois pour tous dans les sections « defaults ». Par défaut, il n’est pas configuré, de sorte que les connexions demi-ouvertes utilisent les autres délais d’expiration (timeout.server ou timeout.tunnel).
Voir également : « timeout client-fin », « timeout server » et « timeout tunnel ».
timeout tarpit <timeout>
Définir la durée pendant laquelle les connexions tarpittées seront maintenues
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Lorsqu’une connexion est soumise à un tarpit via la directive « http-request tarpit », elle reste ouverte sans activité pendant une durée déterminée, puis est fermée. La directive « timeout tarpit » définit la durée pendant laquelle elle reste ouverte.
La valeur est 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 indiqué en haut du présent document. Si non spécifiée, la même valeur que le délai d’expiration de connexion du backend (“timeout connect”) est utilisée, pour assurer la compatibilité descendante avec les versions antérieures ne disposant pas du paramètre “timeout tarpit”.
Voir également : « timeout connect ».
timeout tunnel <timeout>
Définir le délai maximal d’inactivité côté client et côté serveur pour les tunnels.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments :
Le délai d’expiration du tunnel s’applique lorsque une connexion bidirectionnelle est établie entre un client et un serveur, et que la connexion reste inactive dans les deux sens. Ce délai d’expiration remplace les délais d’expiration du client et du serveur une fois que la connexion devient un tunnel. En TCP, ce délai d’expiration est utilisé dès qu’aucun analyseur n’est attaché à l’une des connexions (par exemple, lorsque des règles de contenu TCP sont acceptées). En HTTP, ce délai d’expiration est utilisé lorsque la connexion est mise à niveau (par exemple, lors du passage au protocole WebSocket, ou lors du transfert d’une requête CONNECT vers un proxy), ou après la première réponse lorsque l’option keepalive/close n’est pas spécifiée.
Étant donné que ce délai d’expiration est généralement utilisé en conjonction avec des connexions longues, il est généralement recommandé de définir également « timeout client-fin » afin de gérer le cas où un client disparaît soudainement du réseau sans reconnaître la fermeture, ou en envoyant une fermeture sans reconnaître les données en attente. Cela peut survenir dans des réseaux bruyants où des pare-feu sont présents, et est détecté par la présence d’un grand nombre de sessions en état FIN_WAIT.
La valeur est 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 indiqué en haut de ce document. Quel que soit le délai d’inactivité normal attendu, il est recommandé de prévoir au moins une ou plusieurs pertes de paquets TCP en définissant des délais d’expiration légèrement supérieurs à des multiples de 3 secondes (par exemple, au moins 4 ou 5 secondes).
Ce paramètre est spécifique aux backends, mais peut être défini une fois pour tous dans les sections « defaults ». Il s’agit en réalité l’une des solutions les plus simples pour ne pas l’oublier.
Exemple :
Voir aussi : « timeout client », « timeout client-fin », « timeout server ».
transparent (deprecated)
Activer le proxy transparent côté client
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | non | oui | oui
Arguments : aucun
Ce mot-clé a été introduit afin de permettre une persistance au niveau 7 aux répartiteurs de charge au niveau 3. L’idée consiste à exploiter la capacité du système d’exploitation à rediriger une connexion entrante provenant d’une adresse distante vers un processus local (ici HAProxy), et à faire en sorte que ce processus connaisse l’adresse initialement demandée. Lorsque cette option est utilisée, les sessions sans cookies seront acheminées vers l’adresse IP d’origine de la requête entrante (qui doit correspondre à celle d’un autre équipement), tandis que les requêtes avec cookies seront toujours acheminées vers le serveur approprié.
Le mot-clé « transparent » est obsolète ; utilisez plutôt « option transparent ».
Notez qu’en dépit d’une croyance répandue, cette option ne fait pas que HAProxy présente l’adresse IP du client au serveur lors de l’établissement de la connexion.
Voir également : « option transparent »
unique-id-format <fmt>
Générez un identifiant unique pour chaque requête.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | oui
Arguments :
Ce mot-clé crée un identifiant pour chaque requête en utilisant le format de journalisation personnalisé. Un identifiant unique est utile pour suivre une requête traversant plusieurs composants d’une infrastructure complexe. L’identifiant nouvellement créé peut également être journalisé à l’aide de l’alias %ID dans la chaîne de format de journalisation personnalisé.
Le format doit être composé d’éléments garantissant l’unicité lorsqu’ils sont combinés. Par exemple, si plusieurs instances HAProxy sont impliquées, il peut être important d’inclure le nom du nœud. Il est souvent nécessaire de journaliser les adresses et ports source et destination de la connexion entrante. Notez qu’étant donné qu’une même connexion peut être utilisée pour plusieurs requêtes, inclure un compteur de requêtes peut aider à les distinguer. De même, une horodatage peut protéger contre un dépassement du compteur. Journaliser l’identifiant du processus évite les conflits après une redémarrage du service.
Il est recommandé d’utiliser la notation hexadécimale pour de nombreux champs, car elle les rend plus compacts et économise de l’espace dans les journaux.
Pour les connexions régulières, le format configuré dans le frontal est utilisé pour générer l’ID unique. Pour les contrôles d’état, le format du backend est utilisé lors de l’utilisation de la directive « unique-id » au sein d’une règle tcp-check ou http-check.
Exemple :
Voir également : « unique-id-header »
unique-id-header <name>
Ajoutez un en-tête d’ID unique dans la requête HTTP.
Peut être utilisé dans les contextes suivants : http
Peut être utilisé dans les sections : defaults | frontal | listen | backend oui | oui | oui | non
Arguments :
Ajoutez un en-tête unique-id à la requête HTTP envoyée au serveur, en utilisant le format unique-id-format. Cela ne peut pas fonctionner si le format unique-id-format n’existe pas.
Exemple :
use_backend <backend> [{if | unless} <condition>]
Passez à un backend spécifique if/unless lorsque une condition basée sur une ACL est remplie.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | oui | oui | non
Arguments :
Lors du commutateur de contenu, les connexions arrivent sur un frontal et sont ensuite acheminées vers divers backends selon un ensemble de conditions. La relation entre ces conditions et les backends est décrite à l’aide du mot-clé “use_backend”. Bien qu’il soit normalement utilisé avec le traitement HTTP, il peut également être utilisé en TCP pur, soit sans contenu en utilisant des ACLs sans état (par exemple, validation de l’adresse source), soit combiné avec une règle « tcp-request » pour attendre une partie du contenu.
Il peut y avoir autant de règles “use_backend” que souhaité. Toutes ces règles sont évaluées dans l’ordre de déclaration, et la première qui correspond attribue le backend. Cela reste valable même si le backend est considéré comme hors service. Toutefois, si une règle correspondante cible un backend désactivé ou non publié, elle est ignorée et l’évaluation des règles se poursuit.
Dans la première forme, le backend sera utilisé si la condition est remplie. Dans la deuxième forme, le backend sera utilisé si la condition n’est pas remplie. Si aucune condition n’est valide, le backend défini avec “default_backend” sera utilisé, à moins qu’il ne soit désactivé ou non publié. Si aucun backend par défaut n’est disponible, les serveurs de la même section sont utilisés (dans le cas d’une section « listen ») ou, dans le cas d’un frontal, aucun serveur n’est utilisé et une réponse 503 service unavailable est renvoyée.
Notez qu’il est possible de passer d’un frontend TCP à un backend HTTP. Dans ce cas, soit le frontend a déjà vérifié que le protocole est HTTP, auquel cas le traitement du backend suit immédiatement, soit le backend attend qu’une requête HTTP complète soit reçue. Cette fonctionnalité est utile lorsque un frontend doit déchiffrer plusieurs protocoles sur un même port, dont l’un est HTTP.
Lorsque <backend> est un nom simple, il est résolu au moment de la configuration, et une erreur est signalée si le backend spécifié n’existe pas. Si <backend> est un format d’enregistrement personnalisé, aucune vérification ne peut être effectuée au moment de la configuration, de sorte que le nom du backend est résolu dynamiquement à l’exécution. Si le nom de backend résultant ne correspond à aucun backend valide, aucune autre règle n’est évaluée, et la directive default_backend est appliquée à la place. Notez qu’en cas d’utilisation de noms de backend dynamiques, il est fortement recommandé d’utiliser un préfixe que aucun autre backend n’utilise afin d’assurer qu’un backend non autorisé ne puisse pas être imposé par la requête.
Il est à noter que les règles “use_backend” portant un nom explicite sont utilisées pour détecter l’association entre les frontaux et les backends afin de calculer le paramètre “fullconn” du backend. Cette opération ne peut pas être réalisée pour les noms dynamiques.
Voir également : “default_backend”, « tcp-request », « fullconn », « log-format » et section 7 concernant les ACL.
use-fcgi-app <name>
Définit l’application FastCGI à utiliser pour le backend.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Consultez section 10.1 pour plus de détails sur la configuration de l’application FastCGI.
use-server <server> if <condition>
Utilisez uniquement un serveur spécifique if/unless lorsque une condition basée sur une ACL est remplie.
Peut être utilisé dans les contextes suivants : tcp, http
Peut être utilisé dans les sections : defaults | frontal | listen | backend non | non | oui | oui
Arguments :
Par défaut, les connexions qui arrivent à un backend sont réparties en charge entre les serveurs disponibles selon l’algorithme configuré, sauf si un mécanisme de persistance, tel qu’un cookie, est utilisé et détecté dans la requête.
Parfois, il est utile de rediriger une requête particulière vers un serveur spécifique sans devoir déclarer un backend dédié pour ce serveur. Cela peut être réalisé à l’aide des règles « use-server ». Ces règles sont évaluées après les règles « redirect » et avant l’évaluation des cookies, et elles ont une priorité sur celles-ci. Il peut y avoir autant de règles « use-server » que souhaité. Toutes ces règles sont évaluées dans l’ordre de leur déclaration, et la première qui correspond attribue le serveur.
Si une règle désigne un serveur hors service, et que « option persist » n’est pas utilisée et qu’aucune règle « force-persist » n’a été validée, la règle est ignorée et l’évaluation continue avec les règles suivantes jusqu’à ce qu’une correspondance soit trouvée.
Dans la première forme, le serveur sera utilisé si la condition est remplie. Dans la deuxième forme, le serveur sera utilisé si la condition n’est pas remplie. Si aucune condition n’est valide, le traitement continue et le serveur sera affecté selon d’autres mécanismes de persistance.
Notez qu’un cookie est toujours traité, même si une règle est correspondante, mais aucun serveur n’est alors attribué. Cela permet de supprimer le préfixe des cookies préfixés.
L’instruction « use-server » fonctionne aussi bien en mode HTTP qu’en mode TCP. Cela la rend adaptée à une inspection basée sur le contenu. Par exemple, un serveur peut être sélectionné dans une ferme en fonction du champ TLS SNI lors de l’utilisation de protocoles avec TLS implicite (voir également “req.ssl_sni”). Et si le poids de ces serveurs est défini à zéro, ils ne seront pas utilisés pour le trafic autre que celui pour lequel ils ont été sélectionnés.
Exemple :
Lorsque <server> est un nom simple, il est vérifié par rapport aux serveurs existants dans la configuration, et une erreur est signalée si le serveur spécifié n’existe pas. Si c’est un format de journal personnalisé, aucune vérification n’est effectuée lors de l’analyse de la configuration, et si un nom de serveur valide ne peut pas être résolu à l’exécution, mais que la règle use-server est conditionnée par une ACL renvoyant true, aucune autre règle use-server n’est appliquée et on passe à la répartition de charge.
Voir également : “use_backend”, section 5 concernant le serveur et section 7 concernant les listes de contrôle d’accès.
4.3. Mots-clés de gestion des actions
Plusieurs jeux de règles sont évalués à divers stades du traitement de la requête ou de la réponse, et pour chaque règle trouvée dans ces jeux de règles, une action peut être exécutée si la condition facultative est remplie.
Un grand nombre d’actions sont fournies par défaut ; elles peuvent modifier les contenus, accept/block le traitement, modifier les états internes, etc. Il est également possible de définir de nouvelles actions en Lua (dans ce cas, leurs noms seront toujours préfixés par “lua.”).
Bien que certaines actions aient historiquement existé uniquement dans des jeux de règles spécifiques, de nombreuses actions sont désormais utilisables avec plusieurs jeux de règles. La liste présentée dans cette section indique pour quel(s) jeu(x) de règles pris en charge une action peut être utilisée, en cochant les noms abrégés correspondants parmi les jeux de règles suivants :
- QUIC Ini : l’action est valide pour les règles « quic-initial »
- TCP RqCon : l’action est valide pour les règles « tcp-request connection »
- TCP RqSes : l’action est valide pour les règles « tcp-request session »
- TCP RqCnt : l’action est valide pour les règles « tcp-request content »
- TCP RsCnt : l’action est valide pour les règles « tcp-response content »
- HTTP Req : l’action est valide pour les règles « http-request »
- HTTP Res : l’action est valide pour les règles « http-response »
- HTTP Aft : l’action est valide pour les règles « http-after-response »
Les mêmes abréviations sont utilisées dans la référence section 4.4 ci-dessous.
4.4. Référence des actions triées par ordre alphabétique
Cette section décrit en détail chaque action et son utilisation, en appliquant les mêmes règles de terminologie et de marquage que celles décrites dans section 4.3 ci-dessus.
accept
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | - | - | -
Cela arrête l’évaluation des règles et permet à la requête ou à la réponse de passer le contrôle. Cette action est définitive, c’est-à-dire qu’aucune règle supplémentaire du même jeu de règles n’est évaluée pour la section courante. Il n’existe aucune différence entre cette action et l’action « allow », à l’exception du fait que, pour des raisons de compatibilité historique, « accept » est utilisé pour les règles TCP et QUIC, tandis que « allow » est utilisé pour les règles HTTP. Voir également l’action « allow » ci-dessous.
add-acl(<file-name>) <key fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela permet d’ajouter une nouvelle entrée à une liste de contrôle d’accès (ACL). L’ACL doit être chargée à partir d’un fichier (même un fichier vide dummy). Le nom du fichier ACL à mettre à jour est passé entre parenthèses. Il prend un argument : <key fmt>, qui suit les règles de format de journalisation personnalisée décrites dans la section 8.2.6
, afin de collecter le contenu de la nouvelle entrée. Une recherche est effectuée dans l’ACL avant l’insertion, afin d’éviter les valeurs en double (ou supplémentaires). Il équivaut à la commande « add acl » du socket de statistiques, mais peut être déclenché par une requête HTTP.
add-header <name> <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela ajoute un champ d’en-tête HTTP dont le nom est spécifié dans <name> et dont la valeur est définie par <fmt>, selon les règles du format de journalisation personnalisé (voir Format de journalisation personnalisé dans la section 8.2.6 ). Cela est particulièrement utile pour transmettre des informations spécifiques à la connexion au serveur (par exemple, le certificat SSL du client), ou pour combiner plusieurs en-têtes en un seul. Cette règle n’est pas définitive, il est donc possible d’ajouter d’autres règles similaires. Notez que l’ajout d’en-tête est effectué immédiatement, de sorte qu’une règle peut réutiliser l’en-tête résultant d’une règle précédente.
add-headers-bin <expr> [ prefix <str> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Il s’agit d’une variante de l’action « add-header » où les noms et les valeurs des en-têtes sont transmis sous forme de chaîne binaire encodée en varint. Consultez l’extraction d’échantillon “req.hdrs_bin” pour en savoir plus sur le format varint. Cette fonctionnalité est utile lorsque vous souhaitez définir plusieurs en-têtes en une seule fois, sans avoir besoin de connaître à l’avance les noms des en-têtes. Notez que ces en-têtes n’ont pas été validés par le parseur HTTP et pourraient entraîner l’émission de messages non valides, voire, dans les cas les plus graves, des attaques par camouflage de requête. Le nombre d’en-têtes insérés est également important, car il est limité par tune.http.maxhdr. Un préfixe facultatif n’appliquera les en-têtes provenant de la chaîne encodée que s’ils commencent par <str>.
Exemple :
allow
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela arrête l’évaluation des règles et permet à la requête de passer le contrôle. Cette action est définitive, c’est-à-dire qu’aucune règle supplémentaire du même jeu de règles n’est évaluée pour la section courante. Il n’y a aucune différence entre cette action et l’action « accept » sauf que, pour des raisons de compatibilité historique, « accept » est utilisé pour les règles TCP et « allow » pour les règles HTTP. Voir également l’action « accept » ci-dessus.
attach-srv <srv> [name <expr>] [ EXPERIMENTAL ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | X | - | - | - | - | -
Cela permet d’intercepter la connexion après établissement correct de HTTP/2. La connexion est inversée du côté backend et insérée dans le pool inactif du serveur <srv>. Cette fonctionnalité ne peut être utilisée qu’avec des serveurs disposant d’une adresse ‘rhttp@’.
La connexion est insérée dans le pool de connexions inactives du serveur avec un nom défini par le résultat de l’évaluation de <expr>. Ce nom est celui qui sera utilisé pour la correspondance par les requêtes soumises aux paramètres “pool-conn-name” ou “sni”. Voir “http-reuse” pour plus de détails.
Le proxy HTTP inverse est actuellement toujours en développement actif. Le mécanisme de configuration peut évoluer à l’avenir. Pour cette raison, il est marqué internement comme expérimental, ce qui signifie que la directive « expose-experimental-directives » doit apparaître sur une ligne précédant cette directive.
Notez qu’un protocole très similaire mais indépendant est en cours de développement. Voir https://www.ietf.org/archive/id/draft-bt-httpbis-reverse-http-00.html .
auth [realm <realm>]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela arrête l’évaluation des règles et renvoie immédiatement un code d’erreur HTTP 401 ou 407 pour inviter l’utilisateur à fournir un nom d’utilisateur et un mot de passe valides. Aucune autre règle “http-request” n’est évaluée. Un paramètre facultatif “realm” est pris en charge ; il définit le domaine d’authentification renvoyé dans la réponse (généralement le nom de l’application).
Le message d’erreur du proxy correspondant est utilisé. Il peut être personnalisé à l’aide d’une directive « errorfile » ou « http-error ». Pour les réponses 401, toutes les occurrences de l’en-tête WWW-Authenticate sont supprimées et remplacées par un nouvel en-tête comportant un défi d’authentification basique pour le domaine “<realm>”. Pour les réponses 407, l’opération est identique sur l’en-tête Proxy-Authenticate. Si le message d’erreur ne doit pas être modifié, envisagez d’utiliser une règle « http-request return » à la place.
Exemple :
cache-store <name>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | - | X | -
Stocke une réponse HTTP dans le cache. Le stockage des en-têtes de réponse s’effectue à cette étape, ce qui signifie que vous pouvez utiliser d’autres actions de réponse HTTP pour modifier les en-têtes avant ou après le stockage de la réponse. Cette action est responsable de la configuration du filtre de stockage du cache.
Voir section 6.2 concernant la configuration du cache.
cache-use <name>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Essayer de livrer un objet mis en cache depuis le cache <name>. Cette directive est également obligatoire pour stocker le cache, car elle calcule le hachage du cache. Si vous souhaitez utiliser une condition à la fois pour le stockage et la livraison, il est recommandé de la placer après celle-ci.
Voir section 6.2 concernant la configuration du cache.
capture <sample> [ len <length> | id <id> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | X | X
Cela capture l’expression d’échantillon <sample> dans le tampon de requête ou de réponse, et la convertit en chaîne de maximum <len> caractères. La chaîne résultante est stockée dans la prochaine case de capture (requête ou réponse), où elle apparaîtra éventuellement à côté d’autres en-têtes HTTP capturés. Elle apparaîtra ensuite automatiquement dans les journaux, et il sera possible de l’extraire à l’aide des méthodes d’extraction d’échantillon afin de la transmettre à des en-têtes ou à tout autre élément. La longueur doit être limitée, car cette taille sera allouée pour chaque capture pendant toute la durée du flux. Notez que cette longueur n’est utilisable qu’avec les règles “http-request”. Veuillez consulter la section 7.3
(Extraction d’échantillon), “capture en-tête de requête” et “capture en-tête de réponse” pour plus d’informations.
Si le mot-clé « id » est utilisé à la place de « len », l’action tente de stocker la chaîne capturée dans une plage de capture prédéfinie. Cela est utile pour exécuter des captures dans les backends. L’identifiant de plage peut être déclaré par une directive précédente « http-request capture » ou avec le mot-clé « declare capture ».
Lorsque vous utilisez cette action dans un backend, vérifiez soigneusement que le ou les frontaux concernés disposent des emplacements de capture nécessaires, faute de quoi cette règle sera ignorée à l’exécution. Cette vérification ne peut pas être effectuée au moment de l’analyse de la configuration en raison de la capacité d’HAProxy à résoudre dynamiquement le nom du backend à l’exécution.
close
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | X | - | - | -
Cette action est utilisée pour fermer immédiatement la connexion avec le serveur. Aucune règle ultérieure de type « tcp-response content » n’est évaluée. Son usage principal consiste à forcer la fermeture d’une connexion entre un client et un serveur après un échange, lorsque le protocole applicatif prévoit des délais d’attente importants avant de pouvoir terminer. L’objectif est d’éliminer les connexions inactives qui consomment des ressources significatives sur les serveurs avec certains protocoles.
del-acl(<file-name>) <key fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela permet de supprimer une entrée d’une liste de contrôle d’accès (ACL). L’ACL doit être chargée à partir d’un fichier (même un fichier vide factice). Le nom du fichier ACL à mettre à jour est passé entre parenthèses. Il prend un argument : <key fmt>, qui suit les règles du format de journalisation personnalisé de la section 8.2.6 , afin de collecter le contenu de l’entrée à supprimer. Il équivaut à la commande « del acl » du socket de statistiques, mais peut être déclenché par une requête ou une réponse HTTP.
del-header <name> [ -m <meth> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela supprime tous les champs d’en-tête HTTP dont le nom est spécifié dans <name>. <meth> est la méthode de correspondance appliquée au nom de l’en-tête. Les méthodes de correspondance prises en charge sont « str » (correspondance exacte), « beg » (correspondance par préfixe), « end » (correspondance par suffixe), « sub » (correspondance par sous-chaîne) et « reg » (correspondance par expression régulière). Si non spécifiée, la méthode de correspondance exacte est utilisée.
del-headers-bin <expr> [ -m <meth> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela supprime tous les champs d’en-tête HTTP dont les noms sont spécifiés dans <expr>. <expr> doit renvoyer une chaîne binaire encodée en varint contenant tous les noms d’en-tête à supprimer. Voir « add-headers-bin » et « set-headers-bin » pour la description de l’encodage et des exemples. <meth> est la méthode de correspondance appliquée à tous les noms d’en-tête. Les méthodes de correspondance prises en charge sont « str » (correspondance exacte), « beg » (correspondance par préfixe), « end » (correspondance par suffixe) et « sub » (correspondance par sous-chaîne). La méthode « reg » (correspondance par expression régulière) n’est pas prise en charge en raison de performances imprévisibles en temps d’exécution. Si non spécifiée, la méthode de correspondance exacte est utilisée.
del-map(<map-name>) <key fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cette commande est utilisée pour supprimer une entrée d’une MAP. <map-name> doit suivre le format décrit dans 2.7.
Concernant le format du nom des MAPs et des ACLs. Le nom de la MAP à mettre à jour est passé entre parenthèses. Elle prend un argument : <key fmt>, qui suit les règles du format personnalisé de journalisation de la section 8.2.6
, afin de collecter le contenu de l’entrée à supprimer. Elle prend un argument : « nom de fichier ». Elle équivaut à la commande « del map » depuis la socket de statistiques, mais peut être déclenchée par une requête ou une réponse HTTP.
deny [ { status | deny_status } <code> ] [ content-type <type> ]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela arrête l’évaluation des règles et rejette immédiatement la requête ou la réponse. Par défaut, une erreur HTTP 403 est renvoyée pour les requêtes, et 502 pour les réponses, mais la réponse renvoyée peut être personnalisée en utilisant la même syntaxe que pour l’action « return ». Voir « return » ci-dessous pour les détails. À des fins de compatibilité, lorsque aucun argument n’est défini, ou uniquement “deny_status”, l’argument « default-errorfiles » est implicite. Cela signifie que « deny [deny_status <status>] » est un alias de « deny [status <status>] default-errorfiles ». Cette action est définitive, c’est-à-dire qu’aucune règle supplémentaire du même jeu de règles n’est évaluée pour la section courante. Voir également l’action « return » pour la syntaxe avancée.
dgram-drop
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | - | - | - | - | - | - | -
Ignore silencieusement la réception d’un paquet initial QUIC qui aurait sinon entraîné l’instanciation d’une nouvelle connexion QUIC et l’exécution de son échange SSL.
disable-l7-retry
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela désactive toute tentative de réessai de la requête en cas d’échec pour toute autre raison qu’une erreur de connexion. Cela peut être utile, par exemple, pour s’assurer que les requêtes POST ne sont pas réessayées en cas d’échec.
do-log [profile <log_profile>]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | X | X | X
Cette action déclenche manuellement l’émission d’un journal sur le proxy. Cela signifie que les options de journalisation du proxy seront prises en compte (y compris les options de formatage telles que « log-format »), mais qu’elle n’interférera pas avec les journaux générés automatiquement par le proxy pendant le traitement des transactions.
En utilisant « log-profile », il est possible de décrire précisément la manière dont le journal doit être émis pour chacun des contextes disponibles où l’action peut être utilisée. Autrement dit, le mot-clé « on » suivi des valeurs suivantes : « quic-init », « tcp-req-conn », « tcp-req-sess », « tcp-req-cont », « tcp-res-cont », « http-req », « http-res », « http-after-res ».
En outre, ils seront correctement signalés lors de l’utilisation de l’alias de format de journalisation “%OG”.
Argument facultatif « profile » peut être utilisé pour spécifier le nom d’une section log-profile à utiliser pour cette action do-log en particulier, plutôt que celle associée au logger actuel, qui s’applique par défaut.
Exemple :
do-resolve(<var>,<resolvers>[,ipv4|ipv6]) <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cette action effectue une résolution DNS de la sortie de <expr> et stocke le résultat dans la variable <var>. Elle utilise la section des résolveurs DNS pointée par <resolvers>. Il est possible de choisir une préférence de résolution à l’aide des arguments facultatifs « ipv4 » ou « ipv6 ». Voir également le mot-clé global « dns-accept-family » pour imposer une utilisation stricte d’une famille spécifique.
Lors de la résolution DNS, la connexion côté client est mise en pause en attendant la fin de la résolution. Si une adresse IP est trouvée, elle est stockée dans <var>. Si une erreur de quelque nature que ce soit survient, <var> n’est pas définie. On peut utiliser cette action pour découvrir l’adresse IP d’un serveur en temps réel, en se basant sur des informations présentes dans la requête (par exemple, un en-tête Host). Si cette action est utilisée pour déterminer l’adresse IP du serveur (en utilisant l’action « set-dst »), l’adresse IP du serveur dans le backend doit être définie sur 0.0.0.0. L’action do-resolve prend un paramètre uniquement composé de l’hôte ; toute port doit être supprimée de la chaîne.
Exemple :
NOTE : N’oubliez pas de définir les règles de « protection » afin d’assurer que HAProxy ne sera pas utilisé pour scanner le réseau, ni pire, entrer en boucle sur lui-même…
early-hint <name> <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela permet de générer une réponse HTTP 103 Early Hints avant toute autre réponse. Cela ajoute un champ d’en-tête HTTP à cette réponse dont le nom est spécifié dans <name> et dont la valeur est définie par <fmt>, selon les règles du format de journalisation personnalisé (voir Format de journalisation personnalisé dans la section 8.2.6 ). Cela est particulièrement utile pour transmettre au client des en-têtes Link afin de précharger des ressources nécessaires à l’affichage des documents HTML.
Consultez le RFC 8297 pour plus d’informations.
expect-netscaler-cip layer4
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | - | - | - | - | - | -
Cela configure la connexion orientée client pour recevoir un en-tête de protocole d’insertion de l’adresse IP client NetScaler avant toute lecture de données depuis la socket. Cela équivaut à utiliser le mot-clé « accept-netscaler-cip » dans la ligne « bind », à ceci près que l’utilisation d’une règle TCP permet d’accepter le protocole PROXY uniquement pour des plages d’adresses IP spécifiques, grâce à une ACL. Cette configuration est pratique lorsque le trafic provenant d’hôtes publics traverse plusieurs couches de répartiteurs de charge.
expect-proxy layer4
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | - | - | - | - | - | -
Cela configure la connexion côté client pour recevoir une en-tête PROXY avant toute lecture sur la socket. Cela équivaut à placer le mot-clé « accept-proxy » dans la ligne « bind », sauf que l’utilisation d’une règle TCP permet d’accepter le protocole PROXY uniquement pour certaines plages d’adresses IP en utilisant une ACL. Cela est pratique lorsque le trafic provenant d’hôtes publics traverse plusieurs couches de répartiteurs de charge.
normalize-uri <normalizer>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Effectue la normalisation de l’URI de la requête.
La normalisation des URI dans HAProxy 2.4 est actuellement disponible en tant que préversion technique expérimentale. En tant que tel, elle nécessite que la directive globale « expose-experimental-directives » soit définie afin de pouvoir l’utiliser. Vous devez vous préparer au fait que le comportement des normalisateurs pourrait évoluer pour corriger des éventuels problèmes, ce qui pourrait entraîner une interruption du traitement correct des requêtes dans votre infrastructure.
Chaque normalisateur gère un seul type de normalisation afin de permettre une sélection fine du niveau de normalisation adapté au backend pris en charge.
Par exemple, le normaliseur « path-strip-dotdot » peut être utile pour un serveur de fichiers statiques qui mappe directement l’URI demandé à un chemin dans le système de fichiers local. Toutefois, il peut perturber le routage d’une API qui attend un nombre spécifique de segments dans le chemin.
Il est important de noter que certains normalisateurs peuvent entraîner des transformations non sécurisées pour des URI corrompues. Il se peut également qu’une combinaison de normalisateurs qui sont sûrs individuellement entraîne des transformations non sécurisées lorsqu’ils sont combinés de manière incorrecte.
Par exemple, le normalisateur « percent-decode-unreserved » peut produire des résultats inattendus lorsqu’une URI corrompue contient des caractères pourcent nus. Une telle URI corrompue est « /%%36%36 », qui serait décodée en « /%66 », ce qui équivaut à « /f ». En spécifiant l’option « strict », les requêtes adressées à une telle URI corrompue seront rejetées de manière sécurisée.
Les normalisateurs suivants sont disponibles :
- fragment-encode : Encodé “#” sous la forme “%23”.
Le normalisateur « fragment-strip » doit être privilégié, sauf si l’on sait que les clients défectueux ne codent pas correctement ‘#’ dans le composant de chemin.
Exemple :
/#foo -> /%23foo
fragment-strip : Supprime le composant « fragment » de l’URI.
Selon la RFC 3986#3.5, le composant « fragment » d’une URI ne doit pas être transmis, mais géré par l’agent utilisateur après avoir récupéré une ressource.
Ce normalisateur doit être appliqué en premier afin de s’assurer que le fragment n’est pas interprété comme faisant partie du composant de chemin de la requête.
Exemple :
/#foo -> /
path-strip-dot : Supprime les segments “/./” dans le composant “path” (RFC 3986#6.2.2.3).
Les segments contenant des points codés en pourcentage ("%2E”) ne seront pas détectés. Utilisez d’abord le normaliseur « percent-decode-unreserved » si ce comportement est indésirable.
Exemple :
/. -> /
/./bar/ -> /bar/
/a/./a -> /a/a
/.well-known/ -> /.well-known/ (aucun changement)
path-strip-dotdot : Normalise les segments “/../” dans le composant “path” (RFC 3986#6.2.2.3).
Cela fusionne les segments qui tentent d’accéder au répertoire parent avec leur segment précédent.
Les segments vides ne reçoivent aucune traitement particulier. Utilisez d’abord le normaliseur « merge-slashes » si ce comportement n’est pas souhaité.
Les segments contenant des points codés en pourcentage ("%2E") ne seront pas détectés. Utilisez d’abord le normaliseur « percent-decode-unreserved » si ce comportement est indésirable.
Exemple :
- /foo/../ -> /
- /foo/../bar/ -> /bar/
- /foo/bar/../ -> /foo/
- /../bar/ -> /../bar/
- /bar/../../ -> /../
- /foo//../ -> /foo/
- /foo/%2E%2E/ -> /foo/%2E%2E/
Si l’option « full » est spécifiée, alors « ../ » au début sera également supprimé :
Exemple :
/../bar/ -> /bar/
/bar/../../ -> /
path-merge-slashes : Fusionne les barres obliques adjacentes dans le composant “path” en une seule barre oblique.
Exemple :
// -> /
/foo//bar -> /foo/bar
percent-decode-unreserved : Décode les caractères encodés en pourcentage non réservés en leur représentation sous forme de caractère régulier (RFC 3986#6.2.2.2).
L’ensemble des caractères non réservés comprend toutes les lettres, tous les chiffres, “-”, “.”, “_”, et “~”.
Exemple :
- /%61dmin -> /admin
- /foo%3Fbar=baz -> /foo%3Fbar=baz (no change)
- /%%36%36 -> /%66 (unsafe)
- /%ZZ -> /%ZZ
Si l’option « strict » est spécifiée, les séquences non valides entraîneront la renvoi d’une réponse HTTP 400 Bad Request.
Exemple :
/%%36%36 -> HTTP 400
/%ZZ -> HTTP 400
percent-to-uppercase : Met en majuscule les lettres au sein des séquences encodées en pourcentage (RFC 3986#6.2.2.1).
Exemple :
- /%6f -> /%6F
- /%zz -> /%zz
Si l’option « strict » est spécifiée, les séquences non valides entraîneront la renvoi d’une réponse HTTP 400 Bad Request.
Exemple :
/%zz -> HTTP 400
query-sort-by-name : Trie les paramètres de chaîne de requête par nom de paramètre. Les paramètres sont supposés être séparés par ‘&’. Les noms plus courts sont placés avant les noms plus longs, et les noms de paramètre identiques conservent leur ordre relatif.
Exemple :
- /?c=3&a=1&b=2 -> /?a=1&b=2&c=3
- /?aaa=3&a=1&aa=2 -> /?a=1&aa=2&aaa=3
- /?a=3&b=4&a=1&b=5&a=2 -> /?a=3&a=1&a=2&b=4&b=5
pause { <timeout> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela suspend l’analyse du message pendant le nombre de millisecondes spécifié. Le délai d’expiration peut être précisé en millisecondes ou avec toute autre unité si le nombre est suivi de l’unité, comme expliqué en haut de ce document. Il est également possible d’écrire une expression qui doit renvoyer un nombre interprété comme un délai d’expiration en millisecondes. Si l’évaluation de l’expression échoue ou si elle renvoie une valeur non valide, l’action est ignorée et l’évaluation se poursuit.
Cette action peut être utilisée à des fins de débogage. Elle peut également servir à ralentir certains clients selon des critères spécifiques. Par exemple, il est possible de ralentir les clients dont le taux de requêtes est trop élevé, en les suivant à l’aide d’une règle « track-sc ».
redirect <rule>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela effectue une redirection HTTP basée sur une règle de redirection. Il s’agit exactement de la même chose que l’instruction « redirect », sauf qu’elle insère une règle de redirection traitée au milieu des autres règles « http-request » ou « http-response », et que ces règles utilisent le format de journalisation personnalisé. Pour les réponses, seule le type de redirection « location » est autorisé. En outre, lorsqu’une redirection est effectuée pendant une réponse, la transmission depuis le serveur vers HAProxy est interrompue, de sorte qu’aucun contenu ne peut être transféré au client. Cela peut entraîner la fermeture de certaines connexions sur HTTP/1.. Cette action est définitive, c’est-à-dire qu’aucune règle supplémentaire du même jeu de règles n’est évaluée pour la section courante. Voir le mot-clé « redirect » pour la syntaxe de la règle.
reject
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | X | - | -
Cela arrête l’évaluation des règles et ferme immédiatement la connexion sans envoyer de réponse. Pour les règles HTTP, cela se comporte de manière similaire aux règles « tcp-request content reject ». Cela peut être utile pour forcer la fermeture immédiate d’une connexion sur les connexions HTTP/2.
Dans les règles « tcp-request connection », les connexions rejetées ne deviennent pas une session, ce qui explique qu’elles soient comptabilisées séparément dans les statistiques, sous le libellé « connexions refusées ». Elles ne sont pas prises en compte pour la limitation du débit de sessions et ne sont pas non plus journalisées. La raison en est que ces règles doivent uniquement être utilisées pour filtrer des taux de connexion extrêmement élevés, tels que ceux observés lors d’une attaque DDoS massive. Dans de telles conditions extrêmes, l’action simple de journaliser chaque événement ferait rapidement planter le système et réduirait considérablement la capacité de filtrage. Si la journalisation est absolument nécessaire, il convient alors d’utiliser des règles « tcp-request content » à la place, car les règles « tcp-request session » ne journalisent pas non plus.
Lorsqu’il est utilisé dans les règles « tcp-response content », la connexion serveur sera fermée et la réponse interrompue. Cela est généralement utilisé pour empêcher la fuite d’informations sensibles, typiquement après l’inspection du contenu en conjonction avec l’action « wait-for-body ».
Cette action peut également être utilisée dans les règles « quic-initial ». La connexion QUIC nouvellement ouverte est immédiatement fermée sans traitement de handshake SSL, et le client est notifié via un code d’erreur CONNECTION_REFUSED.
replace-header <name> <match-regex> <replace-fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela correspond à la valeur de toutes les occurrences du champ d’en-tête <name> contre <match-regex>. La correspondance est effectuée de manière sensible à la casse. Les valeurs correspondantes sont entièrement remplacées par <replace-fmt>. Les caractères de format sont autorisés dans <replace-fmt> et fonctionnent comme les arguments <fmt> dans « http-request add-header ». Les références arrière standard utilisant une barre oblique inversée (’\’) suivie d’un nombre sont prises en charge.
Cette action agit sur des lignes entières d’en-têtes, quelle que soit la quantité de valeurs qu’elles contiennent. Elle est donc particulièrement adaptée au traitement des en-têtes contenant naturellement des virgules dans leurs valeurs, tels que If-Modified-Since ou Set-Cookie. Les en-têtes contenant une liste séparée par des virgules de valeurs, tels qu’Accept ou Cache-Control, doivent être traités à l’aide de l’action « replace-value » à la place. Voir également l’action « replace-value ».
Exemple :
Exemple :
replace-path <match-regex> <replace-fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela fonctionne comme « replace-header », sauf qu’il s’applique à la composante chemin de la requête plutôt qu’à un en-tête. La composante chemin commence au premier « / » après un schéma et une autorité éventuels et se termine avant le point d’interrogation. Ainsi, le remplacement n’affecte pas le schéma, l’autorité ni la chaîne de requête.
Il convient de noter que les expressions régulières peuvent être plus coûteuses à évaluer que certaines ACL, si bien qu’une substitution rare peut bénéficier d’une condition afin d’éviter toute évaluation si elle ne correspond pas.
Exemple :
replace-pathq <match-regex> <replace-fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela a le même effet que « http-request replace-path », sauf que le chemin inclut la chaîne de requête si une telle chaîne est présente. Ainsi, le chemin et la chaîne de requête sont remplacés.
Exemple :
replace-uri <match-regex> <replace-fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela fonctionne comme « replace-header », sauf qu’il s’applique à la partie URI de la requête au lieu d’un en-tête. La partie URI peut contenir un schéma, une autorité ou une chaîne de requête facultatifs. Ces éléments sont considérés comme faisant partie de la valeur qui est comparée.
Il convient de noter que les expressions régulières peuvent être plus coûteuses à évaluer que certaines ACL, si bien qu’une substitution rare peut bénéficier d’une condition afin d’éviter toute évaluation si elle ne correspond pas.
NOTE IMPORTANTE : historiquement, dans HTTP/1.x, la grande majorité des requêtes envoyées par les navigateurs utilisent la « forme origin », qui diffère de la « forme absolue » en ce qu’elles ne contiennent ni schéma ni autorité dans la partie URI. La forme absolue est principalement utilisée pour les requêtes envoyées aux proxies, celles créées manuellement et certaines émises par des applications spécifiques. En conséquence, « replace-uri » fonctionne généralement correctement dans HTTP/1.x avec des règles commençant par un « / ». Toutefois, dans HTTP/2, les clients sont encouragés à envoyer uniquement des URI absolus, similaires à ceux utilisés par les clients HTTP/1 pour communiquer avec les proxies. Dans ce cas, des règles partielles de « replace-uri » peuvent échouer dans HTTP/2 alors qu’elles fonctionnent dans HTTP/1.. Soit les règles doivent être adaptées pour éventuellement correspondre à un schéma et une autorité, soit il faut utiliser « replace-path ».
Exemple :
replace-value <name> <match-regex> <replace-fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela fonctionne comme « replace-header », sauf qu’il effectue la correspondance de l’expression régulière contre chaque valeur délimitée par une virgule du champ d’en-tête <name> au lieu de l’intégralité de l’en-tête. Cette directive convient à tous les en-têtes autorisés à contenir plusieurs valeurs. Un exemple pourrait être l’en-tête de requête Accept, ou Cache-Control pour les requêtes ou les réponses.
Exemple :
Exemple :
return [ status <code> ] [ content-type <type> ]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela arrête l’évaluation des règles et renvoie immédiatement une réponse. Le code d’état par défaut utilisé pour la réponse est 200. Il peut être spécifié de manière optionnelle en tant qu’argument à « status ». Le type de contenu de la réponse peut également être précisé en tant qu’argument à « content-type ». Enfin, la réponse elle-même peut être définie. Elle peut être une réponse HTTP complète spécifiant le fichier d’erreur à utiliser, ou le corps de la réponse spécifiant le fichier ou la chaîne à utiliser. Les règles suivantes sont appliquées pour créer la réponse :
Si ni le fichier d’erreur ni la charge utile à utiliser ne sont définis, une réponse factice est renvoyée. Seul l’argument « status » est pris en compte. Il peut être n’importe quel code compris dans la plage [200, 599]. L’argument « content-type », le cas échéant, est ignoré.
Si l’argument « default-errorfiles » est défini, les fichiers d’erreur du proxy sont pris en compte. Si l’argument « status » est défini, il doit être l’un des codes d’état gérés par HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503 ou 504). L’argument « content-type », le cas échéant, est ignoré.
Si un fichier d’erreur spécifique est défini, via l’argument « errorfile », le fichier correspondant, contenant une réponse HTTP complète, est renvoyé. Seul l’argument « status » est pris en compte. Il doit être l’un des codes d’état gérés par HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503 ou 504). L’argument « content-type », le cas échéant, est ignoré.
Si une section http-errors est définie, avec un argument “errorfiles”, le fichier correspondant dans la section http-errors spécifiée, contenant une réponse HTTP complète, est renvoyé. Seul l’argument “status” est pris en compte. Il doit être l’un des codes d’état gérés par HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503 ou 504). L’argument “content-type”, le cas échéant, est ignoré.
Si un argument « file » ou « lf-file » est spécifié, le contenu du fichier est utilisé comme charge utile de la réponse. Si le fichier n’est pas vide, son type de contenu doit être précisé en tant qu’argument à « content-type ». Sinon, tout argument « content-type » est ignoré. Avec un argument « lf-file », le contenu du fichier est évalué comme un format de journal personnalisé (voir section 8.2.6 ). Avec un argument « file », il est considéré comme un contenu brut.
Si un argument « string » ou « lf-string » est spécifié, la chaîne définie est utilisée comme charge utile de la réponse. Le type de contenu doit toujours être défini en tant qu’argument à « content-type ». Avec un argument « lf-string », la chaîne est évaluée comme un format de journalisation personnalisé (voir section 8.2.6 ). Avec un argument « string », il est considéré comme une chaîne brute.
Lorsque la réponse n’est pas basée sur un fichier d’erreur, il est possible d’ajouter des champs d’en-tête HTTP à la réponse à l’aide des arguments « hdr ». Dans le cas contraire, tous les arguments « hdr » sont ignorés. Pour chacun d’eux, le nom de l’en-tête est spécifié dans <name> et sa valeur est définie par <fmt>, selon les règles du format de journalisation personnalisé décrites dans la section 8.2.6
.
Notez que la réponse générée doit être plus petite qu’une mémoire tampon. Pour éviter tout avertissement, lorsque un fichier d’erreur ou un fichier brut est chargé, l’espace mémoire réservé pour la réécriture des en-têtes doit également être libre.
Cette action est définitive, c’est-à-dire que aucune règle supplémentaire du même jeu de règles n’est évaluée pour la section courante.
Exemple :
sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cette action incrémente le compteur généralisé à l’index <idx> du tableau associé au compteur collant désigné par <sc-id> de la valeur de l’entier <int> ou de l’évaluation entière de l’expression <expr>. Les entiers et les expressions sont limités aux valeurs 32 bits non signées. En cas d’erreur, cette action échoue silencieusement et l’évaluation des actions se poursuit. <idx> est un entier compris entre 0 et 99 et <sc-id> est un entier compris entre 0 et 2. L’action échoue également silencieusement si aucun compteur généralisé n’est stocké à cet index. L’entrée dans la table est actualisée même si la valeur est nulle. Le ‘gpc_rate’ est automatiquement ajusté pour refléter le taux moyen de croissance de la valeur du compteur généralisé.
Cette action s’applique uniquement aux types de données ‘gpc’ et ‘gpc_rate’ (et non aux types de données hérités ‘gpc0’, ‘gpc1’, ‘gpc0_rate’ ni ‘gpc1_rate’). Il n’existe aucune fonction équivalente pour les types de données hérités, mais si la valeur est toujours 1, veuillez consulter ‘sc-inc-gpc()’, ‘sc-inc-gpc0()’ et ‘sc-inc-gpc1()’. Il n’existe aucun moyen de décrémenter la valeur, mais il est possible de stocker des valeurs exactes dans une étiquette à usage général à l’aide de ‘sc-set-gpt()’.
L’utilisation principale de cette action consiste à compter des scores ou des volumes totaux (par exemple, le danger estimé par adresse IP source signalé par le serveur ou un WAF, les octets téléchargés au total, etc.).
sc-inc-gpc(<idx>,<sc-id>)
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cette action incrémente le compteur généralisé à l’index <idx> du tableau associé au compteur collant désigné par <sc-id>. En cas d’erreur, cette action échoue silencieusement et l’évaluation des actions continue. <idx> est un entier compris entre 0 et 99 et <sc-id> est un entier compris entre 0 et 2. L’action échoue également silencieusement si aucun compteur généralisé n’est stocké à cet index. Cette action s’applique uniquement aux types de données ‘gpc’ et ‘gpc_rate’ (et non aux types de données hérités ‘gpc0’, ‘gpc1’, ‘gpc0_rate’ ni ‘gpc1_rate’).
sc-inc-gpc0(<sc-id>)
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cette action incrémente le compteur GPC0 ou GPC1 selon le compteur de persistance désigné par <sc-id>. En cas d’erreur, cette action échoue silencieusement et l’évaluation des actions se poursuit.
sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cette action définit le GPT 32 bits non signé à l’index <idx> du tableau associé au compteur collant désigné par <sc-id> à la valeur de <int>/<expr>.. Le résultat attendu est un booléen.
En cas d’erreur, cette action échoue silencieusement et l’évaluation des actions se poursuit. <idx> est un entier compris entre 0 et 99 et <sc-id> est un entier compris entre 0 et 2. L’action échoue également silencieusement si aucun GPT n’est stocké à cet index.
Cette action s’applique uniquement au type de données ‘gpt’ (et non au type de données hérité ‘gpt0’).
sc-set-gpt0(<sc-id>) { <int> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cette action définit l’étiquette 32 bits non signée GPT0 selon le compteur collant désigné par <sc-id> et la valeur de <int>/<expr>.. Le résultat attendu est une valeur booléenne. En cas d’erreur, cette action échoue silencieusement et l’évaluation des actions se poursuit. Cette action est un alias de « sc-set-gpt(0,<sc-id>) ». Voir également l’action « sc-set-gpt ».
send-retry
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | - | - | - | - | - | - | -
Cette action force l’émission d’un paquet Retry en réponse à un paquet Initial client sans jeton. Cela permet de s’assurer que l’adresse client est validée avant d’instancier tout élément de connexion et de commencer l’échange.
send-spoe-group <engine-name> <group-name>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | -
Cette action est utilisée pour déclencher l’envoi d’un groupe de messages SPOE. Pour cela, le moteur SPOE utilisé pour envoyer les messages doit être défini, ainsi que le groupe SPOE à envoyer. Bien entendu, le moteur SPOE doit faire référence à un filtre SPOE existant. Si aucun nom de moteur n’est fourni sur la ligne du filtre SPOE, le nom de l’agent SPOE doit être utilisé.
Arguments :
set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | -
Cette action permet d’activer le filtre de limitation de débit <name>, soit dans le sens montant, soit dans le sens descendant, selon le type de filtre. Une limite et une période personnalisées peuvent être définies, mais uniquement si <name> fait référence à un filtre de limitation de débit par flux. Lorsqu’une règle set-bandwidth-limit est exécutée, elle réinitialise d’abord toutes les paramètres du filtre à leurs valeurs par défaut avant de l’activer. En conséquence, si plusieurs actions set-bandwidth-limit sont exécutées pour le même filtre, seule la dernière est prise en compte. Plusieurs filtres de limitation de débit peuvent être activés sur un même flux.
Notez que cette action ne peut pas être utilisée dans une section defaults, car les filtres de limitation de bande passante ne peuvent pas être définis dans des sections defaults. En outre, seule la transmission du corps HTTP est limitée. Les en-têtes HTTP ne sont pas pris en compte.
Arguments :
Exemple :
Voir section 9.7 pour la configuration du filtre de limitation de bande passante.
set-bc-mark { <mark> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cela permet de définir la marque Netfilter/IPFW sur la connexion backend (tous les paquets envoyés au serveur) à la valeur passée dans <mark> ou <expr> sur les plates-formes qui le supportent. Cette valeur est un entier non signé sur 32 bits pouvant être associée à netfilter/ipfw ainsi qu’aux tables de routage ou à la surveillance des paquets via DTrace. <mark> peut être exprimée en notation décimale ou hexadécimale (précédée de « 0x »). En alternative, <expr> peut être utilisé : il s’agit d’une expression standard HAProxy composée d’une récupération d’échantillon suivie de convertisseurs qui doivent aboutir à un type entier. Cette action peut être utile pour forcer certains paquets à emprunter un chemin différent (par exemple, un chemin réseau moins coûteux pour les téléchargements massifs). Cette fonctionnalité est disponible sur les noyaux Linux 2.6.32 et versions ultérieures, nécessite des privilèges d’administrateur, ainsi que sur FreeBSD et OpenBSD. La marque est définie pour toute la durée de la connexion backend/server (de la connexion à la fermeture).
set-bc-tos { <tos> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cela permet de définir la valeur du champ TOS ou DSCP sur la connexion au backend (tous les paquets envoyés au serveur) à la valeur passée dans <tos> ou <expr> sur les plates-formes qui le supportent. Cette valeur représente les 8 bits entiers du champ TOS IP. Notez que seuls les 6 bits supérieurs sont utilisés en DSCP ou TOS, tandis que les deux bits inférieurs sont toujours à 0. En alternative, <expr> peut être utilisé : il s’agit d’une expression standard HAProxy composée d’un extrait de données suivi de convertisseurs, qui doit aboutir à un type entier. Cette action peut être utilisée pour ajuster certains comportements de routage sur les routeurs internes en fonction d’informations provenant de la requête. Le champ TOS sera défini pour toute la durée de la connexion backend/server (de la connexion à la fermeture).
Voir les RFC 2474, 2597, 3260 et 4594 pour plus d’informations.
set-dst <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
Cela permet de définir l’adresse IP de destination avec la valeur de l’expression spécifiée. Utile lorsque un proxy placé devant HAProxy modifie l’adresse IP de destination, mais fournit l’IP correcte dans un en-tête HTTP ; ou lorsque vous souhaitez masquer l’IP pour des raisons de confidentialité. Si vous souhaitez vous connecter au nouvel address/port, utilisez « 0.0.0.0:0 » comme adresse de serveur dans le backend.
Arguments :
Exemple :
Lorsqu’il est possible, set-dst conserve le port de destination d’origine tant que la famille d’adresses le permet ; sinon, le port de destination est défini à 0.
set-dst-port <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
Cela permet de définir le port de destination selon la valeur de l’expression spécifiée. Si vous souhaitez vous connecter au nouveau address/port, utilisez ‘0.0.0.0:0’ comme adresse serveur dans le backend.
Arguments :
Exemple :
Lorsqu’il est possible, set-dst-port préserve l’adresse de destination d’origine tant que la famille d’adresse prend en charge un port ; sinon, il force l’adresse de destination à IPv4 “0.0.0.0” avant de réécrire le port.
set-fc-mark { <mark> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | -
Cela permet de définir la marque Netfilter/IPFW sur tous les paquets envoyés au client avec la valeur transmise dans <mark> ou <expr> sur les plates-formes qui le supportent. Cette valeur est un entier non signé sur 32 bits pouvant être associée à netfilter/ipfw ainsi qu’à la table de routage ou surveillée via DTrace.
<mark> peut être exprimé en notation décimale ou hexadécimale (précédée de « 0x »). En alternative, <expr> peut être utilisé : il s’agit d’une expression standard HAProxy composée d’une récupération d’échantillon suivie de convertisseurs, qui doit aboutir à un type entier. Cette action peut être utile pour forcer certains paquets à emprunter un chemin différent (par exemple, un chemin réseau moins coûteux pour les téléchargements massifs). Cette fonctionnalité est disponible sur les noyaux Linux 2.6.32 et ultérieurs, nécessite des privilèges d’administrateur, ainsi que sur FreeBSD et OpenBSD.
set-fc-tos { <tos | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | -
Cela permet de définir la valeur du champ TOS ou DSCP des paquets envoyés au client à la valeur transmise via <tos> ou <expr> sur les plates-formes qui le supportent. Cette valeur représente les 8 bits entiers du champ TOS IP. Notez que seuls les 6 bits supérieurs sont utilisés en DSCP ou TOS, tandis que les deux bits inférieurs sont toujours à 0. En alternative, <expr> peut être utilisé : il s’agit d’une expression standard HAProxy composée d’un échantillonnage suivi de convertisseurs, qui doit se résoudre en un type entier. Cette action peut être utilisée pour ajuster certains comportements de routage sur les routeurs frontières en fonction d’informations provenant de la requête.
Voir les RFC 2474, 2597, 3260 et 4594 pour plus d’informations.
set-header <name> <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela a le même effet que l’action « add-header », sauf que l’en-tête est d’abord supprimé s’il existait déjà. Cela est utile lors du passage d’informations de sécurité au serveur, où l’en-tête ne doit pas être manipulé par des utilisateurs externes, ou pour forcer certains en-têtes de réponse tels que « Server » afin de masquer des informations externes. Notez que la nouvelle valeur est calculée avant la suppression, ce qui permet de concaténer une valeur à un en-tête existant.
Exemple :
set-headers-bin <expr> [ prefix <str> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Il s’agit d’une variante de l’action « set-header » où les noms et les valeurs des en-têtes sont transmis sous forme de chaîne binaire encodée en varint. Consultez l’extraction d’échantillon “req.hdrs_bin” pour en savoir plus sur le format varint. Cette fonctionnalité est utile lorsque vous souhaitez définir plusieurs en-têtes à la fois, sans avoir besoin de connaître à l’avance les noms des en-têtes. Notez que ces en-têtes n’ont pas été validés par le parseur HTTP et pourraient entraîner l’émission de messages non valides, voire, dans les cas les plus graves, des attaques par camouflage de requête. Le nombre d’en-têtes insérés est également important, car il est limité par tune.http.maxhdr. Un préfixe facultatif ne définira que les en-têtes provenant de la chaîne encodée qui commencent par <str>.
Exemple :
set-log-level <level>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | X
Cela permet de modifier le niveau de journalisation de la requête en cours lorsque certaine condition est remplie. Les niveaux valides sont les 8 niveaux syslog (voir le mot-clé « log ») ainsi que le niveau spécial « silent », qui désactive la journalisation pour cette requête. Cette règle n’est pas définitive, aussi la dernière règle correspondante l’emporte. Cette règle peut être utile pour désactiver les contrôles d’état provenant d’un autre équipement.
set-map(<map-name>) <key fmt> <value fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela permet d’ajouter une nouvelle entrée dans une carte. <map-name> doit suivre le format décrit dans 2.7.
Concernant le format du nom des cartes et des listes ACL. Le nom de la MAP à mettre à jour est passé entre parenthèses. Elle prend 2 arguments : <key fmt>, qui suit les règles du format de journal personnalisé décrites dans section 8.2.6
, utilisé pour collecter la clé de la carte, et <value fmt>, qui suit les règles du format de journal personnalisé,
utilisé pour collecter le contenu de la nouvelle entrée. Elle effectue une recherche dans la carte avant l’insertion, afin d’éviter les valeurs en double (ou supplémentaires). Elle équivaut à la commande « set map » depuis le socket de statistiques, mais peut être déclenchée par une requête HTTP.
set-mark <mark> (deprecated)
Ceci est un alias de « set-fc-mark » (à utiliser à la place).
set-method <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cette directive réécrit la méthode de la requête avec le résultat de l’évaluation de la chaîne de format <fmt>. Il devrait y avoir très peu de raisons valables pour le faire, car cela risque davantage de briser quelque chose que de le corriger.
set-nice <nice>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | -
Cela définit le facteur « nice » de la request/response en cours de traitement. Il n’a d’effet que sur les autres requêtes traitées en même temps. La valeur par défaut est 0, sauf si elle est modifiée par le paramètre « nice » dans la ligne « bind ». La plage acceptée est -1024..1024.. Plus la valeur est élevée, plus la requête est « gentille ». Les valeurs plus faibles rendent la requête plus prioritaire que les autres. Cette option peut être utile pour accélérer certaines requêtes ou réduire la priorité des requêtes non importantes. Son utilisation sans expérimentation préalable peut entraîner des ralentissements importants.
set-path <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cette directive réécrit le chemin de la requête avec le résultat de l'évaluation de la chaîne de format `<fmt>`. La chaîne de requête, le cas échéant, est conservée telle quelle. Si un schéma et une autorité sont présents avant le chemin, ils sont également conservés. Si la requête ne contient pas de chemin ("*"), celui-ci est remplacé par la chaîne de format. Cette fonctionnalité peut être utilisée, par exemple, pour ajouter un composant de répertoire au début d'un chemin. Voir également « http-request set-query » et « http-request set-uri ».
Exemple :
set-pathq <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela a le même effet que « http-request set-path », sauf que la chaîne de requête est également réécrite. Il peut être utilisé pour supprimer la chaîne de requête, y compris le point d’interrogation (ce qui n’est pas possible avec « http-request set-query »).
set-priority-class <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cela permet de définir la classe de priorité de la file d’attente de la requête courante. La valeur doit être une expression échantillonnée qui se convertit en entier dans la plage -2047..2047.. Les valeurs en dehors de cette plage seront tronquées. La classe de priorité détermine l’ordre dans lequel les requêtes en file d’attente sont traitées. Les valeurs plus faibles ont une priorité plus élevée.
set-priority-offset <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cela permet de définir le décalage d’horodatage de priorité de la requête courante. La valeur doit être une expression d’échantillonnage qui se convertit en un entier compris dans la plage -524287..524287.. Les valeurs situées en dehors de cette plage seront tronquées. Lorsqu’une requête est mise en file d’attente, elle est triée d’abord par classe de priorité, puis par l’horodatage actuel ajusté selon le décalage indiqué, en millisecondes. Les valeurs plus faibles ont une priorité plus élevée. Notez que l’horodatage résultant n’est suivi qu’avec une précision suffisante pour 524 287 ms (8 min 44 s 287 ms). Si la requête est en file d’attente assez longtemps pour que l’horodatage ajusté dépasse cette valeur, elle sera mal identifiée comme ayant la priorité la plus élevée. Il est donc important de définir « timeout queue » avec une valeur telle que, combinée au décalage, elle ne dépasse pas cette limite.
set-query <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela réécrit la chaîne de requête de la requête, située après le premier point d’interrogation ("?"), par le résultat de l’évaluation de la chaîne de format <fmt>. La partie située avant le point d’interrogation est conservée intacte. Si la requête ne contient pas de point d’interrogation et que la nouvelle valeur n’est pas vide, un point d’interrogation est ajouté à la fin de l’URI, suivi de la nouvelle valeur. Si un point d’interrogation était présent, il ne sera jamais supprimé, même si la valeur est vide. Cette fonctionnalité peut être utilisée pour ajouter ou supprimer des paramètres de la chaîne de requête.
Voir également « http-request set-query » et « http-request set-uri ».
Exemple :
set-retries <int> | <epxr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cette action remplace la valeur « retries » spécifiée pour le flux actuel uniquement. Elle peut être une valeur entière comprise dans la plage [0, 100], ou une expression qui doit renvoyer un entier compris dans la plage [0, 100].
Notez que cette action n’est pertinente que du côté du backend et n’est donc disponible que pour les proxies disposant d’une capacité backend. Elle n’est pas autorisée dans les sections « defaults ». Lorsqu’elle est utilisée pour un écouteur, elle est évaluée dans le contexte du frontal. Ainsi, la valeur de réessais est conservée uniquement si le flux n’est pas acheminé vers un backend différent, par exemple via une règle use-backend. Dans le cas contraire, la valeur par défaut de réessais du backend sélectionné s’applique.
Exemple :
set-src <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
Cela permet de définir l’adresse IP source à la valeur de l’expression spécifiée. Utile lorsque un proxy placé devant HAProxy modifie l’adresse IP source, mais fournit l’IP correcte dans un en-tête HTTP ; ou lorsque vous souhaitez masquer l’adresse IP source pour des raisons de confidentialité. Toutes les appels ultérieurs à « src » récupéreront cette valeur (voir l’exemple).
Arguments :
Voir également « option forwardfor ».
Exemple :
Lorsqu’il est possible, l’option set-src conserve le port source d’origine tant que la famille d’adresses le permet ; sinon, le port source est défini à 0.
set-src-port <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
Cela permet de définir l’adresse du port source à la valeur de l’expression spécifiée.
Arguments :
Exemple :
Lorsqu’il est possible, l’option set-src-port conserve l’adresse source d’origine tant que la famille d’adresses prend en charge un port ; sinon, elle force l’adresse source à IPv4 “0.0.0.0” avant de réécrire le port.
set-status <status> [reason <str>]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | - | X | X
Cela remplace le code d’état de la réponse par <status>, qui doit être un entier compris entre 100 et 999.
Optionnellement, un texte de raison personnalisé peut être fourni, défini par <str>, ou la raison par défaut correspondant au code spécifié sera utilisée comme valeur de secours. Notez que la chaîne de raison n’existe que dans HTTP/1.x et est ignorée par les autres versions du protocole.
Exemple :
set-timeout { client | connect | queue | server | tarpit | tunnel } { <timeout> | <expr> }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cette action remplace le délai d’expiration spécifié pour « client », « connect », « queue », « serveur », « tarpit » ou « tunnel » uniquement pour le flux courant. Modifier un délai d’expiration n’affecte aucun autre délai, même s’ils sont hérités les uns des autres lors de l’analyse de la configuration (voir le dernier exemple). Le délai d’expiration peut être spécifié en millisecondes ou avec toute autre unité si le nombre est suivi de l’unité, comme expliqué en haut de ce document. Il est également possible d’écrire une expression qui doit renvoyer un nombre interprété comme un délai d’expiration en millisecondes.
Notez que les délais d’expiration connect, queue, server et tunnel ne sont pertinents que du côté backend, et ce règle n’est donc disponible que pour les proxies disposant de capacités backend. De même, le délai d’expiration client n’est pertinent que du côté frontal. Le délai d’expiration tarpit est disponible des deux côtés. La valeur du délai d’expiration doit être non nulle pour obtenir les résultats attendus. Lorsque l’action est utilisée pour un écouteur, elle est évaluée dans le contexte frontal. Ainsi, les valeurs personnalisées pour les délais d’expiration côté backend sont conservées uniquement si le flux n’est pas acheminé vers un autre backend, par exemple via une règle use-backend. Sinon, les valeurs par défaut du backend sélectionné seront appliquées.
Exemple :
Exemple :
Exemple :
set-tos <tos> (deprecated)
Ceci est un alias de « set-fc-tos » (à utiliser à la place).
set-uri <fmt>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela réécrit l’URI de la requête avec le résultat de l’évaluation de la chaîne de format <fmt>. Le schéma, l’autorité, le chemin et la chaîne de requête sont tous remplacés en même temps. Cela peut être utilisé pour réécrire des hôtes devant des proxies, ou pour effectuer des modifications complexes de l’URI, telles que le déplacement de parties entre le chemin et la chaîne de requête. Si une URI absolue est définie, elle sera envoyée telle quelle aux serveurs HTTP/1.1. Si ce n’est pas le comportement souhaité, l’hôte, le chemin et/ou la chaîne de requête doivent être définis séparément. Voir également « http-request set-path » et « http-request set-query ».
set-var(<var-name>[,<cond>...]) <expr>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cela sert à définir le contenu d’une variable. La variable est déclarée en inline.
Arguments :
Toutes les portées sont utilisables pour les règles HTTP, mais seules les portées « proc » et « sess » sont disponibles dans les jeux de règles qui n’ont pas accès aux contenus tels que « tcp-request connection » et « tcp-request session ».
Exemple :
silent-drop [ rst-ttl <ttl> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | -
Cela arrête l’évaluation des règles et fait disparaître soudainement la connexion côté client selon une méthode dépendante du système, visant à empêcher la notification du client. Lorsqu’il est appelé sans l’argument rst-ttl, nous tentons d’éviter l’envoi de tout paquet FIN ou RST au client en utilisant TCP_REPAIR. Si cette tentative échoue (notamment en raison d’un manque de privilèges), nous passons à l’envoi d’un paquet RST avec un TTL de 1.
L’effet est que le client perçoit toujours une connexion établie, alors qu’aucune connexion n’existe côté HAProxy, ce qui permet d’économiser des ressources. Toutefois, tout équipement étatique placé entre HAProxy et le client (pare-feux, proxies, répartiteurs de charge) conservera également la connexion établie dans ses tables de session.
Le paramètre facultatif rst-ttl modifie ce comportement : TCP_REPAIR n’est pas utilisé, et un paquet RST avec un TTL configurable est envoyé. Lorsqu’il est défini à une valeur raisonnable, le paquet RST traverse l’infrastructure locale, supprimant la connexion dans les pare-feu et d’autres systèmes, mais disparaît avant d’atteindre le client. Les paquets ultérieurs provenant du client seront alors rejetés directement par l’équipement frontal. Ces RST locaux protègent les ressources locales, mais non le client. Cette fonctionnalité ne doit pas être utilisée à moins que les conséquences de son utilisation soient entièrement comprises.
strict-mode { on | off }
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
Cela active ou désactive le mode de réécriture stricte pour les règles suivantes. Il n’affecte pas les règles déclarées auparavant et n’est applicable qu’aux règles effectuant une réécriture sur les requêtes. Lorsque le mode strict est activé, toute erreur de réécriture déclenche une erreur interne. Sinon, de telles erreurs sont ignorées silencieusement. Le but du mode de réécriture stricte est de rendre certaines réécritures facultatives tout en rendant obligatoires d’autres réécritures pour poursuivre le traitement des requêtes.
Par défaut, le mode de réécriture strict est activé. Sa valeur est également réinitialisée lorsque l’évaluation d’un jeu de règles se termine. Ainsi, par exemple, si vous modifiez le mode sur le frontal, le mode par défaut est restauré lorsque HAProxy commence l’évaluation des règles du backend.
switch-mode http [ proto <name> ]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | - | - | -
Cette action est utilisée pour effectuer une mise à niveau de connexion. Seules les mises à niveau HTTP sont actuellement prises en charge. Le protocole peut éventuellement être précisé. Cette action n’est disponible que pour un proxy disposant de la capacité frontal. La mise à niveau de connexion est immédiatement effectuée ; les règles définies par “tcp-request content” ne sont pas évaluées. Cette méthode de mise à niveau doit être privilégiée à la méthode implicite consistant à s’appuyer sur le mode backend. Lorsqu’elle est utilisée, il est possible de définir des directives HTTP dans un frontal sans avertissement. Ces directives seront évaluées de manière conditionnelle si la mise à niveau HTTP est effectuée. Toutefois, un backend HTTP doit toujours être sélectionné. Il reste impossible de router une connexion HTTP (mise à niveau ou non) vers un serveur TCP.
Consultez section 4 pour en savoir plus sur les mises à jour HTTP.
tarpit [ { status | deny_status } <code>] [content-type <type>]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela arrête l’évaluation des règles et bloque immédiatement la requête sans réponse pendant un délai spécifié par « timeout tarpit » ou « timeout connect » si le premier n’est pas défini. Après ce délai, si le client reste connecté, une réponse est renvoyée afin que le client ne soupçonne pas avoir été tarpité. Les journaux signaleront les indicateurs « PT ». Le but de la règle tarpit est de ralentir les robots pendant une attaque, lorsque ceux-ci sont limités en nombre de requêtes simultanées. Elle peut être très efficace contre des robots très rudimentaires, et réduire considérablement la charge sur les pare-feu par rapport à une règle « deny ». Toutefois, face à des robots correctement conçus, elle peut aggraver la situation en obligeant HAProxy et le pare-feu frontal à gérer un nombre insensé de connexions simultanées. Par défaut, une erreur HTTP 500 est renvoyée. Toutefois, la réponse peut être personnalisée en utilisant la même syntaxe que les règles « http-request return ». Voir « http-request return » pour les détails.
Pour des raisons de compatibilité, lorsque aucun argument n’est défini, ou uniquement “deny_status”, l’argument
« default-errorfiles » est implicite. Cela signifie que « http-request tarpit [deny_status <status>] » est un alias de
« http-request tarpit [status <status>] default-errorfiles ». Aucune règle supplémentaire « http-request » n’est évaluée. Voir également « http-request return » et « http-request silent-drop ».
track-sc0 <key> [table <table>]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | X | -
Cela active le suivi des compteurs de persistance à partir de la requête en cours. Ces règles n’interrompent pas l’évaluation ni ne modifient l’action par défaut. Le nombre de compteurs pouvant être suivis simultanément par la même connexion est défini par le paramètre global “tune.stick-counters”, qui vaut MAX_SESS_STKCTR s’il est défini au moment de la compilation (il est indiqué dans HAProxy -vv) et qui vaut 3 par défaut, de sorte que le nombre de suivi de compteurs (track-sc) est compris entre 0 et (tune.stick-counters-1). La première règle « track-sc0 » exécutée active le suivi des compteurs du tableau spécifié comme premier ensemble. La première règle « track-sc1 » exécutée active le suivi des compteurs du tableau spécifié comme deuxième ensemble. La première règle « track-sc2 » exécutée active le suivi des compteurs du tableau spécifié comme troisième ensemble. Il est recommandé d’utiliser le premier ensemble de compteurs pour les compteurs par frontal et le second ensemble pour les compteurs par backend. Mais il s’agit simplement d’une orientation ; tous les ensembles peuvent être utilisés partout.
Arguments :
Une fois qu’une règle « track-sc* » a été exécutée, la clé est recherchée dans la table. Si elle n’est pas trouvée, une entrée lui est attribuée. Ensuite, un pointeur vers cette entrée est conservé pendant toute la durée de la session, et les compteurs de cette entrée sont mis à jour aussi fréquemment que possible, à chaque mise à jour des compteurs de la session, ainsi qu’au moment systématique de la fin de la session. Les compteurs ne sont mis à jour que pour les événements survenus après le démarrage du suivi. À titre d’exception, les compteurs de connexion et les compteurs de requête sont systématiquement mis à jour afin de refléter des informations utiles.
Si l’entrée suit les compteurs de connexions simultanées, une connexion est comptabilisée tant que l’entrée est suivie, et l’entrée ne peut pas expirer pendant cette période. Le suivi des compteurs offre également un avantage de performance par rapport à la simple vérification des clés, car une seule recherche dans la table est effectuée pour toutes les vérifications ACL qui en font usage.
unset-var(<var-name>)
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
Cela sert à supprimer une variable. Consultez l’action « set-var » pour plus de détails sur <var-name>.
Exemple :
use-service <service-name>
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
Cette action exécute le service TCP ou HTTP configuré pour répondre à la requête, selon la règle dans laquelle elle est utilisée. La règle est finale, c’est-à-dire qu’aucune autre règle n’est évaluée dans le même ensemble de règles.
Un service peut choisir de répondre en envoyant une réponse valide ou de fermer immédiatement la connexion sans envoyer de réponse. Pour les services HTTP, une réponse valide nécessite une réponse HTTP valide. En dehors des services natifs, par exemple l’exportateur Prometheus pour les services HTTP, il est possible d’écrire des services TCP et HTTP personnalisés en Lua.
Arguments :
Exemple :
wait-for-body time <time> [ at-least <bytes> ] [use-large-buffer]
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
Cela retardera le traitement de la requête ou de la réponse jusqu’à ce qu’une des conditions suivantes se produise :
- Le corps complet de la requête a été reçu, auquel cas le traitement s’effectue normalement.
<bytes>octets ont été reçus, lorsque l’argument « at-least » est fourni et que<bytes>est non nul, auquel cas le traitement s’effectue normalement.- Le tampon de requête est plein, auquel cas le traitement s’effectue normalement. La taille de ce tampon est déterminée par l’option “tune.bufsize”.
- La requête attend depuis plus de
<time>millisecondes. Dans ce cas, HAProxy répondra à la client avec une erreur 408 « Request Timeout » et interrompra le traitement de la requête. Notez qu’en cas de survenance d’une autre condition en premier, ce délai d’expiration ne sera pas déclenché, même si le corps complet n’a pas encore été reçu.
L’option « use-large-buffer » peut être définie pour allouer un tampon volumineux si le tampon régulier est trop petit pour stocker le corps du message. Pour être utilisée, l’option globale “tune.bufsize.large” doit être définie.
Cette action peut être utilisée comme remplacement de « option http-buffer-request ».
Arguments :
Exemple :
Voir également : « option http-buffer-request » et “tune.bufsize.large”
wait-for-handshake
Utilisable dans : QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Cela retardera le traitement de la requête jusqu’à l’achèvement de la négociation SSL. Cela est principalement utile pour retarder le traitement des données préliminaires jusqu’à ce que nous soyons certains de leur validité.