7. Listes de contrôle d'accès et extraction d'échantillon
HAProxy est capable d’extraire des données des flux de requêtes ou de réponses, des informations client ou serveur, des tables, des informations environnementales, etc. L’opération d’extraction de ces données est appelée « récupération d’un échantillon ». Une fois récupérés, ces échantillons peuvent être utilisés à diverses fins, par exemple comme clé dans une table de persistance, mais les usages les plus courants consistent à les comparer à des données constantes prédéfinies appelées modèles.
7.1. Notions de base sur les ACL
Listes de contrôle d’accès (ACL) consistent à déclarer une méthode nommée permettant de comparer une information quelconque à une liste de modèles prédéfinis. Elles doivent être considérées comme pratiquement équivalentes aux fonctions dans la plupart des langages de programmation, dans la mesure où leur déclaration les rend disponibles pour être appelées ultérieurement lorsqu’elles sont nécessaires. Leur évaluation ne retourne qu’une correspondance ou un manque de correspondance, ce qui est comparable aux valeurs booléennes dans de nombreux langages de programmation. Contrairement aux fonctions dans les langages de programmation, les ACL peuvent être surchargées autant de fois que nécessaire afin de définir des méthodes de correspondance supplémentaires pour le même nom. Dans ce cas, toutes seront évaluées dans l’ordre de leur déclaration jusqu’à ce qu’une correspondance soit trouvée.
L’utilisation des listes de contrôle d’accès (ACL) offre une solution souple pour effectuer un commutage de contenu et, plus généralement, prendre des décisions fondées sur le contenu extrait de la requête, de la réponse ou d’un état environnemental. Le principe est simple :
- extraire un échantillon de données à partir d’un flux, d’une table ou de l’environnement
- appliquer éventuellement une conversion de format à l’échantillon extrait
- appliquer une ou plusieurs méthodes de correspondance de motifs à cet échantillon
- effectuer des actions uniquement lorsque un motif correspond à l’échantillon
Les actions consistent généralement à bloquer une requête, sélectionner un backend ou ajouter un en-tête.
Pour définir un test, le mot-clé « acl » est utilisé. La syntaxe est :
Cela crée une nouvelle ACL <aclname> ou complète une existante avec de nouveaux tests. Ces tests s’appliquent à la portion de request/response spécifiée dans <criterion> et peuvent être ajustés à l’aide d’indicateurs facultatifs [flags]. Certains critères prennent également en charge un opérateur, qui peut être précisé avant l’ensemble des valeurs. Facultativement, certains opérateurs de conversion peuvent être appliqués à l’échantillon, et ils seront indiqués sous forme de liste séparée par des virgules de mots-clés, juste après le premier mot-clé. Les valeurs sont du type pris en charge par le critère et sont séparées par des espaces.
Les noms d’ACL doivent être composés de lettres majuscules et minuscules, de chiffres, de ‘-’ (tiret), de ‘_’ (souligné), de ‘.’ (point) et de ‘:’ (deux-points). Les noms d’ACL sont sensibles à la casse, ce qui signifie que “my_acl” et “My_Acl” représentent deux ACL différentes.
Il n’y a aucune limite imposée au nombre d’ACL. Les ACL non utilisées n’affectent pas les performances, elles ne consomment qu’une petite quantité de mémoire.
Le critère est généralement le nom d’une méthode d’extraction d’échantillon, ou l’une de ses déclinaisons spécifiques à une ACL. La méthode de test par défaut est implicite selon le type de sortie de cette méthode d’extraction d’échantillon. Les déclinaisons ACL peuvent décrire des méthodes de correspondance alternatives pour une même méthode d’extraction d’échantillon. Seules les méthodes d’extraction d’échantillon supportent une conversion.
Les méthodes d’extraction d’échantillon renvoient des données pouvant être des types suivants :
- booléen
- entier (signé ou non signé)
- adresse IPv4 ou IPv6
- chaîne de caractères
- bloc de données
Les convertisseurs transforment n’importe quel type de données en n’importe quel autre type. Par exemple, certains convertisseurs peuvent convertir une chaîne en une chaîne en minuscules, tandis que d’autres peuvent transformer une chaîne en adresse IPv4 ou appliquer un masque réseau à une adresse IP. L’échantillon résultant est du type du dernier convertisseur appliqué à la liste, qui par défaut correspond au type de la méthode d’extraction d’échantillon.
Chaque échantillon ou convertisseur retourne des données d’un type spécifique, précisé par son mot-clé dans cette documentation. Lorsqu’une ACL est déclarée à l’aide d’une méthode d’extraction d’échantillon standard, certains types impliquent automatiquement une méthode de correspondance par défaut, résumée dans le tableau ci-dessous :
Notez qu’en vue de correspondre à des échantillons binaires, il est obligatoire de préciser une méthode de correspondance, voir ci-dessous.
Le moteur ACL peut effectuer des correspondances entre ces types et des modèles des types suivants :
- booléen
- entier ou plage d’entiers
- adresse IP / réseau
- chaîne (exacte, sous-chaîne, suffixe, préfixe, sous-répertoire, domaine)
- expression régulière
- bloc hexadécimal
Les indicateurs ACL suivants sont actuellement pris en charge :
Le drapeau “-f” est suivi du nom qui doit respecter le format décrit en 2.7 concernant le format des noms pour les cartes et les listes ACL. Il est même possible de passer plusieurs arguments “-f” si les modèles doivent être chargés à partir de plusieurs listes. Si un fichier existant est référencé, toutes les lignes seront lues comme des valeurs individuelles. Les lignes vides ainsi que les lignes commençant par un dièse (’#’) seront ignorées. Tous les espaces et tabulations en début de ligne seront supprimés. Si une valeur valide commençant par un dièse doit absolument être insérée, il suffit de lui ajouter un espace en préfixe afin qu’elle ne soit pas interprétée comme un commentaire. Selon le type de données et la méthode de correspondance, HAProxy peut charger les lignes dans un arbre binaire, permettant des recherches très rapides. Cela s’applique aux correspondances exactes sur IPv4 et les chaînes de caractères. Dans ce cas, les doublons seront automatiquement supprimés.
L’indicateur “-M” permet à une liste de contrôle d’accès (ACL) d’utiliser une carte. Si cet indicateur est défini, la liste est analysée comme étant composée de deux colonnes. La première colonne contient les modèles utilisés par l’ACL, et la deuxième colonne contient les échantillons. Ces échantillons peuvent être utilisés ultérieurement par une carte. Cela peut être utile dans certains cas rares où une ACL ne serait utilisée qu’afin de vérifier l’existence d’un modèle dans une carte avant d’appliquer une correspondance.
L’indicateur “-u” impose l’identifiant unique de la liste ACL. Cet identifiant unique est utilisé avec l’interface socket pour identifier la liste ACL et modifier dynamiquement ses valeurs. Notez qu’un fichier est toujours identifié par son nom, même si un identifiant est défini.
En outre, notez que le drapeau “-i” s’applique aux entrées ultérieures et non aux entrées chargées à partir de fichiers antérieurs. Par exemple :
Dans cet exemple, chaque ligne de “exact-ua.lst” sera exactement correspondante avec l’en-tête « user-agent » de la requête. Ensuite, chaque ligne de « generic-ua » sera correspondante sans tenir compte de la casse. Enfin, le mot « test » sera également correspondant sans tenir compte de la casse.
Le drapeau “-m” est utilisé pour sélectionner une méthode spécifique de correspondance de modèle sur l’échantillon d’entrée. Tous les critères spécifiques aux ACL impliquent une méthode de correspondance de modèle et n’ont généralement pas besoin de ce drapeau. Toutefois, ce drapeau est utile avec les méthodes d’extraction d’échantillon génériques pour préciser la manière dont elles seront comparées aux modèles. Cela est nécessaire pour les extraits d’échantillon renvoyant un type de données pour lequel aucune méthode de correspondance évidente n’existe (par exemple, chaîne ou binaire). Lorsque “-m” est spécifié, suivi d’un nom de méthode de correspondance de modèle, cette méthode est utilisée à la place de celle par défaut pour le critère. Cela permet de correspondre aux contenus de manière non prévue initialement, ou avec des méthodes d’extraction d’échantillon renvoyant une chaîne. La méthode de correspondance affecte également la manière dont les modèles sont analysés. Elle ne doit donc pas être utilisée avec les extraits d’échantillon ayant un suffixe de correspondance (_beg, _end, _sub…). En outre, il n’est pas autorisé de spécifier plusieurs méthodes de correspondance de modèle “-m”.
Le drapeau “-n” interdit les résolutions DNS. Il est utilisé en conjonction avec le chargement de fichiers d’adresses IP. Par défaut, si le parseur ne parvient pas à analyser une adresse IP, il considère que la chaîne analysée pourrait être un nom de domaine et tente une résolution DNS. Le drapeau “-n” désactive cette résolution. Il est utile pour détecter des listes d’adresses IP malformées. Notez que si le serveur DNS n’est pas accessible, l’analyse de la configuration HAProxy peut durer plusieurs minutes en attendant le délai d’expiration. Pendant cette période, aucune message d’erreur n’est affiché. Le drapeau “-n” désactive ce comportement. Notez également que, pendant l’exécution, cette fonction est désactivée pour les modifications dynamiques des ACL.
Toutefois, certaines restrictions s’appliquent. Toutes les méthodes ne peuvent pas être utilisées avec toutes les méthodes d’extraction d’échantillon. En outre, si “-m” est utilisé conjointement avec “-f”, il doit être placé en premier. La méthode de correspondance de modèle doit être l’une des suivantes :
“found”: vérifie uniquement si l’échantillon demandé est présent dans le flux, sans le comparer à tout motif. Il est recommandé de ne pas passer de motif afin d’éviter toute confusion. Cette méthode de correspondance est particulièrement utile pour détecter la présence de contenus spécifiques, tels que des en-têtes, des cookies, etc., même s’ils sont vides, sans les comparer à quoi que ce soit ni les compter.
“bool” : vérifie la valeur comme une valeur booléenne. Cette option ne peut être utilisée que sur les requêtes renvoyant une valeur booléenne ou entière, et ne prend pas de motif. Une valeur nulle ou fausse ne correspond pas, toutes les autres valeurs correspondent.
“int” : correspond à une valeur entière. Peut être utilisé avec des échantillons entiers et booléens. Le booléen faux correspond à l’entier 0, le booléen vrai à l’entier 1.
“ip” : correspond à une adresse IPv4 ou IPv6. Elle n’est compatible qu’avec des exemples d’adresses IP, aussi elle est implicite et jamais nécessaire.
“bin” : correspondre au contenu à une chaîne hexadécimale représentant une séquence binaire. Cela peut être utilisé avec des échantillons binaires ou des chaînes.
“len” : correspond à la longueur de l’échantillon, exprimée sous forme d’entier. Cette option peut être utilisée avec des échantillons binaires ou chaînes de caractères.
“str” : correspondance exacte : compare le contenu à une chaîne. Cette option peut être utilisée avec des échantillons binaires ou textuels.
“sub” : correspondance de sous-chaîne : vérifie que le contenu contient au moins l’une des chaînes fournies. Cette option peut être utilisée avec des échantillons binaires ou de chaînes.
“reg” : correspondance par expression régulière : compare le contenu à une liste d’expressions régulières. Cela peut être utilisé avec des échantillons binaires ou chaînes de caractères.
“beg” : correspondance par préfixe : vérifie que le contenu commence par les chaînes fournies. Cela peut être utilisé avec des échantillons binaires ou de chaînes.
“end” : correspondance par suffixe : vérifie que le contenu se termine par les motifs de chaîne fournis. Cela peut être utilisé avec des échantillons binaires ou de chaînes.
“dir” : sous-répertoire correspondance : vérifie qu’une portion délimitée par des barres obliques du contenu correspond exactement à l’une des chaînes de motifs fournies. Cette option peut être utilisée avec des échantillons binaires ou textuels.
“dom” : correspondance de domaine : vérifie que une portion délimitée par des points du contenu correspond exactement à l’une des chaînes fournies. Cette option peut être utilisée avec des échantillons binaires ou textuels.
Par exemple, pour détecter rapidement la présence du cookie « JSESSIONID » dans une requête HTTP, il est possible de procéder ainsi :
Pour appliquer une expression régulière sur les 500 premiers octets de données dans le tampon, on utiliserait la règle d’accès suivante :
Sur les systèmes où la bibliothèque regex est beaucoup plus lente lors de l’utilisation de “-i”, il est possible de convertir l’exemple en minuscules avant la correspondance, comme ceci :
Tous les critères spécifiques aux ACL impliquent une méthode de correspondance par défaut. Le plus souvent, ces critères sont composés en concaténant le nom de la méthode d’extraction d’échantillon d’origine et la méthode de correspondance. Par exemple, “hdr_beg” applique la correspondance « beg » aux échantillons récupérés à l’aide de la méthode d’extraction « hdr ». Cette méthode de correspondance n’est utilisable qu’en tant que mot-clé unique, sans convertisseur associé. Si un tel convertisseur était appliqué après un mot-clé ACL de ce type, la méthode de correspondance par défaut du mot-clé ACL est simplement ignorée, car ce qui importe pour la correspondance est le type de sortie du dernier convertisseur. Étant donné que tous les critères spécifiques aux ACL reposent sur une méthode d’extraction d’échantillon, il est toujours possible de remplacer ces critères par la méthode d’extraction d’échantillon d’origine et la méthode de correspondance explicite en utilisant “-m”.
Si une correspondance alternative est spécifiée à l’aide de “-m” sur un critère spécifique à une ACL, la méthode de correspondance est simplement appliquée au mécanisme d’extraction d’échantillon sous-jacent. Par exemple, toutes les ACLs ci-dessous sont exactement équivalentes :
Le tableau ci-dessous résume la matrice de compatibilité entre les types d’échantillonnage ou de convertisseur et les types de modèle à interroger. Il indique pour chaque combinaison compatible le nom de la méthode correspondante à utiliser, entouré de crochets « > » et « < » lorsque la méthode est la valeur par défaut et fonctionnera par défaut sans -m.
7.1.1. Correspondance des booléens
Pour effectuer une correspondance booléenne, aucune valeur n’est requise et toutes les valeurs sont ignorées. La correspondance booléenne est utilisée par défaut pour toutes les méthodes de récupération de type « boolean ». Lorsqu’elle est utilisée, la valeur récupérée est renvoyée telle quelle : un booléen « true » correspond toujours, tandis qu’un booléen « false » ne correspond jamais.
La correspondance booléenne peut également être imposée en utilisant “-m bool” sur les méthodes de récupération renvoyant une valeur entière. Dans ce cas, la valeur entière 0 est convertie en booléen “false”, et toutes les autres valeurs sont converties en “true”.
7.1.2. Correspondance des entiers
La correspondance entière s’applique par défaut aux méthodes de récupération entières. Elle peut également être imposée aux récupérations booléennes en utilisant “-m int”. Dans ce cas, “false” est converti en entier 0, et “true” en entier 1.
La correspondance entière prend également en charge les plages d’entiers et les opérateurs. Notez que la correspondance entière ne s’applique qu’aux valeurs positives. Une plage est une valeur exprimée avec une borne inférieure et une borne supérieure séparées par deux points, les deux bornes pouvant être omises.
Par exemple, « 1024:65535 » est une plage valide pour représenter une plage de ports non privilégiés, et « 1024: » fonctionnerait également. « 0:1023 » est une représentation valide des ports privilégiés, et « :1023 » fonctionnerait également.
Dans un cas particulier, certaines fonctions ACL prennent en charge des nombres décimaux, qui sont en réalité deux entiers séparés par un point. Cela est utilisé, par exemple, pour certaines vérifications de version. Toutes les propriétés applicables aux entiers s’appliquent également à ces nombres décimaux, y compris les plages et les opérateurs.
Pour une utilisation plus simple, les opérateurs de comparaison sont également pris en charge. Notez qu’utiliser des opérateurs avec des plages ne présente guère de sens et est fortement déconseillé. De même, il ne semble pas pertinent d’effectuer des comparaisons d’ordre avec un ensemble de valeurs.
Opérateurs disponibles pour le correspondance entière :
Par exemple, la règle ACL suivante correspond à tout en-tête Content-Length négatif :
Ce paramètre correspond aux versions SSL comprises entre 3.0 et 3.1 (incluses) :
7.1.3. Chaînes de correspondance
La correspondance de chaînes s’applique aux méthodes d’accès en chaîne ou binaire, et existe sous 6 formes différentes :
correspondance exacte (-m str) : la chaîne extraite doit correspondre exactement aux modèles ;
correspondance de sous-chaîne (-m sub) : les modèles sont recherchés à l’intérieur de la chaîne extraite, et la règle d’accès correspond si l’un d’entre eux est trouvé à l’intérieur ;
correspondance de préfixe (-m début) : les modèles sont comparés au début de la chaîne extraite, et la règle d’accès correspond si l’un d’entre eux correspond.
suffix match (-m end) : les modèles sont comparés à la fin de la chaîne extraite, et la règle d’accès (ACL) est appliquée si l’un d’entre eux correspond.
sous-répertoire correspondant (-m répertoire) : les modèles sont recherchés n’importe où dans la chaîne extraite, délimités par des barres obliques ("/"), le début ou la fin de la chaîne. La règle d’accès est respectée si l’un des modèles correspond. Ainsi, la chaîne “/images/png/logo/32x32.png” correspond à “/images”, “/images/png”, “images/png”, “/png/logo”, “logo/32x32.png” ou “32x32.png”, mais pas à “png” ni à “32x32”.
domain match (-m dom) : les modèles sont recherchés n’importe où dans la chaîne extraite, séparés par des points ("."), des deux-points (":"), des barres obliques ("/"), des points d’interrogation ("?"), au début ou à la fin de la chaîne. Cette option est destinée à être utilisée avec les URL. Les délimiteurs en début ou en fin de modèle sont ignorés. L’ACL correspond si l’un des modèles correspond. Ainsi, dans la chaîne d’exemple “http://www1.dc-eu.example.com:80/blah ”, les modèles “http”, “www1”, “.www1”, “dc-eu”, “example”, “com”, “80”, “dc-eu.example”, “blah”, “:www1:”, “dc-eu.example:80” correspondent, mais pas “eu” ni “dc”. Il n’est généralement pas recommandé de l’utiliser pour correspondre aux suffixes de domaine afin de filtrer ou acheminer le trafic, car l’acheminement pourrait facilement être trompé en ajoutant le préfixe correspondant devant un autre domaine, par exemple.
La correspondance de chaîne s’applique aux chaînes littérales telles qu’elles sont transmises, à l’exception de la barre oblique inverse ("\") qui permet d’échapper certains caractères, tels que l’espace. Si le drapeau “-i” est passé avant la première chaîne, la correspondance sera effectuée sans tenir compte de la casse. Pour correspondre à la chaîne “-i”, soit la définir en deuxième position, soit passer l’option “–” avant la première chaîne. La même règle s’applique bien entendu pour correspondre à la chaîne “–”.
N’utilisez pas de correspondances de chaînes pour les récupérations binaires pouvant contenir des octets nuls (0x00), car la comparaison s’arrête à la première occurrence d’un octet nul. À la place, convertissez d’abord la récupération binaire en chaîne hexadécimale à l’aide du convertisseur hexadécimal.
Exemple :
7.1.4. Correspondance des expressions régulières (regexes)
Tout comme pour la correspondance de chaîne, la correspondance par expression régulière s’applique aux chaînes littérales telles qu’elles sont transmises, à l’exception de la barre oblique inverse ("\") qui permet d’échapper à certains caractères, tels que l’espace. Si le drapeau “-i” est passé avant la première expression régulière, la correspondance se fera sans tenir compte de la casse. Pour correspondre à la chaîne “-i”, il faut soit la placer en deuxième position, soit passer l’option “–” avant la première chaîne. Le même principe s’applique bien entendu pour correspondre à la chaîne “–”.
7.1.5. Correspondance de blocs de données arbitraires
Il est possible de comparer certains échantillons extraits à un bloc binaire qui ne peut pas être représenté en toute sécurité sous forme de chaîne. Pour cela, les modèles doivent être fournis sous forme d’une série de chiffres hexadécimaux en nombre pair, lorsque la méthode de correspondance est définie sur binaire. Chaque séquence de deux chiffres représente un octet. Les chiffres hexadécimaux peuvent être utilisés en majuscules ou en minuscules.
Exemple :
7.1.6. Correspondance des adresses IPv4 et IPv6
Les valeurs d’adresses IPv4 peuvent être spécifiées soit sous forme d’adresses brutes, soit avec un masque réseau ajouté, auquel cas l’adresse IPv4 correspond si elle se trouve dans le réseau. Les adresses brutes peuvent également être remplacées par un nom d’hôte résolvable, mais cette pratique est généralement déconseillée car elle rend la lecture et le débogage des configurations plus difficiles. Si des noms d’hôtes sont utilisés, vous devez au moins vous assurer qu’ils sont présents dans /etc/hosts afin que la configuration ne dépende pas d’une correspondance DNS aléatoire au moment de l’analyse de la configuration.
La notation en adresse IPv4 avec points est prise en charge, tant sous sa forme classique que sous sa forme abrégée, où les octets nuls sont omis :
Remarque : cela diffère de la notation d’adresses CIDR RFC 4632, dans laquelle 192.168.42/24 serait équivalent à 192.168.42.0/24.
IPv6 peut être entré sous sa forme habituelle, avec ou sans masque réseau ajouté. Seuls les nombres de bits sont acceptés pour les masques réseau IPv6. Afin d’éviter tout risque de problème lié à des adresses IP résolues aléatoirement, les noms d’hôte ne sont jamais autorisés dans les modèles IPv6.
HAProxy est également capable de correspondre aux adresses IPv4 aux adresses IPv6 dans les situations suivantes :
- l’adresse testée est en IPv4, l’adresse modèle est en IPv4, la correspondance s’applique en IPv4 en utilisant le masque fourni, le cas échéant.
- l’adresse testée est en IPv6, l’adresse modèle est en IPv6, la correspondance s’applique en IPv6 en utilisant le masque fourni, le cas échéant.
- l’adresse testée est en IPv6, l’adresse modèle est en IPv4, la correspondance s’applique en IPv4 en utilisant le masque du modèle si l’adresse IPv6 correspond à 2002:IPV4::, ::IPV4 ou ::ffff:IPV4, sinon elle échoue.
- l’adresse testée est en IPv4, l’adresse modèle est en IPv6, l’adresse IPv4 est d’abord convertie en IPv6 en préfixant ::ffff: devant, puis la correspondance s’applique en IPv6 en utilisant le masque IPv6 fourni.
7.2. Utilisation des ACL pour définir des conditions
Certaines actions ne sont exécutées que si une condition valide est remplie. Une condition est une combinaison d’ACLs avec des opérateurs. Trois opérateurs sont pris en charge :
- ET (implicite)
- OU (explicite avec le mot-clé “or” ou l’opérateur “||”)
- Négation avec le point d’exclamation ("!")
Une condition est formulée sous forme disjonctive :
Ces conditions sont généralement utilisées après une instruction « if » ou « unless », indiquant le moment où la condition déclenchera l’action.
Par exemple, bloquer les requêtes HTTP vers l’URL « * » avec des méthodes autres que « OPTIONS », ainsi que les requêtes POST sans en-tête content-length, et les requêtes GET ou HEAD avec un content-length supérieur à 0, et enfin toute requête qui n’est ni GET/HEAD/POST/OPTIONS !
acl missing_cl req.hdr_cnt(Content-length) eq 0 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl http-request deny if METH_GET HTTP_CONTENT http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Pour sélectionner un backend différent pour les requêtes relatives aux contenus statiques du site « www » et pour toutes les requêtes sur les hôtes « img », « video », « download » et « ftp » :
Il est également possible de créer des règles à l’aide d’« ACL anonymes ». Il s’agit d’expressions ACL sans nom, qui sont construites dynamiquement sans avoir besoin d’être déclarées. Elles doivent être encloses entre des accolades, avec un espace avant et après chaque accolade (car les accolades doivent être considérées comme des mots indépendants). Exemple :
Il est généralement déconseillé d’utiliser cette construction, car il est bien plus facile de laisser des erreurs dans la configuration lorsqu’elle est écrite de cette manière. Toutefois, pour des règles très simples correspondant à une seule adresse IP source, par exemple, il peut être plus pertinent de l’utiliser que de déclarer des ACLs avec des noms aléatoires. Un autre exemple d’utilisation appropriée est le suivant :
Voir section 4.2 pour obtenir une aide détaillée sur les mots-clés « http-request deny » et “use_backend”.
7.3. Récupération des échantillons
Historiquement, les méthodes d’extraction d’échantillon étaient utilisées uniquement pour récupérer des données afin de les comparer à des modèles à l’aide des listes de contrôle d’accès (ACL). Avec l’arrivée des tables de persistance (stick-tables), une nouvelle catégorie de méthodes d’extraction d’échantillon a été introduite, dont la syntaxe est généralement identique à celle de leurs homologues ACL. Ces méthodes d’extraction d’échantillon sont également appelées « fetches ». À ce jour, les ACL et les fetches se sont convergées. Toutes les méthodes d’extraction d’échantillon disponibles pour les ACL sont désormais accessibles en tant que méthodes fetch, et les ACL peuvent utiliser n’importe quelle méthode d’extraction d’échantillon.
Cette section détaille toutes les méthodes d’extraction d’échantillon disponibles ainsi que leur type de sortie. Certaines méthodes d’extraction d’échantillon disposent d’alias obsolètes, utilisés pour maintenir la compatibilité avec les configurations existantes. Elles sont alors explicitement marquées comme obsolètes et ne doivent pas être utilisées dans de nouvelles configurations.
Les dérivés de ACL sont également indiqués lorsqu’ils sont disponibles, accompagnés de leurs méthodes de correspondance respectives. Tous disposent d’une méthode de correspondance par défaut bien définie, aussi n’est-il jamais nécessaire (bien qu’autorisé) de passer l’option “-m” pour indiquer comment l’échantillon sera correspondant via les ACLs.
Comme indiqué dans la matrice ci-dessus indiquant la compatibilité entre les types d’extraction d’échantillon et les correspondances, lorsque l’on utilise une méthode d’extraction d’échantillon générique dans une ACL, l’option “-m” est obligatoire, sauf si le type d’extraction est l’un des suivants : booléen, entier, IPv4 ou IPv6. Lorsque le même mot-clé existe à la fois comme mot-clé ACL et comme méthode d’extraction standard, le moteur ACL choisit automatiquement celui propre aux ACL par défaut.
Certains de ces mots-clés prennent un ou plusieurs arguments obligatoires, ainsi qu’un ou plusieurs arguments facultatifs. Ces arguments sont fortement typés et vérifiés lors de l’analyse de la configuration, afin d’éviter tout risque d’exécution avec un argument incorrect (par exemple, un nom de backend non résolu). Les arguments des fonctions de récupération sont placés entre parenthèses et séparés par des virgules. Lorsqu’un argument est facultatif, il est indiqué ci-dessous entre crochets (’[ ]’). Lorsque tous les arguments sont facultatifs, les parenthèses peuvent être omises.
Ainsi, la syntaxe d’une méthode d’extraction d’échantillon standard est l’une des suivantes :
- name
- name(arg1)
- name(arg1,arg2)
7.3.1. Convertisseurs
Les méthodes d’extraction d’échantillon peuvent être combinées avec des transformations à appliquer sur l’échantillon extrait (appelées également « convertisseurs »). Ces combinaisons forment ce qu’on appelle des « expressions d’échantillon », dont le résultat est un « échantillon ». Initialement, cette fonctionnalité n’était supportée que par les directives « stick on » et « stick store-request », mais elle a maintenant été étendue à toutes les situations où des échantillons peuvent être utilisés (ACLs, log-format, unique-id-format, add-header, …).
Ces transformations sont énumérées sous la forme d’une série de mots-clés spécifiques placés après la méthode d’extraction d’échantillon. Ces mots-clés peuvent également être ajoutés immédiatement après l’argument du mot-clé fetch, séparés par une virgule. Ces mots-clés peuvent également prendre certains arguments (par exemple, un masque réseau), qui doivent être passés entre parenthèses.
Une catégorie de convertisseurs est constituée d’opérateurs bit à bit et arithmétiques, qui permettent d’effectuer des opérations élémentaires sur des entiers. Certains opérations bit à bit sont prises en charge (et, ou, ou exclusif, complément), ainsi que certaines opérations arithmétiques (addition, soustraction, multiplication, division, modulo, négation). Certains comparateurs sont également fournis (impair, pair, non, booléen), ce qui permet de signaler une correspondance sans avoir à écrire une ACL.
Les mots-clés suivants sont pris en charge :
La liste détaillée des mots-clés convertisseurs suit :
51d.single(<prop>[,<prop>*])
Retourne les valeurs des propriétés demandées sous forme de chaîne, où les valeurs sont séparées par le délimiteur spécifié par « 51degrees-property-separator ». L’appareil est identifié à l’aide de l’en-tête User-Agent transmis au convertisseur. La fonction peut recevoir jusqu’à cinq noms de propriété ; si un nom de propriété n’est pas trouvé, la valeur « NoData » est retournée.
Exemple :
add(<value>)
Ajoute <value> à la valeur d’entrée de type entier signé, et retourne le résultat sous forme d’entier signé. <value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8
concernant les variables pour plus de détails.
add_item(<delim>[,<var>[,<suff>]])
Concatène un minimum de 2 et jusqu’à 3 champs situés après l’échantillon courant, qui est ensuite converti en chaîne. Le premier, <delim>, est une chaîne constante, qui est ajoutée immédiatement après l’échantillon existant si l’échantillon existant n’est pas vide et si au moins l’un des champs <var> ou <suff> n’est pas vide. Le second, <var>, est un nom de variable. Cette variable est recherchée, son contenu converti en chaîne, puis ajouté immédiatement après la partie <delim>. Si la variable n’est pas trouvée, rien n’est ajouté. Ce champ est facultatif et peut éventuellement être suivi d’une chaîne constante <suff>, toutefois si <var> est omis, alors <suff> est obligatoire. Ce convertisseur est similaire au convertisseur concat et peut être utilisé pour construire de nouvelles variables à partir d’une succession d’autres variables, mais la principale différence réside dans le fait qu’il effectue des vérifications pour déterminer si l’ajout d’un séparateur est pertinent, contrairement à ce qui serait le cas si, par exemple, l’échantillon courant était vide. Dans ce dernier cas, deux règles distinctes seraient nécessaires en utilisant le convertisseur concat, la première devant vérifier si la chaîne de l’échantillon courant est vide avant d’ajouter un séparateur. Si des virgules ou des parenthèses fermantes sont nécessaires comme séparateurs, ils doivent être protégés par des guillemets ou des barres obliques, eux-mêmes protégés afin de ne pas être supprimés par le parseur de premier niveau (voir la section 2.2
pour la mise en quote et l’échappement). Voir les exemples ci-dessous.
Exemple :
aes_cbc_dec(<bits>,<nonce>,<key>[,<aad>])
Déchiffre l’entrée binaire brute en utilisant l’algorithme AES128-CBC, AES192-CBC ou AES256-CBC, selon le paramètre <bits>. Tous les autres paramètres doivent être encodés en base64 et le résultat renvoyé est au format binaire brut. Le paramètre <aad> est facultatif. Si la validation <aad> échoue, le convertisseur ne renvoie aucune donnée. Les paramètres <nonce>, <key> et <aad> peuvent être des chaînes ou des variables. Ce convertisseur nécessite au moins OpenSSL 1.0.1.
Exemple :
aes_cbc_enc(<bits>,<nonce>,<key>[,<aad>])
Chiffre l’entrée en octets bruts en utilisant l’algorithme AES128-CBC, AES192-CBC ou AES256-CBC, selon le paramètre <bits>. Les paramètres <nonce>, <key> et <aad> doivent être encodés en base64. Le paramètre <aad> est facultatif. Le résultat renvoyé est au format octets bruts. Les paramètres <nonce>, <key> et <aad> peuvent être des chaînes ou des variables. Ce convertisseur nécessite au moins OpenSSL 1.0.1.
Exemple :
aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>[,<aad>])
Déchiffre l’entrée binaire brute à l’aide de l’algorithme AES128-GCM, AES192-GCM ou AES256-GCM, selon le paramètre <bits>. Tous les autres paramètres doivent être encodés en base64, et le résultat retourné est au format binaire brut. Si la validation <aead_tag> ou <aad> échoue, le convertisseur ne retourne aucune donnée. Le paramètre <aad> est facultatif. Les paramètres <nonce>, <key>, <aead_tag> et <aad> peuvent être des chaînes ou des variables. Ce convertisseur nécessite au moins OpenSSL 1.0.1.
Exemple :
aes_gcm_enc(<bits>,<nonce>,<key>,<aead_tag>[,<aad>])
Chiffre l’entrée en octets bruts à l’aide de l’algorithme AES128-GCM, AES192-GCM ou AES256-GCM, selon le paramètre <bits>. Les paramètres <nonce>, <key> et <aad> doivent être encodés en base64. Le paramètre <aead_tag> doit être une variable. Le tag AEAD sera stocké au format base64 dans cette variable. Le paramètre <aad> est facultatif. Le résultat renvoyé est au format octets bruts. Les paramètres <nonce>, <key> et <aad> peuvent être des chaînes ou des variables. Ce convertisseur nécessite au moins OpenSSL 1.0.1.
Exemple :
and(<value>)
Effectue un opérateur “ET” bit à bit entre <value> et la valeur d’entrée de type entier signé, puis retourne le résultat sous forme d’entier signé. <value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8
sur les variables pour plus de détails.
b64dec
Convertit (décodifie) une chaîne encodée en base64 en sa représentation binaire. Elle effectue l’opération inverse de base64(). Pour la variante base64url(“alphabet sécurisé pour les URL et les noms de fichiers” (RFC 4648)), voir « ub64dec ».
base2
Convertit un échantillon d’entrée binaire en chaîne binaire contenant huit chiffres binaires par octet d’entrée. Elle est utilisée pour permettre la correspondance du préfixe le plus long sur des types dont la représentation native ne permet pas la correspondance de préfixe, par exemple les préfixes IP.
base64
Convertit un échantillon binaire en chaîne base64. Cette fonction est utilisée pour journaliser ou transférer du contenu binaire de manière fiable (par exemple, un identifiant SSL peut être copié dans un en-tête). Pour la variante base64url (“alphabet sécurisé pour les URL et les noms de fichiers” (RFC 4648)), voir « ub64enc ».
be2dec(<separator>,<chunk_size>[,<truncate>])
Convertit un échantillon d’entrée binaire au format big-endian en une chaîne contenant un nombre entier non signé par <chunk_size> octets d’entrée. <separator> est inséré tous les <chunk_size> octets d’entrée binaires, le cas échéant. Le drapeau <truncate> indique si l’entrée binaire est tronquée aux limites de <chunk_size>. La valeur maximale de <chunk_size> est limitée par la taille d’un entier long long (8 octets).
Exemple :
le2dec(<separator>,<chunk_size>[,<truncate>])
Convertit un échantillon d’entrée binaire en little-endian en une chaîne contenant un nombre entier non signé par <chunk_size> octets d’entrée. <separator> est inséré tous les <chunk_size> octets d’entrée binaires, si spécifié. Le drapeau <truncate> indique si l’entrée binaire est tronquée aux limites <chunk_size>. La valeur maximale de <chunk_size> est limitée par la taille d’un entier long long (8 octets).
Exemple :
be2hex([<separator>[,<chunk_size>[,<truncate>]]])
Convertit un échantillon d’entrée binaire au format big-endian en chaîne hexadécimale contenant deux chiffres hexadécimaux par octet d’entrée. Elle est utilisée pour journaliser ou transférer des dumps hexadécimaux de données binaires de manière fiable (par exemple, un identifiant SSL peut être copié dans un en-tête). <separator> est inséré tous les <chunk_size> octets d’entrée binaires, le cas échéant. Le drapeau <truncate> indique si l’entrée binaire est tronquée aux limites de <chunk_size>.
Exemple :
bool
Renvoie une valeur booléenne TRUE si la valeur d’entrée de type entier signé est non nulle, sinon renvoie FALSE. Utilisé en conjonction avec and(), il peut être utilisé pour signaler true/false lors du test de bits sur les valeurs d’entrée (par exemple, vérifier la présence d’un indicateur).
bytes(<offset>[,<length>])
Extrait certains octets à partir d’un échantillon binaire d’entrée. Le résultat est un échantillon binaire commençant à un décalage (en octets) par rapport à l’échantillon d’origine, et éventuellement tronqué à la longueur indiquée. <offset> et <length> peuvent être des valeurs numériques ou des noms de variables. Le convertisseur retourne un échantillon vide si <offset> ou <length> est invalide. Un <offset> invalide signifie une valeur négative ou une valeur supérieure ou égale à la longueur de l’échantillon d’entrée. Un <length> invalide signifie une valeur négative.
Exemple :
capture-req(<id>)
Capture la chaîne présente dans l’emplacement de requête <id> et la renvoie telle quelle. Si l’emplacement n’existe pas, la capture échoue silencieusement.
Voir aussi : « declare capture », « http-request capture », « http-response capture », “capture.req.hdr” et “capture.res.hdr” (extraction d’échantillon).
capture-res(<id>)
Capture la chaîne présente dans l’emplacement de réponse <id> et la renvoie telle quelle. Si l’emplacement n’existe pas, la capture échoue silencieusement.
Voir aussi : « declare capture », « http-request capture », « http-response capture », “capture.req.hdr” et “capture.res.hdr” (extraction d’échantillon).
concat([<start>[,<var>[,<end>]]])
Concatène jusqu’à 3 champs après l’échantillon courant, qui est ensuite converti en chaîne. Le premier, <start>, est une chaîne constante, ajoutée immédiatement après l’échantillon existant. Il peut être omis s’il n’est pas utilisé. Le second, <var>, est un nom de variable. La variable est recherchée, son contenu converti en chaîne, puis ajouté immédiatement après la partie <first>. Si la variable n’est pas trouvée, rien n’est ajouté. Il peut également être omis. Le troisième champ, <end>, est une chaîne constante ajoutée après la variable. Il peut aussi être omis. Ensemble, ces éléments permettent de concaténer des variables avec des délimiteurs à un ensemble existant de variables. Cela peut être utilisé pour créer de nouvelles variables à partir d’une succession d’autres variables, par exemple des valeurs séparées par des deux-points. Si des virgules ou des parenthèses fermantes sont nécessaires comme délimiteurs, elles doivent être protégées par des guillemets ou des barres obliques, elles-mêmes protégées afin de ne pas être supprimées par le parseur de premier niveau. Cela est souvent utilisé pour construire des variables composées à partir d’autres, mais parfois, l’utilisation d’une chaîne de format avec plusieurs champs peut être plus pratique. Voir les exemples ci-dessous.
Exemple :
cpl
Prend la valeur d’entrée de type entier signé, applique une complémentation à un (inverse tous les bits) et renvoie le résultat sous forme d’entier signé.
crc32([<avalanche>])
Hache une entrée binaire en une quantité non signée sur 32 bits en utilisant la fonction de hachage CRC32.
Optionnellement, il est possible d’appliquer une fonction de hachage à avalanche complète à la sortie si l’argument facultatif <avalanche> vaut 1. Ce convertisseur utilise les mêmes fonctions que celles employées par les divers algorithmes de répartition de charge basés sur le hachage, il produira donc exactement les mêmes résultats. Il est fourni pour assurer la compatibilité avec d’autres logiciels qui souhaitent calculer un CRC32 à partir de certaines clés d’entrée, il suit donc l’implémentation la plus courante telle qu’elle se trouve dans Ethernet, Gzip, PNG, etc. Il est plus lent que les autres algorithmes, mais peut offrir une répartition meilleure ou du moins moins prévisible. Il ne doit pas être utilisé à des fins de sécurité, car un hachage sur 32 bits est facile à casser. Voir également « djb2 », « sdbm », « wt6 », « crc32c » et la directive « hash-type ».
crc32c([<avalanche>])
Hache une entrée binaire en une quantité non signée sur 32 bits à l’aide de la fonction de hachage CRC32C.
Optionnellement, il est possible d’appliquer une fonction de hachage à avalanche complète à la sortie si l’argument optionnel <avalanche> est égal à 1. Ce convertisseur utilise les mêmes fonctions décrites dans RFC4960, Annexe B [8]. Il est fourni pour assurer la compatibilité avec d’autres logiciels souhaitant calculer un CRC32C sur certaines clés d’entrée. Il est plus lent que les autres algorithmes et ne doit pas être utilisé à des fins de sécurité, car un hachage sur 32 bits est facile à casser. Voir également « djb2 », « sdbm », « wt6 », « crc32 » et la directive « hash-type ».
cut_crlf
Découpe la représentation sous forme de chaîne d’entrée sur le premier caractère de retour chariot (’\r’) ou de saut de ligne (’\n’) trouvé. Seule la longueur de la chaîne est mise à jour.
da-csv-conv(<prop>[,<prop>*])
Demande au convertisseur DeviceAtlas d’identifier la chaîne User Agent fournie en entrée, puis d’émettre une chaîne constituée de la concaténation des propriétés énumérées en argument, séparées par le séparateur défini par le mot-clé global « deviceatlas-property-separator », ou par défaut le caractère barre verticale (’|’). Une limite de 12 propriétés différentes est imposée par le langage de configuration HAProxy.
Exemple :
date
Ce convertisseur est utilisé pour convertir une date provenant d’un en-tête HTTP. Il peut s’agir d’une date IMF, d’une date ASCTIME ou d’une date RFC850. Il produira une horodatage UNIX.
Exemple :
debug([<prefix][,<destination>])
Ce convertisseur est utilisé comme outil de débogage. Il capture un échantillon d’entrée et l’envoie vers un réceptacle d’événements <destination>, qui peut désigner un tampon circulaire tel que “buf0”, ainsi que “stdout” ou “stderr”. Les réceptacles disponibles peuvent être vérifiés en temps réel en émettant la commande “show events” sur l’interface CLI. Lorsqu’aucun réceptacle n’est spécifié, la sortie par défaut est “buf0”, qui peut être consultée via la commande “show events” de l’interface CLI. Un préfixe optionnel <prefix> peut être fourni afin de distinguer les sorties provenant de plusieurs expressions. Il apparaîtra alors avant deux-points dans le message de sortie. L’échantillon d’entrée est transmis tel quel en sortie, ce qui permet de placer en toute sécurité le convertisseur de débogage n’importe où dans une chaîne, même avec des types d’échantillons non imprimables.
Exemple :
digest(<algorithm>)
Convertit un échantillon d’entrée binaire en empreinte de message. Le résultat est un échantillon binaire. Le <algorithm> doit être un nom d’empreinte OpenSSL (par exemple, sha256).
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
div(<value>)
Divise la valeur d’entrée de type entier signé par <value>, et retourne le résultat sous forme d’entier signé. Si <value> est nul, le plus grand entier non signé est retourné (généralement 2^63-1).
<value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8 concernant les variables pour plus de détails.
djb2([<avalanche>])
Hache un échantillon d’entrée binaire en une quantité non signée sur 32 bits en utilisant la fonction de hachage DJB2.
Optionnellement, il est possible d’appliquer une fonction de hachage à avalanche complète à la sortie si l’argument facultatif <avalanche> vaut 1. Ce convertisseur utilise les mêmes fonctions que celles employées par les divers algorithmes de répartition de charge basés sur le hachage, il produira donc exactement les mêmes résultats. Il est principalement destiné au débogage, mais peut être utilisé comme entrée de table de persistance pour collecter des statistiques brutes. Il ne doit pas être utilisé à des fins de sécurité, car un hachage sur 32 bits est facile à casser. Voir également « crc32 », « sdbm », « wt6 », « crc32c » et la directive « hash-type ».
eth.data
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “2”. Il ignore l’en-tête Ethernet entier, y compris les VLAN éventuels, et renvoie un bloc de données binaires commençant au protocole de couche 3 (généralement IPv4 ou IPv6). Voir également “fc_saved_syn” et “tcp-ss”.
eth.dst
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “2”. Il renvoie les 6 octets de l’en-tête Ethernet correspondant à l’adresse de destination du cadre, sous forme de bloc binaire. Voir également “fc_saved_syn” et “tcp-ss”.
eth.hdr
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “2”. Il supprime tout ce qui suit l’en-tête Ethernet tout en conservant éventuellement les VLAN, puis renvoie cet en-tête sous forme de bloc de données binaires. Voir également “fc_saved_syn” et “tcp-ss”.
eth.proto
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “2”. Il retourne le numéro de protocole (également appelé EtherType) trouvé dans un en-tête Ethernet après tout VLAN facultatif, sous forme de valeur entière. Il devrait normalement être soit 0x800 pour IPv4, soit 0x86DD pour IPv6. Voir également “fc_saved_syn” et “tcp-ss”.
eth.src
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “2”. Il renvoie les 6 octets de l’en-tête Ethernet correspondant à l’adresse source du cadre, sous forme de bloc binaire. Voir également “fc_saved_syn” et “tcp-ss”.
eth.vlan
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option bind “tcp-ss” définie sur “2”. Il retourne l’identifiant VLAN dernier trouvé dans un en-tête Ethernet sous forme de valeur entière. Voir également “fc_saved_syn” et “tcp-ss”.
even
Renvoie une valeur booléenne TRUE si la valeur d’entrée de type entier signé est paire, sinon renvoie FALSE. Elle est fonctionnellement équivalente à « not,and(1),bool ».
field(<index>,<delimiters>[,<count>])
Extrait la sous-chaîne à l’indice donné, en comptant depuis le début (indice positif) ou depuis la fin (indice négatif), en tenant compte des délimiteurs spécifiés dans une chaîne d’entrée. Les indices commencent à 1 ou -1. Les délimiteurs sont une liste de caractères formatée sous forme de chaîne. Vous pouvez éventuellement préciser le nombre de champs à extraire (<count> par défaut : 1). Une valeur de 0 indique l’extraction de tous les champs restants.
Exemple :
fe_exists
Prend un nom de frontal en valeur d’entrée et renvoie une valeur booléenne TRUE si un frontal portant ce nom existe dans la configuration actuelle, sinon renvoie FALSE. Peut être utilisé là où il est utile de vérifier l’existence d’un frontal à partir d’un nom dynamique, par exemple dans des recherches dans des cartes ou lors de réponses à une vérification externe.
Exemple :
fix_is_valid
Analyse une charge utile binaire et effectue des vérifications de cohérence concernant FIX (Financial Information eXchange) :
- vérifie que tous les identifiants et valeurs d’étiquettes sont non vides et que les identifiants d’étiquettes sont bien numériques
- vérifie que l’étiquette BeginString est la première étiquette avec une version FIX valide
- vérifie que l’étiquette BodyLength est la deuxième étiquette avec la longueur de corps correcte
- vérifie que l’étiquette MsgType est la troisième étiquette
- vérifie que la dernière étiquette du message est l’étiquette CheckSum avec un checksum valide
En raison de la conception actuelle d’HAProxy, seul le premier message envoyé par le client et par le serveur peut être analysé.
Ce convertisseur renvoie une valeur booléenne : true si le contenu contient un message FIX valide, false sinon.
Voir également le convertisseur fix_tag_value.
Exemple :
fix_tag_value(<tag>)
Analyse un message FIX (Financial Information eXchange) et extrait la valeur associée à l’étiquette <tag>.
<tag> peut être une chaîne de caractères ou un entier indiquant l’étiquette souhaitée. Toute valeur entière est acceptée,
mais seules les chaînes suivantes sont traduites en leur équivalent entier : BeginString, BodyLength, MsgType, SenderCompID, TargetCompID, CheckSum. D’autres noms d’étiquettes peuvent être facilement ajoutés.
En raison de la conception actuelle d’HAProxy, seul le premier message envoyé par le client et par le serveur peut être analysé. Aucune validation du message n’est effectuée par ce convertisseur. Il est fortement recommandé de valider le message en premier lieu à l’aide du convertisseur fix_is_valid.
Voir également le convertisseur fix_is_valid.
Exemple :
has_ctl([mask])
Vérifie l’échantillon binaire d’entrée pour les caractères de contrôle définis par l’argument masque. Le masque est un nombre sur 33 bits (décimal ou hexadécimal préfixé par « 0x »), dont un bit est défini pour chaque caractère à détecter dans la plage 0x00 à 0x1F, et le bit 32 est défini pour correspondre au caractère DEL (0x7F). Lorsqu’aucun masque n’est spécifié, le convertisseur utilise la valeur 0x1FFFFFDFF, qui correspond à tous les caractères de contrôle sauf TAB (0x09), couramment utilisé dans les en-têtes HTTP. Le masque spécial « any » correspond à 0x1FFFFFFFF et correspond à tous les caractères de contrôle, y compris TAB. Le masque spécial « http » correspond à 0x2401 et ne détecte que les caractères de contrôle interdits dans les valeurs d’en-tête HTTP, à savoir CR (0x0D), LF (0x0A) et NUL (0x00).
Exemples :
hex
Convertit un échantillon binaire en chaîne hexadécimale contenant deux chiffres hexadécimaux par octet d’entrée. Elle est utilisée pour journaliser ou transférer des dumps hexadécimaux de données binaires d’une manière pouvant être transférée de façon fiable (par exemple, un ID SSL peut être copié dans un en-tête).
hex2i
Convertit une chaîne hexadécimale contenant deux chiffres hexadécimaux par octet d’entrée en entier. Si la valeur d’entrée ne peut pas être convertie, zéro est retourné.
hmac(<algorithm>,<key>)
Convertit un échantillon d’entrée binaire en code d’authentification de message à l’aide de la clé fournie. Le résultat est un échantillon binaire. Le paramètre <algorithm> doit être l’un des noms de hachage OpenSSL enregistrés (par exemple, sha256). Le paramètre <key> doit être encodé en base64 et peut être une chaîne ou une variable.
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
host_only
Convertit une chaîne contenant une valeur d’en-tête Host en supprimant son port. L’entrée doit respecter le format de la valeur d’en-tête Host (rfc9110#section-7.2). Elle prend en charge les entrées suivantes : hostname, hostname:80, 127.0.0.1, 127.0.0.1:80, [::1], [::1]:80.
Ce convertisseur met également la chaîne en minuscules.
Voir également : le convertisseur “port_only” qui retournera le port.
htonl
Convertit la valeur entière d’entrée en sa représentation binaire sur 32 bits, selon l’ordre des octets réseau. Comme l’extraction d’échantillon utilise un entier signé 64 bits, lorsque ce convertisseur est utilisé, la valeur entière d’entrée est d’abord convertie en entier non signé sur 32 bits.
http_date([<offset[,<unit>]])
Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date au format adapté à une utilisation dans des champs d’en-tête HTTP. Si une valeur de décalage est spécifiée, elle est ajoutée à la date avant la conversion. Cela est particulièrement utile pour émettre des champs d’en-tête Date, des valeurs Expires dans les réponses lorsqu’elles sont combinées avec un décalage positif, ou des valeurs Last-Modified lorsque le décalage est négatif. Si une unité est spécifiée, considérer l’horodatage comme étant en « s » pour secondes (comportement par défaut), « ms » pour millisecondes, ou « us » pour microsecondes depuis l’époque. Le décalage est supposé avoir la même unité que l’horodatage d’entrée.
iif(<true>,<false>)
Renvoie la chaîne <true> si la valeur d’entrée est true. Renvoie la chaîne <false> sinon.
Exemple :
in_table([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, une valeur booléenne false est renvoyée. Sinon, une valeur booléenne true est renvoyée. Cette fonction peut être utilisée pour vérifier la présence d’une clé spécifique dans une table suivant certains éléments (par exemple, si une adresse IP source ou un en-tête Authorization a déjà été vue).
ip.data
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il ignore l’en-tête IP et toutes les options ou extensions facultatives, puis renvoie un bloc de données binaires commençant au niveau du protocole transport (généralement TCP ou UDP). Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ip.df
Utilisé avec un échantillon d’entrée représentant un cadre Ethernet binaire, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Renvoie la valeur entière 1 si le drapeau DF (ne pas fragmenter) est défini dans l’en-tête IP, 0 sinon. IPv6 ne possède pas de drapeau DF et ne fragmente pas par défaut, aussi renvoie-t-il toujours 1. Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ip.dst
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il renvoie l’adresse de destination IPv4 ou IPv6 issue de l’en-tête IPv4/v6. Voir également “fc_saved_syn”, “tcp-ss” et “eth.data”.
ip.fp([<mode>])
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il examine diverses parties de l’en-tête IP et de l’en-tête TCP afin de construire une empreinte de parties invariantes pouvant être utilisées pour distinguer plusieurs hôtes apparemment identiques. Le cas d’utilisation réel consiste à affiner l’identification des hôtes défaillants partageant une même adresse IP, afin d’éviter de bloquer des utilisateurs légitimes lorsque seul un d’entre eux est défaillant et doit être bloqué. Le convertisseur construit un bloc binaire minimal de 8 octets à partir de l’entrée. Les octets de l’empreinte sont disposés comme suit : - octet 0 : champ IP TOS (voir ip.tos) - octet 1 : - bit 7 : IPv6 (1) / IPv4 (0) - bit 6 : ip.df - bit 5..4 : 0 : ip.ttl ≤ 32 ; 1 : ip.ttl ≤ 64 ; 2 : ip.ttl ≤ 128 ; 3 : ip.ttl ≤ 255 - bit 3 : options IP présentes (1) / absentes (0) - bit 2 : données TCP présentes (1) / absentes (0) - bit 1 : le bit CWR de TCP.flags est défini (1) / effacé (0) - bit 0 : le bit ECE de TCP.flags est défini (1) / effacé (0) - octet 2 : - bits 7..4 : longueur de l’en-tête TCP en mots de 4 octets - bits 3..0 : mise à l’échelle de la fenêtre TCP + 1 (1..15) / 0 (aucune mise à l’échelle annoncée) - octet 3..4 : tcp.win - octet 5..6 : tcp.options.mss, ou zéro si absent - octet 7 : 1 bit par option TCP présente, les options 2 à 8 étant mappées respectivement aux bits 0 à 6, et le bit 7 indiquant la présence d’une option quelconque comprise entre 9 et 255
L’argument <mode> permet d’ajouter des informations supplémentaires à l’empreinte. Par défaut, lorsque l’argument <mode> n’est pas défini ou vaut zéro, l’empreinte est constituée uniquement des 8 octets décrits ci-dessus. Si <mode> est spécifié avec une autre valeur, celle-ci correspond à la somme des valeurs suivantes, et les composants correspondants sont concaténés à l’empreinte, dans l’ordre ci-dessous : - 1 : la valeur TTL reçue est ajoutée à l’empreinte (1 octet) - 2 : la liste des types d’options TCP, telle qu’elle est retournée par “tcp.options_list”, comprenant de 0 à 40 octets supplémentaires, est ajoutée à l’empreinte - 4 : l’adresse IP source est ajoutée à l’empreinte, ce qui ajoute 4 octets pour IPv4 et 16 pour IPv6
Exemple : créer une empreinte de 13 à 25 octets en utilisant l’empreinte de base, le TTL et l’adresse source (1+4=5) :
frontend test
mode http
bind:4445 tcp-ss 1
tcp-request connection set-var(sess.syn) fc_saved_syn
http-request return status 200 content-type text/plain lf-string \
"src=%[var(sess.syn),ip.src] fp=%[var(sess.syn),ip.fp(5),hex]\n"
Voir également “fc_saved_syn”, « tcp-ss », “eth.data”, “ip.df”, “ip.ttl”, “tcp.win”, “tcp.options.mss” et “tcp.options_list”.
ip.hdr
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il renvoie un bloc de données binaires commençant par l’en-tête IP et s’arrêtant après la dernière option ou extension, avant l’en-tête du protocole de transport. Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ip.proto
Cela est utilisé avec un échantillon d’entrée représentant un cadre Ethernet binaire, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il renvoie le numéro de protocole transport, généralement 6 pour TCP ou 17 pour UDP. Voir également “fc_saved_syn”, “tcp-ss” et “eth.data”.
ip.src
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Il retourne l’adresse source IPv4 ou IPv6 à partir de l’en-tête IPv4/v6. Voir également “fc_saved_syn”, “tcp-ss” et “eth.data”.
ip.tos
Utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Renvoie un entier correspondant à la valeur du champ type de service (TOS) dans l’en-tête IPv4 ou du champ classe de trafic (TC) dans l’en-tête IPv6. Notez qu’Internet moderne, ce champ contient généralement une valeur DSCP (Codepoint de services différenciés) dans les 6 bits supérieurs, tandis que les deux bits inférieurs sont soit non utilisés, soit utilisés par l’ECN IP. Voir RFC2474 et RFC8436 pour les valeurs DSCP, et RFC3168 pour les champs ECN IP. Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ip.ttl
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Cela renvoie un entier correspondant au champ TTL (Time To Live) ou HL (Hop Limit) dans l’en-tête IPv4/IPv6. Cette valeur est généralement prédéfinie à une valeur fixe et décrémentée à chaque routeur traversé par le paquet. Elle peut aider à estimer la distance entre un client et le serveur lorsque la valeur initiale est connue. Notez que la plupart des systèmes d’exploitation modernes partent d’une valeur initiale de 64. Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ip.ver
Cela est utilisé avec un échantillon d’entrée représentant un cadre binaire Ethernet, tel que renvoyé par “fc_saved_syn” combiné à l’option de liaison “tcp-ss” définie sur “1”, ou avec la sortie de “eth.data”. Cela renvoie la version IP présente dans l’en-tête IP, normalement 4 ou 6. Notez que cela ne vérifie pas si le numéro de protocole dans le cadre Ethernet supérieur correspond, mais comme il est attendu qu’il soit utilisé avec des paquets valides, on suppose que le système d’exploitation a déjà effectué cette vérification. Voir également “fc_saved_syn”, “tcp-ss”, et “eth.data”.
ipmask(<mask4>[,<mask6>])
Applique un masque à une adresse IP, et utilise le résultat pour les recherches et le stockage. Cela permet de faire en sorte que tous les hôtes situés dans une plage définie par un masque partagent les mêmes entrées de table, et utilisent ainsi le même serveur. Le masque4 peut être fourni sous forme décimale pointée (par exemple 255.255.255.0) ou sous forme CIDR (par exemple 24). Le masque6 peut être fourni sous forme quadruplète (par exemple ffff:ffff::) ou sous forme CIDR (par exemple 64). Si aucun masque6 n’est fourni, les adresses IPv6 ne pourront pas être converties, pour des raisons de compatibilité descendante.
json([<input-code>])
Échappe la chaîne d’entrée et produit une chaîne ASCII prête à être utilisée comme chaîne JSON. Le convertisseur tente de décoder la chaîne d’entrée selon le paramètre <input-code>. Celui-ci peut prendre les valeurs « ascii », « utf8 », « utf8s », « utf8p » ou « utf8ps ». Le décodeur « ascii » ne peut jamais échouer. Le décodeur « utf8 » détecte 3 types d’erreurs :
- séquence UTF-8 non valide (octet de continuation isolé, nombre d’octets de continuation non valide, …)
- plage non valide (la valeur décodée se trouve dans une plage interdite UTF-8),
- code trop long (la valeur est encodée avec plus d’octets que nécessaire).
Le codage JSON UTF-8 peut produire une erreur « too long value » lorsque le caractère UTF-8 est supérieur à 0xffff, car la spécification d’échappement des chaînes JSON ne permet que 4 chiffres hexadécimaux pour le codage de la valeur. Le décodeur UTF-8 existe sous 4 variantes, identifiées par une combinaison de deux lettres de suffixe : « p » pour « permissif » et « s » pour « ignorer silencieusement ». Les comportements des décodeurs sont :
- “ascii” : ne peut jamais échouer ;
- “utf8” : échoue en cas de détection d’erreurs ;
- “utf8s” : ne peut jamais échouer, mais supprime les caractères correspondant aux erreurs ;
- “utf8p” : accepte et corrige les erreurs de surlongueur, mais échoue en cas d’autres erreurs ;
- “utf8ps” : ne peut jamais échouer, accepte et corrige les erreurs de surlongueur, mais supprime les caractères correspondant aux autres erreurs.
Ce convertisseur est particulièrement utile pour créer un JSON correctement échappé destiné à la journalisation sur des serveurs qui consomment des journaux de trafic au format JSON.
Exemple :
Requête entrante du client 127.0.0.1 :
Journal de sortie :
json_query(<json_path>[,<output_type>])
Le convertisseur json_query prend en charge les types JSON string, boolean, number et array. Les nombres à virgule flottante sont renvoyés sous forme de chaîne. En spécifiant le type de sortie ‘int’, la valeur est convertie en entier. Les tableaux sont renvoyés sous forme de chaîne, entourés de crochets. Le contenu est au format CSV. Selon le type de données, les valeurs du tableau peuvent être entre guillemets. Si les valeurs du tableau sont des types complexes, la chaîne contient la représentation JSON complète de chaque valeur, séparée par une virgule. Exemple de résultat pour une requête roles sur un JWT :
Si la conversion n’est pas possible, le convertisseur json_query échoue.
<json_path> doit être une chaîne de chemin JSON valide telle que définie dans
https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/
Note : selon le contexte et l’implémentation sous-jacente, l’extraction des clés JSON en double est indéfinie et peut renvoyer la première, la dernière ou toute autre occurrence de la même clé provenant du contenu d’entrée ; si les noms de clés sont passés encodés, ils ne sont pas toujours correctement associés. En résumé, ce convertisseur n’est pas adapté à la purification de contenu.
Exemple :
jwt_decrypt_cert(<cert>)
Effectue une validation de signature d’un jeton web JSON conforme au format JSON Web Encryption (voir RFC 7516), reçoit en entrée et renvoie son contenu déchiffré grâce au certificat fourni. Le paramètre <cert> doit être un chemin vers un certificat déjà chargé (pouvant être extrait via la commande CLI « dump ssl cert »). Le certificat doit avoir son option « jwt » explicitement définie sur « on » (voir l’option « jwt » de crt-list). Il peut être fourni directement ou via une variable. Les seuls jetons pris en charge pour l’instant sont ceux utilisant la sérialisation compacte (cinq chaînes encodées en base64-url séparées par un point).
Ce convertisseur peut être utilisé pour les jetons ayant un algorithme (“alg” du champ d’en-tête JOSE) parmi les suivants : RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW ou ECDH-ES+A256KW. L’algorithme RSA1_5 est implémenté mais désactivé par défaut, conformément aux recommandations de la section 3.2 de la RFC 8725. Il peut être réactivé si nécessaire grâce à l’option globale ‘jwt.decrypt_alg_list’.
Les algorithmes pris en charge et les algorithmes de chiffrement (“alg” et “enc” dans l’en-tête JOSE respectivement) peuvent être modifiés grâce aux options globales ‘jwt.decrypt_alg_list’ et ‘jwt.decrypt_enc_list’.
Le jeton JWE doit être fourni encodé en base64url, et la sortie sera fournie « brute ». En cas d’erreur lors de l’analyse du jeton, de la vérification de la signature ou du déchiffrement du contenu, une chaîne vide sera renvoyée.
Exemple :
jwt_decrypt_jwk(<jwk>)
Effectue une validation de signature d’un jeton web JSON selon le format JSON Web Encryption (voir RFC 7516), fourni en entrée, et retourne son contenu déchiffré grâce à la clé web JSON fournie (RFC7517). Le paramètre <jwk> doit être une JWK valide de type « oct », « EC » ou « RSA » (champ « kty » de la clé JSON) pouvant être fournie soit sous forme de chaîne, soit via une variable.
Les seuls jetons gérés pour l’instant sont ceux utilisant le format de sérialisation Compact (cinq chaînes encodées en base64-url séparées par des points).
Ce convertisseur peut être utilisé pour décoder un jeton ayant un algorithme de type symétrique (champ « alg » de l’en-tête JOSE) parmi les suivants : A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW, dir. Dans ce cas, on s’attend à ce que la JWK fournie soit de type « oct ».
Ce convertisseur gère également les jetons dont l’algorithme (champ “alg” de l’en-tête JOSE) appartient à la famille RSA (RSA-OAEP ou RSA-OAEP-256) lorsqu’une JWK ‘RSA’ est fournie, ou à la famille ECDH (ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW ou ECDH-ES+A256KW) lorsqu’une JWK ‘EC’ est fournie. L’algorithme RSA1_5 est implémenté, mais désactivé par défaut conformément à la section 3.2 de RFC 8725. Il peut être réactivé si nécessaire grâce à l’option globale ‘jwt.decrypt_alg_list’.
Veuillez noter que les algorithmes A128KW et A192KW ne sont pas disponibles sur AWS-LC, les algorithmes A128KW, A192KW, ECDH-ES+A128KW et ECDH-ES+A192KW ne fonctionneront donc pas.
Les algorithmes pris en charge et les algorithmes de chiffrement (“alg” et “enc” dans l’en-tête JOSE respectivement) peuvent être modifiés grâce aux options globales ‘jwt.decrypt_alg_list’ et ‘jwt.decrypt_enc_list’.
Le jeton JWE doit être fourni encodé en base64url, et la sortie sera fournie « brute ». En cas d’erreur lors de l’analyse du jeton, de la vérification de la signature ou du déchiffrement du contenu, une chaîne vide sera renvoyée.
En raison de la manière dont les guillemets, les virgules et les guillemets doubles sont traités dans la configuration, le contenu de la JWK doit être correctement échappé pour que ce convertisseur fonctionne correctement (voir section 2.2 pour plus d’informations).
Exemple :
jwt_decrypt_secret(<secret>)
Effectue une validation de signature d’un jeton web JSON conforme au format JSON Web Encryption (voir RFC 7516), reçoit en entrée et renvoie son contenu déchiffré grâce à la clé secrète encodée en base64 fournie. La clé secrète peut être fournie sous forme de chaîne ou via une variable. Seuls les jetons utilisant le format de sérialisation compacte sont actuellement pris en charge (cinq chaînes encodées en base64-url séparées par des points).
Ce convertisseur peut être utilisé pour les jetons ayant un algorithme (“alg” du champ d’en-tête JOSE) parmi les suivants : A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW, dir. Veuillez noter que les algorithmes A128KW et A192KW ne sont pas disponibles sur AWS-LC et que le déchiffrement ne fonctionnera pas.
Le jeton JWE doit être fourni encodé en base64url, et la sortie sera fournie « brute ». En cas d’erreur lors de l’analyse du jeton, de la vérification de la signature ou du déchiffrement du contenu, une chaîne vide sera renvoyée.
Exemple :
jwt_header_query([<json_path>[,<output_type>]])
Lorsqu’un jeton Web JSON (JWT) est fourni en entrée, renvoie soit la partie en-tête décodée du jeton (le premier segment encodé en base64-url du JWT) si aucun paramètre n’est fourni, soit effectue une requête json_query sur la partie en-tête décodée du jeton. Pour plus de détails sur les paramètres json_path et output_type pris en charge, reportez-vous au convertisseur “json_query”. Ce convertisseur peut être utilisé avec des jetons JWS ou JWE, à condition qu’ils soient au format de sérialisation compacte.
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
jwt_payload_query([<json_path>[,<output_type>]])
Lorsqu’un jeton JWT au format JWS lui est fourni en entrée, renvoie soit la partie charge utile décodée du jeton (la deuxième partie encodée en base64-url du JWT) si aucun paramètre n’est fourni, soit effectue une requête json_query sur la partie charge utile décodée du jeton. Pour plus de détails sur les paramètres json_path et output_type pris en charge, consulter le convertisseur “json_query”.
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
jwt_verify(<alg>,<key>)
Effectue une vérification de signature pour le jeton JWT (JSON Web Token) fourni en entrée en utilisant l’algorithme <alg> et le paramètre <key>. Pour l’instant, seuls les jetons JWS utilisant le format de sérialisation compacte peuvent être traités (trois chaînes encodées en base64-url séparées par des points). Ce convertisseur ne vérifie que la signature du jeton et n’effectue pas une validation complète du JWT telle que spécifiée dans la section 7.2 de de RFC7519. Nous ne garantissons pas que les contenus de l’en-tête et du chargement utile soient des JSON complets une fois décodés, par exemple, et aucune vérification n’est effectuée concernant leurs contenus respectifs.
<alg>peut être une chaîne de caractères ou un nom de variable (voir également « set-var ») qui contient le nom de l’algorithme utilisé pour la vérification.
Les algorithmes mentionnés dans la section 3.1 de RFC7518 sont gérés :
<key>peut être une chaîne de caractères ou un nom de variable (voir également « set-var ») qui contient un secret ou un chemin vers une clé publique.
Les secrets ne sont applicables que lors de l’utilisation d’algorithmes HMAC.
Les clés publiques doivent être au format PKCS#1 (pour les clés RSA, commençant par BEGIN RSA PUBLIC KEY) ou au format SPKI (Subject Public Key Info, commençant par BEGIN PUBLIC KEY). Les clés publiques doivent être disponibles pendant l’analyse de la configuration et ne peuvent pas être mises à jour ou chargées en temps réel. Voir le convertisseur “jwt_verify_cert” pour la validation des jetons JWT basée sur des certificats PEM complets.
Toutes les clés publiques pouvant être utilisées pour vérifier les JWT doivent être connues lors de l’initialisation afin d’être ajoutées à une mémoire tampon dédiée, afin d’éviter tout accès au disque pendant l’exécution.
Renvoie 1 en cas de vérification réussie, 0 en cas d’échec de vérification et une valeur strictement négative pour toute autre erreur. En raison de toutes ces valeurs de retour non nulles, le résultat de ce convertisseur ne doit jamais être converti en booléen. Consultez ci-dessous la liste complète des valeurs de retour possibles.
Les valeurs de retour possibles sont les suivantes :
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
Exemple :
jwt_verify_cert(<alg>,<cert>)
Effectue une vérification de signature pour le jeton JSON Web (JWT) fourni en entrée en utilisant l’algorithme <alg> et le paramètre <cert>. Pour l’instant, seuls les jetons JWS utilisant la sérialisation compacte peuvent être traités (trois chaînes encodées en base64-url séparées par des points). Ce convertisseur ne vérifie que la signature du jeton et ne réalise pas une validation complète du JWT telle qu’elle est spécifiée dans la section 7.2 de de RFC7519. Nous ne garantissons pas que les contenus de l’en-tête et du chargement utile soient des JSON complets une fois décodés, ni qu’aucune vérification ne soit effectuée sur leurs contenus respectifs.
<alg>peut être une chaîne ou un nom de variable (voir également « set-var ») qui contient le nom de l’algorithme utilisé pour la vérification. Contrairement au convertisseur “jwt_verify”, ce convertisseur n’attend qu’un certificat en deuxième paramètre, il ne doit donc pas être utilisé pour les jetons utilisant des algorithmes HMAC.
Les algorithmes mentionnés dans la section 3.1 de RFC7518 sont gérés (à l’exception des algorithmes HMAC) :
<key>peut être une chaîne de caractères ou un nom de variable (voir également « set-var ») qui contient le chemin d’un certificat.
Les certificats doivent être des certificats PEM standards (commençant par BEGIN CERTIFICATE). Leur chemin peut être passé directement au convertisseur ou référencé via une variable. Si une variable est utilisée, les certificats correspondants peuvent être déclarés dans un crt-store ou chargés dynamiquement via le socket stats. Lorsqu’un chemin est fourni directement, si le certificat correspondant n’a pas encore été chargé dans le magasin de certificats interne, il sera chargé pendant l’analyse de la configuration et doit donc déjà exister, sinon une erreur sera levée.
Seules les certificats explicitement définis comme utilisables pour la validation JWT peuvent être utilisés. Voir l’option « jwt » crt-store.
Il est possible de mettre à jour les certificats de manière dynamique et d’ajouter de nouveaux certificats à l’aide de la socket de statistiques. Voir également « set ssl cert » et « new ssl cert » dans le guide d’administration.
Renvoie 1 en cas de vérification réussie, 0 en cas d’échec de vérification et une valeur strictement négative pour toute autre erreur. En raison de toutes ces valeurs de retour non nulles, le résultat de ce convertisseur ne doit jamais être converti en booléen. Consultez ci-dessous la liste complète des valeurs de retour possibles.
Les valeurs de retour possibles sont les suivantes :
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
Exemple :
language(<value>[,<default>])
Retourne la valeur ayant le facteur q le plus élevé à partir d’une liste extraite de l’en-tête « accept-language » en utilisant “req.fhdr”. Les valeurs sans facteur q ont un facteur q de 1. Les valeurs ayant un facteur q de 0 sont supprimées. Seules les valeurs appartenant à la liste séparée par des points-virgules <values> sont prises en compte. La syntaxe de l’argument <value> est « lang[;lang[;lang[;…]]] ». Si aucune valeur ne correspond à la liste fournie et qu’une valeur par défaut est fournie, celle-ci est retournée. Notez que les noms de langue peuvent comporter une variante après un trait d’union (’-’). Si cette variante figure dans la liste, elle sera prise en compte, mais si elle n’est pas présente, seule la langue de base est vérifiée. La correspondance est sensible à la casse, et la chaîne de sortie est toujours l’une des chaînes fournies en argument. L’ordre des arguments est sans importance, seul l’ordre des valeurs dans la requête compte, la première valeur parmi celles ayant le même facteur q étant utilisée.
Exemple :
length
Obtient la longueur de la chaîne. Cette instruction ne peut être utilisée qu’après une fonction d’extraction d’échantillon de chaîne ou après un mot-clé de transformation retournant un type chaîne. Le résultat est de type entier.
lower
Convertit une chaîne d’échantillon en minuscules. Cette instruction ne peut être utilisée qu’après une fonction d’extraction d’échantillon de chaîne ou après un mot-clé de transformation retournant un type chaîne. Le résultat est de type chaîne.
ltime(<format>[,<offset>])
Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure locale, selon un format défini par la chaîne <format> en utilisant strftime(3). Le but est de permettre l’utilisation de tout format de date dans les journaux. Un décalage optionnel <offset> en secondes peut être appliqué à la date d’entrée (positif ou négatif). Consultez la page man strftime() pour connaître les formats pris en charge par votre système d’exploitation. Voir également le convertisseur utime.
Exemple :
ltrim(<chars>)
Ignore tout caractère de <chars> au début de la représentation sous forme de chaîne d’entrée.
map(<map_name>[,<default_value>])
Rechercher la valeur d’entrée à partir de <map_name> en utilisant la méthode de correspondance <match_type>, puis retourner la valeur associée convertie dans le type <output_type>. Si la valeur d’entrée ne peut pas être trouvée dans <map_name>, le convertisseur retourne <default_value>. Si <default_value> n’est pas défini, le convertisseur échoue et se comporte comme s’aucune valeur d’entrée n’avait pu être récupérée. Si <match_type> n’est pas défini, sa valeur par défaut est « str ». De même, si <output_type> n’est pas défini, sa valeur par défaut est « str ». Pour plus de commodité, le mot-clé « map » est un alias de “map_str” et permet de mapper une chaîne vers une autre chaîne. <map_name> doit suivre le format décrit en 2.7 concernant le format des noms pour les cartes et les listes de contrôle d’accès.
Il est important d’éviter les chevauchements entre les clés : les adresses IP et les chaînes sont stockées dans des arbres, donc la première correspondance la plus précise sera utilisée. Les autres clés sont stockées dans des listes, donc la première occurrence correspondante sera utilisée.
Le tableau suivant contient la liste de toutes les fonctions de mappage disponibles, triées par type d’entrée, type de correspondance et type de sortie.
La carte spéciale appelée “map_regm” attend une zone correspondante dans l’expression régulière et modifie la sortie en remplaçant la référence arrière (comme “\1”) par le texte correspondant à la correspondance.
Le type de sortie « key » signifie que la clé de l’entrée correspondante (telle qu’elle apparaît dans le fichier de carte) sera renvoyée sous forme de chaîne de caractères au lieu de la valeur. Notez que l’argument optionnel <default_value> n’est pas pris en charge lorsque le type de sortie « key » est utilisé.
Les fichiers référencés par <map_name> contiennent une paire clé+valeur par ligne. Les lignes commençant par ‘#’ sont ignorées, tout comme les lignes vides. Les tabulations et espaces en début de ligne sont supprimés. La clé correspond alors au premier « mot » (suite de caractères non-space/tabs), et la valeur est ce qui suit cette suite de caractères space/tab jusqu’à la fin de la ligne, en excluant les spaces/tabs. en fin de ligne.
Exemple :
mod(<value>)
Divise la valeur d’entrée de type entier signé par <value>, et retourne le reste sous forme d’entier signé. Si <value> est nul, alors zéro est retourné. <value> peut être une valeur numérique ou un nom de variable. Voir section 2.8
à propos des variables pour plus de détails.
mqtt_field_value(<packettype>,<fieldname_or_property_ID>)
Valeur renvoyée par <fieldname> trouvée dans le charge utile MQTT d’entrée de type <packettype>. <packettype>
peut être soit une chaîne (correspondance insensible à la casse), soit une valeur numérique correspondant au type de paquet dont les données doivent être extraites. Les chaînes et entiers pris en charge figurent ici :
https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718021
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901022
<fieldname> dépend de <packettype> et peut prendre l’une des valeurs suivantes. (Notez que la correspondance <fieldname> est insensible à la casse.) <property id> ne peut être trouvée que dans les flux MQTT v5.0.
Vérifiez ce tableau : https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901029
- CONNECT (ou 1) : drapeaux, nom_protocole, version_protocole, identifiant_client, sujet_annonce, charge_utile_annonce, nom_utilisateur, mot_de_passe, intervalle_heartbeat OU tout identifiant_de_propriété sous forme de valeur numérique (uniquement pour les paquets MQTT v5.0) :
Non pris en charge pour l’instant :
- CONNACK (ou 2) : drapeaux, version_protocole, code_raison OU tout identifiant de propriété sous forme de valeur numérique (uniquement pour les paquets MQTT v5.0) :
Non pris en charge pour l’instant :
En raison de la conception actuelle d’HAProxy, seul le premier message envoyé par le client et le serveur peut être analysé. Ce convertisseur ne peut donc extraire des données que des types de paquets CONNECT et CONNACK. CONNECT est le premier message envoyé par le client, et CONNACK est la première réponse envoyée par le serveur.
Exemple :
mqtt_is_valid
Vérifie que l’entrée binaire est un paquet MQTT valide. Retourne une valeur booléenne.
En raison de la conception actuelle d’HAProxy, seul le premier message envoyé par le client et le serveur peut être analysé. Ce convertisseur ne peut donc extraire des données que des types de paquets CONNECT et CONNACK. CONNECT est le premier message envoyé par le client, et CONNACK est la première réponse envoyée par le serveur.
Seuls MQTT 3.1, 3.1.1 et 5.0 sont pris en charge.
Exemple :
ms_ltime(<format>[,<offset>])
Cela fonctionne comme « ltime » mais prend en entrée une valeur en millisecondes. Il prend également en charge le spécificateur de conversion %N inspiré de date(1). Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure locale, selon un format défini par la chaîne <format> en utilisant strftime(3). L’objectif est de permettre l’utilisation de tout format de date dans les journaux. Une valeur optionnelle <offset> en millisecondes peut être appliquée à la date d’entrée (positive ou négative). Consultez la page de manuel de strftime() pour connaître les formats pris en charge par votre système d’exploitation.
Le spécificateur de conversion %N permet de sortir la partie nanosecondes de la date, la précision étant limitée car l’entrée est en millisecondes. (000000000..999000000). %N peut prendre un argument de largeur entre % et N. Il est utile pour afficher les millisecondes (%3N) ou les microsecondes (%6N). La largeur par défaut et maximale est 9 (%N = %9N).
Voir également le convertisseur utime pour UTC ainsi que les convertisseurs “ltime” et “us_ltime”.
Exemple :
ms_utime(<format>[,<offset>])
Cela fonctionne comme « utime » mais prend une entrée en millisecondes. Il prend également en charge le spécificateur de conversion %N inspiré de date(1). Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure UTC, selon un format défini par la chaîne <format> en utilisant strftime(3). Le but est de permettre l’utilisation de tout format de date dans les journaux. Un <offset> facultatif en millisecondes peut être appliqué à la date d’entrée (positif ou négatif). Consultez la page man strftime() pour connaître les formats pris en charge par votre système d’exploitation.
Le spécificateur de conversion %N permet de sortir la partie nanosecondes de la date, la précision étant limitée car l’entrée est en millisecondes. (000000000..999000000). %N peut prendre un argument de largeur entre % et N. Il est utile pour afficher les millisecondes (%3N) ou les microsecondes (%6N). La largeur par défaut et maximale est 9 (%N = %9N).
Voir également le convertisseur ltime pour les conversions locales ainsi que les convertisseurs utime et “us_utime”.
Exemple :
mul(<value>)
Multiplie la valeur d’entrée de type entier signé par <value>, et retourne le produit sous forme d’entier signé. En cas de dépassement, la plus grande valeur possible pour le signe est retournée afin que l’opération ne provoque pas de dépassement. <value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8 pour plus de détails sur les variables.
nbsrv
Prend une valeur d’entrée de type chaîne, l’interprète comme un nom de backend et renvoie le nombre de serveurs utilisables dans ce backend. Peut être utilisé là où l’on souhaite rechercher un backend à partir d’un nom dynamique, comme le résultat d’une recherche dans une table.
neg
Prend la valeur d’entrée de type entier signé, calcule sa valeur opposée, et renvoie le reste sous forme d’entier signé. La valeur 0 est l’identité. Cet opérateur est fourni pour les soustractions inversées : afin de soustraire l’entrée d’une constante, il suffit d’effectuer une opération « neg,add(valeur) ».
not
Renvoie une valeur booléenne FALSE si la valeur d’entrée de type entier signé est non nulle, sinon renvoie TRUE. Utilisé en conjonction avec and(), il peut servir à signaler true/false pour le test de bits sur les valeurs d’entrée (par exemple, vérifier l’absence d’un drapeau).
odd
Renvoie une valeur booléenne TRUE si la valeur d’entrée de type entier signé est impaire, sinon renvoie FALSE. Elle est fonctionnellement équivalente à « and(1),bool ».
or(<value>)
Effectue un opérateur “OU” bit à bit entre <value> et la valeur d’entrée de type entier signé, puis retourne le résultat sous forme d’entier signé. <value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8
sur les variables pour plus de détails.
param(<name>[,<delim>])
Cela extrait la première occurrence du paramètre <name> dans la chaîne d’entrée, où les paramètres sont délimités par <delim>, qui vaut par défaut “&”, et le nom et la valeur du paramètre sont séparés par un “=”. Si aucun “=” ni valeur n’est présent avant la fin du segment de paramètre, celui-ci est traité comme ayant une valeur vide.
Cela peut être utile pour extraire des paramètres à partir d’une chaîne de requête, ou éventuellement d’un corps x-www-form-urlencoded. En particulier, query,param(<name>) peut être utilisé comme alternative à urlp(<name>), qui n’utilise que le caractère “&” comme délimiteur, tandis que “urlp” utilise également “?” et “;”.
Notez que ce convertisseur ne traite pas spécialement les caractères encodés dans l’URL. Si vous souhaitez décoder la valeur, vous pouvez utiliser le convertisseur url_dec sur la sortie. Si le nom du paramètre en entrée peut contenir des caractères encodés, vous devriez probablement normaliser l’entrée avant d’appeler “param”. Cela peut être réalisé à l’aide de “http-request normalize-uri”, en particulier avec les options percent-decode-unreserved et percent-to-uppercase.
Exemple :
port_only
Convertit une chaîne contenant une valeur d’en-tête Host en entier en renvoyant son port. L’entrée doit respecter le format de la valeur d’en-tête Host (rfc9110#section-7.2). Elle prend en charge les entrées suivantes : hostname, hostname:80, 127.0.0.1, 127.0.0.1:80, [::1], [::1]:80.
Si aucun port n’est fourni dans l’entrée, la valeur renvoyée sera 0.
Voir également : le convertisseur “host_only” qui retournera l’hôte.
protobuf(<field_number>[,<field_type>])
Cela extrait le champ de message Protocol Buffers en mode brut à partir d’une représentation binaire d’entrée d’un message Protocol Buffers, avec <field_number> comme numéro de champ (notation pointée). Si <field_type> est absent, l’extraction se fait sous forme d’un échantillon entier ; sinon, elle se fait selon le type du champ (voir également “ungrpc” ci-dessous). La liste des types autorisés est la suivante : « int32 », « int64 », « uint32 », « uint64 », « sint32 », « sint64 », « bool », « enum » pour le type de filaire « varint » (type 0), « fixed64 », « sfixed64 », « double » pour le type de filaire 64 bits (type 1), « fixed32 », « sfixed32 », « float » pour le type de filaire 5. Notez que « string » est considéré comme un type délimité par longueur, donc il ne nécessite aucun argument <field_type> pour être extrait. Plus d’informations concernant les types de champs de message Protocol Buffers sont disponibles ici : https://developers.google.com/protocol-buffers/docs/encoding
regsub(<regex>,<subst>[,<flags>])
Applique une substitution basée sur une expression régulière à la chaîne d’entrée. Elle effectue la même opération que l’utilitaire bien connu « sed » avec « s/<regex>/<subst>/ ». Par défaut, elle remplace dans la chaîne d’entrée la première occurrence de la plus grande partie correspondant à l’expression régulière <regex> par la chaîne de substitution <subst>. Il est possible de remplacer toutes les occurrences au lieu de la première en ajoutant le drapeau « g » dans le troisième argument <flags>. Il est également possible de rendre l’expression régulière insensible à la casse en ajoutant le drapeau « i » dans <flags>. Étant donné que <flags> est une chaîne, elle est constituée de la concaténation de tous les drapeaux souhaités. Ainsi, si les deux drapeaux « i » et « g » sont requis, l’utilisation de « gi » ou de « ig » aura le même effet. La première utilisation de ce convertisseur consiste à remplacer certains caractères ou séquences de caractères par d’autres.
Il est fortement recommandé d’entourer la partie regex de guillemets protégés afin d’améliorer la clarté et d’éviter toute confusion entre une parenthèse fermante provenant de la regex et une parenthèse provenant de la fonction. Comme dans le shell Bourne, le premier niveau de guillemets est traité lors de la délimitation des groupes de mots sur la ligne, tandis qu’un second niveau est disponible pour les arguments. Il est recommandé d’utiliser des guillemets simples à l’extérieur, car ceux-ci ne tentent pas de résoudre les barres obliques inverses ni les signes dollar.
Exemples :
reverse
Inverse la chaîne d’entrée par octets.
Ce convertisseur est indépendant de l’encodage et inverse les octets, pas les caractères ; il n’est pas adapté à la réversibilité du texte humain encodé en UTF-8.
Cela peut transformer les recherches de suffixes sur la chaîne d’origine en recherches de préfixes sur la chaîne inversée, permettant ainsi d’utiliser des correspondances de préfixe indexées telles que “map_beg” sur de grandes cartes.
Exemples :
reverse_dom
Convertit une chaîne contenant un nom d’hôte de type FQDN en sa forme inversée par étiquettes. Un point final unique dans l’entrée est ignoré. Les étiquettes vides entraînent l’échec du convertisseur.
Ce convertisseur ne met pas en minuscules son entrée et ne supprime aucun port. Il est destiné à être combiné avec des convertisseurs existants tels que « lower » ou “host_only” lorsqu’il est nécessaire.
La politique des points de fin est intentionnellement laissée au chargeur. Cela permet aux appelants de décider s’ils souhaitent correspondre au sommet également ou uniquement aux sous-domaines.
La forme avec étiquettes inversées est utile pour les grandes cartes de domaine, car elle transforme les recherches de suffixes de domaine en recherches de préfixes, permettant ainsi d’utiliser des correspondances de préfixe indexées telles que “map_beg”.
Exemples :
rfc7239_field(<field>)
Extrait un seul field/parameter à partir d’une valeur d’en-tête conforme à la RFC 7239.
Champs pris en charge : - proto : soit « http » soit « https » - host : hôte conforme à HTTP - for : RFC7239 nœud - par : RFC7239 nœud
Plus d’informations ici :
Exemple :
rfc7239_is_valid
Renvoie true si la valeur d’en-tête d’entrée est conforme à la RFC 7239, false dans le cas contraire.
Exemple :
rfc7239_n2nn
Convertit le nœud RFC7239, fourni par les champs d’en-tête 7239 ‘for’ ou ‘by’, dans la forme finale correspondante de son nom de nœud : - adresse IPv4 - adresse IPv6 - ‘unknown’ - identifiant ‘_obfs’
Exemple :
rfc7239_n2np
Convertit le nœud RFC7239, fourni par les champs d’en-tête 7239 ‘for’ ou ‘by’, dans la forme finale correspondante de son port de nœud : - entier non signé - identifiant ‘_obfs’
Exemple :
rfc7239_nn
Convertit l’adresse ou la chaîne fournie en un nom de nœud conforme à RFC7239. Cette fonction peut être utilisée pour construire manuellement les champs d’en-tête ‘for’ ou ‘by’ du protocole 7239.
Lorsque l’entrée fournie est une chaîne, elle sera automatiquement préfixée par le caractère ‘_’ afin de représenter un identifiant masqué. La chaîne doit respecter l’ensemble de caractères RFC7239. Si la chaîne est vide, elle sera convertie en identifiant « unknown ».
Exemple :
Voir également : “rfc7239_np”
rfc7239_np
Convertit l’entrée entier non signé ou chaîne fournie en port de nœud conforme à RFC7239. Elle peut être utilisée pour construire manuellement les champs d’en-tête ‘for’ ou ‘by’ selon la spécification 7239.
Lorsque l’entrée fournie est une chaîne, elle sera automatiquement préfixée par le caractère ‘_’ afin de représenter un identifiant masqué. La chaîne doit respecter l’ensemble de caractères RFC7239 et ne peut pas être vide.
Exemple :
Voir également : “rfc7239_nn”
rtrim(<chars>)
Ignore tout caractère provenant de <chars> à la fin de la représentation sous forme de chaîne de l’échantillon d’entrée.
sdbm([<avalanche>])
Hache une entrée binaire en une quantité non signée sur 32 bits à l’aide de la fonction de hachage SDBM.
Optionnellement, il est possible d’appliquer une fonction de hachage à avalanche complète à la sortie si l’argument optionnel
<avalanche> vaut 1. Ce convertisseur utilise les mêmes fonctions que celles employées par les divers algorithmes de répartition de charge basés sur le hachage, il produira donc exactement les mêmes résultats. Il est principalement destiné au débogage, mais peut être utilisé comme entrée de table de persistance pour collecter des statistiques brutes. Il ne doit pas être utilisé à des fins de sécurité, car un hachage sur 32 bits est facile à casser. Voir également « crc32 », « djb2 », « wt6 », « crc32c » et la directive « hash-type ».
secure_memcmp(<var>)
Compare le contenu de <var> avec la valeur d’entrée. Les deux valeurs sont traitées comme des chaînes binaires.
Renvoie une valeur booléenne indiquant si les deux chaînes binaires correspondent.
Si les deux chaînes binaires ont la même longueur, la comparaison sera effectuée en temps constant.
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
Exemple :
set-var(<var>[,<cond>...])
Définit une variable avec le contenu d’entrée et renvoie le contenu en sortie tel quel si toutes les conditions spécifiées sont remplies (voir ci-dessous la liste des conditions possibles). La variable conserve sa valeur et le type d’entrée associé. Voir section 2.8 sur les variables pour plus de détails.
Vous pouvez passer au plus quatre conditions au convertisseur parmi les conditions suivantes :
- “siexiste”/“sinaexistent” :
- “ifempty”/“ifnotempty” :
- « ifset » / « ifnotset » :
- “ifgt”/“iflt” :
sha1
Convertit un échantillon d’entrée binaire en somme de contrôle SHA-1. Le résultat est un échantillon binaire de 20 octets.
sha2([<bits>])
Convertit un échantillon d’entrée binaire en un hachage de la famille SHA-2. Le résultat est un échantillon binaire de <bits>/8 octets.
Les valeurs autorisées pour <bits> sont 224, 256, 384, 512, chacune correspondant à SHA-<bits>. La valeur par défaut est 256.
Veuillez noter que ce convertisseur n’est disponible que si HAProxy a été compilé avec USE_OPENSSL.
srv_is_up
Prend une valeur d’entrée de type chaîne, soit un nom de serveur, soit au format <backend>/<server>, et renvoie true lorsque le serveur désigné est actuellement actif. Peut être utilisé là où l’on souhaite vérifier l’état d’un serveur à partir d’un nom dynamique, comme une valeur de cookie (par exemple req.cook(SRVID),srv_is_up), puis prendre une décision pour rediriger une requête ailleurs. Avant de l’utiliser, veuillez noter qu’utiliser ce convertisseur sur des données non contrôlées pourrait permettre à un observateur externe de consulter l’état de n’importe quel serveur dans toute la configuration, ce qui pourrait ne pas être acceptable dans certains environnements.
srv_queue
Prend une valeur d’entrée de type chaîne, soit un nom de serveur, soit au format <backend>/<server>, et retourne le nombre de flux en attente sur ce serveur. Peut être utilisé là où l’on souhaite rechercher le nombre de flux en attente à partir d’un nom dynamique, comme une valeur de cookie (par exemple req.cook(SRVID),srv_queue), puis prendre une décision pour rompre la persistance ou rediriger la requête ailleurs. Avant de l’utiliser, veuillez noter qu’utiliser ce convertisseur sur des données non contrôlées pourrait permettre à un observateur externe de consulter l’état de n’importe quel serveur dans toute la configuration, ce qui pourrait ne pas être acceptable dans certains environnements.
strcmp(<var>)
Compare le contenu de <var> avec la valeur d’entrée de type chaîne. Retourne le résultat sous forme d’entier signé compatible avec strcmp(3) : 0 si les deux chaînes sont identiques. Une valeur inférieure à 0 si la chaîne de gauche est lexicographiquement plus petite que la chaîne de droite ou si la chaîne de gauche est plus courte. Une valeur supérieure à 0 dans les autres cas (chaîne de droite plus grande que la chaîne de gauche ou la chaîne de droite est plus courte).
Voir également le convertisseur secure_memcmp si vous devez comparer deux chaînes binaires en temps constant.
Exemple :
sub(<value>)
Soustrait <value> à la valeur d’entrée de type entier signé, et retourne le résultat sous forme d’entier signé. Note : pour soustraire la valeur d’entrée d’une constante, il suffit d’effectuer une opération « neg,add(valeur) ».
<value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8
sur les variables pour plus de détails.
table_bytes_in_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le débit moyen en octets client-serveur associé à l’échantillon d’entrée dans la table désignée, mesuré en quantité d’octets sur la période configurée dans la table. Voir également le mot-clé d’extraction d’échantillon sc_bytes_in_rate.
table_bytes_out_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne le débit moyen en octets émis par le serveur vers le client associé à l’échantillon d’entrée dans la table désignée, mesuré en quantité d’octets sur la période configurée dans la table. Voir également le mot-clé d’extraction d’échantillon sc_bytes_out_rate.
table_clr_gpc(<idx>[,<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Efface le compteur général à l’index <idx> du tableau gpc et retourne sa valeur précédente. <idx> est un entier compris entre 0 et 99. Si l’entrée n’est pas trouvée, une entrée est créée et 0 est retourné. Ce convertisseur s’applique uniquement au type de données ‘gpc’ (et non aux types hérités ‘gpc0’ ni ‘gpc1’). Voir également le mot-clé d’extraction d’échantillon sc_clr_gpc.
table_clr_gpc0([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Efface le premier compteur général ‘0’ et retourne sa valeur précédente. Si l’entrée n’est pas trouvée, une entrée est créée et 0 est retourné. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée :
Exemple :
Voir également le mot-clé d’extraction d’échantillon sc_clr_gpc0.
table_clr_gpc1([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Efface le premier compteur général ‘1’ et retourne sa valeur précédente. Si l’entrée n’est pas trouvée, une entrée est créée et 0 est retourné. Cela est généralement utilisé comme deuxième mot-clé ACL dans une expression afin de marquer une connexion lorsque la première condition ACL a été vérifiée. Voir également le mot-clé d’extraction d’échantillon sc_clr_gpc1.
table_conn_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé de connexions entrantes associées à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_conn_cnt.
table_conn_cur([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre actuel de connexions simultanées suivies associées à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_conn_cur.
table_conn_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le débit moyen de connexions entrantes associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_conn_rate.
table_expire([<table>[,<default_value>]])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, le convertisseur échoue, sauf si <default_value> est défini : cela fait échouer le convertisseur et retourne <default_value>. Si la clé est trouvée, le convertisseur retourne le délai d’expiration associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon table_idle.
table_glitch_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé d’instabilités de connexion frontales associées à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_glitch_cnt et fc_glitches pour la valeur mesurée sur la connexion frontale actuelle.
table_glitch_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le taux moyen de perturbations de connexion frontale associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_glitch_rate.
table_gpc(<idx>[,<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie la valeur actuelle du compteur général à l’index <idx> du tableau associé à l’échantillon d’entrée dans la table de persistance désignée <table>. <idx> est un entier compris entre 0 et 99. Si aucun compteur général n’est stocké à cet index, la valeur entière zéro est également renvoyée. Cela ne s’applique qu’au type de données ‘gpc’ (et non aux types de données hérités ‘gpc0’ ni ‘gpc1’). Voir également le mot-clé d’extraction d’échantillon sc_get_gpc.
table_gpc0([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie la valeur actuelle du premier compteur généraliste associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_get_gpc0.
table_gpc0_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne la fréquence à laquelle le compteur gpc0 a été incrémenté durant la période configurée dans la table, associée à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_get_gpc0_rate.
table_gpc1([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne la valeur actuelle du deuxième compteur généraliste associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_get_gpc1.
table_gpc1_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne la fréquence à laquelle le compteur gpc1 a été incrémenté durant la période configurée dans la table, associée à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_get_gpc1_rate.
table_gpc_rate(<idx>[,<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie la fréquence à laquelle le compteur global de but (GPC) à l’index <idx> du tableau (associé à l’échantillon d’entrée dans la table de persistance désignée <table>) a été incrémenté durant la période configurée. <idx> est un entier compris entre 0 et 99. Si aucune valeur gpc_rate n’est stockée à cet index, la valeur entière zéro est également renvoyée. Cela ne s’applique qu’au type de données ‘gpc_rate’ (et non aux types de données hérités ‘gpc0_rate’ ni ‘gpc1_rate’). Voir également le mot-clé d’extraction d’échantillon sc_gpc_rate.
table_gpt(<idx>[,<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie la valeur actuelle de l’étiquette générale au niveau <idx> du tableau associé à l’échantillon d’entrée dans la table de persistance désignée <table>. <idx> est un entier compris entre 0 et 99. Si aucune étiquette générale n’est stockée à cet index, la valeur entière zéro est également renvoyée. Cela ne s’applique qu’au type de données ‘gpt’ (et non au type de données hérité ‘gpt0’). Voir également le mot-clé d’extraction sc_get_gpt.
table_gpt0([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie la valeur actuelle de la première étiquette générale associée à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_get_gpt0.
table_http_err_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé d’erreurs HTTP associé à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_http_err_cnt.
table_http_err_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, retourne le taux moyen d’erreurs HTTP associé à l’échantillon d’entrée dans la table désignée, exprimé en nombre d’erreurs sur la période configurée dans la table. Voir également le mot-clé d’extraction d’échantillon sc_http_err_rate.
table_http_fail_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé d’échecs HTTP associés à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_http_fail_cnt.
table_http_fail_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, renvoie le taux moyen d’échecs HTTP associé à l’échantillon d’entrée dans la table désignée, exprimé comme nombre d’échecs sur la période configurée dans la table. Voir également le mot-clé d’extraction sc_http_fail_rate.
table_http_req_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé de requêtes HTTP associées à l’échantillon d’entrée dans la table désignée. Voir également le mot-clé d’extraction d’échantillon sc_http_req_cnt.
table_http_req_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, la fréquence moyenne des requêtes HTTP associées à l’échantillon d’entrée dans la table désignée, mesurée en nombre de requêtes sur la période configurée dans la table. Voir également le mot-clé d’extraction sc_http_req_rate.
table_idle([<table>[,<default_value>]])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, le convertisseur échoue, sauf si <default_value> est défini : cela fait échouer le convertisseur et retourne <default_value>. Si la clé est trouvée, le convertisseur retourne le temps pendant lequel l’entrée associée à l’échantillon d’entrée dans la table désignée est restée inactif depuis la dernière mise à jour. Voir également le mot-clé d’extrais d’échantillon table_expire.
table_inc_gpc(<idx>[,<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Incrémente le compteur généralisé à l’index <idx> du tableau et retourne sa nouvelle valeur. <idx> est un entier compris entre 0 et 99. Si l’entrée n’est pas trouvée, une entrée est créée et la valeur 1 est retournée. Ce convertisseur s’applique uniquement au type de données ‘gpc’ (et non aux types hérités ‘gpc0’ ni ‘gpc1’). Voir également sc_inc_gpc.
table_inc_gpc0([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Incrémente le compteur généralisé « 0 » et retourne sa nouvelle valeur. Si l’entrée n’est pas trouvée, une entrée est créée et la valeur 1 est retournée. Voir également sc0/sc2/sc2_inc_gpc0.. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée :
Exemple :
table_inc_gpc1([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Incrémente le compteur généralisé « 1 » et retourne sa nouvelle valeur. Si l’entrée n’est pas trouvée, une entrée est créée et la valeur 1 est retournée. Voir également sc0/sc2/sc2_inc_gpc1.. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée.
table_kbytes_in([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne le nombre cumulé de données client-serveur associées à l’échantillon d’entrée dans la table désignée, exprimé en kilo-octets. Le test est actuellement effectué sur des entiers 32 bits, ce qui limite les valeurs à 4 téraoctets. Voir également le mot-clé d’extraction d’échantillon sc_kbytes_in.
table_kbytes_out([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur retourne le nombre cumulé de données serveur-vers-client associées à l’échantillon d’entrée dans la table désignée, exprimé en kilo-octets. Le test est actuellement effectué sur des entiers 32 bits, ce qui limite les valeurs à 4 téraoctets. Voir également le mot-clé d’extraction d’échantillon sc_kbytes_out.
table_server_id([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie l’identifiant de serveur associé à l’échantillon d’entrée dans la table désignée. Un identifiant de serveur est associé à un échantillon par une règle « stick » lorsque la connexion à un serveur réussit. Un identifiant de serveur zéro signifie qu’aucun serveur n’est associé à cette clé.
table_sess_cnt([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre cumulé de sessions entrantes associées à l’échantillon d’entrée dans la table désignée. Notez qu’une session désigne ici une connexion entrante acceptée par les règles “tcp-request connection”. Voir également le mot-clé d’extraction d’échantillon sc_sess_cnt.
table_sess_rate([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le taux moyen de sessions entrantes associé à l’échantillon d’entrée dans la table désignée. Notez qu’une session fait référence à une connexion entrante acceptée par les règles “tcp-request connection”. Voir également le mot-clé d’extraction d’échantillon sc_sess_rate.
table_trackers([<table>])
Utilise l’échantillon d’entrée pour effectuer une recherche dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Si la clé n’est pas trouvée dans la table, la valeur entière zéro est renvoyée. Sinon, le convertisseur renvoie le nombre actuel de connexions simultanées suivant la même clé que l’échantillon d’entrée dans la table désignée. Contrairement à table_conn_cur, il ne repose pas sur des informations stockées, mais sur le compteur de référence de la table (la valeur « use » renvoyée par la commande « show table » en ligne de commande). Cette approche peut parfois être plus adaptée au suivi de layer7. Elle peut être utilisée pour indiquer à un serveur combien de connexions simultanées proviennent d’une adresse donnée, par exemple. Voir également le mot-clé d’extraction d’échantillon sc_trackers.
tcp.dst
Cela est utilisé avec un échantillon d’entrée représentant un en-tête binaire TCP, tel que renvoyé par “ip.data”. Il renvoie un entier représentant le port de destination présent dans l’en-tête TCP. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.flags
Cela est utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que renvoyé par “ip.data”. Il renvoie un entier représentant les drapeaux TCP issus de cet en-tête TCP. Les 8 drapeaux allant de FIN à CWR sont tous récupérés. Chaque drapeau peut être testé à l’aide du convertisseur “and()”. Voir RFC9293 pour la valeur de chaque drapeau. Voir également “fc_saved_syn”, “tcp-ss”, et “ip.data”.
tcp.options.mss
Cela est utilisé avec un échantillon d’entrée représentant un en-tête binaire TCP, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « MSS », et, s’il la trouve, renvoie une valeur entière correspondant à la valeur annoncée dans cette option, sinon zéro. Le MSS est la taille maximale du segment et indique la taille maximale du segment que le pair peut recevoir, en octets. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.options.sack
Cela est utilisé avec un échantillon d’entrée représentant un en-tête binaire TCP, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « Sack-Permitted », et, s’il la trouve, renvoie 1, sinon zéro. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.options.tsopt
Cela est utilisé avec un échantillon d’entrée représentant un en-tête binaire TCP, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « Timestamp », et, s’il la trouve, renvoie 1, sinon 0. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.options.tsval
Utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « Timestamp », et, s’il la trouve, renvoie la valeur d’horodatage émise par le pair ; sinon, il ne renvoie rien. Notez que les horodatages sont des valeurs non signées sur 32 bits sans unité particulière, choisie par le pair, et qu’ils sont censés être indépendants entre différentes connexions. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.options.wscale
Cela est utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « Window Scale », et, si trouvée, renvoie la valeur d’échelle de fenêtre émise par le pair, sinon zéro. Notez que les valeurs ne sont pas censées dépasser 14, bien que aucune limitation technique ne l’empêche d’être envoyées. Pour détecter si l’option d’échelle de fenêtre a été utilisée, veuillez utiliser “tcp.options.wsopt”. Voir également « tcp-ss », “fc_saved_syn”, “ip.data”, et “tcp.options.wsopt”.
tcp.options.wsopt
Cela est utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que renvoyé par “ip.data”. Il recherche une option TCP de type « Window Scale », et, s’il la trouve, renvoie 1, sinon 0. Voir également “fc_saved_syn”, « tcp-ss », “ip.data” “tcp.options.wscale”.
tcp.options_list
Utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel qu’il est retourné par “ip.data”. Il construit une séquence binaire contenant tous les types d’options TCP dans le même ordre qu’ils apparaissent dans l’en-tête TCP. Il peut produire entre 0 et 60 octets (dans le cas le plus défavorable). La marque de fin d’options n’est pas émise. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.seq
Cela est utilisé avec un échantillon d’entrée représentant un en-tête binaire TCP, tel que renvoyé par “ip.data”. Il renvoie un entier représentant le numéro de séquence utilisé par le pair dans l’en-tête TCP. Les numéros de séquence sont des valeurs non signées sur 32 bits. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.src
Cela est utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que renvoyé par “ip.data”. Il renvoie un entier représentant le port source présent dans l’en-tête TCP. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
tcp.win
Utilisé avec un échantillon d’entrée représentant un en-tête TCP binaire, tel que retourné par “ip.data”. Renvoie un entier représentant la taille de fenêtre annoncée par le pair dans l’en-tête TCP. La valeur est fournie telle quelle, sous forme de quantité non signée sur 16 bits, sans appliquer le facteur de mise à l’échelle de la fenêtre. Voir également “fc_saved_syn”, « tcp-ss », et “ip.data”.
ub64dec
Ce convertisseur est la variante base64url du convertisseur b64dec. Le codage base64url est la variante « alphabet sécurisé pour les URL et les noms de fichiers » du codage base64. Il est également utilisé dans la norme JWT (JSON Web Token).
Exemple :
ub64enc
Ce convertisseur est la variante base64url du convertisseur base64.
ungrpc(<field_number>[,<field_type>])
Cela extrait le champ de message Protocol Buffers en mode brut à partir d’une représentation binaire d’entrée d’un message gRPC, avec <field_number> comme numéro de champ (notation pointée) si <field_type> est absent, ou comme échantillon entier si ce champ est présent. La liste des types autorisés est la suivante : « int32 », « int64 », « uint32 », « uint64 », « sint32 », « sint64 », « bool », « enum » pour le type de filaire « varint » (type 0), « fixed64 », « sfixed64 », « double » pour le type de filaire 64 bits (type 1), « fixed32 », « sfixed32 », « float » pour le type de filaire 5. Notez que « string » est considéré comme un type délimité par longueur, aussi n’exige-t-il aucun argument <field_type> pour être extrait. Plus d’informations sont disponibles ici concernant les types de champs de message Protocol Buffers : https://developers.google.com/protocol-buffers/docs/encoding
Exemple :
Supposons qu’une requête corporelle contienne une valeur d’objet « Rectangle » (deux messages Protocol Buffers PPoint), les quatre champs des messages Protocol Buffers pourraient être extraits à l’aide de ces directives « ungrpc » :
Nous pourrions également extraire le champ intermédiaire 48.59 sous forme d’échantillon binaire comme suit :
Comme un message gRPC est toujours constitué d’un en-tête gRPC suivi de messages protocol buffers, dans l’exemple précédent, la « latitude » du premier PPoint « lo » aurait pu être extraite à l’aide de ces directives équivalentes :
Notez que la première conversion doit être « ungrpc », les suivantes doivent être « protobuf » et seule la dernière peut éventuellement avoir un deuxième argument pour interpréter l’échantillon binaire précédent.
unset-var(<var>)
Supprime une variable si le contenu d’entrée est défini. Le nom de la variable commence par une indication relative à sa portée. Voir section 2.8 sur les variables pour plus de détails.
upper
Convertit une chaîne d’échantillon en majuscules. Cette instruction ne peut être utilisée qu’après une fonction d’extraction d’échantillon de chaîne ou après un mot-clé de transformation retournant un type chaîne. Le résultat est de type chaîne.
url_dec([<in_form>])
Prend une chaîne encodée URL en entrée et renvoie la version décodée en sortie. L’entrée et la sortie sont de type chaîne. Si l’argument <in_form> est défini à une valeur entière non nulle, la chaîne d’entrée est supposée faire partie d’une chaîne de formulaire ou de requête, et le caractère ‘+’ sera remplacé par un espace (’ ‘). Sinon, cela n’aura lieu qu’après un point d’interrogation indiquant une chaîne de requête (’?’).
url_enc([<enc_type>])
Prend une chaîne fournie en entrée et renvoie la version encodée en sortie. L’entrée et la sortie sont de type chaîne. Par défaut, le type d’encodage est destiné au type query. Aucun autre type n’est actuellement pris en charge, mais l’argument facultatif est présent pour permettre des évolutions futures.
us_ltime(<format>[,<offset>])
Cela fonctionne comme « ltime » mais prend en entrée une valeur en microsecondes. Il prend également en charge le spécificateur de conversion %N inspiré de date(1). Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure locale, selon un format défini par la chaîne <format> en utilisant strftime(3). L’objectif est de permettre l’utilisation de tout format de date dans les journaux. Un <offset> facultatif en microsecondes peut être appliqué à la date d’entrée (positif ou négatif). Consultez la page man strftime() pour connaître les formats pris en charge par votre système d’exploitation.
Le spécificateur de conversion %N permet de sortir la partie nanosecondes de la date, la précision étant limitée car l’entrée est en microsecondes. (000000000..999999000). %N peut prendre un argument de largeur entre % et N. Il est utile pour afficher des millisecondes (%3N) ou des microsecondes (%6N). La largeur par défaut et maximale est 9 (%N = %9N).
Voir également le convertisseur « utime » pour UTC, ainsi que les convertisseurs « ltime » et “ms_ltime”.
Exemple :
us_utime(<format>[,<offset>])
Cela fonctionne comme « utime » mais prend une entrée en microsecondes. Il prend également en charge le spécificateur de conversion %N inspiré de date(1). Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure UTC selon un format défini par la chaîne <format> en utilisant strftime(3). Le but est de permettre l’utilisation de tout format de date dans les journaux. Un <offset> facultatif en microsecondes peut être appliqué à la date d’entrée (positif ou négatif). Consultez la page de manuel de strftime() pour connaître les formats pris en charge par votre système d’exploitation.
Le spécificateur de conversion %N permet de sortir la partie nanosecondes de la date, la précision étant limitée car l’entrée est en microsecondes. (000000000..999999000). %N peut prendre un argument de largeur entre % et N. Il est utile pour afficher des millisecondes (%3N) ou des microsecondes (%6N). La largeur par défaut et maximale est 9 (%N = %9N).
Voir également le convertisseur « ltime » pour les heures locales ainsi que les convertisseurs « utime » et “ms_utime”.
Exemple :
utime(<format>[,<offset>])
Convertit un entier supposé contenir une date depuis l’époque en une chaîne représentant cette date en heure UTC, selon un format défini par la chaîne <format> en utilisant strftime(3). Le but est de permettre l’utilisation de tout format de date dans les journaux. Un décalage optionnel <offset> en secondes peut être appliqué à la date d’entrée (positif ou négatif). Consultez la page de manuel strftime() pour connaître les formats pris en charge par votre système d’exploitation. Voir également le convertisseur “ltime”, ainsi que “ms_utime” et “us_utime”.
Exemple :
when(<condition>[,<args>...])
Évalue la condition et, si elle est vraie, transmet l’échantillon d’entrée tel quel en sortie ; sinon, ne retourne rien. Cette fonction est spécifiquement conçue pour produire des données rarement nécessaires, qui ne doivent être émises que sous certaines conditions, telles que des informations de débogage lorsqu’une erreur est détectée.
La condition est constituée d’un mot-clé parmi la liste suivante, éventuellement précédé d’un point d’exclamation (’!’) pour le nier, et éventuellement suivi de certains arguments propres à cette condition :
- "error" retourne true lorsqu'une erreur est survenue pendant le traitement de la requête ou du flux. Elle utilise les mêmes règles que "dontlog-normal" (par exemple, une réexpédition réussie est considérée comme une erreur).
- "forwarded" retourne true lorsque la requête a été transférée vers un backend
- "normal" renvoie true lorsque aucune erreur ne s'est produite (ce qui équivaut à "!error").
- "processed" retourne true lorsque la requête a été soit transférée vers un backend, soit traitée par un applet.
- "stopping" renvoie true si le processus est actuellement en cours d'arrêt au moment où la règle est évaluée
- "toapplet" retourne true lorsque la requête a été traitée par un applet.
- "acl" renvoie true lorsque l'ACL désignée par l'argument suivant évalue à true. Notez que l'ACL est évaluée inline par le convertisseur, de sorte que ce vers quoi elle fait référence doit être valide dans ce contexte. Un cas d'utilisation particulier consiste à déterminer si le temps total de transfert est trop long avant de décider de journaliser les détails des transferts anormalement longs.
Notez que le contenu est évalué dans tous les cas, donc cette action ne permet pas d’éviter la génération de ces informations. Elle vise uniquement à empêcher leur production.
Par exemple, ajouter des informations de débogage du flux backend dans les journaux uniquement lorsqu’une erreur est survenue pendant le traitement, ou journaliser des informations supplémentaires lors de l’arrêt, etc.
Exemple :
Exemple # log “dbg={-}” en cas de traitement rapide, ou “dbg={… informations de débogage …}” en cas de transferts lents acl slow_xfer res.timer.data ge 10000 # plus de 10 s est considéré comme lent log-format “$HAPROXY_HTTP_LOG_FMT \ fsdbg={%[fs.debug_str,when(acl,slow_xfer)]} \ bsdbg={%[bs.debug_str,when(acl,slow_xfer)]}”
Exemple # émettre uniquement le backend src/port lorsqu’une connexion réelle a été établie : log-format “$HAPROXY_HTTP_LOG_FMT \ src=[%[bc_src,when(forwarded)]:%[bc_src_port,when(forwarded)]]”
Étant donné qu’il interrompt l’évaluation de l’expression lorsqu’elle est fausse, il est également possible de l’utiliser pour empêcher l’appel d’un convertisseur ultérieur. Cela peut par exemple servir à appeler le convertisseur debug() uniquement en cas d’erreur, ou à journaliser un élément uniquement lorsqu’il est absolument nécessaire.
Exemple :
Voir aussi : convertisseur de débogage
word(<index>,<delimiters>[,<count>])
Extrait le n-ième mot en comptant depuis le début (indice positif) ou depuis la fin (indice négatif) d’une chaîne d’entrée, en tenant compte des délimiteurs spécifiés. Les indices commencent à 1 ou -1. Les délimiteurs sont une liste de caractères formatée sous forme de chaîne. Les mots vides sont ignorés. Cela signifie que les délimiteurs situés au début ou à la fin de la chaîne d’entrée sont ignorés, et que des délimiteurs consécutifs à l’intérieur de la chaîne sont traités comme un seul délimiteur. Vous pouvez éventuellement préciser le nombre <count> de mots à extraire (par défaut : 1). Une valeur de 0 indique l’extraction de tous les mots restants.
Exemple :
wt6([<avalanche>])
Hache une entrée binaire en une quantité non signée sur 32 bits en utilisant la fonction de hachage WT6.
Optionnellement, il est possible d’appliquer une fonction de hachage à avalanche complète à la sortie si l’argument facultatif <avalanche> vaut 1. Ce convertisseur utilise les mêmes fonctions que celles employées par les divers algorithmes de répartition de charge basés sur le hachage, il produira donc exactement les mêmes résultats. Il est principalement destiné au débogage, mais peut être utilisé comme entrée de table de persistance pour collecter des statistiques brutes. Il ne doit pas être utilisé à des fins de sécurité, car un hachage sur 32 bits est facile à casser. Voir également « crc32 », « djb2 », « sdbm », « crc32c » et la directive « hash-type ».
x509_v_err_str
Convertit une valeur numérique en son nom de constante correspondant X509_V_ERR. Utile dans les listes de contrôle d’accès (ACL) afin d’obtenir une configuration fonctionnelle avec plusieurs versions d’OpenSSL, car certains codes peuvent varier selon la version utilisée.
Lorsque le nom de la constante correspondante n’a pas été trouvé, affiche la valeur numérique sous forme de chaîne.
La liste des constantes fournie par OpenSSL est disponible à l’adresse https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html#ERROR-CODES Prenez garde à lire la page correspondant à la bonne version d’OpenSSL.
Exemple :
xor(<value>)
Effectue un opérateur “XOR” (OU exclusif) au niveau des bits entre <value> et la valeur d’entrée de type entier signé, et retourne le résultat sous forme d’entier signé. <value> peut être une valeur numérique ou un nom de variable. Voir la section 2.8
sur les variables pour plus de détails.
xxh3([<seed>])
Hache une entrée binaire en une quantité signée sur 64 bits en utilisant la variante 64 bits de la fonction de hachage XXhash, XXH3. Ce hachage prend en charge une graine dont la valeur par défaut est zéro, mais une valeur différente peut être passée en tant qu’argument <seed>. Ce hachage est connu pour être très performant et très efficace, aussi peut-il être utilisé pour hacher des URL and/or des paramètres d’URL afin d’en faire des clés de table de persistance, permettant de collecter des statistiques avec un taux de collision faible, bien qu’il faille exercer une vigilance car l’algorithme n’est pas considéré comme sécurisé au sens cryptographique.
xxh32([<seed>])
Hache une entrée binaire en une quantité non signée sur 32 bits en utilisant la variante 32 bits de la fonction de hachage XXHash. Ce hachage prend en charge une graine dont la valeur par défaut est zéro, mais une valeur différente peut être passée en tant qu’argument <seed>. Ce hachage est connu pour être très efficace et très rapide, aussi peut-il être utilisé pour hacher des URLs and/or des paramètres d’URL afin d’en faire des clés de table de persistance, permettant de collecter des statistiques avec un taux de collision faible, tout en tenant compte du fait que l’algorithme n’est pas considéré comme sécurisé au niveau cryptographique.
xxh64([<seed>])
Hache une entrée binaire en une quantité signée sur 64 bits en utilisant la variante 64 bits de la fonction de hachage XXHash. Ce hachage prend en charge une graine dont la valeur par défaut est zéro, mais une valeur différente peut être passée en tant qu’argument <seed>. Ce hachage est connu pour être très performant et très rapide, aussi peut-il être utilisé pour hacher des URLs and/or des paramètres d’URL afin d’en faire des clés de table de persistance afin de collecter des statistiques avec un taux de collision faible, bien qu’il faille faire preuve de prudence car cet algorithme n’est pas considéré comme sécurisé de manière cryptographique.
7.3.2. Récupération d’échantillons à partir des états internes
Un premier ensemble de méthodes d’extraction d’échantillon s’applique à des informations internes qui ne concernent même pas les clients. Ces méthodes sont parfois utilisées avec les directives « monitor fail » pour signaler un état interne aux observateurs externes. Les méthodes d’extraction d’échantillon décrites dans cette section sont utilisables n’importe où.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
acl([!]<name>[,...]): boolean
Renvoie true si l’évaluation de toutes les ACLs nommées est true, sinon renvoie false. Jusqu’à 12 ACLs peuvent être fournies, chacune séparée par une virgule. Chaque ACL nommée peut être précédée d’un “!” pour inverser le résultat. Si une évaluation produit une erreur, l’échantillon renvoie également une erreur. Notez qu’HAProxy ne réalise aucune vérification de validation sur les ACLs référencées, par exemple si une ACL utilisant un échantillon de requête HTTP est utilisée dans un contexte de réponse. Ce comportement pourrait évoluer à l’avenir.
act_conn : entier Renvoie le nombre total de connexions actives concurrentes sur le processus.
always_false : boolean Toujours retourne la valeur booléenne « false ». Peut être utilisé avec les ACLs comme remplacement temporaire d’une autre lorsque l’ajustement de la configuration est en cours.
always_true : booléen Retourne toujours la valeur booléenne « true ». Peut être utilisé avec les ACLs comme remplacement temporaire d’une autre lorsque l’ajustement de la configuration est en cours.
avg_queue([<backend>]): integer
Renvoie le nombre total de connexions en file d’attente pour le backend spécifié, divisé par le nombre de serveurs actifs. Le backend actuel est utilisé si aucun backend n’est précisé. Cette mesure est très similaire à « queue », sauf qu’elle tient compte de la taille de la ferme afin d’obtenir une estimation plus précise du temps nécessaire au traitement d’une nouvelle connexion. Son usage principal consiste à utiliser une ACL pour renvoyer une page d’excuse aux nouveaux utilisateurs lorsque l’on est certain qu’ils recevront un service dégradé, ou à transmettre cette valeur aux serveurs backend via un en-tête afin qu’ils décident de fonctionner en mode dégradé ou de désactiver certaines fonctions afin d’accélérer le traitement. Notez qu’en cas d’absence de serveur actif, le double du nombre de connexions en file d’attente est considéré comme la valeur mesurée. Il s’agit d’une estimation raisonnable, puisque l’on s’attend à ce qu’un serveur revienne bientôt, mais il est préférable de diriger le trafic nouveau vers un autre backend si celui-ci se trouve dans un meilleur état. Voir également les échantillons d’extraction « queue », “be_conn”, et “be_sess_rate”.
be_conn([<backend>]): integer
S’applique au nombre de connexions établies actuellement sur le backend, pouvant inclure la connexion en cours d’évaluation. Si aucun nom de backend n’est précisé, celui en cours est utilisé. Il est également possible de vérifier un autre backend. Cette option peut être utilisée pour utiliser une ferme spécifique lorsque la ferme nominale est pleine. Voir également les critères “fe_conn”, « queue », “be_conn_free”, et “be_sess_rate”.
be_conn_free([<backend>]): integer
Renvoie une valeur entière correspondant au nombre de connexions disponibles parmi les serveurs du backend. Les emplacements de file d’attente ne sont pas pris en compte. Les serveurs de secours ne sont pas inclus, sauf si tous les autres serveurs sont hors service. Si aucun nom de backend n’est spécifié, celui en cours est utilisé. Il est également possible de vérifier un autre backend. Cela peut être utilisé pour utiliser une ferme spécifique lorsque la ferme nominale est pleine. Voir également les critères “be_conn”, « connslots », et “srv_conn_free”.
AUTRES PRÉCAUTIONS ET NOTES : si l’une des valeurs server maxconn ou maxqueue est égale à 0 (ce qui signifie sans limite), alors cette requête n’a clairement pas de sens ; dans ce cas, la valeur renvoyée sera -1.
be_sess_rate([<backend>]): integer
Renvoie une valeur entière correspondant au taux de création de sessions sur le backend, exprimé en nombre de nouvelles sessions par seconde. Cette valeur peut être utilisée avec des ACL pour basculer vers un backend alternatif lorsque le backend coûteux ou fragile atteint un taux de sessions trop élevé, ou pour limiter l’abus de service (par exemple, empêcher l’usure d’un dictionnaire en ligne). Elle peut également être utile pour inclure cet élément dans les journaux à l’aide d’une directive log-format.
Exemple :
bin(<hex>): bin
Renvoie une chaîne binaire. L’entrée est la représentation hexadécimale de la chaîne.
bool(<bool>): bool
Renvoie une valeur booléenne. <bool> peut être « true », « false », « 1 » ou « 0 ». « false » et « 0 » sont identiques.
« true » et « 1 » sont identiques.
connslots([<backend>]): integer
Renvoie une valeur entière correspondant au nombre d’emplacements de connexion encore disponibles dans le backend, en additionnant le nombre maximal de connexions sur tous les serveurs et la taille maximale de la file d’attente. Cela n’est probablement utilisé que dans le cadre des ACLs.
L’idée fondamentale consiste à pouvoir mesurer le nombre de “places” de connexion encore disponibles (connexion + file d’attente), afin que tout ce qui dépasse ce seuil (utilisation prévue ; voir le mot-clé “use_backend”) puisse être redirigé vers un autre backend.
‘connslots’ = nombre d’emplacements de connexion serveur disponibles, + nombre d’emplacements de file d’attente serveur disponibles.
Notez que bien que “fe_conn” puisse être utilisé, le paramètre « connslots » est particulièrement utile lorsque le trafic est dirigé vers une seule adresse IP, réparti entre plusieurs backends (par exemple, en utilisant des ACLs pour une répartition de charge basée sur le nom), et que vous souhaitez pouvoir distinguer les différents backends ainsi que leurs connslots disponibles. De plus, contrairement à « nbsrv », qui ne mesure que les serveurs effectivement hors service, cette requête est plus fine et examine également le nombre de connslots disponibles. Voir également « queue » et “avg_queue”.
AUTRES PRÉCAUTIONS ET NOTES : à ce stade, le code ne gère pas les connexions dynamiques. En outre, si l’une des valeurs server maxconn ou maxqueue est égale à 0, alors cette requête n’a clairement pas de sens, auquel cas la valeur renvoyée sera -1.
cpu_calls : entier Retourne le nombre d’appels effectués à la tâche traitant le flux ou la requête en cours depuis son allocation. Ce compteur est réinitialisé pour chaque nouvelle requête sur la même connexion en cas de maintien de la connexion HTTP (keep-alive). Cette valeur devrait généralement rester faible et stable (environ 2 appels pour une requête simple typique), mais peut augmenter si des traitements (compression, mise en cache ou analyse) sont effectués. Cette métrique est destinée exclusivement à la surveillance des performances.
cpu_ns_avg : entier Renvoie le nombre moyen de nanosecondes passées à chaque appel du traitement de la tâche sur le flux ou la requête en cours. Cette valeur est réinitialisée pour chaque nouvelle requête sur la même connexion en cas de maintien de la connexion HTTP (keep-alive). Cette valeur indique le coût global du traitement de la requête ou de la connexion pour chaque appel. Il n’existe pas de valeur bonne ni mauvaise, mais le temps passé dans un appel entraîne automatiquement une latence pour les autres traitements (voir lat_ns_avg ci-dessous) et peut affecter le temps de réponse apparent d’autres connexions. Certaines opérations, comme la compression, les correspondances regex complexes ou les opérations Lua intensives, peuvent directement affecter cette valeur, et son inclusion dans les journaux facilitera la détection du traitement défaillant nécessitant une correction pour retrouver des performances acceptables. Note : cette valeur est exactement égale à cpu_ns_tot divisé par cpu_calls.
cpu_ns_tot : entier Renvoie le nombre total de nanosecondes passées lors de chaque appel au traitement de la tâche sur le flux ou la requête en cours. Cette valeur est réinitialisée pour chaque nouvelle requête sur la même connexion en cas de maintien de la connexion HTTP (keep-alive). Cette valeur indique le coût global du traitement de la requête ou de la connexion pour chaque appel. Il n’existe pas de valeur bonne ni mauvaise, mais le temps passé dans un appel entraîne automatiquement une latence pour les autres traitements (voir lat_ns_avg ci-dessous), engendre des coûts CPU sur la machine et peut affecter le temps de réponse apparent d’autres connexions. Certaines opérations, comme la compression, les correspondances regex complexes ou les opérations Lua intensives, peuvent directement affecter cette valeur, et son inclusion dans les journaux facilite la détection du traitement défaillant qui doit être corrigé pour retrouver des performances correctes. La valeur peut être artificiellement élevée en raison d’un nombre élevé de cpu_calls, par exemple lors du traitement de nombreuses tranches HTTP, et c’est pourquoi il est souvent préférable de journaliser cpu_ns_avg à la place.
cpu_usage_grp : entier Retourne l’utilisation CPU mesurée au cours de la dernière boucle de sondage, comprise entre 0 et 100, moyennée sur tous les threads du groupe de threads courant. Cette mesure peut être utilisée pour le dépannage et la journalisation. La mesure est extrêmement volatile, mais reste précise pour des charges soutenues, chaque thread la mesurant sur quelques dizaines à plusieurs centaines de requêtes.
cpu_usage_proc : entier Retourne l’utilisation CPU mesurée au cours de la dernière boucle d’échantillonnage, comprise entre 0 et 100, moyennée sur tous les threads en cours d’exécution. Cette valeur peut être utilisée pour le dépannage et la journalisation. La mesure est extrêmement volatile, mais reste précise pour des charges soutenues, chaque thread la mesurant sur quelques dizaines à plusieurs centaines de requêtes. Cette valeur correspond à 100 moins celle indiquée dans le ratio inactif de la page de statistiques et dans la commande « show info ».
cpu_usage_thr : integer Renvoie l’utilisation du CPU mesurée au cours de la dernière boucle de sondage, comprise entre 0 et 100, pour le thread appelant. Cette valeur peut être utilisée pour le dépannage et la journalisation. La mesure est extrêmement volatile, mais reste précise pour des charges soutenues, car elle est établie sur quelques dizaines à plusieurs centaines de requêtes. Il s’agit de la même valeur utilisée pour décider d’activer le tuer des connexions en cas de pics trop élevés, ou de désactiver la compression. Voir également “tune.glitches.kill.cpu-usage” et « maxcompcpuusage ».
date([<offset>[,<unit>]]): integer
Renvoie la date actuelle au format epoch (nombre de secondes écoulées depuis 01/01/1970).
Si une valeur d’offset est spécifiée, elle est ajoutée à la date courante avant le retour de la valeur. Cela est particulièrement utile pour calculer des dates relatives, les offsets positifs et négatifs étant autorisés. Il est utile en combinaison avec le convertisseur http_date.
<unit> est facultatif et peut être défini à « s » pour secondes (comportement par défaut), « ms » pour millisecondes ou « us » pour microsecondes. Si l’unité est définie, la valeur renvoyée est un entier représentant respectivement les secondes, millisecondes ou microsecondes écoulées depuis l’époque, augmentées du décalage. Cette option est utile lorsque une résolution temporelle inférieure à une seconde est requise.
Exemple :
date_us : entier Retourne la partie microsecondes de la date (la partie « seconde » est retournée par date_sample). Cet échantillon est cohérent avec l’échantillon de date car il provient de la même structure timeval.
env(<name>): string
Renvoie une chaîne contenant la valeur de la variable d’environnement <name>. Pour rappel, les variables d’environnement sont propres au processus et sont échantillonnées au démarrage du processus. Cela peut être utile pour transmettre certaines informations à un serveur suivant, ou en combinaison avec des listes de contrôle d’accès afin d’effectuer une action spécifique lorsque le processus est lancé d’une manière particulière.
Exemples :
fe_conn([<frontend>]): integer
Renvoie le nombre de connexions établies actuellement sur le frontal, pouvant inclure la connexion en cours d’évaluation. Si aucun nom de frontal n’est précisé, celui en cours est utilisé. Il est également possible de vérifier un autre frontal. Cette fonction peut être utilisée pour renvoyer une page d’excuses avant un blocage strict, ou pour rediriger les nouvelles requêtes vers un backend spécifique lorsqu’une ferme est considérée comme pleine. Elle est principalement utilisée avec les ACLs, mais peut aussi servir à transmettre certaines statistiques aux serveurs via des en-têtes HTTP. Voir également les récupérations “dst_conn”, “be_conn”, “fe_sess_rate”.
fe_req_rate([<frontend>]): integer
Renvoie une valeur entière correspondant au nombre de requêtes HTTP par seconde envoyées à un frontal. Ce nombre peut différer de “fe_sess_rate” dans les cas où la réutilisation de connexion côté client est activée.
fe_sess_rate([<frontend>]): integer
Renvoie une valeur entière correspondant au taux de création de sessions sur le frontal, exprimé en nombre de nouvelles sessions par seconde. Cette valeur peut être utilisée avec des ACLs afin de limiter le taux d’arrivée des sessions à une plage acceptable, afin d’éviter toute abuse du service dès le plus tôt possible, par exemple en combinaison avec d’autres ACLs au niveau 4 pour obliger les clients à attendre que le taux descende en dessous de la limite. Elle peut également être utile pour inclure cet élément dans les journaux en utilisant une directive log-format. Voir également la directive « rate-limit sessions » pour une utilisation dans les frontaux.
Exemple :
hostname : chaîne Retourne le nom d’hôte du système.
int(<integer>): signed integer
Renvoie un entier signé.
ipv4(<ipv4>): ipv4
Renvoie un IPv4.
ipv6(<ipv6>): ipv6
Renvoie une adresse ipv6.
last_entity : chaîne Cette valeur retourne l’identité de la dernière entité évaluée lors de l’analyse en flux. Il peut s’agir de la règle finale correspondante ou du filtre ayant interrompu le traitement.
Une règle finale est une règle qui termine l’évaluation de l’ensemble de règles (comme une « accept », une « deny » ou une « redirect »). Cette fonctionnalité s’applique aux règles TCP de requête et de réponse agissant sur les jeux de règles « content », ainsi qu’aux règles HTTP des jeux « http-request », « http-response » et « http-after-response ». Les anciens jeux de règles « redirect » ne sont pas pris en charge (les informations ne sont pas stockées là-bas), ni les jeux de règles « tcp-request connection » ni « tcp-request session », car les informations sont stockées au niveau du flux et les flux n’existent pas lors de l’évaluation de ces règles. Dans ce cas, la valeur renvoyée est équivalente à « last_rule_file:last_rule_line ». Voir également “last_rule_file”, “last_rule_line”.
Pour un filtre, son identifiant est renvoyé tel qu’il est défini par les développeurs. Si cet identifiant n’est pas défini, une valeur hexadécimale est renvoyée, correspondant à un identifiant interne unique.
Le but principal de cette fonction est de permettre de signaler dans les journaux l’entité ayant interrompu le traitement en dernier, afin d’aider au débogage des problèmes. Les informations renvoyées concernant les entités peuvent évoluer au fil du temps et ne doivent pas être utilisées à d’autres fins que le débogage.
Exemple :
last_rule_file: chaîne Cette fonction retourne le nom du fichier de configuration contenant la dernière règle finale correspondante durant l’analyse du flux. Une règle finale est une règle qui termine l’évaluation de l’ensemble des règles (comme une règle « accept », « deny » ou « redirect »). Cette fonction est applicable aux règles TCP de requête et de réponse agissant sur les jeux de règles « content », ainsi qu’aux règles HTTP des jeux « http-request », « http-response » et « http-after-response ». Les anciens jeux de règles « redirect » ne sont pas pris en charge (cette information n’est pas stockée là-dedans), ni les jeux de règles « tcp-request connection » ni « tcp-request session », car l’information est stockée au niveau du flux, or les flux n’existent pas lors de l’évaluation de ces règles. Le but principal de cette fonction est de permettre de signaler dans les journaux où se trouvait la règle qui a donné le verdict final, afin d’aider à déterminer pourquoi une requête a été refusée, par exemple. Voir également “last_rule_line”.
last_rule_line: integer Cette fonction renvoie le numéro de ligne dans le fichier de configuration où se trouve la dernière règle finale correspondante durant l’analyse du flux. Une règle finale est une règle qui met fin à l’évaluation de l’ensemble des règles (comme une règle « accept », « deny » ou « redirect »). Cette fonction est valable pour les règles TCP de requête et réponse agissant sur les jeux de règles « content », ainsi que pour les règles HTTP des jeux « http-request », « http-response » et « http-after-response ». Les jeux de règles « redirect » obsolètes ne sont pas pris en charge (cette information n’est pas stockée là-dedans), ni les jeux de règles « tcp-request connection » ni « tcp-request session », car l’information est stockée au niveau du flux et les flux n’existent pas lors de l’évaluation de ces règles. Le principal objectif de cette fonction est de permettre de signaler dans les journaux où se trouvait la règle qui a donné le verdict final, afin d’aider à déterminer pourquoi une requête a été refusée, par exemple. Voir également “last_rule_file”.
lat_ns_avg : entier Retourne le nombre moyen de nanosecondes passées entre le moment où la tâche gérant le flux est réveillée et le moment où elle est effectivement appelée. Cette valeur est réinitialisée pour chaque nouvelle requête sur la même connexion en cas de maintien de la connexion HTTP (keep-alive). Cette valeur indique la latence globale imposée à la requête courante par toutes les autres requêtes traitées en parallèle, et constitue un indicateur direct des performances perçues en raison de voisins bruyants. Pour maintenir cette valeur faible, il est possible de réduire la profondeur de la file d’exécution du planificateur en utilisant “tune.runqueue-depth”, de réduire le nombre d’événements concurrents traités simultanément en utilisant “tune.maxpollevents”, de diminuer la priorité du flux en utilisant l’option “nice” dans les lignes “bind” ou dans le frontal, d’activer la planification à faible latence en utilisant “tune.sched.low-latency”, ou de rechercher d’autres requêtes lourdes dans les journaux (celles présentant des valeurs élevées de “cpu_ns_avg”), dont le traitement doit être ajusté ou corrigé. La compression de grands tampons pourrait être en cause, tout comme les expressions régulières complexes ou les listes longues d’expressions régulières. Remarque : cette valeur est exactement égale à lat_ns_tot divisé par cpu_calls.
lat_ns_tot : entier Retourne le nombre total de nanosecondes passées entre le moment où la tâche chargée du traitement du flux est réveillée et le moment où elle est effectivement appelée. Cette valeur est réinitialisée pour chaque nouvelle requête sur la même connexion en cas de maintien de la connexion HTTP (keep-alive). Cette mesure indique la latence globale imposée à la requête courante par toutes les autres requêtes en cours d’exécution en parallèle, et constitue un indicateur direct des performances perçues en raison de voisins bruyants. Pour maintenir cette valeur faible, il est possible de réduire la profondeur de la file d’exécution du planificateur en utilisant “tune.runqueue-depth”, de réduire le nombre d’événements concurrents traités simultanément en utilisant “tune.maxpollevents”, de diminuer la priorité du flux en utilisant l’option “nice” dans les lignes “bind” ou au niveau du frontal, d’activer le planification à faible latence en utilisant “tune.sched.low-latency”, ou de rechercher d’autres requêtes lourdes dans les journaux (celles présentant des valeurs élevées de “cpu_ns_avg”), dont le traitement doit être ajusté ou corrigé. La compression de grands tampons pourrait être une cause, tout comme des expressions régulières complexes ou des listes longues d’expressions régulières. Remarque : bien que l’on puisse intuitivement penser que la latence totale s’ajoute au temps de transfert, cela est presque jamais le cas, car pendant qu’une tâche attend le CPU, les tampons réseau continuent de se remplir et l’appel suivant traitera davantage d’un coup. La valeur peut être artificiellement élevée en raison d’un nombre élevé de cpu_calls, par exemple lors du traitement de nombreuses tranches HTTP, et c’est pourquoi il est souvent préférable de journaliser lat_ns_avg à la place, qui constitue un indicateur de performance plus pertinent.
meth(<method>): method
Renvoie une méthode.
nbsrv([<backend>]): integer
Renvoie une valeur entière correspondant au nombre de serveurs utilisables du backend actuel ou du backend nommé. Cette fonction est principalement utilisée avec les ACLs, mais peut également être utile lorsqu’elle est ajoutée aux journaux. Elle est normalement utilisée pour basculer vers un backend alternatif lorsque le nombre de serveurs est trop faible pour gérer une charge donnée. Elle est utile pour signaler une défaillance lorsqu’elle est combinée avec « monitor fail ».
pid : entier Retourne le PID du processus en cours. Dans la plupart des cas, il s’agit du PID du processus worker.
prio_class : integer Renvoie la classe de priorité du flux actuel en mode http ou de la connexion en mode tcp. La valeur correspond à celle définie par l’appel précédent à « http-request set-priority-class » ou « tcp-request content set-priority-class ».
prio_offset : entier Renvoie le décalage de priorité du flux actuel en mode http ou de connexion en mode tcp. La valeur correspond à celle définie par l’appel précédent à « http-request set-priority-offset » ou « tcp-request content set-priority-offset ».
proc : entier Retourne toujours la valeur 1 (historiquement, elle renvoyait le numéro du processus appelant).
queue([<backend>]): integer
Renvoie le nombre total de connexions en file d’attente du backend spécifié, y compris toutes les connexions dans les files d’attente serveur. Si aucun nom de backend n’est précisé, celui actuel est utilisé, mais il est également possible de vérifier un autre backend. Cela est utile avec les listes de contrôle d’accès (ACL) ou pour transmettre des statistiques aux serveurs backend. Cette information peut être utilisée pour déclencher des actions lorsque la file d’attente dépasse un seuil connu, généralement un indicateur d’une forte augmentation du trafic ou d’un ralentissement massif des serveurs. Une action possible pourrait être de rejeter les nouveaux utilisateurs tout en acceptant les anciens. Voir également les récupérations “avg_queue”, “be_conn”, et “be_sess_rate”.
quic_enabled: boolean Retourne true lorsque le support du protocole de transport QUIC a été compilé et que les écouteurs QUIC ne sont pas désactivés par l’option globale “tune.quic.listen”. Voir également l’option globale “tune.quic.listen”.
rand([<range>]): integer
Renvoie une valeur entière aléatoire dans une plage de <range> valeurs possibles, en commençant à zéro. Si la plage n’est pas spécifiée, elle vaut par défaut 2^32, ce qui donne des nombres compris entre 0 et 4294967295. Elle peut être utile pour transmettre certaines valeurs permettant de prendre des décisions de routage, par exemple, ou simplement à des fins de débogage. Ce hasard ne doit pas être utilisé à des fins de sécurité.
srv_conn([<backend>/]<server>): integer
Renvoie une valeur entière correspondant au nombre de connexions établies actuellement sur le serveur désigné, pouvant inclure la connexion en cours d’évaluation. Si <backend> est omis, le serveur est recherché dans le backend actuel. Cette fonction peut être utilisée pour cibler une ferme spécifique lorsqu’un serveur est plein, ou pour informer le serveur de notre vue sur le nombre de connexions actives avec lui. Voir également les méthodes de récupération “fe_conn”, “be_conn”, “queue” et “srv_conn_free”.
srv_conn_free([<backend>/]<server>): integer
Renvoie une valeur entière correspondant au nombre de connexions disponibles sur le serveur désigné, pouvant inclure la connexion en cours d’évaluation. La valeur ne tient pas compte des emplacements dans la file d’attente. Si <backend> est omis, le serveur est recherché dans le backend actuel. Cette fonction peut être utilisée pour sélectionner une ferme spécifique lorsque un serveur est plein, ou pour informer le serveur de notre vue du nombre de connexions actives avec lui. Voir également les méthodes de récupération “be_conn_free” et “srv_conn”.
AUTRES PRÉCAUTIONS ET NOTES : Si la limite maxconn du serveur est 0, alors cette récupération n’a clairement pas de sens, auquel cas la valeur renvoyée sera -1.
srv_is_up([<backend>/]<server>): boolean
Retourne true lorsque le serveur désigné est UP, et false lorsqu’il est DOWN ou en mode maintenance. Si <backend> est omis, le serveur est recherché dans le backend actuel. Il est principalement utilisé pour déclencher une action en fonction d’un état externe rapporté par un contrôle d’état (par exemple, la disponibilité d’un site géographique). Une autre utilisation possible, plus proche d’un hack, consiste à utiliser des serveurs fictifs comme des variables booléennes pouvant être activées ou désactivées depuis la ligne de commande, afin de modifier en temps réel les règles dépendant de ces ACLs.
srv_iweight([<backend>/]<server>): integer
Renvoie un entier correspondant au poids initial du serveur. Si <backend> est omis, alors le serveur est recherché dans le backend actuel. Voir également “srv_weight” et “srv_uweight”.
srv_queue([<backend>/]<server>): integer
Renvoie une valeur entière correspondant au nombre de connexions actuellement en attente dans la file d’attente du serveur désigné. Si <backend> est omis, le serveur est recherché dans le backend actuel. Cette fonction peut parfois être utilisée conjointement avec la directive “use-server” afin de forcer l’utilisation d’un serveur connu plus rapide lorsque celui-ci n’est pas trop chargé. Voir également les méthodes d’extraction “srv_conn”, “avg_queue” et “queue”.
srv_sess_rate([<backend>/]<server>): integer
Renvoie un entier correspondant au taux de création de sessions sur le serveur désigné, en nombre de nouvelles sessions par seconde. Si <backend> est omis, le serveur est recherché dans le backend actuel. Cette fonction est principalement utilisée avec les ACLs, mais peut également être utile dans les journaux. Elle permet de basculer vers un backend alternatif lorsque celui-ci, coûteux ou fragile, atteint un taux de sessions trop élevé, ou de limiter l’abus de service (par exemple, empêcher les requêtes latentes de surcharger les serveurs).
Exemple :
srv_uweight([<backend>/]<server>): integer
Renvoie un entier correspondant au poids du serveur visible par l’utilisateur. Si <backend> est omis, alors le serveur est recherché dans le backend actuel. Voir également “srv_weight” et “srv_iweight”.
srv_weight([<backend>/]<server>): integer
Renvoie un entier correspondant au poids du serveur actuel (ou effectif). Si <backend> est omis, le serveur est recherché dans le backend actuel. Voir également “srv_iweight” et “srv_uweight”.
arrêt : booléen Retourne TRUE si le processus appelant la fonction est actuellement en arrêt. Cela peut être utile pour la journalisation, ou pour assouplir certaines vérifications ou aider à fermer certaines connexions lors d’un arrêt progressif.
str(<string>): string
Renvoie une chaîne de caractères.
table_avl([<table>]): integer
Renvoie le nombre total d’entrées disponibles dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Voir également “table_cnt”.
table_cnt([<table>]): integer
Renvoie le nombre total d’entrées actuellement utilisées dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Voir également “table_conn_cnt” et table_avl pour d’autres méthodes de comptage des entrées.
term_events : chaîne Retourne tous les événements de terminaison connus pour toutes les entités attachées à un flux, côté client et côté serveur. Un tuple de sept éléments est retourné, contenant les informations suivantes :
- les événements de terminaison de la connexion frontale
- les événements de terminaison de la connexion multiplexée frontale
- les événements de terminaison du descripteur de point d’entrée de flux frontale
(le flux multiplexé ou l’application)
- les événements de terminaison du flux
- les événements de terminaison du descripteur de point d’entrée de flux arrière
(le flux multiplexé ou l’application)
- les événements de terminaison de la connexion multiplexée arrière
- les événements de terminaison de la connexion arrière
À chaque niveau, les quatre premiers événements sont signalés. Une chaîne vide est renvoyée si aucun événement n’a encore été signalé pour un niveau spécifique. Si les événements de terminaison ne sont pas pris en charge, un tiret “-” est renvoyé.
Il ne doit être utilisé que à des fins de débogage. Le format exact n’est pas documenté car il peut évoluer en fonction des besoins des développeurs.
tgroup : integer Renvoie une valeur entière correspondant à la position du groupe de threads appelant la fonction, comprise entre 0 et (global.thread-groups - 1). Utile à des fins de journalisation et de débogage.
thread : entier Renvoie une valeur entière correspondant à la position du thread appelant la fonction, comprise entre 0 et (global.nbthread-1). Cela est utile à des fins de journalisation et de débogage.
txn.id32 : entier Renvoie l’identifiant interne de la transaction. Il s’agit d’un entier sur 32 bits. En valeur absolue, sa valeur n’est donc pas unique ; les identifiants de transaction peuvent donc s’entourer. La période d’entouragement dépend du débit des requêtes. En pratique, cela ne devrait pas poser de problème. Pour un identifiant unique véritable, voir la directive « unique-id-format ».
txn.sess_term_state : chaîne Retourne l’état de terminaison du flux TCP ou HTTP, tel qu’indiqué dans le journal. Il s’agit d’une chaîne de deux caractères : l’état final du flux suivi de l’événement ayant provoqué sa terminaison. Consultez la section 8.5 pour obtenir la liste des événements possibles. La valeur actuelle au moment de l’évaluation de l’extraction d’échantillon est retournée. Elle peut évoluer. Sauf lorsqu’elle est utilisée dans des règles ACL du type « http-after-response » ou dans des messages de journalisation, elle sera toujours « – ».
Exemple :
uptime : entier Retourne le temps d’exécution du worker HAProxy actuel en secondes.
uuid([<version>]): string
Renvoie un UUID conforme à la norme RFC 9562. Si la version n’est pas précisée, un UUID de version 4 (entièrement aléatoire) est renvoyé.
Les versions 4 et 7 sont prises en charge.
var(<var-name>[,<default>]): undefined
Renvoie une variable avec son type stocké. Si la variable n’est pas définie, l’extraction d’échantillon échoue, sauf si une valeur par défaut est fournie, auquel cas celle-ci est renvoyée sous forme de chaîne. Les chaînes vides sont autorisées. Voir section 2.8 sur les variables pour plus de détails.
dump_all_vars([<scope>][,<prefix>][,<delimiter>]): string
Renvoie la liste de toutes les variables dans la portée spécifiée, éventuellement filtrée par un préfixe de nom et avec un délimiteur personnalisable.
Format de sortie : var1=value1<delim>var2=value2<delim>…
Encodage des valeurs par type :
- Chaînes : entre guillemets et échappées (", \, \r, \n, \b, \0) Exemple : txn.name=“John \“Doe\””
- Binaire : encodé en hexadécimal avec préfixe ‘x’, non entre guillemets Exemple : txn.data=x48656c6c6f
- Entiers : décimal non entre guillemets Exemple : txn.count=42
- Booléens : “true” ou “false” non entre guillemets Exemple : txn.active=true
- Adresses : chaîne d’adresse IP non entre guillemets Exemple : txn.client=192.168.1.1
- Méthodes HTTP : chaîne entre guillemets Exemple : req.method=“GET”
Arguments :
<scope>(facultatif) : sess, txn, req, res ou proc. Si omis, toutes ces portées sont parcourues dans le même ordre que présenté ici.<prefix>(facultatif) : filtre les variables dont le nom commence par le préfixe spécifié (après suppression du préfixe d’étendue). Note sur les performances : lorsque le filtrage par préfixe est utilisé, toutes les variables de l’étendue sont toujours parcourues. Ce paramètre ne doit pas être utilisé avec des configurations comportant des milliers de variables.<delimiter>(facultatif) : chaîne utilisée pour séparer les variables. Valeur par défaut : “, " (virgule-espace). Peut être personnalisée avec n’importe quelle chaîne. Pour rappel, afin de passer des virgules ou des espaces en tant qu’argument de fonction, ils doivent être enclos entre guillemets simples ou doubles (si l’expression elle-même est déjà entre guillemets, utiliser l’autre type).
Valeur de retour :
- En cas de succès : chaîne contenant toutes les variables correspondantes
- En cas d’échec : chaîne vide (l’extraction d’échantillon échoue) si la mémoire tampon de sortie est trop petite. La fonction ne tronque pas la sortie ; elle échoue complètement afin d’éviter les données partielles.
Cela est particulièrement utile pour le débogage, la journalisation ou l’exportation d’états de variables.
Exemples :
wait_end : boolean Cette instruction renvoie soit true lorsque la période d’inspection est terminée, soit ne renvoie rien. Elle n’est utilisée qu’avec les listes de contrôle d’accès (ACL), en conjonction avec l’analyse du contenu, afin d’éviter de renvoyer un verdict erroné prématurément. Elle peut également servir à retarder certaines actions, comme un rejet différé pour certaines adresses spéciales. Étant donné qu’elle arrête soit l’évaluation des règles, soit renvoie immédiatement true, il est recommandé de placer cette ACL en dernière position d’une règle. Veuillez noter que la liste de contrôle d’accès par défaut “WAIT_END” est toujours utilisable sans déclaration préalable. Ce test a été conçu pour être utilisé avec l’inspection du contenu des requêtes TCP.
Exemples :
waiting_entity : chaîne Cette valeur retourne l’identité de l’entité qui attendait de poursuivre son traitement lorsque une erreur ou un délai d’expiration a été rencontré. Il peut s’agir par exemple d’une règle ou d’un filtre. Toutefois, cette liste n’est pas exhaustive et le format de toutes les entités possibles n’est pas obligatoirement documenté.
Lorsque l’entité est une règle, son emplacement est renvoyé. Il s’agit du fichier de configuration contenant la règle, suivi de la ligne où la règle est définie dans ce fichier, séparés par deux points.
Pour un filtre, son identifiant est renvoyé tel qu’il est défini par les développeurs. Si cet identifiant n’est pas défini, une valeur hexadécimale est renvoyée, correspondant à un identifiant interne unique.
Le but principal de cette fonction est de permettre de signaler dans les journaux l’entité bloquant l’analyse du flux lorsqu’une erreur ou un délai d’expiration est détecté, interrompant ainsi ce traitement, afin d’aider au débogage des problèmes. Les informations renvoyées concernant les entités peuvent évoluer au fil du temps et ne doivent pas être utilisées à d’autres fins que le débogage.
Exemple :
7.3.3. Récupération des échantillons au niveau 4
Le niveau 4 décrit généralement la couche transport, qui chez HAProxy correspond le plus près à la connexion, où aucun contenu n’est encore disponible. Les méthodes de récupération décrites ici sont utilisables dès la règle “tcp-request connection”, à moins qu’elles nécessitent des informations futures. Celles-ci incluent généralement les adresses et ports TCP/IP, ainsi que les éléments des tables de persistance liés à la connexion entrante. Pour récupérer une valeur à partir d’un compteur de persistance, le numéro du compteur peut être explicitement défini à 0, 1 ou 2 en utilisant les préfixes prédéfinis “sc0_”, “sc1_” ou “sc2_”. Ces trois préfixes prédéfinis ne peuvent être utilisés que si la valeur globale “tune.stick-counters” ne dépasse pas 3 ; sinon, le numéro du compteur peut être spécifié comme premier argument entier lors de l’utilisation du préfixe “sc_”, à partir de “sc_0” jusqu’à “sc_N”, où N est égal à (tune.stick-counters-1). Une table optionnelle peut être spécifiée au format “sc*”, auquel cas la clé actuellement suivie sera recherchée dans cette table alternative plutôt que dans la table actuellement suivie.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
accept_date([<unit>]): integer
C’est la date exacte à laquelle la connexion a été reçue par HAProxy (qui peut différer très légèrement de la date observée sur le réseau si une file d’attente s’est formée dans la file de backlog du système). Cette date correspond généralement à celle qui peut apparaître dans les journaux de tout pare-feu en amont. En mode HTTP, le champ accept_date est réinitialisé au moment où la connexion est prête à recevoir une nouvelle requête (fin de la réponse précédente pour HTTP/1, immédiatement après la requête précédente pour HTTP/2).
Renvoie une valeur en nombre de secondes depuis l’époque.
<unit> est facultatif et peut être défini à « s » pour secondes (comportement par défaut), « ms » pour millisecondes ou « us » pour microsecondes. Si l’unité est définie, la valeur renvoyée est un entier représentant respectivement les secondes, millisecondes ou microsecondes écoulées depuis l’époque. Cette option est utile lorsque une résolution temporelle inférieure à une seconde est requise.
bc.timer.connect : entier Temps total nécessaire pour établir la connexion TCP au serveur. Cela correspond à %Tc dans le format de journalisation. Cette valeur est exprimée en millisecondes (ms). Pour plus d’informations, voir Section 8.4 « Événements de temporisation »
bc_be_queue : entier Nombre de flux défilés pendant l’attente d’un slot de connexion sur le backend. Cela correspond à %bq dans le format de journalisation.
bc_dst: ip Adresse IP de destination de la connexion côté serveur, soit l’adresse du serveur vers lequel HAProxy est connecté. Ce champ est de type IP et fonctionne sur les tables IPv4 et IPv6. Sur les tables IPv6, les adresses IPv4 sont mappées vers leur équivalent IPv6, conformément au RFC 4291.
bc_dst_port : entier Renvoie une valeur entière correspondant au port TCP de destination de la connexion côté serveur, c’est-à-dire le port vers lequel HAProxy s’est connecté.
bc_err : integer Renvoie l’identifiant de l’erreur qui pourrait être survenue lors de la connexion au backend actuel. Consultez la requête “fc_err_str” pour obtenir la liste complète des codes d’erreur et leurs messages correspondants.
bc_err_name : chaîne Retourne le nom d’erreur interne décrivant le problème survenu sur le backend de connexion, entraînant une échec de connexion. Cette chaîne est composée d’un seul mot et est vide lorsqu’aucune erreur n’est présente. Elle correspond à la colonne « name » du tableau présenté dans le mot-clé “fc_err_str”.
bc_err_str : chaîne Retourne un message d’erreur décrivant le problème survenu sur le backend actuel, entraînant une échec de connexion. Consultez la récupération “fc_err_str” pour obtenir la liste complète des codes d’erreur et leurs messages correspondants.
bc_glitches : entier Retourne le nombre de dysfonctionnements de protocole détectés sur la connexion au backend. Ces dysfonctionnements couvrent généralement des violations de protocole ainsi que des anomalies mineures qui indiquent généralement un serveur non fiable ou mal comporté, pouvant entraîner des problèmes dans l’infrastructure (par exemple, des connexions interrompues prématurément, provoquant des renégociations TLS fréquentes). Ces dysfonctionnements peuvent également être dus à des réponses trop volumineuses ne pouvant pas tenir dans un seul tampon, expliquant les erreurs HTTP 502. Ce nombre devrait idéalement rester à zéro, bien qu’il soit généralement acceptable qu’il reste très faible par rapport au nombre total de requêtes. Ces valeurs ne devraient normalement pas être considérées comme alarmantes (en particulier lorsqu’elles sont faibles), bien qu’une augmentation soudaine puisse indiquer une anomalie. Tous les multiplexeurs de protocole ne mesurent pas cette métrique, et la seule façon d’obtenir des détails supplémentaires sur les événements est d’activer les traces pour capturer toutes les échanges.
bc_http_major : integer Renvoie la version majeure HTTP de la connexion au backend, qui peut être 1 pour HTTP/0.9 à HTTP/1.1 ou 2 pour HTTP/2.. Note : cette valeur est basée sur le codage sur le réseau et non sur la version présente dans l’en-tête de la requête.
bc_nb_streams : entier Retourne le nombre de flux ouverts sur la connexion backend.
bc_reused : boolean Retourne true si le transfert a été effectué via une connexion backend réutilisée.
bc_rtt(<unit>): integer
Retourne le temps de trajet aller-retour (RTT) mesuré par le noyau pour la connexion au backend. <unit> est facultatif, la valeur par défaut est en millisecondes. <unit> peut être défini sur « ms » pour les millisecondes ou « us » pour les microsecondes. Si la connexion au serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’échantillonnage échoue.
bc_rttvar(<unit>): integer
Retourne la variance du temps de trajet aller-retour (RTT) mesurée par le noyau pour la connexion au backend.
<unit> est facultatif, la valeur par défaut est en millisecondes. <unit> peut être défini sur « ms » pour les millisecondes ou « us » pour les microsecondes. Si la connexion au serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
bc_settings_streams_limit : integer Renvoie le nombre maximum de flux autorisés sur la connexion backend. Pour les connexions TCP et HTTP/1.1, la valeur est toujours 1. Pour les autres protocoles, elle dépend des paramètres négociés avec le serveur.
bc_src: ip Adresse IP de la source de la connexion côté serveur, soit l’adresse du serveur depuis lequel HAProxy s’est connecté. Ce champ est de type IP et fonctionne sur les tables IPv4 et IPv6. Sur les tables IPv6, les adresses IPv4 sont mappées vers leur équivalent IPv6, conformément au RFC 4291.
bc_src_port : entier Renvoie une valeur entière correspondant au port source TCP de la connexion côté serveur, c’est-à-dire le port depuis lequel HAProxy s’est connecté.
bc_srv_queue : entier Nombre de flux défilés pendant l’attente d’un emplacement de connexion sur le serveur cible. Cela correspond à %sq au format de journalisation.
be_id : entier Renvoie un entier contenant l’identifiant du backend actuel. Il peut être utilisé dans les frontaux avec des réponses pour vérifier quel backend a traité la requête. S’il est utilisé dans un frontal et qu’aucun backend n’a été utilisé, il renvoie l’identifiant du frontal actuel. Il peut également être utilisé dans un règle tcp-check ou http-check.
be_connect_timeout : integer Renvoie la valeur de configuration en millisecondes du délai d’expiration de la connexion au backend actuel. Ce délai peut être remplacé par une règle « set-timeout ». Voir également “cur_connect_timeout”.
be_name : chaîne Renvoie une chaîne contenant le nom du backend actuel. Elle peut être utilisée dans les frontaux avec des réponses pour vérifier quel backend a traité la requête. Si elle est utilisée dans un frontal et qu’aucun backend n’a été utilisé, elle renvoie le nom du frontal actuel. Elle peut également être utilisée dans un ensemble de règles tcp-check ou http-check.
be_queue_timeout: integer Retourne la valeur de configuration en millisecondes du délai d’expiration de la file d’attente du backend actuel. Ce délai peut être remplacé par une règle « set-timeout ». Voir également “cur_queue_timeout”.
be_server_timeout: integer Retourne la valeur de configuration en millisecondes pour le délai d’expiration du serveur du backend actuel. Ce délai peut être remplacé par une règle « set-timeout ». Voir également “cur_server_timeout”.
be_tarpit_timeout: integer Retourne la valeur de configuration en millisecondes pour le délai d’expiration de la file d’attente du backend actuel. Ce délai peut être remplacé par une règle « set-timeout ». Voir également “cur_tarpit_timeout”.
be_tunnel_timeout: integer Retourne la valeur de configuration en millisecondes du délai d’expiration du tunnel du backend actuel. Ce délai peut être remplacé par une règle « set-timeout ». Voir également “cur_tunnel_timeout”.
bytes_in : entier Voir “req.bytes_in”.
bytes_out : entier Voir “res.bytes_in”.
cur_connect_timeout : entier Renvoie le délai d’expiration de connexion actuellement appliqué en millisecondes pour le flux. Dans le cas par défaut, cette valeur est égale à be_connect_timeout, sauf si une règle « set-timeout » a été appliquée. Voir également “be_connect_timeout”.
cur_client_timeout : integer Renvoie le délai d’expiration client actuellement appliqué en millisecondes pour le flux. Dans le cas par défaut, cette valeur est égale à fe_client_timeout, sauf si une règle « set-timeout » a été appliquée. Voir également “fe_client_timeout”.
cur_queue_timeout : entier Renvoie le délai d’expiration de file d’attente actuellement appliqué, en millisecondes, pour le flux. Dans le cas par défaut, cette valeur est égale à be_queue_timeout, sauf si une règle « set-timeout » a été appliquée. Voir également “be_queue_timeout”.
cur_server_timeout : integer Renvoie le délai d’expiration serveur actuellement appliqué en millisecondes pour le flux. Dans le cas par défaut, cette valeur est égale à be_server_timeout, sauf si une règle « set-timeout » a été appliquée. Voir également “be_server_timeout”.
cur_tarpit_timeout : integer Renvoie le délai d’expiration actuellement appliqué, en millisecondes, pour le flux. Dans le cas par défaut, cette valeur est égale à fe_tarpit_timeout/be_tarpit_timeout sauf si une règle « set-timeout » a été appliquée. Voir également “fe_tarpit_timeout” et “be_tarpit_timeout”.
cur_tunnel_timeout : integer Renvoie le délai d’expiration du tunnel actuellement appliqué, en millisecondes, pour le flux. Dans le cas par défaut, cette valeur est égale à be_tunnel_timeout, sauf si une règle « set-timeout » a été appliquée. Voir également “be_tunnel_timeout”.
dst: ip Cette adresse IP est celle de la destination de la connexion côté client, c’est-à-dire l’adresse vers laquelle le client s’est connecté. Les règles tcp/http peuvent modifier cette adresse. Elle peut être utile lors de l’exécution en mode transparent. Elle est de type IP et fonctionne sur les tables IPv4 et IPv6. Sur les tables IPv6, les adresses IPv4 sont mappées vers leur équivalent IPv6 selon la RFC 4291. Lorsqu’une connexion entrante passe par une translation ou une redirection impliquant le suivi des connexions, l’adresse de destination d’origine avant la redirection est rapportée. Sur les systèmes Linux, la source et la destination peuvent parfois apparaître inversées si l’option sysctl nf_conntrack_tcp_loose est activée, car une réponse tardive peut réouvrir une connexion expirée et inverser ce qui est considéré comme la source et la destination.
dst_conn : integer Renvoie une valeur entière correspondant au nombre de connexions actuellement établies sur le même socket, y compris celle en cours d’évaluation. Il est normalement utilisé avec des listes de contrôle d’accès (ACL), mais peut également être utilisé pour transmettre des informations aux serveurs via un en-tête HTTP ou dans les journaux. Il peut servir à afficher une page d’excuse avant un blocage strict, ou à rediriger les nouvelles requêtes vers un backend spécifique lorsqu’un socket est considéré comme saturé. Cela permet d’attribuer des limites différentes à différentes adresses ou ports d’écoute. Voir également les récupérations “fe_conn” et “be_conn”.
dst_is_local : booléen Renvoie true si l’adresse de destination de la connexion entrante est locale au système, ou false si l’adresse n’existe pas sur le système, ce qui signifie qu’elle a été interceptée en mode transparent. Cette information peut être utile pour appliquer certaines règles par défaut au trafic transféré, et d’autres règles au trafic ciblant l’adresse réelle de la machine. Par exemple, la page de statistiques pourrait être servie uniquement sur cette adresse, ou l’accès SSH pourrait être redirigé localement. Veuillez noter que la vérification implique quelques appels système, il est donc préférable de la réaliser une seule fois par connexion.
dst_port : integer Renvoie une valeur entière correspondant au port TCP de destination de la connexion côté client, c’est-à-dire le port auquel le client s’est connecté. Les règles tcp/http peuvent modifier cette adresse. Cette information peut être utilisée lors de l’exécution en mode transparent, lors de l’affectation de ports dynamiques à certains clients pour une session d’application entière, pour affecter tous les utilisateurs à un même serveur, ou pour transmettre les informations relatives au port de destination à un serveur via un en-tête HTTP.
fc.timer.handshake : entier Temps total pour accepter une connexion TCP et exécuter les échanges de handshake pour les protocoles de bas niveau. Actuellement, ces protocoles sont proxy-protocol et SSL. Ceci correspond à %Th dans le format de journalisation. Cette valeur est exprimée en millisecondes (ms). Pour plus d’informations, voir Section 8.4 “Événements de temporisation”
fc.timer.total : entier Durée totale du flux, mesurée entre l’instant où le proxy l’a accepté et l’instant où les deux extrémités ont été fermées. Cela correspond à %Tt dans le format de journalisation. Cette valeur est exprimée en millisecondes (ms). Pour plus d’informations, voir Section 8.4 « Événements de temporisation »
fc_dst : ip Cette adresse IP correspond à l’adresse de destination initiale de la connexion du côté client. Seules les règles « tcp-request connection » peuvent modifier cette adresse. Voir « dst » pour plus de détails.
fc_dst_is_local : boolean Renvoie true si l’adresse de destination d’origine de la connexion entrante est locale au système, ou false si l’adresse n’existe pas sur le système. Voir “dst_is_local” pour les détails.
fc_dst_port : entier Renvoie une valeur entière correspondant au port TCP de destination original de la connexion côté client. Seules les règles « tcp-request connection » peuvent modifier cette adresse. Voir « dst-port » pour plus de détails.
fc_err : integer Renvoie l’identifiant de l’erreur qui aurait pu se produire sur la connexion courante. Toute valeur strictement positive de cette requête indique que la connexion n’a pas réussi et entraînera la sortie d’un message d’erreur dans les journaux (comme décrit dans section 8.2.5 ). Voir le “fc_err_str” fetch pour la liste complète des codes d’erreur et leurs messages correspondants.
fc_err_name : chaîne Retourne le nom d’erreur interne décrivant le problème survenu au frontal, entraînant une échec de connexion. Cette chaîne est composée d’un seul mot et est vide lorsqu’aucune erreur n’est présente. Elle correspond à la colonne « name » du tableau présenté dans le mot-clé “fc_err_str”.
fc_err_str : chaîne Retourne un message d’erreur décrivant le problème survenu sur la connexion actuelle, entraînant une échec de connexion. Cette chaîne correspond à la partie « message » du format d’enregistrement d’erreur (voir section 8.2.5 ). Consultez ci-dessous la liste complète des codes d’erreur et leurs messages correspondants :
fc_fackets : entier Retourne le compteur fack mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_glitches : integer Retourne le nombre de perturbations de protocole détectées sur la connexion frontale. Ces perturbations couvrent généralement des violations de protocole ainsi que de petites anomalies qui indiquent généralement un client frauduleux ou mal comporté, susceptible de provoquer des problèmes dans l’infrastructure, comme un trop grand nombre d’erreurs dans les journaux, ou de nombreuses connexions interrompues prématurément, entraînant des renégociations TLS fréquentes. Elles peuvent également être causées par des requêtes trop volumineuses pour tenir dans un seul tampon, expliquant les erreurs HTTP 400. Idéalement, ce nombre doit rester à zéro, bien qu’il puisse arriver que certains navigateurs, en jouant avec les limites du protocole, déclenchent cette mesure occasionnellement. Ces valeurs ne devraient normalement pas être considérées comme alarmantes (en particulier les petites valeurs), bien qu’une augmentation soudaine puisse indiquer une anomalie quelque part. Des valeurs élevées (par exemple, des centaines à des milliers par connexion, ou autant que le nombre de requêtes) peuvent indiquer un client spécifiquement conçu pour repérer ou attaquer la pile de protocole. Tous les multiplexeurs de protocole ne mesurent pas cette métrique, et la seule façon d’obtenir des détails supplémentaires sur les événements est d’activer les traces pour capturer toutes les échanges.
fc_http_major : integer Rapporte la version majeure HTTP de la connexion frontale, qui peut être 1 pour HTTP/0.9 à HTTP/1.1 ou 2 pour HTTP/2.. Note : cette information est basée sur le codage sur le réseau et non sur la version présente dans l’en-tête de la requête.
fc_lost : entier Si la connexion n’est ni TCP, ni QUIC, l’extraction d’échantillon échoue. Pour QUIC, retourne le nombre de paquets QUIC perdus par la connexion cliente. Pour TCP, retourne le compteur de pertes mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_nb_streams : entier Retourne le nombre de flux ouverts sur la connexion frontale.
fc_pp_authority : chaîne Retourne la première valeur TLV d’autorité envoyée par le client dans le protocole PROXY, en-tête, le cas échéant.
fc_pp_tlv(<id>): string
Renvoie la valeur TLV correspondant à l’ID TLV donné. L’ID doit être soit une valeur numérique comprise entre 0 et 255, soit l’un des noms symboliques suivants, qui correspondent aux suffixes de constante TLV spécifiés dans la norme PPv2 : “ALPN” : PP2_TYPE_ALPN, “AUTHORITY” : PP2_TYPE_AUTHORITY, “CRC32” : PP2_TYPE_CRC32C, “NETNS” : PP2_TYPE_NETNS, “NOOP” : PP2_TYPE_NOOP, “SSL” : PP2_TYPE_SSL, “SSL_CIPHER” : PP2_SUBTYPE_SSL_CIPHER, “SSL_CN” : PP2_SUBTYPE_SSL_CN, “SSL_KEY_ALG” : PP2_SUBTYPE_SSL_KEY_ALG, “SSL_SIG_ALG” : PP2_SUBTYPE_SSL_SIG_ALG, “SSL_VERSION” : PP2_SUBTYPE_SSL_VERSION, “UNIQUE_ID” : PP2_TYPE_UNIQUE_ID.
La valeur reçue doit être inférieure ou égale à 1024 octets. Cela permet de prévenir les attaques DoS potentielles. Les valeurs inférieures ou égales à 256 octets peuvent être regroupées en pool mémoire. Par conséquent, privilégiez une longueur de valeur envoyée de 256 octets au maximum pour des performances optimales.
Notez qu’à la différence de fc_pp_authority et fc_pp_unique_id, fc_pp_tlv est capable d’itérer sur toutes les occurrences d’un TLV demandé en cas de duplication d’ID TLV. L’ordre d’itération correspond à la position dans l’en-tête du protocole PROXY. Toutefois, il est généralement préférable d’éviter les doublons, car les TLV sont généralement supposés être uniques. La présence de plusieurs ID TLV identiques indique généralement une erreur côté émetteur de l’en-tête du protocole PROXY.
fc_pp_unique_id : chaîne Retourne le premier identifiant unique TLV envoyé par le client dans le protocole PROXY, en-tête, le cas échéant.
fc_rcvd_proxy : boolean Retourne true si le client a établi la connexion avec un protocole PROXY via un en-tête.
fc_reordering : entier Si la connexion n’est ni TCP, ni QUIC, l’extraction d’échantillon échoue. Pour QUIC, retourne le nombre de paquets réordonnés QUIC pour la connexion cliente. Pour TCP, retourne le compteur de réordonnancement mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_retrans : entier Retourne le compteur de retransmissions mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_rtt(<unit>): integer
Si la connexion n’est ni TCP, ni QUIC, l’extraction d’échantillon échoue. Pour QUIC, retourne le temps de trajet lissé (Smoothed Round Trip Time) de la connexion cliente. Pour TCP, retourne le temps de trajet (RTT) mesuré par le noyau pour la connexion cliente. <unit> est facultatif, la valeur par défaut est en millisecondes. <unit> peut être défini sur « ms » pour les millisecondes ou « us » pour les microsecondes. Si la connexion serveur n’est pas établie, ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_rttvar(<unit>): integer
Si la connexion n’est ni TCP, ni QUIC, l’extraction d’échantillon échoue. Pour QUIC, renvoie la variance du temps de trajet lissé pour la connexion cliente. Pour TCP, renvoie la variance du temps de trajet (RTT) mesurée par le noyau pour la connexion cliente. <unit> est facultatif, la valeur par défaut est en millisecondes. <unit> peut être défini sur « ms » pour les millisecondes ou « us » pour les microsecondes. Si la connexion serveur n’est pas établie, ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_sacked : integer Renvoie le compteur sacked mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO, par exemple les noyaux Linux antérieurs à la version 2.4, l’extraction d’échantillon échoue.
fc_saved_syn : binaire Renvoie une copie du paquet SYN sauvegardé par le système pendant la mise en place de la connexion entrante. Cela nécessite que l’option « tcp-ss » soit présente dans la ligne « bind », ainsi qu’un noyau Linux 4.3 au minimum. Lorsque « tcp-ss » est défini à 1, seuls les en-têtes IP et TCP sont présents. Lorsque « tcp-ss » est défini à 2, l’en-tête Ethernet est également présent avant l’en-tête IP, et peut être utilisé pour contrôler ou journaliser l’adresse MAC source ou les VLANs, par exemple. Notez qu’aucune garantie n’est donnée quant à la sauvegarde d’un paquet SYN. Par exemple, si les cookies SYN sont utilisés, le paquet SYN n’est pas conservé et la connexion est établie à partir du paquet ACK correspondant. En outre, le système ne garantit pas la conservation de la copie au-delà de la première lecture. Il est donc fortement recommandé de copier ce paquet dans une variable portant la portée « sess » à partir d’une règle « tcp-request connection », et d’utiliser uniquement cette variable pour les manipulations ultérieures. Il convient de noter qu’au niveau de l’interface boucle, le système construit un en-tête Ethernet factice de 14 octets, dont les adresses source et destination sont nulles, et seul le protocole est défini. Il est pratique de convertir ces échantillons en hexadécimal à l’aide du convertisseur « hex » lors du débogage. Exemple (champs séparés manuellement et commentés ci-dessous) :
Le convertisseur « bytes() » permet d’extraire des champs spécifiques du paquet. Le convertisseur be2dec() permet également de lire des tronçons et de les émettre sous forme d’entier. Pour une extraction plus précise, veuillez vous référer aux convertisseurs “eth.XXX”.
Exemple avec entrée IPv4 :
Voir également l’action « set-var », les convertisseurs « be2dec », « bytes », « hex », “eth.XXX”, “ip.XXX”, et “tcp.XXX”.
fc_settings_streams_limit : entier Renvoie le nombre maximum de flux autorisés sur la connexion frontale. Pour les connexions TCP et HTTP/1.1, il est toujours égal à 1. Pour les autres protocoles, cela dépend des paramètres négociés avec le client.
fc_src: ip Cette adresse IP correspond à l’adresse IP source d’origine de la connexion côté client. Seules les règles “tcp-request connection” peuvent modifier cette adresse. Voir “src” pour plus de détails.
fc_src_is_local : boolean Renvoie true si l’adresse source de la connexion entrante est locale au système, ou false si l’adresse n’existe pas sur le système. Voir “src_is_local” pour les détails.
fc_src_port : entier Renvoie une valeur entière correspondant au port source TCP de la connexion côté client. Seules les règles « tcp-request connection » peuvent modifier cette adresse. Voir « src-port » pour plus de détails.
fc_unacked : integer Retourne le compteur d’éléments non confirmés mesuré par le noyau pour la connexion cliente. Si la connexion serveur n’est pas établie, si la connexion n’est pas TCP ou si le système d’exploitation ne prend pas en charge TCP_INFO (par exemple, les noyaux Linux antérieurs à la version 2.4), l’extraction d’échantillon échoue.
fe_client_timeout : entier Renvoie la valeur de configuration en millisecondes pour le délai d’expiration client du frontend actuel. Ce délai peut être remplacé par une règle « set-timeout ».
fe_defbe : chaîne Retourne une chaîne contenant le nom du backend par défaut du frontal. Elle peut être utilisée dans les frontaux pour vérifier quel backend gérera les requêtes par défaut.
fe_id : entier Renvoie un entier contenant l’identifiant du frontend actuel. Il peut être utilisé dans les backends pour vérifier depuis quel frontend il a été appelé, ou pour affecter tous les utilisateurs provenant du même frontend au même serveur.
fe_name : chaîne Retourne une chaîne contenant le nom du frontend actuel. Elle peut être utilisée dans les backends pour vérifier depuis quel frontend elle a été appelée, ou pour affecter tous les utilisateurs provenant du même frontend au même serveur.
fe_tarpit_timeout : entier Retourne la valeur de configuration en millisecondes du délai d’expiration du tarpit du frontend actuel. Ce délai peut être remplacé par une règle « set-timeout ».
req.bytes_in : entier Cette valeur retourne le nombre d’octets reçus depuis le client. La valeur correspond à ce qui a été reçu par HAProxy, y compris certains en-têtes et une surcharge liée à l’encodage interne. La compression des requêtes n’affecte pas la valeur indiquée ici.
req.bytes_out : entier Cette valeur retourne le nombre d’octets envoyés au serveur. La valeur correspond à ce qui a été envoyé par HAProxy, y compris certains en-têtes et une surcharge liée à un encodage interne. La compression des requêtes affecte la valeur rapportée ici.
res.bytes_in : entier Cette valeur retourne le nombre d’octets reçus depuis le serveur. La valeur correspond à ce qui a été reçu par HAProxy, y compris certains en-têtes et une surcharge liée à l’encodage interne. La compression de la réponse n’affecte pas la valeur indiquée ici.
res.bytes_out : entier Cette valeur retourne le nombre d’octets envoyés au client. La valeur correspond à ce qui a été envoyé par HAProxy, y compris certains en-têtes et une surcharge liée à l’encodage interne. La compression de la réponse affecte la valeur rapportée ici.
res.timer.data : entier indique le temps total de transfert du contenu de la réponse jusqu’à l’envoi du dernier octet au client. En HTTP, il commence après le dernier en-tête de réponse (après Tr). Il correspond à %Td dans le format de journalisation et est exprimé en millisecondes (ms). Pour plus d’informations, voir Section 8.4 « Événements de temporisation »
sc_bytes_in_rate(<ctr>[,<table>]): integer
Retourne le débit moyen en octets client-serveur issu des compteurs actuellement suivis, mesuré en quantité d’octets sur la période configurée dans le tableau. Voir également “table_bytes_in_rate”.
sc_bytes_out_rate(<ctr>[,<table>]): integer
Retourne le débit moyen en octets émis par le serveur vers le client, calculé à partir des compteurs actuellement suivis, exprimé en nombre d’octets sur la période configurée dans le tableau. Voir également “table_bytes_out_rate”.
sc_clr_gpc(<idx>,<ctr>[,<table>]): integer
Efface le compteur général à l’index <idx> du tableau associé au compteur suivi désigné d’ID <ctr> depuis la table de persistance du proxy actuel ou depuis la table de persistance désignée <table>, et retourne sa valeur précédente. <idx> est un entier compris entre 0 et 99 et <ctr> un entier compris entre 0 et 2. Avant la première invocation, la valeur stockée est zéro, donc la première invocation retournera toujours zéro. Cette opération s’applique uniquement au type de données ‘gpc’ (et non aux types hérités ‘gpc0’ ni ‘gpc1’).
sc_clr_gpc0(<ctr>[,<table>]): integer
Efface le premier compteur généralisé associé aux compteurs actuellement suivis, puis retourne sa valeur précédente. Avant la première invocation, la valeur stockée est zéro, donc la première invocation retournera toujours zéro. Cette fonction est généralement utilisée comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée :
Exemple :
sc_clr_gpc1(<ctr>[,<table>]): integer
Efface la deuxième compteur général associé aux compteurs actuellement suivis, et retourne sa valeur précédente. Avant la première invocation, la valeur stockée est zéro, donc la première invocation retournera toujours zéro. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée.
sc_conn_cnt(<ctr>[,<table>]): integer
Retourne le nombre cumulatif de connexions entrantes provenant des compteurs actuellement suivis. Voir également “table_conn_cnt”.
sc_conn_cur(<ctr>[,<table>]): integer
Retourne le nombre actuel de connexions simultanées suivant les mêmes compteurs suivis. Ce nombre est automatiquement incrémenté au début du suivi et décrémenté à la fin du suivi. Voir également “table_conn_cur”.
sc_conn_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen de connexion issu des compteurs actuellement suivis, mesuré en nombre de connexions sur la période configurée dans le tableau. Voir également “table_conn_rate”.
sc_get_gpc(<idx>,<ctr>[,<table>]): integer
Renvoie la valeur du compteur généralisé à l’index <idx> du tableau GPC et associée au compteur actuellement suivi d’ID <ctr> dans la table de persistance du proxy actuel ou dans la table de persistance désignée <table>. <idx> est un entier compris entre 0 et 99 et <ctr> un entier compris entre 0 et 2. Si aucun gpc n’est stocké à cet index, la valeur renvoyée est zéro. Cette opération s’applique uniquement au type de données ‘gpc’ (et non aux types hérités ‘gpc0’ ni ‘gpc1’). Voir également “table_gpc” et “sc_inc_gpc”.
sc_get_gpc0(<ctr>[,<table>]): integer
Renvoie la valeur du premier compteur généralisé associé aux compteurs actuellement suivis. Voir également “table_gpc0” et sc/sc0/sc1/sc2_inc_gpc0.
sc_get_gpc1(<ctr>[,<table>]): integer
Renvoie la valeur du deuxième compteur généralisé associé aux compteurs actuellement suivis. Voir également “table_gpc1” et sc/sc0/sc1/sc2_inc_gpc1.
sc_get_gpt(<idx>,<ctr>[,<table>]): integer
- Renvoie la valeur du premier Tag généralisé à l’index
<idx>du tableau associé au compteur suivi d’identifiant<ctr>et provenant de la table de persistance du proxy actuel ou de la table de persistance désignée<table>.<idx>est un entier compris entre 0 et 99 et<ctr>un entier compris entre 0 et . Si aucun Tag généralisé n’est stocké à cet index, la valeur zéro est renvoyée. Cette opération s’applique uniquement au type de données ‘gpt’ (et non au type de données hérité ‘gpt0’). Voir également “table_gpt”.
sc_get_gpt0(<ctr>[,<table>]): integer
Renvoie la valeur de la première balise générale associée aux compteurs actuellement suivis. Voir également “table_gpt0”.
sc_glitch_cnt(<ctr>[,<table>]): integer
Renvoie le nombre cumulé de perturbations de connexion frontales observées sur les connexions associées aux compteurs actuellement suivis. Ces perturbations entraînent généralement l’abandon de requêtes ou de connexions, de sorte que la valeur renvoyée correspond souvent à des connexions passées. Il n’existe pas de valeur bonne ou mauvaise, mais un client de mauvaise qualité peut occasionnellement provoquer quelques perturbations par connexion, tandis qu’un client très défectueux ou malveillant peut rapidement entraîner l’ajout de milliers d’événements sur une même connexion. Voir également fc_glitches pour le nombre affectant la connexion actuelle, src_glitch_cnt pour les consulter par source, et sc_glitch_rate pour les mesures de taux d’événements.
sc_glitch_rate(<ctr>[,<table>]): integer
Retourne le taux moyen auquel des anomalies de connexion côté client ont été observées pour les compteurs actuellement suivis, mesuré en nombre d’événements sur la période configurée dans le tableau. Ces anomalies provoquent généralement l’abandon de requêtes ou de connexions, de sorte que la valeur renvoyée est souvent liée à des connexions passées. Il n’existe pas de valeur bonne ou mauvaise, mais un client de mauvaise qualité peut occasionnellement provoquer quelques anomalies par connexion, ce qui entraîne un taux faible. Toutefois, un client très malveillant ou frauduleux peut rapidement générer des milliers d’événements par connexion, entraînant un taux élevé. Voir également “table_glitch_rate” et “sc_glitch_cnt”.
sc_gpc_rate(<idx>,<ctr>[,<table>]): integer
Renvoie le taux d’incrémentation moyen du compteur généraliste à l’index <idx> du tableau associé au compteur suivi d’ID <ctr> depuis la table du proxy actuel ou depuis la table de persistance désignée <table>. Il indique la fréquence à laquelle le compteur gpc a été incrémenté durant la période configurée. <idx> est un entier compris entre 0 et 99 et <ctr> un entier compris entre 0 et 2. Notez que le tableau de compteurs ‘gpc_rate’ doit être stocké dans la table de persistance pour qu’une valeur soit renvoyée, car ‘gpc’ ne conserve que le nombre d’événements. Cette fonction ne s’applique qu’au type de données ‘gpc_rate’ (et non aux types hérités ‘gpc0_rate’ ni ‘gpc1_rate’). Voir également “table_gpc_rate”, “sc_get_gpc”, et “sc_inc_gpc”.
sc_gpc0_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen d’incrémentation du premier compteur généralisé associé aux compteurs actuellement suivis. Il indique la fréquence à laquelle le compteur gpc0 a été incrémenté durant la période configurée. Voir également src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, et sc/sc0/sc1/sc2_inc_gpc0..
Notez que le compteur “gpc0_rate” doit être stocké dans la table de persistance pour qu’une valeur soit renvoyée, car « gpc0 » ne conserve que le nombre d’événements.
sc_gpc1_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen d’incrémentation du deuxième Compteur Généralisé à usage général associé aux compteurs actuellement suivis. Il indique la fréquence à laquelle le compteur gpc1 a été incrémenté durant la période configurée. Voir également src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, et sc/sc0/sc1/sc2_inc_gpc1..
Notez que le compteur “gpc1_rate” doit être stocké dans la table de persistance pour qu’une valeur soit renvoyée, car « gpc1 » ne conserve que le nombre d’événements.
sc_http_err_cnt(<ctr>[,<table>]): integer
Retourne le nombre cumulé d’erreurs HTTP provenant des compteurs actuellement suivis. Cela inclut les erreurs de requête ainsi que les réponses avec codes d’erreur 4xx. Voir également “table_http_err_cnt”.
sc_http_err_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen d’erreurs HTTP provenant des compteurs actuellement suivis, mesuré en nombre d’erreurs sur la période configurée dans le tableau. Cela inclut les erreurs de requête ainsi que les réponses avec codes 4xx. Voir également src_http_err_rate.
sc_http_fail_cnt(<ctr>[,<table>]): integer
Retourne le nombre cumulatif d’échecs de réponse HTTP provenant des compteurs actuellement suivis. Cela inclut les erreurs de réponse ainsi que les codes d’état 5xx autres que 501 et 505. Voir également “table_http_fail_cnt”.
sc_http_fail_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen d’échecs de réponses HTTP provenant des compteurs actuellement suivis, mesuré en nombre d’échecs sur la période configurée dans le tableau. Cela inclut les erreurs de réponse ainsi que les codes d’état 5xx autres que 501 et 505. Voir également “table_http_fail_rate”.
sc_http_req_cnt(<ctr>[,<table>]): integer
Retourne le nombre cumulatif de requêtes HTTP provenant des compteurs actuellement suivis. Cela inclut chaque requête démarrée, qu’elle soit valide ou non. Voir également src_http_req_cnt.
sc_http_req_rate(<ctr>[,<table>]): integer
Renvoie le taux moyen de requêtes HTTP issues des compteurs actuellement suivis, mesuré en nombre de requêtes sur la période configurée dans le tableau. Cela inclut toutes les requêtes démarrées, qu’elles soient valides ou non. Voir aussi src_http_req_rate.
sc_inc_gpc(<idx>,<ctr>[,<table>]): integer
Incrémente le compteur généralisé à l’index <idx> du tableau associé au compteur suivi désigné d’ID <ctr> depuis la table de persistance du proxy actuel ou depuis la table de persistance désignée <table>, puis retourne sa nouvelle valeur. <idx> est un entier compris entre 0 et 99 et <ctr> un entier compris entre 0 et 2. Avant la première invocation, la valeur stockée est zéro, donc la première invocation l’augmente à 1 et retourne 1. Cette opération s’applique uniquement au type de données ‘gpc’ (et non aux types hérités ‘gpc0’ ni ‘gpc1’).
sc_inc_gpc0(<ctr>[,<table>]): integer
Incrémente le premier compteur généralisé associé aux compteurs actuellement suivis, puis retourne sa nouvelle valeur. Avant la première invocation, la valeur stockée est zéro, donc la première invocation l’augmente à 1 et retourne 1. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée :
Exemple :
sc_inc_gpc1(<ctr>[,<table>]): integer
Incrémente le second compteur généralisé associé aux compteurs actuellement suivis, puis retourne sa nouvelle valeur. Avant la première invocation, la valeur stockée est zéro, donc la première invocation l’augmente à 1 et retourne 1. Cela est généralement utilisé comme deuxième ACL dans une expression afin de marquer une connexion lorsque la première ACL a été vérifiée.
sc_kbytes_in(<ctr>[,<table>]): integer
Retourne la quantité totale de données client-serveur provenant des compteurs actuellement suivis, exprimée en kilo-octets. Le test est actuellement effectué sur des entiers 32 bits, ce qui limite les valeurs à 4 téraoctets. Voir également “table_kbytes_in”.
sc_kbytes_out(<ctr>[,<table>]): integer
Retourne la quantité totale de données serveur vers client provenant des compteurs actuellement suivis, mesurée en kilo-octets. Le test est actuellement effectué sur des entiers 32 bits, ce qui limite les valeurs à 4 téraoctets. Voir également “table_kbytes_out”.
sc_key(<ctr>): any sc0_key: any sc1_key: any sc2_key: any Retourne la clé utilisée pour correspondre au compteur actuellement suivi.
sc_sess_cnt(<ctr>[,<table>]): integer
Retourne le nombre cumulatif de connexions entrantes qui ont été transformées en sessions, c’est-à-dire acceptées par une règle « tcp-request connection », à partir des compteurs actuellement suivis. Un backend peut compter plus de sessions que de connexions, car chaque connexion peut donner lieu à plusieurs sessions backend si une mise en mémoire tampon HTTP keep-alive est utilisée sur la connexion avec le client. Voir également “table_sess_cnt”.
sc_sess_rate(<ctr>[,<table>]): integer
Renvoie le débit moyen de sessions à partir des compteurs actuellement suivis, mesuré en nombre de sessions sur la période configurée dans le tableau. Une session correspond à une connexion ayant franchi les règles précoces « tcp-request connection ». Un backend peut compter plus de sessions que de connexions, car chaque connexion peut donner lieu à plusieurs sessions backend si une maintien de connexion HTTP (keep-alive) est utilisé sur la connexion avec le client. Voir également “table_sess_rate”.
sc_tracked(<ctr>[,<table>]): boolean
Renvoie true si le compteur de session désigné est actuellement suivi par la session en cours. Cela peut être utile pour déterminer si nous devons ou non définir certaines valeurs dans un en-tête transmis au serveur.
sc_trackers(<ctr>[,<table>]): integer
Retourne le nombre actuel de connexions simultanées suivant les mêmes compteurs suivis. Ce nombre est automatiquement incrémenté au début du suivi et décrémenté à la fin du suivi. Il diffère de sc0_conn_cur en ce qu’il ne repose pas sur des informations stockées, mais sur le compteur de référence de la table (valeur « use » renvoyée par « show table » en ligne de commande). Ce mécanisme peut parfois être plus adapté au suivi de layer7. Il peut être utilisé pour indiquer à un serveur le nombre de connexions simultanées provenant d’une adresse donnée, par exemple.
so_id : entier Renvoie un entier contenant l’identifiant du socket d’écoute actuel. Utile dans les frontaux comportant de nombreuses lignes « bind », ou pour affecter tous les utilisateurs arrivant via un même socket au même serveur.
so_name : chaîne Renvoie une chaîne contenant le nom du socket d’écoute actuel, tel qu’il est défini avec le mot-clé name sur une ligne “bind”. Il peut servir aux mêmes fins que so_id, mais avec des chaînes au lieu d’entiers.
src: ip Cette adresse IP est celle du client de la session. Les règles tcp/http peuvent modifier cette adresse. Elle est de type IP et fonctionne sur les tables IPv4 et IPv6. Sur les tables IPv6, les adresses IPv4 sont mappées vers leur équivalent IPv6 selon la RFC 4291. Notez qu’il s’agit de l’adresse source au niveau TCP, et non de l’adresse d’un client derrière un proxy. Toutefois, si la directive bind “accept-proxy” ou “accept-netscaler-cip” est utilisée, cette adresse peut correspondre à celle d’un client derrière un autre composant compatible avec le protocole PROXY, pour l’ensemble des jeux de règles sauf “tcp-request connection”, qui voit l’adresse réelle. Lorsqu’une connexion entrante passe par une translation d’adresse ou une redirection impliquant le suivi des connexions, l’adresse de destination d’origine avant la redirection sera rapportée. Sur les systèmes Linux, la source et la destination peuvent parfois apparaître inversées si l’option sysctl nf_conntrack_tcp_loose est activée, car une réponse tardive peut réouvrir une connexion expirée et inverser ce qui est considéré comme la source et la destination.
Exemple :
src_bytes_in_rate([<table>]): integer
Identique au convertisseur “table_bytes_in_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_bytes_in_rate([<table>])
src_bytes_out_rate([<table>]): integer
Identique au convertisseur “table_bytes_out_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_bytes_out_rate([<table>])
src_clr_gpc(<idx>[,<table>]): integer
Identique au convertisseur “table_clr_gpc” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_clr_gpc(<idx>[,<table>])
src_clr_gpc0([<table>]): integer
Identique au convertisseur “table_clr_gpc0” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_clr_gpc0([<table>])
src_clr_gpc1([<table>]): integer
Identique au convertisseur “table_clr_gpc1” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_clr_gpc1([<table>])
src_conn_cnt([<table>]): integer
Identique au convertisseur “table_conn_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_conn_cnt([<table>])
src_conn_cur([<table>]): integer
Identique au convertisseur “table_conn_cur” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_conn_cur([<table>])
src_conn_rate([<table>]): integer
Identique au convertisseur “table_conn_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_conn_rate([<table>])
src_get_gpc(<idx>[,<table>]): integer
Identique au convertisseur “table_gpc” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc(<idx>[,<table>])
src_get_gpc0([<table>]): integer
Identique au convertisseur “table_gpc0” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc0([<table>])
src_get_gpc1([<table>]): integer
Identique au convertisseur “table_gpc1” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc1([<table>])
src_get_gpt(<idx>[,<table>]): integer
Identique au convertisseur “table_gpt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpt(<idx>[,<table>])
src_get_gpt0([<table>]): integer
Identique au convertisseur “table_gpt0” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpt0([<table>])
src_glitch_cnt([<table>]): integer
Identique au convertisseur “table_glitch_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_glitch_cnt([<table>])
src_glitch_rate([<table>]): integer
Identique au convertisseur “table_glitch_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_glitch_rate([<table>])
src_gpc_rate(<idx>[,<table>]): integer
Identique au convertisseur “table_gpc_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc_rate(<idx>[,<table>])
src_gpc0_rate([<table>]): integer
Identique au convertisseur “table_gpc0_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc0_rate([<table>])
src_gpc1_rate([<table>]): integer
Identique au convertisseur “table_gpc1_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_gpc1_rate([<table>])
src_http_err_cnt([<table>]): integer
Identique au convertisseur “table_http_err_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_err_cnt([<table>])
src_http_err_rate([<table>]): integer
Identique au convertisseur “table_http_err_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_err_rate([<table>])
src_http_fail_cnt([<table>]): integer
Identique au convertisseur “table_http_fail_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_fail_cnt([<table>])
src_http_fail_rate([<table>]): integer
Identique au convertisseur “table_http_fail_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_fail_rate([<table>])
src_http_req_cnt([<table>]): integer
Identique au convertisseur “table_http_req_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_req_cnt([<table>])
src_http_req_rate([<table>]): integer
Identique au convertisseur “table_http_req_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_http_req_rate([<table>])
src_inc_gpc(<idx>[,<table>]): integer
Identique au convertisseur “src_inc_gpc” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_inc_gpc(<idx>[,<table>])
src_inc_gpc0([<table>]): integer
Identique au convertisseur “src_inc_gpc0” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_inc_gpc0([<table>])
src_inc_gpc1([<table>]): integer
Identique au convertisseur “src_inc_gpc1” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_inc_gpc1([<table>])
src_is_local : boolean Renvoie true si l’adresse source de la connexion entrante est locale au système, ou false si l’adresse n’existe pas sur le système, ce qui signifie qu’elle provient d’une machine distante. Notez que les adresses UNIX sont considérées comme locales. Il peut être utile d’appliquer certaines restrictions d’accès en fonction de l’origine du client (par exemple, exiger une authentification ou HTTPS pour les machines distantes). Veuillez noter que cette vérification implique quelques appels système, il est donc préférable de la réaliser une seule fois par connexion.
src_kbytes_in([<table>]): integer
Identique au convertisseur “table_kbytes_in” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_kbytes_in([<table>])
src_kbytes_out([<table>]): integer
Identique au convertisseur “table_kbytes_out” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_kbytes_out([<table>])
src_port : integer Renvoie une valeur entière correspondant au port source TCP de la connexion côté client, c’est-à-dire le port depuis lequel le client s’est connecté. Les règles tcp/http peuvent modifier cette adresse. L’utilisation de cette fonction est très limitée, car les protocoles modernes ne tiennent pas compte des ports sources de nos jours.
src_sess_cnt([<table>]): integer
Identique au convertisseur “table_sess_cnt” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_sess_cnt([<table>])
src_sess_rate([<table>]): integer
Identique au convertisseur “table_sess_rate” avec la clé définie sur l’adresse source de la connexion entrante.
Équivalent à : src,table_sess_rate([<table>])
src_updt_conn_cnt([<table>]): integer
Crée ou met à jour l’entrée associée à l’adresse source de la connexion entrante dans la table de persistance du proxy actuel ou dans la table de persistance désignée. Cette table doit être configurée pour stocker le type de données “conn_cnt”, sinon la correspondance sera ignorée. Le compteur actuel est incrémenté de un, et le minuteur d’expiration actualisé. Le compteur mis à jour est retourné, de sorte que cette correspondance ne peut pas retourner zéro. Cette fonctionnalité était utilisée pour rejeter les abusateurs de service en fonction de leur adresse source. Remarque : il est recommandé d’utiliser les actions plus complètes « track-sc* » dans les règles « tcp-request » à la place.
Exemple :
srv_id : entier Renvoie un entier contenant l’identifiant du serveur lors du traitement de la réponse. Bien qu’il soit presque exclusivement utilisé avec les ACLs, il peut également être utilisé pour la journalisation ou le débogage. Il peut également être utilisé dans un ensemble de règles tcp-check ou http-check.
srv_name : chaîne Renvoie une chaîne contenant le nom du serveur lors du traitement de la réponse. Bien qu’il soit presque exclusivement utilisé avec les ACLs, il peut également être utilisé pour la journalisation ou le débogage. Il peut également être utilisé dans un ensemble de règles tcp-check ou http-check.
txn.conn_retries : entier Renvoie le nombre de tentatives de connexion subies par ce flux lors de la tentative de connexion au serveur. Cette valeur peut varier tant que la connexion n’est pas pleinement établie. Pour les connexions HTTP, la valeur peut être affectée par les tentatives de L7.
txn.redispatched : boolean Retourne true si la connexion a fait l’objet d’une redistribution après une tentative de réessai, conformément à la configuration « option redispatch ». Cette valeur peut évoluer tant que la connexion n’est pas entièrement établie. Pour les connexions HTTP, la valeur peut être influencée par les réessais L7.
7.3.4. Récupération des échantillons au niveau 5
Le niveau 5 décrit généralement la couche session, qui, dans HAProxy, correspond le plus près de la session une fois que toutes les négociations de connexion sont terminées, mais avant que tout contenu ne soit disponible. Les méthodes de récupération décrites ici sont utilisables aussi bas que les règles « tcp-request content », à moins qu’elles n’exigent des informations futures. Celles-ci incluent généralement les résultats des négociations SSL.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
51d.all(<prop>[,<prop>*]): string
Retourne les valeurs des propriétés demandées sous forme de chaîne, où les valeurs sont séparées par le délimiteur spécifié par « 51degrees-property-separator ». L’appareil est identifié à l’aide de tous les en-têtes HTTP importants de la requête. La fonction peut recevoir jusqu’à cinq noms de propriété ; si un nom de propriété n’est pas trouvé, la valeur « NoData » est retournée.
Exemple :
bs.aborted : boolean Retourne true si une interruption a été reçue du serveur pour le flux courant. Sinon, retourne false.
bs.debug_str([<bitmap>]): string
Cette fonction est destinée à être utilisée par les développeurs lors de séances de dépannage complexes. Elle extrait certains états internes des couches inférieures du flux et de la connexion backend, puis les organise sous forme de chaîne, généralement sous la forme d’une série de paires « nom=valeur » séparées par des espaces. L’argument facultatif <bitmap> indique quelle(s) couche(s) extraire, et correspond à une opération OU arithmétique (ou une somme) des valeurs suivantes : - couche socket : 16 - couche connexion : 8 - couche transport (par exemple SSL) : 4 - connexion mux : 2 - flux mux : 1
Ces valeurs peuvent évoluer d’une version à l’autre. La valeur par défaut zéro est spéciale et active toutes les couches. Veuillez ne pas vous fier à la sortie de cette fonction pour un suivi de production à long terme. Elle est destinée à évoluer même au sein d’une branche stable, au fur et à mesure que les besoins en détails croissent. Un cas d’utilisation typique consiste à concaténer ces informations à la fin d’un format de journal, conjointement avec fs.debug_str(). Exemple :
bs.id : entier Retourne l’identifiant du flux du multiplexeur côté serveur. Il incombe au multiplexeur de retourner les informations appropriées.
bs.rst_code: integer Retourne le code de réinitialisation reçu du serveur pour le flux courant. Le code du cadre H2 RST_STREAM ou du cadre QUIC STOP_SENDING reçu du serveur est retourné. L’extraction d’échantillon échoue si aucun arrêt n’a été reçu ou si le flux serveur n’est pas un flux H2/QUIC.
fs.aborted : boolean Retourne true si une interruption a été reçue du client pour le flux actuel. Sinon, retourne false.
fs.debug_str([<bitmap>]): string
Cette fonction est destinée à être utilisée par les développeurs lors de séances de dépannage complexes. Elle extrait certains états internes des couches inférieures du flux frontal et de la connexion, puis les organise sous forme de chaîne, généralement sous la forme d’une série de paires « nom=valeur » séparées par des espaces. L’argument facultatif <bitmap> indique la ou les couches dont il faut extraire les informations, et correspond à une opération OU arithmétique (ou une somme) des valeurs suivantes : - couche socket : 16 - couche connexion : 8 - couche transport (par exemple SSL) : 4 - connexion mux : 2 - flux mux : 1
Ces valeurs peuvent évoluer d’une version à l’autre. La valeur par défaut zéro est spéciale et active toutes les couches. Veuillez ne pas vous fier à la sortie de cette fonction pour un suivi de production à long terme. Elle est destinée à évoluer même au sein d’une branche stable, au fur et à mesure que la nécessité d’informations plus détaillées se fait sentir. Un cas d’utilisation typique consiste à concaténer ces informations à la fin d’un format de journal, conjointement avec bs.debug_str(). Exemple :
fs.id : entier Renvoie l’identifiant de flux du multiplexeur côté client. Il incombe au multiplexeur de renvoyer les informations appropriées. Par exemple, pour un TCP brut, 0 est toujours renvoyé, car aucun flux n’existe.
fs.rst_code: integer Retourne le code de réinitialisation reçu du client pour le flux courant. Le code du cadre H2 RST_STREAM ou du cadre QUIC STOP_SENDING reçu du client est retourné. L’extraction d’échantillon échoue si aucun arrêt n’a été reçu ou si le flux client n’est pas un flux H2/QUIC.
ssl_bc: boolean Retourne true lorsque la connexion vers le backend a été établie via une couche de transport SSL/TLS et a été déchiffrée localement. Cela signifie que la connexion sortante a été établie vers un serveur ayant l’option “ssl” activée. Cette information peut être utilisée dans une règle tcp-check ou http-check.
ssl_bc_alg_keysize : entier Retourne la taille de la clé du chiffrement symétrique pris en charge, en bits, lorsque la connexion sortante a été établie sur un transport SSL/TLS. Peut être utilisé dans un ensemble de règles tcp-check ou http-check.
ssl_bc_alpn : chaîne Cette directive extrait le champ de négociation de protocole au niveau de la couche application d’une connexion sortante effectuée via une couche transport TLS. Le résultat est une chaîne contenant le nom du protocole négocié avec le serveur. La bibliothèque SSL doit avoir été compilée avec le support des extensions TLS activé (vérifiez haproxy -vv). Notez que l’extension TLS ALPN n’est pas annoncée à moins que le mot-clé “alpn” sur la ligne “server” ne spécifie une liste de protocoles. En outre, rien ne force le serveur à choisir un protocole parmi cette liste ; un autre protocole peut être demandé. L’extension TLS ALPN est destinée à remplacer l’extension TLS NPN. Voir également “ssl_bc_npn”. Elle peut être utilisée dans un ensemble de règles tcp-check ou http-check.
ssl_bc_cipher: chaîne Retourne le nom du chiffrement utilisé lors de la connexion sortante établie sur un transport SSL/TLS. Peut être utilisé dans un ensemble de règles tcp-check ou http-check.
ssl_bc_client_early_traffic_secret : chaîne Renvoie le CLIENT_EARLY_TRAFFIC_SECRET sous forme de chaîne hexadécimale pour la connexion vers le serveur lorsque la connexion sortante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation des clés OpenSSL afin de générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_client_handshake_traffic_secret : chaîne Renvoie le CLIENT_HANDSHAKE_TRAFFIC_SECRET sous forme de chaîne héxadécimale pour la connexion bacl lorsque la connexion sortante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’une des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_client_random : binaire Renvoie la valeur aléatoire du client de la connexion vers le serveur backend lorsque la connexion entrante a été établie via un transport SSL/TLS. Utile pour décrypter le trafic envoyé à l’aide de chiffres éphémères. Nécessite OpenSSL >= 1.1.0 ou BoringSSL. Peut être utilisé dans une règle tcp-check ou http-check.
ssl_bc_client_traffic_secret_0 : chaîne Retourne le CLIENT_TRAFFIC_SECRET_0 sous forme de chaîne héxadécimale pour la connexion vers le back-end lorsque la connexion sortante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_curve : chaîne Retourne le nom de la courbe utilisée dans l’accord de clé lorsqu’une connexion sortante a été établie sur un transport SSL/TLS. Cela nécessite OpenSSL >= 3.0.0 ou AWS-LC >= 1.57.0.
ssl_bc_early_exporter_secret: chaîne Retourne le EARLY_EXPORTER_SECRET sous forme de chaîne héxadécimale pour la connexion vers le serveur backend lorsque la connexion sortante a été établie sur une couche transport TLS 1.3. Nécessite OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation des clés OpenSSL afin de générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_err : entier Lorsque la connexion sortante a été établie via une couche de transport SSL/TLS, renvoie l’ID de la dernière erreur de la première pile d’erreurs levée du côté du backend. Cette valeur peut indiquer des erreurs d’établissement de connexion ainsi que d’autres erreurs de lecture ou d’écriture survenues durant la durée de vie de la connexion. Pour obtenir une description textuelle de ce code d’erreur, vous pouvez soit utiliser l’extraction d’échantillon “ssl_bc_err_str”, soit utiliser la commande “openssl errstr” (qui prend en paramètre un code d’erreur sous forme hexadécimale). Veuillez consulter la documentation de votre bibliothèque SSL pour obtenir la liste exhaustive des codes d’erreur.
ssl_bc_err_str : chaîne Lorsque la connexion sortante a été établie via une couche de transport SSL/TLS, renvoie une représentation sous forme de chaîne du dernier erreur de la première pile d’erreurs levée sur la connexion du point de vue du backend. Voir également “ssl_fc_err”.
ssl_bc_exporter_secret: chaîne Retourne le EXPORTER_SECRET sous forme de chaîne héxadécimale pour la connexion vers le back-end lorsque la connexion sortante a été établie sur une couche transport TLS 1.3. Nécessite OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_is_resumed : boolean Retourne true lorsque la connexion vers le serveur backend a été établie via un transport SSL/TLS et que la nouvelle session SSL a été rétablie à partir d’une session mise en cache ou d’un jeton TLS. Peut être utilisée dans une règle tcp-check ou http-check.
ssl_bc_npn : chaîne Cette option extrait le champ Next Protocol Negotiation d’une connexion sortante effectuée via une couche transport TLS. Le résultat est une chaîne contenant le nom du protocole négocié avec le serveur. La bibliothèque SSL doit avoir été compilée avec le support des extensions TLS activé (vérifiez haproxy -vv). Notez que l’extension TLS NPN n’est pas annoncée à moins que le mot-clé “npn” sur la ligne “server” ne spécifie une liste de protocoles. De plus, rien ne force le serveur à choisir un protocole parmi cette liste ; un autre protocole peut être utilisé. Veuillez noter que l’extension TLS NPN a été remplacée par ALPN. Cette option peut être utilisée dans un ensemble de règles tcp-check ou http-check.
ssl_bc_protocol : chaîne Retourne le nom du protocole utilisé lors de la connexion sortante établie sur une couche transport SSL/TLS. Peut être utilisé dans un ensemble de règles tcp-check ou http-check.
ssl_bc_server_handshake_traffic_secret : chaîne Renvoie le SERVER_HANDSHAKE_TRAFFIC_SECRET sous forme de chaîne héxadécimale pour la connexion retour lorsque la connexion sortante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’une des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_server_random : binaire Renvoie la valeur aléatoire du serveur de la connexion côté serveur lorsque la connexion entrante a été établie via une couche de transport SSL/TLS. Utile pour décrypter le trafic envoyé à l’aide de chiffres éphémères. Nécessite OpenSSL >= 1.1.0 ou BoringSSL. Peut être utilisé dans une règle tcp-check ou http-check.
ssl_bc_server_traffic_secret_0 : chaîne Retourne le SERVER_TRAFFIC_SECRET_0 sous forme de chaîne hexadécimale pour la connexion retour lorsque la connexion sortante a été établie sur une couche transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_bc_session_id: binaire Retourne l’ID SSL de la connexion vers le serveur backend lorsque la connexion sortante a été établie sur une couche transport SSL/TLS. Utile pour la journalisation afin de savoir si la session a été réutilisée ou non. Peut être utilisé dans une règle tcp-check ou http-check.
ssl_bc_session_key : binaire Retourne la clé principale de session SSL de la connexion vers le back-end lorsque la connexion sortante a été établie sur un transport SSL/TLS. Utile pour décrypter le trafic envoyé à l’aide de chiffres éphémères. Nécessite OpenSSL >= 1.1.0 ou BoringSSL. Peut être utilisé dans un ensemble de règles tcp-check ou http-check.
ssl_bc_sni : chaîne Cette option récupère le champ de l’extension TLS SNI (Server Name Indication) utilisé lors de la connexion au serveur. Le résultat (lorsqu’il est présent) est généralement une chaîne correspondant au nom d’hôte HTTPS (253 caractères ou moins). L’utilisation principale est à des fins de journalisation et de débogage (par exemple, déterminer quel SNI a été utilisé lors de l’établissement de la connexion, afin de le comparer à ce que le serveur a vu).
ssl_bc_unique_id: binaire Lorsque la connexion sortante a été établie sur une couche transport SSL/TLS, renvoie l’identifiant TLS unique tel qu défini dans la section 3 de RFC5929 RFC5929 . L’identifiant unique peut être encodé en base64 à l’aide du convertisseur : “ssl_bc_unique_id,base64”. Il peut être utilisé dans une règle tcp-check ou http-check.
ssl_bc_use_keysize : entier Renvoie la taille de la clé du chiffrement symétrique utilisé, en bits, lorsqu’une connexion sortante a été établie sur un transport SSL/TLS. Cette valeur peut être utilisée dans un ensemble de règles tcp-check ou http-check.
ssl_c_ca_err : integer Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie l’ID de la première erreur détectée lors de la vérification du certificat client à une profondeur supérieure à 0, ou 0 si aucune erreur n’a été rencontrée au cours de ce processus de vérification. Veuillez consulter la documentation de votre bibliothèque SSL pour obtenir la liste exhaustive des codes d’erreur.
ssl_c_ca_err_depth: entier Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, retourne la profondeur dans la chaîne de certification de la première erreur détectée lors de la vérification du certificat client. Si aucune erreur n’est détectée, la valeur renvoyée est 0.
ssl_c_chain_der : binaire Renvoie le certificat de chaîne au format DER présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une ACL, les valeurs à comparer peuvent être fournies sous forme hexadécimale. Le résultat peut être analysé à l’aide de toute bibliothèque acceptant des données ASN.1 au format DER. Cette fonction ne prend pas en charge les sessions réinitialisées.
ssl_c_der: binary Retourne le certificat au format DER présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une ACL, les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_c_err : integer Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie l’identifiant de la première erreur détectée lors de la vérification au niveau de profondeur 0, ou 0 si aucune erreur n’a été détectée au cours de ce processus de vérification. Veuillez consulter la documentation de votre bibliothèque SSL pour obtenir la liste exhaustive des codes d’erreur.
ssl_c_i_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie le nom distingué complet de l’émetteur du certificat présenté par le client lorsque aucun <entry> n’est spécifié, ou la valeur du premier élément trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième élément à partir du beginning/end du DN. Par exemple, « ssl_c_i_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_c_i_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez modifier uniquement le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_c_i_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme mal formée et aucune donnée n’est renvoyée.
ssl_c_key_alg : chaîne Retourne le nom de l’algorithme utilisé pour générer la clé du certificat présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS.
ssl_c_notafter : chaîne Retourne la date de fin présentée par le client sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion entrante a été établie via une couche de transport SSL/TLS.
ssl_c_notbefore : chaîne Retourne la date de début fournie par le client sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion entrante a été établie via une couche de transport SSL/TLS.
ssl_c_r_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS et qu’elle est correctement validée à l’aide du fichier CA configuré, renvoie le nom distingué complet de l’autorité de certification racine du certificat présenté par le client lorsque aucun <entry> n’est spécifié, ou la valeur du premier élément trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième élément donné à partir du beginning/end du DN. Par exemple, « ssl_c_r_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_c_r_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez modifier uniquement le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_c_r_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme malformée et aucune donnée n’est renvoyée.
ssl_c_s_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie le nom distingué complet du sujet du certificat présenté par le client lorsque aucun <entry> n’est spécifié, ou la valeur du premier élément trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième élément à partir du beginning/end du DN. Par exemple, « ssl_c_s_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_c_s_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez uniquement modifier le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_c_s_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme malformée et aucune donnée n’est renvoyée.
ssl_c_san: chaîne Lorsque la connexion entrante a été établie via une couche de transport SSL/TLS, et qu’un certificat client a été fourni. Retourne une chaîne de champs Nom de sujet alternatif (Subject Alt Name) séparés par des virgules contenus dans le certificat fourni.
Cela peut être utilisé pour inspecter le certificat client.
Exemple :
aura pour résultat :
ssl_c_serial : binary Renvoie le numéro de série du certificat présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une règle d’accès, les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_c_sha1: binary Retourne l’empreinte SHA-1 du certificat présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS. Cette information peut être utilisée pour associer un client à un serveur, ou pour la transmettre à un serveur. Notez que la sortie est binaire, donc si vous souhaitez transmettre cette empreinte au serveur, vous devez la coder en hexadécimal ou en base64, comme illustré dans l’exemple ci-dessous :
Exemple :
ssl_c_sig_alg : chaîne Retourne le nom de l’algorithme utilisé pour signer le certificat présenté par le client lorsque la connexion entrante a été établie sur un transport SSL/TLS.
ssl_c_used : boolean Retourne true si la session SSL actuelle utilise un certificat client, même si la connexion actuelle utilise une reprise de session SSL. Voir également “ssl_fc_has_crt”.
ssl_c_verify: integer Retourne l’identifiant d’erreur du résultat de vérification lorsque la connexion entrante a été établie sur une couche transport SSL/TLS, sinon zéro si aucune erreur n’est détectée. Veuillez vous référer à la documentation de votre bibliothèque SSL pour obtenir la liste exhaustive des codes d’erreur.
ssl_c_version: integer Retourne la version du certificat présenté par le client lors de la connexion entrante établie sur un transport SSL/TLS.
ssl_f_der: binary Retourne le certificat au format DER présenté par le frontal lors de la connexion entrante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une ACL, les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_f_i_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie le nom distingué complet de l’émetteur du certificat présenté par le frontal lorsque aucun <entry> n’est spécifié, ou la valeur du premier champ donné trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du n-ième champ donné à partir du beginning/end du DN. Par exemple, « ssl_f_i_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_f_i_dn(CN) » renvoie le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez uniquement modifier le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_f_i_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme mal formée et aucune donnée n’est renvoyée.
ssl_f_key_alg : chaîne Retourne le nom de l’algorithme utilisé pour générer la clé du certificat présenté par le frontal lors de la connexion entrante établie sur un transport SSL/TLS.
ssl_f_notafter : chaîne Retourne la date de fin présentée par le frontal sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion entrante a été établie via une couche de transport SSL/TLS.
ssl_f_notbefore : chaîne Retourne la date de début présentée par le frontal sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion entrante a été établie via une couche de transport SSL/TLS.
ssl_f_s_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie le nom distingué complet du sujet du certificat présenté par le frontal lorsque aucun <entry> n’est spécifié, ou la valeur du premier champ donné trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième champ donné à partir du beginning/end du DN. Par exemple, « ssl_f_s_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_f_s_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez modifier uniquement le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_f_s_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme malformée et aucune donnée n’est renvoyée.
ssl_f_serial: binary Renvoie le numéro de série du certificat présenté par le frontal lors de la connexion entrante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une règle d’accès (ACL), les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_f_sha1 : binaire Retourne l’empreinte SHA-1 du certificat présenté par le frontal lors de la connexion entrante établie sur un transport SSL/TLS. Cela permet de savoir quel certificat a été sélectionné à l’aide de SNI.
ssl_f_sig_alg : chaîne Retourne le nom de l’algorithme utilisé pour signer le certificat présenté par le frontal lorsque la connexion entrante a été établie sur un transport SSL/TLS.
ssl_f_version : integer Renvoie la version du certificat présenté par le frontal lors de la connexion entrante établie sur un transport SSL/TLS.
ssl_fc : boolean Retourne true lorsque la connexion frontale a été établie via une couche de transport SSL/TLS et a été déchiffrée localement. Cela signifie qu’elle correspond à une socket déclarée avec une ligne “bind” comportant l’option “ssl”.
Exemple :
ssl_fc_alg_keysize : entier Renvoie la taille de la clé du chiffrement symétrique pris en charge, en bits, lorsque la connexion entrante a été établie sur un transport SSL/TLS.
ssl_fc_alpn : chaîne Cette directive extrait le champ de négociation de protocole au niveau de la couche application d’une connexion entrante effectuée via une couche transport TLS et déchiffrée localement par HAProxy. Le résultat est une chaîne contenant le nom du protocole annoncé par le client. La bibliothèque SSL doit avoir été compilée avec le support des extensions TLS activé (vérifiez haproxy -vv). Notez que l’extension TLS ALPN n’est pas annoncée à moins que le mot-clé « alpn » sur la ligne « bind » ne spécifie une liste de protocoles. En outre, rien ne force le client à choisir un protocole parmi cette liste ; tout autre protocole peut être demandé. L’extension TLS ALPN est destinée à remplacer l’extension TLS NPN. Voir également “ssl_fc_npn”.
ssl_fc_cipher : chaîne Renvoie le nom du chiffrement utilisé lorsque la connexion entrante a été établie sur une couche transport SSL/TLS.
ssl_fc_cipherlist_bin([<filter_option>]): binary
Renvoie la forme binaire de la liste des chiffres du message ClientHello. La longueur maximale de la valeur renvoyée est limitée par la taille du tampon partagé de capture contrôlée par le paramètre “tune.ssl.capture-buffer-size”.
La configuration <filter_option> permet de filtrer les données renvoyées. Valeurs acceptées :
Exemple :
ssl_fc_cipherlist_hex([<filter_option>]): string
Renvoie la forme binaire de la liste des chiffres du client hello encodée en hexadécimal. La longueur maximale de la valeur renvoyée est limitée par la taille du tampon de capture partagé contrôlée par le paramètre “tune.ssl.capture-buffer-size”. Le paramètre <filter_option> permet de filtrer les données renvoyées.
Valeurs acceptées :
ssl_fc_cipherlist_str([<filter_option>]): string
Renvoie la forme texte décodée de la liste des chiffres du client hello. La longueur maximale de la valeur renvoyée est limitée par la taille du tampon de capture partagé contrôlée par le paramètre “tune.ssl.capture-buffer-size”.
Le paramètre <filter_option> permet de filtrer les données renvoyées. Valeurs acceptées :
Notez que cet extrait d’échantillonnage n’est disponible qu’avec OpenSSL >= 1.0.2. Si la fonction n’est pas activée, cet extrait d’échantillonnage retourne le hachage tel que “ssl_fc_cipherlist_xxh”.
ssl_fc_cipherlist_xxh: integer Renvoie un hachage xxh64 de la liste de chiffrements. Ce hachage ne peut être retourné que si la valeur “tune.ssl.capture-buffer-size” est définie à une valeur supérieure à 0, mais il prend en compte l’intégralité des données de la liste de chiffrements.
ssl_fc_client_early_traffic_secret : chaîne Retourne le CLIENT_EARLY_TRAFFIC_SECRET sous forme hexadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur un transport TLS 1.3. Nécessite OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_client_handshake_traffic_secret : chaîne Renvoie le CLIENT_HANDSHAKE_TRAFFIC_SECRET sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_client_random : binaire Renvoie la valeur aléatoire du client de la connexion frontale lorsque la connexion entrante a été établie via un transport SSL/TLS. Utile pour décrypter le trafic envoyé à l’aide de chiffres éphémères. Cela nécessite OpenSSL >= 1.1.0, ou BoringSSL.
ssl_fc_client_traffic_secret_0 : chaîne Retourne le CLIENT_TRAFFIC_SECRET_0 sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_crtname : chaîne Renvoie le nom du certificat sélectionné pour la connexion entrante SSL/TLS. Ce nom correspond à celui affiché par la commande « show ssl cert » : il peut s’agir du nom de fichier avec son chemin relatif ou absolu, ou d’un alias, selon la manière dont le certificat a été déclaré dans la configuration.
Exemple :
ssl_fc_curve : chaîne Retourne le nom de la courbe utilisée dans l’accord de clé lorsque la connexion entrante a été établie sur un transport SSL/TLS. Cela nécessite OpenSSL >= 3.0.0.
ssl_fc_early_rcvd : boolean Retourne true si des données anticipées ont été reçues sur cette connexion, indépendamment du fait que la négociation soit depuis terminée. Ce champ n’a pas d’utilité pratique pour le traitement du trafic, mais il constitue pratiquement la seule manière de « détecter » qu’un client a utilisé le 0-RTT pour envoyer des données anticipées, et peut s’avérer utile lors du débogage, car les autres alternatives consistent à capturer le trafic réseau ou à journaliser les indicateurs de la connexion frontale et à les comparer dans le code. Il peut également être utile pour obtenir des statistiques sur les capacités des clients. Voir également “ssl_fc_has_early”.
ssl_fc_early_exporter_secret: chaîne Retourne le EARLY_EXPORTER_SECRET sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur une couche transport TLS 1.3. Nécessite OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation des clés OpenSSL afin de générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_ecformats_bin : binaire Retourne la forme binaire des formats de point de courbe elliptique pris en charge dans le client hello. La longueur maximale de la valeur retournée est limitée par la taille du tampon de capture partagé contrôlée par le paramètre “tune.ssl.capture-buffer-size”.
Exemple :
ssl_fc_eclist_bin([<filter_option>]): binary
Renvoie la forme binaire des courbes elliptiques prises en charge dans le message ClientHello. La longueur maximale renvoyée est limitée par la taille du tampon de capture partagé contrôlée par le paramètre “tune.ssl.capture-buffer-size”. La configuration <filter_option> permet de filtrer les données renvoyées. Valeurs acceptées :
Exemple :
ssl_fc_err : entier Lorsque la connexion entrante a été établie via une couche de transport SSL/TLS, renvoie l’ID de la dernière erreur de la première pile d’erreurs levée du côté frontal, ou 0 si aucune erreur n’a été rencontrée. Cette valeur peut être utilisée pour identifier les erreurs liées à l’établissement de la connexion autres que celles liées à la vérification (comme un désaccord sur le chiffrement), ainsi que d’autres erreurs de lecture ou d’écriture survenues pendant la durée de vie de la connexion. Toute erreur survenue lors du processus de vérification du certificat client ne sera pas signalée via cette récupération, mais via les récupérations existantes “ssl_c_err”, “ssl_c_ca_err” et “ssl_c_ca_err_depth”. Pour obtenir une description textuelle de ce code d’erreur, vous pouvez soit utiliser l’exemple de récupération “ssl_fc_err_str”, soit utiliser la commande “openssl errstr” (qui prend en paramètre un code d’erreur sous forme hexadécimale). Veuillez consulter la documentation de votre bibliothèque SSL pour obtenir la liste exhaustive des codes d’erreur.
ssl_fc_err_str : chaîne Lorsqu’une connexion entrante a été établie via une couche de transport SSL/TLS, renvoie une représentation sous forme de chaîne du dernier erreur de la première pile d’erreurs levée du côté frontal. Aucune erreur survenue lors du processus de vérification du certificat client ne sera signalée via cette récupération. Voir également “ssl_fc_err”.
ssl_fc_exporter_secret: chaîne Retourne le EXPORTER_SECRET sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie via un transport TLS 1.3. Nécessite OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation des clés OpenSSL afin de générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_extlist_bin([<filter_option>]): binary
Renvoie la forme binaire de la liste des extensions ClientHello. La longueur maximale de la valeur renvoyée est limitée par la taille du tampon partagé contrôlée par le paramètre “tune.ssl.capture-buffer-size”.
Le paramètre <filter_option> permet de filtrer les données renvoyées. Valeurs acceptées :
Exemple :
ssl_fc_has_crt : boolean Renvoie true si un certificat client est présent dans une connexion entrante via le transport SSL/TLS. Utile si l’instruction ‘verify’ est définie sur ‘optional’. Remarque : lors d’une reprise de session SSL avec ID de session ou ticket TLS, le certificat client n’est pas présent dans la connexion actuelle, mais peut être récupéré depuis le cache ou le ticket. Préférez donc “ssl_c_used” si vous souhaitez vérifier si la session SSL actuelle utilise un certificat client.
ssl_fc_has_early : boolean Renvoie true si des données anticipées ont été envoyées, et que la négociation n’est pas encore terminée. Étant donné les implications en matière de sécurité, il peut être utile de refuser ces données, ou d’attendre la fin de la négociation (via l’action « wait-for-handshake »). Voir également “ssl_fc_early_rcvd”.
ssl_fc_has_sni : boolean Cette option vérifie la présence d’une extension TLS Server Name Indication (SNI) dans une connexion entrante établie sur un transport SSL/TLS. Retourne true lorsque la connexion entrante inclut un champ SNI TLS. Cette fonctionnalité nécessite que la bibliothèque SSL soit compilée avec le support des extensions TLS activé (vérifiez HAProxy -vv).
ssl_fc_is_resumed : boolean Retourne true si la session SSL/TLS a été rétablie grâce à l’utilisation du cache de session SSL ou des tickets TLS sur une connexion entrante via une couche de transport SSL/TLS.
ssl_fc_npn : chaîne Cette directive extrait le champ Next Protocol Negotiation d’une connexion entrante effectuée via une couche transport TLS et déchiffrée localement par HAProxy. Le résultat est une chaîne contenant le nom du protocole annoncé par le client. La bibliothèque SSL doit avoir été compilée avec le support des extensions TLS activé (vérifiez haproxy -vv). Notez que l’extension TLS NPN n’est pas annoncée à moins que le mot-clé “npn” dans la ligne “bind” ne spécifie une liste de protocoles. En outre, rien n’oblige le client à choisir un protocole parmi cette liste ; un autre protocole peut être demandé. Veuillez noter que l’extension TLS NPN a été remplacée par ALPN.
ssl_fc_protocol : chaîne Retourne le nom du protocole utilisé lorsque la connexion entrante a été établie sur une couche transport SSL/TLS.
ssl_fc_protocol_hello_id : integer Le numéro de version du protocole TLS utilisé par le client pour la communication pendant la session, tel qu’indiqué dans le message Client Hello. Cette valeur n’est renvoyée que si la valeur “tune.ssl.capture-buffer-size” est supérieure à 0.
Exemple :
ssl_fc_server_handshake_traffic_secret : chaîne Renvoie le SERVER_HANDSHAKE_TRAFFIC_SECRET sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur un transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation OpenSSL pour générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_server_random : binaire Renvoie la valeur aléatoire du serveur de la connexion frontale lorsque la connexion entrante a été établie via un transport SSL/TLS. Utile pour décrypter le trafic envoyé à l’aide de chiffres éphémères. Cela nécessite OpenSSL >= 1.1.0, ou BoringSSL.
ssl_fc_server_traffic_secret_0 : chaîne Retourne le SERVER_TRAFFIC_SECRET_0 sous forme de chaîne héxadécimale pour la connexion frontale lorsque la connexion entrante a été établie sur une couche transport TLS 1.3. Exige OpenSSL >= 1.1.1. Il s’agit l’un des clés extraites par le rappel de journalisation des clés OpenSSL afin de générer le fichier SSLKEYLOGFILE. La journalisation des clés SSL doit être activée avec « tune.ssl.keylog on » dans la section globale. Voir également “tune.ssl.keylog”
ssl_fc_session_id : binaire Renvoie l’ID SSL de la connexion frontale lorsque la connexion entrante a été établie via une couche de transport SSL/TLS. Utile pour associer un client donné à un serveur. Il est important de noter que certains navigateurs actualisent leur ID de session tous les quelques minutes.
ssl_fc_session_key : binaire Retourne la clé principale de session SSL de la connexion frontale lorsque la connexion entrante a été établie via une couche de transport SSL/TLS. Utile pour décrypter le trafic envoyé en utilisant des chiffres éphémères. Nécessite OpenSSL >= 1.1.0, ou BoringSSL.
ssl_fc_sigalgs_bin([<filter_option>]): binary
Renvoie le contenu de l’extension TLS signatures_algorithms (13) présentée lors de l’échange Client Hello. Il s’agit d’une liste binaire de algorithmes sur 2 octets, définis dans le RFC TLS : https://datatracker.ietf.org/doc/html/rfc8446#section-4.2.3 .
Cette valeur ne peut être retournée que si la valeur “tune.ssl.capture-buffer-size” est définie supérieure à 0.
La configuration de <filter_option> permet de filtrer les données retournées. Valeurs acceptées : 0 : retourner la liste complète des chiffrements (par défaut), 1 : exclure les valeurs GREASE (RFC8701) de la sortie
ssl_fc_sni : chaîne Cette option extrait le champ de l’extension TLS Server Name Indication (SNI) d’une connexion entrante effectuée via une couche de transport SSL/TLS et déchiffrée localement par HAProxy. Le résultat (lorsqu’il est présent) est généralement une chaîne correspondant au nom d’hôte HTTPS (253 caractères ou moins). La bibliothèque SSL doit avoir été compilée avec le support des extensions TLS activé (vérifiez HAProxy -vv).
Cette récupération diffère de “req.ssl_sni” ci-dessus en ce qu’elle s’applique à la connexion étant déchiffrée par HAProxy et non aux contenus SSL étant simplement acheminés. Voir également “ssl_fc_sni_end” et “ssl_fc_sni_reg” ci-dessous. Cela nécessite que la bibliothèque SSL soit compilée avec le support des extensions TLS activé (vérifier HAProxy -vv).
ATTENTION ! Sauf dans des conditions très spécifiques, il n’est généralement pas correct d’utiliser ce champ à la place du champ d’en-tête HTTP « Host ». Par exemple, lors du transfert d’une connexion HTTPS vers un serveur, le champ SNI doit être défini à partir du champ d’en-tête HTTP « Host » en utilisant « req.hdr(host) » et non à partir de la valeur SNI côté client. La raison en est que le SNI est utilisé uniquement pour sélectionner le certificat que le serveur présentera, et les clients sont autorisés à envoyer des requêtes avec des valeurs Host différentes, à condition qu’elles correspondent aux noms présents dans le certificat. En conséquence, “ssl_fc_sni” ne devrait normalement pas être utilisé comme argument pour le mot-clé serveur « sni », sauf si le backend fonctionne en mode TCP.
Dérivés ACL :
ssl_fc_supported_versions_bin([<filter_option>]): binary
Renvoie le contenu de l’extension TLS supported_versions (43) présentée lors du Client Hello. Elle fournit une liste binaire de versions sur 2 octets. TLSv1.3 (0x0304), TLSv1.2 (0x0303).
Cette valeur ne peut être retournée que si la valeur “tune.ssl.capture-buffer-size” est définie supérieure à 0.
La configuration de <filter_option> permet de filtrer les données retournées. Valeurs acceptées : 0 : retourner la liste complète des chiffrements (par défaut), 1 : exclure les valeurs GREASE (RFC8701) de la sortie
ssl_fc_unique_id : binaire Lorsque la connexion entrante a été établie via une couche de transport SSL/TLS, renvoie l’identifiant unique TLS tel qu défini dans la section 3 de RFC5929 . L’identifiant unique peut être encodé au format base64 à l’aide du convertisseur : « ssl_fc_unique_id,base64 ».
ssl_fc_use_keysize : entier Renvoie la taille de la clé du chiffrement symétrique utilisée en bits lorsque la connexion entrante a été établie sur un transport SSL/TLS.
ssl_s_chain_der : binaire Renvoie le certificat de chaîne au format DER présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une règle d’accès (ACL), les valeurs à comparer peuvent être fournies sous forme hexadécimale. Le résultat peut être analysé à l’aide de toute bibliothèque acceptant des données ASN.1 au format DER. Cette fonction ne prend pas en charge les sessions réutilisées.
ssl_s_der: binary Retourne le certificat au format DER présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une ACL, les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_s_i_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion sortante a été établie au moyen d’une couche de transport SSL/TLS, renvoie le nom distingué complet de l’émetteur du certificat présenté par le serveur lorsque aucun <entry> n’est spécifié, ou la valeur du premier élément donné trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième élément donné à partir du beginning/end du DN. Par exemple, « ssl_s_i_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_s_i_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez uniquement modifier le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_s_i_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme malformée et aucune donnée n’est renvoyée.
ssl_s_key_alg : chaîne Retourne le nom de l’algorithme utilisé pour générer la clé du certificat présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS.
ssl_s_notafter : chaîne Retourne la date de fin présentée par le serveur sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion sortante a été établie via une couche de transport SSL/TLS.
ssl_s_notbefore : chaîne Retourne la date de début fournie par le serveur sous forme de chaîne formatée YYMMDDhhmmss[Z] lorsque la connexion sortante a été établie via une couche de transport SSL/TLS.
ssl_s_s_dn([<entry>[,<occ>[,<format>]]]): string
Lorsqu’une connexion sortante a été établie au moyen d’une couche de transport SSL/TLS, renvoie le nom distingué complet du sujet du certificat présenté par le serveur lorsque aucun <entry> n’est spécifié, ou la valeur du premier élément trouvé à partir du début du DN. Si un nombre d’occurrence positive/negative est spécifié en tant qu’argument optionnel second, renvoie la valeur du nième élément à partir du beginning/end du DN. Par exemple, « ssl_s_s_dn(OU,2) » renvoie la deuxième unité organisationnelle, et « ssl_s_s_dn(CN) » récupère le nom commun. Le paramètre <format> permet de recevoir un DN adapté à la consommation par différents protocoles. Actuellement pris en charge : rfc2253 pour LDAP v3. Si vous souhaitez uniquement modifier le format, vous pouvez spécifier une chaîne vide et zéro pour les deux premiers paramètres. Exemple : ssl_s_s_dn(,0,rfc2253). Si la valeur ASN.1 de l’entrée demandée (ou, lorsqu’aucun <entry> n’est spécifié, toute entrée du DN) contient un octet NUL intégré suivi d’autres données, elle est considérée comme malformée et aucune donnée n’est renvoyée.
ssl_s_serial: binary Renvoie le numéro de série du certificat présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS. Lorsqu’il est utilisé dans une règle d’accès, les valeurs à comparer peuvent être fournies sous forme hexadécimale.
ssl_s_sha1 : binaire Retourne l’empreinte SHA-1 du certificat présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS. Cela permet de savoir quel certificat a été sélectionné à l’aide de SNI.
ssl_s_sig_alg : chaîne Retourne le nom de l’algorithme utilisé pour signer le certificat présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS.
ssl_s_version: integer Retourne la version du certificat présenté par le serveur lors de la connexion sortante établie sur un transport SSL/TLS.
txn.timer.user : entier Temps total estimé perçu par le client, entre l’instant où le proxy l’a accepté et l’instant où les deux extrémités ont été fermées, sans temps d’inactivité. Il s’agit de l’équivalent de %Tu dans le format de journalisation et est exprimé en millisecondes (ms). Pour plus de détails, voir Section 8.4 “Événements de temporisation”
7.3.5. Récupération d’échantillons à partir du contenu du tampon (couche 6)
Extraire des échantillons à partir du contenu du tampon diffère un peu des extraits d’échantillons précédents, car les données échantillonnées sont éphémères. Ces données ne peuvent être utilisées que lorsqu’elles sont disponibles et seront perdues lorsqu’elles seront transmises. Pour cette raison, les échantillons extraits à partir du contenu du tampon au cours d’une requête ne peuvent par exemple pas être utilisés dans une réponse. Même pendant leur extraction, ces données peuvent changer. Il peut être nécessaire de définir certains délais ou de combiner plusieurs méthodes d’extraction d’échantillons afin de garantir que les données attendues sont complètes et utilisables, par exemple via l’inspection du contenu de requête TCP. Voir le mot-clé « tcp-request content » pour plus d’informations détaillées sur le sujet.
Avertissement : Les extraits d’échantillons suivants sont ignorés s’ils sont utilisés depuis des proxies HTTP. Ils ne traitent que les contenus bruts présents dans les tampons. En revanche, les proxies HTTP utilisent des contenus structurés. Par conséquent, la représentation brute de ces données est sans sens. Un avertissement est émis si une ACL repose sur l’un des extraits d’échantillons suivants. Toutefois, il n’est pas possible de détecter toutes les utilisations incorrectes (par exemple, dans un format de journal personnalisé ou une expression d’échantillonnage). Faites donc preuve de prudence.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
distcc_body(<token>[,<occ>]): binary
Analyse un message distcc et renvoie le corps associé à l’occurrence #<occ> du jeton
<token>. Les occurrences commencent à 1, et lorsqu’elles ne sont pas spécifiées, toute occurrence peut correspondre, bien que dans la pratique seule la première soit vérifiée pour l’instant. Cette fonction peut être utilisée pour extraire des noms de fichiers ou des arguments dans des fichiers compilés à l’aide de distcc via HAProxy. Veuillez vous référer à la documentation du protocole distcc pour la liste complète des jetons pris en charge.
distcc_param(<token>[,<occ>]): integer
Analyse un message distcc et renvoie le paramètre associé à l’occurrence #<occ> du jeton
<token>. Les occurrences commencent à 1, et lorsqu’elles ne sont pas précisées, toute occurrence peut correspondre, bien que dans la pratique seule la première soit vérifiée pour l’instant. Cette fonctionnalité peut être utilisée pour extraire certaines informations, telles que la version du protocole, la taille du fichier ou l’argument dans les fichiers compilés via distcc avec HAProxy. Un autre cas d’utilisation consiste à attendre le début du contenu du fichier prétraité avant de se connecter au serveur, afin d’éviter de maintenir des connexions inactives. Veuillez vous référer à la documentation du protocole distcc pour la liste complète des jetons pris en charge.
Exemple :
payload(<offset>,<length>): binary (deprecated)
Ceci est un alias de “req.payload” lorsqu’il est utilisé dans le contexte d’une requête (par exemple, « stick on », « stick match »), et de “res.payload” lorsqu’il est utilisé dans le contexte d’une réponse, par exemple dans « stick store response ».
payload_lv(<offset1>,<length>[,<offset2>]): binary (deprecated)
Ceci est un alias de “req.payload_lv” lorsqu’il est utilisé dans le contexte d’une requête (par exemple, « stick on », « stick match »), et de “res.payload_lv” lorsqu’il est utilisé dans le contexte d’une réponse, par exemple dans « stick store response ».
req.len : integer req_len : integer (obsolète) Renvoie une valeur entière correspondant au nombre d’octets présents dans le tampon de requête. Cette fonction est principalement utilisée dans les ACL. Il est important de comprendre que ce test ne renvoie pas false tant que le tampon est en cours de modification. Cela signifie qu’une vérification d’égalité à zéro correspond presque toujours immédiatement au début de la session, tandis qu’un test pour plus de données attendra que les données arrivent et ne renverra false que lorsque HAProxy est certain qu’aucune autre donnée ne parviendra. Ce test a été conçu pour être utilisé avec l’inspection du contenu des requêtes TCP.
req.payload(<offset>,<length>): binary
Cela extrait un bloc binaire de <length> octets à partir de l’octet <offset> dans le tampon de requête. Dans un cas particulier, si l’argument <length> vaut zéro, l’intégralité du tampon depuis <offset> jusqu’à la fin est extraite. Cette fonctionnalité peut être utilisée avec des listes de contrôle d’accès afin de vérifier la présence de certains contenus dans un tampon à n’importe quelle position.
Dérivés ACL :
req.payload_lv(<offset1>,<length>[,<offset2>]): binary
Cela extrait un bloc binaire dont la taille est spécifiée à <offset1> pour <length> octets, et qui commence à <offset2> si spécifié, ou juste après la longueur dans le tampon de requête. Le paramètre <offset2> prend également en charge des décalages relatifs si précédés d’un signe ‘+’ ou ‘-’.
Dérivés ACL :
Exemple : consultez l’exemple fourni avec le mot-clé « stick store-response ».
req.proto_http : boolean req_proto_http : boolean (obsolète) Retourne true lorsque les données dans le tampon de requête semblent être HTTP et se parse correctement comme telles. Il s’agit du même analyseur que celui utilisé par l’analyseur de requête HTTP classique, ce qui garantit une comportement prévisible. Le test ne s’effectue pas tant que la requête n’est pas complète, échouée ou expirée. Ce test peut être utilisé pour signaler le protocole dans les journaux TCP, mais son usage principal consiste à bloquer l’analyse des requêtes TCP jusqu’à ce qu’une requête HTTP complète soit présente dans le tampon, par exemple pour suivre un en-tête.
Exemple :
req.rdp_cookie([<name>]): string
Lorsque le tampon de requête ressemble au protocole RDP, extrait le cookie RDP <name>, ou tout cookie si non spécifié. Le parseur ne vérifie qu’un seul cookie, comme illustré dans la spécification du protocole RDP. Le nom du cookie est insensible à la casse. En général, le nom de cookie « MSTS » est utilisé, car il peut contenir le nom d’utilisateur du client se connectant au serveur si correctement configuré côté client. Le cookie « MSTSHASH » est également fréquemment utilisé pour assurer la persistance de session vers les serveurs.
Cela diffère de « balance rdp-cookie » en ce sens qu’un algorithme de répartition quelconque peut être utilisé, et la répartition des clients vers les serveurs backend n’est donc pas liée au hachage du cookie RDP. Il est prévu qu’en utilisant un algorithme de répartition tel que « balance roundrobin » ou « balance leastconn », on obtienne une répartition plus équilibrée des clients vers les serveurs backend qu’avec le hachage utilisé par « balance rdp-cookie ».
Dérivés ACL :
Exemple :
Voir également : « balance rdp-cookie », « persist rdp-cookie », « tcp-request » et la liste ACL “req.rdp_cookie”.
req.rdp_cookie_cnt([name]): integer
Tente d’analyser le tampon de requête selon le protocole RDP, puis renvoie un entier correspondant au nombre de cookies RDP trouvés. Si un nom de cookie facultatif est fourni, seuls les cookies correspondant à ce nom sont pris en compte. Cela est principalement utilisé dans les listes de contrôle d’accès (ACL).
Dérivés ACL :
req.ssl_alpn : chaîne Retourne une chaîne contenant les valeurs de l’extension de négociation de protocole au niveau de la couche application (ALPN) TLS (RFC7301), envoyées par le client dans le message SSL ClientHello. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche de données SSL, donc cela ne fonctionnera pas avec les lignes « bind » comportant l’option « ssl ». Cela est utile dans les ACL pour prendre une décision de routage basée sur les préférences ALPN d’un client TLS, comme dans l’exemple ci-dessous. Voir également “ssl_fc_alpn”. Ce récupérateur analyse uniquement le premier message ClientHello trouvé dans le tampon de requête, consultez la documentation du mot-clé “req.ssl_sni” pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré).
Exemples :
req.ssl_cipherlist binary
Renvoie la forme binaire de la liste des options de chiffrement symétrique prises en charge par le client, telles qu’indiquées dans le contenu d’un message ClientHello TLS. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, ce qui signifie que cela ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Reportez-vous à “ssl_fc_cipherlist_bin”, qui est l’équivalent bind SSL pouvant être utilisé lorsque l’option « ssl » est spécifiée. Cette fonction ne traite que le premier message ClientHello trouvé dans le tampon de requête ; consultez la documentation du mot-clé “req.ssl_sni” pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré).
Exemples :
req.ssl_ec_ext : boolean Renvoie une valeur booléenne indiquant si le client a envoyé l’extension Courbes elliptiques prises en charge, telle que définie dans RFC4492, section 5.1 , dans le message SSL ClientHello. Cette information peut être utilisée pour présenter un certificat EC aux clients compatibles ECC, et utiliser RSA pour tous les autres, sur la même adresse IP. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête, et non aux contenus déchiffrés via une couche SSL, donc cela ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Cette fonction ne traite que le premier message ClientHello trouvé dans le tampon de requête ; pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré), consulter la documentation du mot-clé “req.ssl_sni”.
req.ssl_hello_type : entier req_ssl_hello_type : entier (obsolète) Renvoie une valeur entière contenant le type du message SSL hello trouvé dans le tampon de requête, si ce tampon contient des données qui s’interprètent comme un message ClientHello SSL complet (v3 ou supérieur). Notez que cela ne s’applique qu’aux contenus bruts présents dans le tampon de requête, et non aux contenus déchiffrés via une couche SSL, donc cela ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Cette fonction est principalement utilisée dans les ACL pour détecter la présence d’un message SSL hello supposé contenir un identifiant de session SSL utilisable pour la persistance. Cette fonction n’analyse qu’le premier message ClientHello trouvé dans le tampon de requête ; pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, Encrypted Client Hello), consultez la documentation du mot-clé “req.ssl_sni”.
req.ssl_keyshare_groups binary
Renvoie le format binaire de la liste des paramètres cryptographiques pris en charge par le client pour l’échange de clés, tel que rapporté dans le message TLS ClientHello. En TLS v1.3, keyshare fait partie du message ClientHello et constitue la dernière extension du ClientHello. Notez que cette fonctionnalité ne s’applique qu’aux contenus bruts présents dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, ce qui signifie qu’elle ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Cette fonction ne traite que le premier message ClientHello trouvé dans le tampon de requête ; pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, Encrypted Client Hello), consultez la documentation du mot-clé “req.ssl_sni”.
Exemples :
req.ssl_sigalgs binary
Renvoie la forme binaire de la liste des algorithmes de signature pris en charge par le client, telle qu’elle est rapportée dans le TLS ClientHello. Cette information est disponible sous forme d’extension ClientHello. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, ce qui signifie qu’elle ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Reportez-vous à “ssl_fc_sigalgs_bin”, qui est l’équivalent SSL pour la liaison et peut être utilisé lorsque l’option « ssl » est spécifiée. Cette fonction ne traite que le premier message ClientHello trouvé dans le tampon de requête ; consultez la documentation du mot-clé “req.ssl_sni” pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré).
Exemples :
req.ssl_sni: chaîne req_ssl_sni: chaîne (obsolète) Retourne une chaîne contenant la valeur de l’extension TLS Server Name envoyée par un client dans un flux TLS passant par le tampon de requête, si le tampon contient des données qui s’interprètent comme un message complet de type Hello client SSL (v3 ou supérieur). Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, donc cela ne fonctionnera pas avec les lignes « bind » comportant l’option « ssl ». Cela ne fonctionne que pour les protocoles TLS implicite, comme HTTPS (443), IMAPS (993), SMTPS (465), mais ne fonctionnera pas pour les protocoles TLS explicite, comme SMTP (25/587) ou IMAP (143). Le SNI contient normalement le nom de l’hôte vers lequel le client tente de se connecter (pour les navigateurs récents). Cette fonction a été conçue pour être utilisée avec l’inspection du contenu des requêtes TCP. Si un commutateur de contenu est nécessaire, il est recommandé d’attendre tout d’abord un message Hello client complet (type 1), comme dans l’exemple ci-dessous. Voir également “ssl_fc_sni”. Attention, pour les raisons détaillées ci-dessous (HelloRetryRequest, Renégociation, Hello client chiffré), la valeur retournée par cette fonction n’est pas suffisamment fiable pour être utilisée seule afin d’autoriser ou de refuser l’accès à certains hôtes.
Cette récupération ne parse que le premier message ClientHello trouvé dans le tampon de requête. Si le client envoie plusieurs messages ClientHello au sein du même flux TCP — par exemple parce que le serveur a demandé une HelloRetryRequest (HRR) dans le cadre de TLS 1.3, ou parce que le client initie une renegotiation TLS (qui envoie un nouveau ClientHello ultérieurement dans le même flux TCP, éventuellement portant un SNI différent) — seul le SNI porté par ce premier ClientHello sera retourné ; le contenu de tout ClientHello ultérieur sera ignoré.
Lorsque le Client Hello chiffré (ECH) est utilisé, le ClientHello observé sur le réseau n’est que le ClientHello « externe », qui contient le ClientHello « interne » réel, chiffré. Le SNI extrait par cette requête dans ce cas est celui du ClientHello externe, qui constitue un SNI trompeur et non l’hôte réel que le client souhaite atteindre. Cette requête ne peut actuellement ni déchiffrer ni analyser le ClientHello interne, elle ne doit donc pas être utilisée pour prendre des décisions de routage ou de contrôle d’accès lorsque ECH est activé.
Dérivés ACL :
Exemples :
req.ssl_st_ext : integer Retourne 0 si le client n’a pas envoyé d’extension SessionTicket TLS (RFC5077) Retourne 1 si le client a envoyé une extension SessionTicket TLS Retourne 2 si le client a également envoyé un ticket TLS de longueur non nulle Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, donc cela ne fonctionne pas avec les lignes « bind » comportant l’option « ssl ». Cela peut par exemple être utilisé pour détecter si le client a envoyé un ticket de session ou non, et agir en conséquence : en cas d’absence de ticket de session, utiliser l’identifiant de session ou ne pas effectuer de persistance, car il n’y a pas d’état côté serveur lorsque les tickets de session sont utilisés. Cette requête analyse uniquement le premier message ClientHello trouvé dans le tampon de requête ; pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré), consulter la documentation de la clé “req.ssl_sni”.
req.ssl_supported_groups binary
Renvoie la forme binaire de la liste des groupes pris en charge par le client, tels qu’indiqués dans le message TLS ClientHello et utilisés pour l’échange de clés, pouvant inclure à la fois des courbes elliptiques et des échanges de clés non-EC. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche SSL, donc cela ne fonctionne pas avec les lignes « bind » ayant l’option « ssl ». Reportez-vous à “ssl_fc_eclist_bin”, qui est l’équivalent SSL de la directive bind et peut être utilisé lorsque l’option « ssl » est spécifiée. Cette fonction ne traite que le premier message ClientHello trouvé dans le tampon de requête ; consultez la documentation du mot-clé “req.ssl_sni” pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré).
Exemples :
req.ssl_ver : entier req_ssl_ver : entier (obsolète) Retourne une valeur entière contenant la version du protocole SSL/TLS d’un flux présent dans le tampon de requête. Les messages Hello SSLv2 et les messages SSLv3 sont pris en charge. TLSv1 est annoncé comme version SSL 3.1. La valeur est composée de la version majeure multipliée par 65536, ajoutée à la version mineure. Notez que cela ne s’applique qu’aux contenus bruts trouvés dans le tampon de requête et non aux contenus déchiffrés via une couche de données SSL, ce qui signifie qu’il ne fonctionnera pas avec les lignes « bind » ayant l’option « ssl ». La version ACL du test correspond à une notation décimale sous la forme MAJEUR.MINEUR (par exemple 3.1). Cette fonction est principalement utilisée dans les ACL. Cette fonction n’analyse que le premier message ClientHello trouvé dans le tampon de requête ; consultez la documentation du mot-clé “req.ssl_sni” pour plus de détails sur les implications de cette limitation (HelloRetryRequest, renegotiation, ClientHello chiffré).
Dérivés ACL :
res.len : integer Renvoie une valeur entière correspondant au nombre d’octets présents dans le tampon de réponse. Cette fonction est principalement utilisée dans les ACL. Il est important de comprendre que ce test ne renvoie pas false tant que le tampon est en cours de modification. Cela signifie qu’une vérification d’égalité à zéro correspond presque toujours immédiatement au début du flux, tandis qu’un test pour plus de données attendra que les données arrivent et ne renverra false que lorsque HAProxy est certain qu’aucune autre donnée n’arrivera. Ce test a été conçu pour être utilisé avec l’inspection du contenu des réponses TCP. Il peut également être utilisé dans les règles d’attente basées sur tcp-check.
res.payload(<offset>,<length>): binary
Cela extrait un bloc binaire de <length> octets à partir de l’octet <offset> dans le tampon de réponse. Dans un cas particulier, si l’argument <length> vaut zéro, tout le tampon à partir de <offset> jusqu’à la fin est extrait. Cela peut être utilisé avec des listes de contrôle d’accès afin de vérifier la présence de certains contenus dans un tampon à n’importe quelle position. Il peut également être utilisé dans les règles d’attente basées sur tcp-check.
res.payload_lv(<offset1>,<length>[,<offset2>]): binary
Cela extrait un bloc binaire dont la taille est spécifiée à <offset1> pour <length> octets, et qui commence à <offset2> si spécifié, ou juste après la longueur dans le tampon de réponse. Le paramètre <offset2> prend également en charge des décalages relatifs si précédé d’un signe ‘+’ ou ‘-’. Il peut également être utilisé dans les règles d’attente basées sur tcp-check.
Exemple : consultez l’exemple fourni avec le mot-clé « stick store-response ».
res.ssl_hello_type : integer rep_ssl_hello_type : integer (obsolète) Retourne une valeur entière contenant le type du message SSL hello trouvé dans le tampon de réponse, si ce tampon contient des données qui se parse comme un message SSL complet (v3 ou supérieur). Notez que cela ne s’applique qu’aux contenus bruts présents dans le tampon de réponse et non aux contenus déchiffrés via une couche de données SSL, donc cela ne fonctionne pas avec les lignes « server » ayant l’option « ssl ». Cette fonction est principalement utilisée dans les ACL pour détecter la présence d’un message SSL hello supposé contenir un identifiant de session SSL utilisable pour la persistance.
7.3.6. Récupération d’échantillons HTTP (couche 7)
Il est possible de récupérer des échantillons à partir du contenu HTTP, des requêtes et des réponses. Ce niveau applicatif est également appelé couche 7. Il n’est possible de récupérer les données dans cette section que lorsque toute la requête ou la réponse HTTP a été entièrement analysée à partir de son tampon respectif. Cela est toujours le cas pour toutes les règles spécifiques à HTTP et pour les sections fonctionnant en mode http. Lors de l’inspection TCP, il peut être nécessaire de prendre en charge un délai d’inspection afin de permettre d’abord l’arrivée de la requête ou de la réponse. Ces récupérations peuvent nécessiter un peu plus de ressources CPU que celles de la couche 4, mais pas beaucoup, car les requêtes et les réponses sont indexées.
Note : En ce qui concerne le traitement HTTP des règles tcp-request content, tout fonctionne comme prévu depuis un proxy HTTP. En revanche, depuis un proxy TCP, sans mise à niveau HTTP, cela ne fonctionne que pour le contenu HTTP/1. Pour le contenu HTTP/2, seul le préambule est visible. Il n’est donc possible de s’appuyer que sur les extraits d’échantillon “req.proto_http”, “req.ver” et éventuellement « method ». Tous les autres extraits d’échantillon L7 échoueront. Après une mise à niveau HTTP, ils fonctionneront de la même manière qu’à partir d’un proxy HTTP.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
base : chaîne Cette valeur retourne la concaténation de la première en-tête Host et de la partie chemin de la requête, qui commence au premier slash et se termine avant le point d’interrogation. Elle peut être utile dans les environnements à hébergement virtuel pour détecter les abus d’URL ainsi que pour améliorer l’efficacité des caches partagés. En l’utilisant avec une table de persistance de taille limitée, il est possible de collecter des statistiques sur les objets les plus fréquemment demandés par host/path.. Avec des listes de contrôle d’accès (ACL), elle permet d’implémenter des règles simples de commutation de contenu impliquant à la fois l’hôte et le chemin, telles que « www.example.com/favicon.ico ». Voir également « path » et « uri ».
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
base32 : entier Cette commande retourne un hachage 32 bits de la valeur renvoyée par la méthode de récupération « base » ci-dessus. Cela est utile pour suivre l’activité par URL sur des sites à fort trafic sans avoir à stocker toutes les URLs. Au lieu de cela, un hachage plus court est stocké, ce qui permet d’économiser beaucoup de mémoire. Le type de sortie est un entier non signé. La fonction de hachage utilisée est SDBM avec avalanche complète sur la sortie. Techniquement, base32 est exactement équivalent à « base,sdbm(1) ».
base32+src : binaire Cette commande retourne la concaténation de la récupération base32 ci-dessus et de la récupération src ci-dessous. Le type résultant est de type binaire, avec une taille de 8 ou 20 octets selon la famille d’adresse source. Cela peut être utilisé pour suivre des compteurs par IP ou par URL.
baseq : chaîne Cette valeur retourne la concaténation du premier en-tête Host et de la partie chemin de la requête avec la chaîne de requête, qui commence au premier slash. Utiliser cette valeur à la place de « base » permet d’identifier correctement la ressource cible, notamment pour les cas d’utilisation statistiques ou de mise en cache. Voir également « path », « pathq » et « base ».
capture.req.hdr(<idx>): string
Cela extrait le contenu de l’en-tête capturé par la directive « capture request header », idx correspond à la position du mot-clé capture dans la configuration. La première entrée a un index de 0. Voir également : « capture request header ».
capture.req.method : chaîne Cela extrait la méthode d’une requête HTTP. Il peut être utilisé dans les requêtes et les réponses. Contrairement à « method », il peut être utilisé dans les requêtes et les réponses car il est alloué.
capture.req.uri : chaîne Cela extrait l’URI de la requête, qui commence au premier slash et se termine avant le premier espace dans la requête (sans la partie hôte). Contrairement à « path » et « url », il peut être utilisé à la fois dans les requêtes et les réponses, car il est alloué.
capture.req.ver : chaîne Cette extraction d’échantillon récupère la version HTTP de la requête et la renvoie au format
“HTTP/<major>.<minor>”. Elle peut être utilisée dans les requêtes, les réponses et les journaux, car elle repose sur une information persistante. Si la version de la requête n’est pas valide, cette extraction d’échantillon échoue.
capture.res.hdr(<idx>): string
Cela extrait le contenu de l’en-tête capturé par la directive « capture response header », idx correspond à la position du mot-clé de capture dans la configuration. La première entrée a un index de 0. Voir également : « capture response header »
capture.res.ver : chaîne Cette extraction récupère la version HTTP de la réponse et la renvoie au format
“HTTP/<major>.<minor>”. Elle peut être utilisée dans les journaux car elle repose sur une information persistante. Si la version de la réponse n’est pas valide, cette extraction d’échantillon échoue.
cookie([<name>]): string (deprecated)
Cela extrait la dernière occurrence du nom de cookie <name> dans une ligne d’en-tête « Cookie » de la requête, ou dans un en-tête « Set-Cookie » de la réponse, et retourne sa valeur sous forme de chaîne. Un usage courant consiste à faire en sorte que plusieurs clients partageant un même profil utilisent le même serveur. Cela peut être similaire à ce que faisait « appsession » avec l’instruction « request-learn », mais avec prise en charge de la synchronisation multi-pair et du maintien d’état entre redémarrages. Si aucun nom n’est spécifié, la première valeur de cookie est retournée. Cette fonction de récupération ne doit plus être utilisée et doit être remplacée par req.cook() ou res.cook() à la place, car elle utilise de manière ambiguë la direction en fonction du contexte dans lequel elle est utilisée.
hdr([<name>[,<occ>]]): string
Cela équivaut à req.hdr() lorsqu’il est utilisé sur les requêtes, et à res.hdr() lorsqu’il est utilisé sur les réponses. Veuillez vous référer à ces extraits respectifs pour plus de détails. En cas de doute sur le sens de l’extraction, utilisez les formes explicites. Notez qu’à la différence de la méthode d’extraction hdr(), les mots-clés ACL hdr_* s’appliquent sans ambiguïté aux en-têtes de requête.
http_auth(<userlist>): boolean
Renvoie une valeur booléenne indiquant si les données d’authentification reçues du client correspondent à un couple nom d’utilisateur et mot de passe stocké dans la liste d’utilisateurs spécifiée. Cette fonction de récupération n’est pas vraiment utile en dehors des ACLs. Seule l’authentification HTTP basique est actuellement prise en charge.
http_auth_bearer([<header>]): string
Renvoie le jeton fourni par le client, extrait des données d’autorisation lorsque le schéma Bearer est utilisé (par exemple, pour envoyer des jetons Web JSON). Aucune vérification n’est effectuée sur les données envoyées par le client. Si un <header> spécifique est fourni, il analysera cet en-tête au lieu de l’en-tête Authorization.
http_auth_group(<userlist>): string
Renvoie une chaîne correspondant au nom d’utilisateur extrait des données d’authentification reçues du client, si le nom d’utilisateur et le mot de passe sont valides selon la liste d’utilisateurs spécifiée. Son usage principal consiste à l’utiliser dans les ACLs, où l’on vérifie ensuite si l’utilisateur appartient à un groupe figurant dans une liste. Cette fonction de récupération n’est pas vraiment utile en dehors des ACLs. Seule l’authentification HTTP basique est actuellement prise en charge.
Dérivés ACL :
http_auth_pass : chaîne Renvoie le mot de passe de l’utilisateur trouvé dans les données d’authentification reçues du client, tel qu’indiqué dans l’en-tête Authorization. Aucune vérification n’est effectuée par cette extraction d’échantillon. Seule l’authentification Basic est prise en charge.
http_auth_type : chaîne Retourne la méthode d’authentification trouvée dans les données d’authentification reçues du client, telles qu’elles sont fournies dans l’en-tête Authorization. Aucune vérification n’est effectuée par cette requête d’échantillonnage. Seule l’authentification Basic est prise en charge.
http_auth_user : chaîne Renvoie le nom d’utilisateur extrait des données d’authentification reçues du client, tel qu’indiqué dans l’en-tête Authorization. Aucune vérification n’est effectuée par cette extraction d’échantillon. Seule l’authentification Basic est prise en charge.
http_first_req : boolean Retourne true lorsque la requête en cours de traitement est la première de la connexion. Cela peut être utilisé pour ajouter ou supprimer des en-têtes manquants dans certaines requêtes lorsque celle-ci n’est pas la première, ou pour aider à regrouper les requêtes dans les journaux.
method : entier + chaîne Renvoie une valeur entière correspondant à la méthode dans la requête HTTP. Par exemple, « GET » vaut 1 (vérifier les sources pour établir la correspondance). La valeur 9 signifie « autre méthode » et peut être convertie en chaîne extraite du flux. Cette valeur ne doit pas être utilisée directement comme échantillon ; elle n’est destinée qu’à être utilisée dans les ACL, qui convertissent automatiquement les méthodes à partir de modèles en ces valeurs entier + chaîne. Certaines ACL prédéfinies vérifient déjà les méthodes les plus courantes.
Dérivés ACL :
Exemple :
path : chaîne Cela extrait le chemin de l’URL de la requête, qui commence au premier slash et se termine avant le point d’interrogation (sans la partie hôte). Une utilisation typique consiste à combiner cette fonctionnalité avec des caches capables de préchargement, ainsi qu’avec des portails qui doivent agréger plusieurs informations provenant de bases de données et les conserver en mémoire cache. Notez que, pour les caches sortants, il serait préférable d’utiliser « url » à la place. Avec les listes de contrôle d’accès (ACL), elle est généralement utilisée pour correspondre à des noms de fichiers exacts (par exemple « /login.php »), ou à des parties de répertoires en utilisant les formes dérivées. Voir également les méthodes d’extraction « url » et « base ». Veuillez noter que toute référence à un fragment dans l’URI (« ‘#’ » après le chemin) est strictement interdite par la norme HTTP et sera rejetée. Toutefois, si le frontal recevant la requête dispose de l’option « accept-unsafe-violations-in-http-request », cette partie de fragment sera acceptée et apparaîtra également dans le chemin.
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
pathq : chaîne Cette extraction d’échantillon récupère le chemin d’URL de la requête, y compris la chaîne de requête, en commençant par la première barre oblique. Cette extraction d’échantillon est particulièrement utile pour toujours récupérer une URI relative, en excluant la partie schéma et autorité, le cas échéant. En effet, bien que cette représentation soit courante pour la cible d’une requête HTTP/1.1, elle est souvent remplacée par une URI absolue dans HTTP/2. Cette extraction d’échantillon retournera le même résultat dans les deux cas. Veuillez noter que toute référence de fragment dans l’URI (’#’ après le chemin) est strictement interdite par la norme HTTP et sera rejetée. Toutefois, si le frontal recevant la requête dispose de l’option accept-unsafe-violations-in-http-request, cette partie de fragment sera acceptée et apparaîtra également dans le chemin.
query([<options>]): string
Cela extrait la chaîne de requête de la requête, qui commence après le premier point d’interrogation. Si aucun point d’interrogation n’est présent, cette fonction retourne rien. Si un point d’interrogation est présent mais qu’il n’est suivi de rien, elle retourne une chaîne vide. Cela permet de déterminer facilement la présence d’une chaîne de requête en utilisant la méthode de correspondance « found ». Cette fonction complète « path », qui s’arrête avant le point d’interrogation, et “query_string”, qui inclut le point d’interrogation.
Un paramètre facultatif peut être utilisé pour personnaliser la valeur de retour. Les options suivantes sont prises en charge :
- with_qm : Inclure le point d'interrogation au début de la chaîne de requête, si elle n'est pas vide.
req.body : binaire Cette fonction renvoie le corps de la requête HTTP disponible sous forme de bloc de données. Il est recommandé d’utiliser « option http-buffer-request » afin de s’assurer d’attendre, dans la mesure du possible, la totalité du corps de la requête.
req.body_len : entier Cette valeur retourne la longueur du corps disponible de la requête HTTP en octets. Elle peut être inférieure à la longueur annoncée si le corps est plus grand que le tampon. Il est recommandé d’utiliser « option http-buffer-request » afin de s’assurer, dans la mesure du possible, d’attendre la totalité du corps de la requête.
req.body_param([<name>[,i]]): string
Cette requête suppose que le corps de la requête POST est encodé en URL. L’utilisateur peut vérifier si l’en-tête « content-type » contient la valeur “application/x-www-form-urlencoded”. Cette opération extrait la première occurrence du paramètre “<name>” dans le corps, qui se termine avant le caractère ‘&’. Le nom du paramètre est sensible à la casse, sauf si « i » est ajouté comme deuxième argument. Si aucun nom n’est fourni, tout paramètre correspondra, et la première valeur sera retournée. Le résultat est une chaîne correspondant à la valeur du paramètre “<name>” telle qu’elle apparaît dans le corps de la requête (aucune décodage URL n’est effectué). Notez que la version ACL de cette requête itère sur plusieurs paramètres et signalera successivement toutes les valeurs si aucun nom n’est spécifié.
req.body_size : integer Cette valeur retourne la taille annoncée du corps de la requête HTTP en octets. Elle correspond à la valeur de l’en-tête Content-Length annoncé, ou à la taille des données disponibles en cas de codage par tronçons.
req.cook([<name>]): string
Cela extrait la dernière occurrence du nom de cookie <name> sur une ligne d’en-tête « Cookie » de la requête, et retourne sa valeur sous forme de chaîne. Si aucun nom n’est spécifié, la première valeur de cookie est retournée. Lorsqu’il est utilisé avec des ACLs, tous les cookies correspondants sont évalués. Les espaces autour du nom et de la valeur sont ignorés, conformément à la spécification de l’en-tête Cookie (RFC6265). Le nom de cookie est sensible à la casse. Les cookies vides sont valides, aussi une valeur vide peut-elle être retournée si le cookie est présent. Utilisez la correspondance « found » pour détecter la présence. Utilisez la variante res.cook() pour les cookies envoyés par le serveur dans la réponse.
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
req.cook_cnt([<name>]): integer
Renvoie une valeur entière représentant le nombre d’occurrences du cookie <name> dans la requête, ou de tous les cookies si <name> n’est pas spécifié.
req.cook_names([<delim>]): string
Cela construit une chaîne issue de la concaténation de tous les noms de cookies tels qu’ils apparaissent dans la requête (en-tête Cookie) au moment de l’évaluation de la règle. Le délimiteur par défaut est la virgule (’,’), mais il peut être remplacé par un argument facultatif <delim>. Dans ce cas, seul le premier caractère de <delim> est pris en compte.
req.cook_val([<name>]): integer
Cela extrait la dernière occurrence du nom de cookie <name> sur une ligne d’en-tête « Cookie » de la requête, et convertit sa valeur en entier, qui est ensuite retournée. Si aucun nom n’est spécifié, la première valeur de cookie est retournée. Lorsqu’il est utilisé dans des ACL, tous les noms correspondants sont parcourus jusqu’à ce qu’une valeur corresponde.
req.fhdr(<name>[,<occ>]): string
Cela renvoie la valeur complète de la dernière occurrence de l’en-tête <name> dans une requête HTTP. Il diffère de req.hdr() en ce sens que les virgules présentes dans la valeur sont renvoyées et ne sont pas utilisées comme délimiteurs. Cela peut parfois être utile avec des en-têtes tels que User-Agent.
Lorsqu’il est utilisé dans une ACL, toutes les occurrences sont parcourues jusqu’à ce qu’une correspondance soit trouvée.
Optionnellement, une occurrence spécifique peut être précisée sous forme de numéro de position. Les valeurs positives indiquent une position à partir de la première occurrence, 1 étant la première. Les valeurs négatives indiquent des positions relatives à la dernière, -1 étant la dernière.
req.fhdr_cnt([<name>]): integer
Renvoie une valeur entière représentant le nombre d’occurrences du nom de champ d’en-tête de requête
<name>, ou le nombre total de champs d’en-tête si <name> n’est pas spécifié. Contrairement à res.hdr_cnt(), il ne fractionne pas les en-têtes aux virgules.
req.hdr([<name>[,<occ>]]): string
Cela retourne la dernière valeur séparée par des virgules de l’en-tête <name> dans une requête HTTP. La récupération considère toute virgule comme un délimiteur entre des valeurs distinctes. Cela est utile si vous devez traiter des en-têtes définis comme une liste de valeurs, tels que Accept ou X-Forwarded-For. Si vous souhaitez obtenir l’en-tête complet à la place, utilisez req.fhdr(). Veuillez vérifier soigneusement le RFC 7231 pour connaître la manière correcte de parser certains en-têtes. Certains d’entre eux sont également insensibles à la casse (par exemple, Connection).
Lorsqu’il est utilisé dans une ACL, toutes les occurrences sont parcourues jusqu’à ce qu’une correspondance soit trouvée.
Optionnellement, une occurrence spécifique peut être précisée sous forme de numéro de position. Les valeurs positives indiquent une position à partir de la première occurrence, 1 étant la première. Les valeurs négatives indiquent des positions relatives à la dernière, -1 étant la dernière.
Un usage typique consiste à utiliser l’en-tête X-Forwarded-For une fois converti en adresse IP, associé à une table IP.
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
req.hdr_cnt([<name>]): integer
Renvoie une valeur entière représentant le nombre d’occurrences du nom de champ d’en-tête de requête <name>, ou le nombre total de valeurs de champ d’en-tête si <name> n’est pas spécifié. Comme req.hdr(), il compte chaque partie séparée par une virgule de la valeur de l’en-tête. Si l’on souhaite compter les en-têtes complets, il convient d’utiliser req.fhdr_cnt() à la place.
Avec les listes de contrôle d’accès (ACL), il peut être utilisé pour détecter la présence, l’absence ou l’abus d’un en-tête spécifique, ainsi que pour bloquer les attaques par camouflage de requête en rejetant les requêtes contenant plus d’un des en-têtes suivants.
Consultez req.hdr() pour plus d’informations sur le correspondance des en-têtes.
req.hdr_ip([<name>[,<occ>]]): ip
Cela extrait la dernière occurrence de l’en-tête <name> dans une requête HTTP, la convertit en adresse IPv4 ou IPv6, puis renvoie cette adresse. Lorsqu’il est utilisé avec des ACL, toutes les occurrences sont vérifiées, et si <name> est omis, chaque valeur de chaque en-tête est vérifiée. Le parseur respecte strictement le format décrit dans RFC7239, avec l’extension selon laquelle les adresses IPv4 peuvent éventuellement être suivies d’un deux-points (’:’) et d’un numéro de port décimal valide (compris entre 0 et 65535), qui sera ignoré sans avertissement. Toutes les autres formes ne correspondent pas et entraînent l’ignorance de l’adresse.
Le paramètre <occ> est traité comme avec req.hdr().
Un usage courant consiste à utiliser les en-têtes X-Forwarded-For et X-Client-IP.
req.hdr_names([<delim>]): string
Cela construit une chaîne formée par la concaténation de tous les noms d’en-tête tels qu’ils apparaissent dans la requête au moment d’évaluer la règle. Le délimiteur par défaut est la virgule (’,’), mais il peut être remplacé par un argument optionnel <delim>. Dans ce cas, seul le premier caractère de <delim> est pris en compte.
req.hdr_val([<name>[,<occ>]]): integer
Cela extrait la dernière occurrence de l’en-tête <name> dans une requête HTTP, et la convertit en valeur entière. Lorsqu’il est utilisé avec des listes de contrôle d’accès (ACL), toutes les occurrences sont vérifiées, et si <name> est omis, chaque valeur de chaque en-tête est vérifiée.
Le paramètre <occ> est traité comme avec req.hdr().
Un usage courant consiste à utiliser l’en-tête X-Forwarded-For.
req.hdrs : chaîne Retourne les en-têtes de la requête courante sous forme de chaîne, y compris la dernière ligne vide séparant les en-têtes du corps de la requête. La dernière ligne vide peut être utilisée pour détecter un bloc d’en-têtes tronqué. Cette extraction d’échantillon est utile pour certains analyseurs d’en-têtes SPOE et pour la journalisation avancée.
req.hdrs_bin : binaire Retourne les en-têtes de la requête actuelle sous forme binaire préanalyse. Cela est utile pour déléguer certaines opérations avec SPOE. Chaque chaîne est décrite par une longueur suivie du nombre d’octets indiqué par cette longueur. La longueur est représentée à l’aide du codage entier variable décrit dans la documentation SPOE. La fin de la liste est marquée par une paire de noms d’en-tête et de valeurs vides (longueur de 0 pour les deux).
*(<str:header-name>``<str:header-value>)<empty string>``<empty string>
int : consultez la documentation SPOE pour le codage ; str : <int:length>``<bytes>
req.timer.hdr : entier Temps total pour obtenir la requête client (mode HTTP uniquement). Il s’agit du temps écoulé entre la réception des premiers octets et le moment où le proxy a reçu la ligne vide marquant la fin des en-têtes HTTP. Cette valeur est exprimée en millisecondes (ms) et équivaut à %TR dans le format de journalisation. Voir section 8.4 « Événements de temporisation » pour plus de détails.
req.timer.idle : entier Ce paramètre indique le délai d’inactivité avant la requête HTTP (mode HTTP uniquement). Ce minuteur compte entre la fin des échanges de main et la première octet de la requête HTTP. La valeur est exprimée en millisecondes et équivaut à %Ti dans le format de journalisation. Pour plus de détails, voir section 8.4 « Événements de temporisation ».
req.timer.queue : entier Temps total passé dans les files d’attente en attente d’une slot de connexion. Cette valeur est exprimée en millisecondes et équivaut à %Tw dans le format de journalisation. Voir section 8.4 « Événements de temporisation » pour plus de détails.
req.timer.tq : entier temps total pour obtenir la requête client à partir de la date d’acceptation ou depuis l’émission du dernier octet de la réponse précédente. Cette valeur est exprimée en millisecondes et équivaut à %Tq dans le format de journalisation. Voir section 8.4 « Événements de temporisation » pour plus de détails.
req.ver : chaîne req_ver : chaîne (obsolète) Retourne la chaîne de version de la requête HTTP, au format “<major>.<minor>”. Cela peut être utile pour les ACL. Certaines ACL prédéfinies vérifient déjà les versions courantes. Cette extraction peut être utilisée dans les requêtes, les réponses et les journaux, car elle repose sur des informations persistantes. Si la version de la requête n’est pas valide, cette extraction d’échantillon échoue.
Les valeurs courantes sont “1.0”, “1.1”, “2.0” ou “3.0”.
Dérivés ACL :
request_date([<unit>]): integer
C’est la date exacte à laquelle le premier octet de la requête HTTP a été reçu par HAProxy (alias de format de journalisation %tr). Cette valeur est calculée à partir de accept_date + temps de main-handshake (%Th) + temps d’attente (%Ti).
Renvoie une valeur en nombre de secondes depuis l’époque.
<unit> est facultatif et peut être défini à « s » pour secondes (comportement par défaut), « ms » pour millisecondes ou « us » pour microsecondes. Si l’unité est définie, la valeur renvoyée est un entier représentant respectivement les secondes, millisecondes ou microsecondes écoulées depuis l’époque. Cette option est utile lorsque une résolution temporelle inférieure à une seconde est requise.
res.body : binaire Cette commande renvoie le corps disponible de la réponse HTTP sous forme de bloc de données. Contrairement au côté requête, aucune directive n’est disponible pour attendre le corps de la réponse. Cette extraction d’échantillon est particulièrement utile (et utilisable) dans le contexte de vérification de santé.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.body_len : entier Cette valeur retourne la longueur du corps de la réponse HTTP disponible, en octets. Contrairement au côté requête, il n’existe aucune directive pour attendre le corps de la réponse. Cette extraction d’échantillon est particulièrement utile (et utilisable) dans le contexte de vérification de santé.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.body_size : entier Cette valeur retourne la taille annoncée du corps de la réponse HTTP en octets. Elle correspond à la valeur de l’en-tête Content-Length annoncé, ou à la taille des données disponibles en cas de codage par tronçons. Contrairement au côté requête, aucune directive n’exige d’attendre le corps de la réponse. Cette extraction d’échantillon est particulièrement utile (et utilisable) dans le contexte de vérification de santé.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.cache_hit : boolean Renvoie la valeur booléenne « true » si la réponse a été construite à partir d’une entrée du cache HTTP, sinon renvoie la valeur booléenne « false ».
res.cache_name : chaîne Retourne une chaîne contenant le nom du cache HTTP utilisé pour construire la réponse HTTP si res.cache_hit est vrai, sinon retourne une chaîne vide.
res.comp : boolean Retourne la valeur booléenne « true » si la réponse a été compressée par HAProxy, sinon retourne la valeur booléenne « false ». Cette information peut être utilisée pour ajouter des données dans les journaux.
res.comp_algo : chaîne Retourne une chaîne contenant le nom de l’algorithme utilisé si la réponse a été compressée par HAProxy, par exemple : « deflate ». Cette information peut être utilisée pour ajouter des données aux journaux.
res.cook([<name>]): string
Cela extrait la dernière occurrence du nom de cookie <name> sur une ligne d’en-tête « Set-Cookie » de la réponse, et retourne sa valeur sous forme de chaîne. Si aucun nom n’est spécifié, la première valeur de cookie est retournée.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
Dérivés ACL :
res.cook_cnt([<name>]): integer
Renvoie une valeur entière représentant le nombre d’occurrences du cookie <name> dans la réponse, ou de tous les cookies si <name> n’est pas spécifié. Cela est principalement utile lorsqu’il est combiné avec des ACLs pour détecter des réponses suspectes.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.cook_names([<delim>]): string
Cela construit une chaîne formée par la concaténation de tous les noms de cookies tels qu’ils apparaissent dans la réponse (en-têtes Set-Cookie) au moment de l’évaluation de la règle. Le délimiteur par défaut est la virgule (’,’), mais il peut être remplacé par un argument optionnel <delim>. Dans ce cas, seul le premier caractère de <delim> est pris en compte.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.cook_val([<name>]): integer
Cela extrait la dernière occurrence du nom de cookie <name> sur une ligne d’en-tête « Set-Cookie » de la réponse, et convertit sa valeur en entier, qui est ensuite retournée. Si aucun nom n’est spécifié, la première valeur de cookie est retournée.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.fhdr([<name>[,<occ>]]): string
Cette requête fonctionne comme la requête req.fhdr() avec la différence qu’elle agit sur les en-têtes présents dans une réponse HTTP.
Comme req.fhdr(), la fonction res.fhdr() renvoie les valeurs complètes. Si l’en-tête est défini comme une liste, vous devez utiliser res.hdr().
Cette récupération est parfois utile avec des en-têtes tels que Date ou Expires.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.fhdr_cnt([<name>]): integer
Cette requête fonctionne comme la requête req.fhdr_cnt() avec la différence qu’elle agit sur les en-têtes présents dans une réponse HTTP.
Comme req.fhdr_cnt(), l’action res.fhdr_cnt() agit sur les valeurs complètes. Si l’en-tête est défini comme une liste, vous devez utiliser res.hdr_cnt().
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.hdr([<name>[,<occ>]]): string
Cette requête fonctionne comme la requête req.hdr(), à la différence qu’elle agit sur les en-têtes présents dans une réponse HTTP.
Comme req.hdr(), la fonction res.hdr() considère la virgule comme un séparateur. Si ce comportement n’est pas souhaité, res.fhdr() doit être utilisée.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
res.hdr_cnt([<name>]): integer
Ce récupérateur fonctionne comme req.hdr_cnt() mais agit sur les en-têtes présents dans une réponse HTTP.
Comme req.hdr_cnt(), la fonction res.hdr_cnt() considère la virgule comme un délimiteur. Si ce comportement n’est pas souhaité, il faut utiliser res.fhdr_cnt().
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.hdr_ip([<name>[,<occ>]]): ip
Ce récupérateur fonctionne comme req.hdr_ip() mais agit sur les en-têtes présents dans une réponse HTTP.
Cela peut être utile pour charger certaines données dans une table de persistance.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.hdr_names([<delim>]): string
Cela construit une chaîne formée par la concaténation de tous les noms d’en-tête tels qu’ils apparaissent dans la réponse lorsque la règle est évaluée. Le délimiteur par défaut est la virgule (’,’), mais il peut être remplacé par un argument optionnel <delim>. Dans ce cas, seul le premier caractère de <delim> est pris en compte.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.hdr_val([<name>[,<occ>]]): integer
Ce récupérateur fonctionne comme req.hdr_val(), à ceci près qu’il agit sur les en-têtes présents dans une réponse HTTP.
Cela peut être utile pour charger certaines données dans une table de persistance.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
res.hdrs : string Retourne les en-têtes de réponse actuels sous forme de chaîne, y compris la dernière ligne vide séparant les en-têtes du corps de la réponse. Cette ligne vide peut être utilisée pour détecter un bloc d’en-têtes tronqué. Cette extraction d’échantillon est utile pour certains analyseurs d’en-têtes SPOE et pour la journalisation avancée.
Il peut également être utilisé dans les règles d’attente basées sur tcp-check.
res.hdrs_bin : binaire Retourne les en-têtes de réponse actuels sous forme binaire préanalyse. Cela est utile pour déléguer certains traitements avec SPOE. Il peut être utilisé dans les règles d’attente basées sur tcp-check. Chaque chaîne est décrite par une longueur suivie du nombre d’octets indiqué par cette longueur. La longueur est représentée à l’aide du codage entier variable décrit dans la documentation SPOE. La fin de la liste est marquée par une paire de noms d’en-tête et de valeurs vides (longueur de 0 pour les deux).
*(<str:header-name>``<str:header-value>)<empty string>``<empty string>
int : consultez la documentation SPOE pour le codage ; str : <int:length>``<bytes>
res.timer.hdr : integer Il s’agit du temps écoulé entre l’instant où la connexion TCP a été établie avec le serveur et l’instant où le serveur a envoyé l’intégralité de ses en-têtes de réponse. Cette valeur est exprimée en millisecondes et correspond à %Tr dans le format de journalisation. Voir section 8.4 « Événements de temporisation » pour plus de détails.
res.ver : chaîne resp_ver : chaîne (obsolète) Retourne la chaîne de version provenant de la réponse HTTP, au format “<major>.<minor>”. Cela peut être utile pour les journaux, mais sert principalement aux ACL. Si la version de la réponse n’est pas valide, cette extraction d’échantillon échoue.
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
Dérivés ACL :
server_status : integer Renvoie un entier contenant le code d’état HTTP reçu du serveur. Si aucune réponse n’a été reçue du serveur, l’extraction d’échantillon échoue.
set-cookie([<name>]): string (deprecated)
Cela extrait la dernière occurrence du nom de cookie <name> dans une ligne d’en-tête « Set-Cookie » de la réponse et utilise la valeur correspondante pour effectuer la correspondance. Cela peut être comparé à ce que faisait « appsession » avec les options par défaut, mais avec prise en charge de la synchronisation multi-pair et du maintien de l’état entre redémarrages.
Cette fonction de récupération est obsolète et a été remplacée par la fonction de récupération “res.cook”. Ce mot-clé disparaîtra prochainement.
status : integer Renvoie un entier contenant le code d’état HTTP dans la réponse HTTP, par exemple 302. Il est principalement utilisé dans les ACLs et les plages d’entiers, par exemple pour supprimer tout en-tête Location si la réponse n’est pas un 3xx. Il correspond au code d’état reçu par le client s’il n’est pas modifié, par exemple via une action « set-status ».
Il peut être utilisé dans les règles d’attente basées sur tcp-check.
txn.status : integer Renvoie un entier contenant le code d’état HTTP de la transaction, tel qu’il est indiqué dans le journal.
txn.timer.total : entier Temps total d’activité pour la requête HTTP, compris entre le moment où le proxy a reçu le premier octet de l’en-tête de la requête et l’émission du dernier octet du corps de la réponse. Il s’agit de l’équivalent de %Ta dans le format de journalisation et est exprimé en millisecondes (ms). Pour plus d’informations, voir Section 8.4 “Événements de temporisation”
unique-id : chaîne Retourne l’identifiant unique attaché à la requête. La directive « unique-id-format » doit être définie. Si elle n’est pas définie, l’extraction d’échantillon unique-id échoue. Notez que l’identifiant unique est généralement utilisé avec les requêtes HTTP, mais cette extraction d’échantillon peut être utilisée avec d’autres protocoles. Évidemment, si elle est utilisée avec des protocoles autres que HTTP, la directive unique-id-format ne doit pas contenir de parties spécifiques à HTTP. Voir : unique-id-format et unique-id-header
url : chaîne Cette extraction permet d’obtenir l’URL de la requête telle qu’elle est présentée dans la requête. Un usage courant consiste à l’utiliser avec des caches capables de préchargement, ainsi que dans les portails qui doivent agréger plusieurs informations provenant de bases de données et les conserver en cache. Avec les listes de contrôle d’accès (ACL), il est préférable d’utiliser « path » plutôt que « url », car les clients peuvent envoyer une URL complète, comme cela se fait normalement avec les proxies. L’unique utilisation réelle consiste à effectuer un match avec « * », qui ne peut pas être effectué avec « path », et pour lequel une ACL prédéfinie existe déjà. Voir également « path » et « base ». Veuillez noter que toute référence à un fragment dans l’URI (’#’ après le chemin) est strictement interdite par la norme HTTP et sera rejetée. Toutefois, si le frontal recevant la requête dispose de l’option « accept-unsafe-violations-in-http-request », cette partie de fragment sera acceptée et apparaîtra également dans « url ».
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
url32 : entier Cette fonction retourne un hachage 32 bits de la valeur obtenue en concaténant le premier en-tête Host et l’URL entière, y compris les paramètres (et non seulement la partie chemin de la requête, comme dans la récupération « base32 » ci-dessus). Cette fonction est utile pour suivre l’activité par URL. Un hachage plus court est stocké, ce qui permet d’économiser beaucoup de mémoire. Le type de sortie est un entier non signé.
url32+src : binaire Cette commande retourne la concaténation des récupérations « url32 » et « src ». Le type résultant est binaire, de taille 8 ou 20 octets selon la famille d’adresse de la source. Cette fonction peut être utilisée pour suivre des compteurs par IP ou par URL.
url_ip: ip Cela extrait l’adresse IP de l’URL de la requête lorsque la partie hôte est présentée sous forme d’adresse IP. Son utilisation est très limitée. Par exemple, un système de surveillance pourrait utiliser ce champ comme alternative à l’adresse IP source afin de tester le chemin suivi par une adresse source donnée, ou pour forcer une entrée dans une table pour une adresse source donnée. Il peut être utilisé en combinaison avec « http-request set-dst » afin d’émuler l’option « option http_proxy » plus ancienne.
url_port : entier Cette option extrait la partie port de l’URL de la requête. Notez que si le port n’est pas spécifié dans la requête, le port 80 est supposé.
urlp([<name>[,<delim>[,i]]]): string
Cela extrait la première occurrence du paramètre <name> dans la chaîne de requête, qui commence après soit ‘?’ soit <delim>, et se termine avant ‘&’, ‘;’ ou <delim>. Le nom du paramètre est sensible à la casse, sauf si « i » est ajouté en troisième argument. Si aucun nom n’est fourni, tout paramètre correspondra, et le premier sera retourné. Le résultat est une chaîne correspondant à la valeur du paramètre <name> telle qu’elle apparaît dans la requête (aucune décodage URL n’est effectué). Cela peut être utilisé pour la persistance de session basée sur un identifiant client, pour extraire un cookie d’application transmis en tant que paramètre d’URL, ou dans les ACLs pour appliquer certaines vérifications. Notez que la version ACL de cette fonction itère sur plusieurs paramètres et signalera successivement toutes les valeurs si aucun nom n’est spécifié.
Dérivés ACL :
Note : Les dérivés ACL ne doivent pas être utilisés suivis d’un convertisseur ou dans des ACL utilisant une méthode de correspondance avec un modèle “-m”.
Exemple :
urlp_val([<name>[,<delim>[,i]]]): integer
Voir « urlp » ci-dessus. Celui-ci extrait le paramètre d’URL <name> de la requête et le convertit en valeur entière. Cela peut être utilisé pour la persistance de session basée sur un identifiant utilisateur, par exemple, ou avec des listes de contrôle d’accès (ACL) pour correspondre à un numéro de page ou un prix.
7.3.7. Récupération d’exemples pour les développeurs
Cet ensemble de méthodes d’extraction d’échantillon est réservé aux développeurs et ne doit jamais être utilisé dans un environnement de production, sauf sur demande explicite du développeur, à des fins de débogage. En outre, aucune attention particulière ne sera portée à la compatibilité descendante. Aucune garantie n’est donnée quant au fait que les extraits d’échantillons suivants ne changeront pas, ne seront pas renommés ou ne seront pas simplement supprimés. Soyez donc particulièrement prudent si vous devez en utiliser un. Pour éviter toute ambiguïté, ces extraits d’échantillons sont placés dans la portée dédiée « internal », par exemple “internal.strm.is_htx”.
Résumé des méthodes d’extraction d’échantillon de cette section et de leurs types respectifs :
Liste détaillée :
internal.htx.data : entier Renvoie la taille en octets utilisée par les données dans le message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.free : entier Renvoie l’espace libre (taille - utilisé) en octets dans le message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.free_data : entier Retourne l’espace libre pour les données en octets dans le message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.has_eom : boolean Renvoie true si le message HTX associé à un canal contient le drapeau de fin de message (EOM). Sinon, renvoie false. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.nbblks : entier Renvoie le nombre de blocs présents dans le message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.size : entier Renvoie la taille totale en octets du message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx.used : entier Retourne la taille totale utilisée en octets (données + métadonnées) dans le message HTX associé à un canal. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
internal.htx_blk.size(<idx>): integer
Retourne la taille du bloc situé à la position <idx> dans le message HTX associé à un canal ou 0 s’il n’existe pas. Le canal est sélectionné en fonction de la direction de l’échantillonnage. <idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : le bloc le plus ancien inséré
* tail : le bloc le plus récent inséré
* first : le premier bloc à partir duquel (re)commencer l’analyse
internal.htx_blk.type(<idx>): string
Renvoie le type du bloc à la position <idx> dans le message HTX associé à un canal ou “HTX_BLK_UNUSED” s’il n’existe pas. Le canal est sélectionné en fonction de la direction de l’échantillonnage.
<idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : le bloc le plus ancien inséré
* tail : le bloc le plus récent inséré
* first : le premier bloc à partir duquel (re)commencer l’analyse
internal.htx_blk.data(<idx>): binary
Renvoie la valeur du bloc DATA à la position <idx> dans le message HTX associé à un canal ou une chaîne vide si celui-ci n’existe pas ou s’il ne s’agit pas d’un bloc DATA. Le canal est sélectionné en fonction de la direction de l’échantillonnage. <idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : Le bloc inséré le plus ancien
* tail : Le bloc inséré le plus récent
* first : Le premier bloc à partir duquel (re)commencer l'analyse
internal.htx_blk.hdrname(<idx>): string
Renvoie le nom de l’en-tête du bloc EN-TÊTE à la position <idx> dans le message HTX associé à un canal ou une chaîne vide si celui-ci n’existe pas ou s’il ne s’agit pas d’un bloc EN-TÊTE. Le canal est choisi en fonction de la direction de l’échantillonnage. <idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : Le bloc inséré le plus ancien
* tail : Le bloc inséré le plus récent
* first : Le premier bloc à partir duquel (re)commencer l'analyse
internal.htx_blk.hdrval(<idx>): string
Renvoie la valeur de l’en-tête du bloc EN-TÊTE à la position <idx> dans le message HTX associé à un canal ou une chaîne vide si celui-ci n’existe pas ou s’il ne s’agit pas d’un bloc EN-TÊTE. Le canal est sélectionné en fonction de la direction de l’échantillonnage. <idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : Le bloc inséré le plus ancien
* tail : Le bloc inséré le plus récent
* first : Le premier bloc à partir duquel (re)commencer l'analyse
internal.htx_blk.start_line(<idx>): string
Renvoie la valeur du bloc REQ_SL ou RES_SL à la position <idx> dans le message HTX associé à un canal, ou une chaîne vide si celui-ci n’existe pas ou s’il ne s’agit pas d’un bloc SL. Le canal est sélectionné en fonction de la direction de l’échantillonnage. <idx> peut être un entier positif quelconque ou l’une des valeurs spéciales suivantes :
* head : Le bloc inséré le plus ancien
* tail : Le bloc inséré le plus récent
* first : Le premier bloc à partir duquel (re)commencer l'analyse
internal.strm.is_htx : boolean Renvoie true si le flux courant est un flux HTX. Cela signifie que les données dans les tampons de canal sont stockées selon la représentation interne HTX. Sinon, renvoie false.
7.4. ACL prédéfinies
Certains ACL prédéfinies sont intégrées en dur afin de ne pas devoir les déclarer dans chaque frontal qui en a besoin. Leur nom est toujours en majuscules pour éviter toute confusion. Leur équivalence est indiquée ci-dessous.