9. Statistiques et surveillance
Il est possible de consulter l’état de HAProxy. Le mécanisme le plus couramment utilisé est la page de statistiques HTTP. Cette page expose également un format de sortie CSV alternatif destiné aux outils de surveillance. Le même format est disponible via le socket Unix.
Les statistiques sont regroupées par catégories désignées sous le nom de domaines, correspondant aux différents composants d’HAProxy. Deux domaines sont disponibles : proxy et resolvers. Si aucun domaine n’est précisé, le domaine proxy est sélectionné. Notez que seules les statistiques du proxy sont affichées sur la page HTTP.
9.1. Format CSV
Les statistiques peuvent être consultées soit via le socket Unix, soit via la page HTTP. Les deux méthodes fournissent un format CSV dont les champs sont décrits ci-dessous. La première ligne commence par un dièse (’#’) et contient un mot par champ séparé par des virgules, représentant le titre de la colonne. Toutes les lignes suivantes, à partir de la deuxième, utilisent un format CSV classique avec une virgule comme délimiteur, et la guillemet double (’"’) comme délimiteur textuel facultatif, uniquement si le texte enclos est ambigu (s’il contient une guillemet ou une virgule). Le caractère guillemet double (’"’) présent dans le texte est doublé (’""’), ce qui correspond au format reconnu par la plupart des outils. Veuillez ne pas insérer de colonne avant celles-ci afin de ne pas rompre les outils utilisant des positions de colonne codées en dur.
Pour les statistiques du proxy, après chaque nom de champ, les types pouvant avoir une valeur pour ce champ sont indiqués entre parenthèses. Les types sont L (écouteurs), F (frontaux), B (backends) et S (serveurs). Un ensemble fixe de champs statiques est toujours disponible dans le même ordre. Une colonne contenant le caractère ‘-’ délimite la fin des champs statiques, après laquelle la présence ou l’ordre des champs n’est pas garanti.
Voici la liste des champs statiques utilisant le domaine de statistiques du proxy :
Pour tous les autres domaines de statistiques, la présence ou l’ordre des champs n’est pas garantie. Dans ce cas, la ligne d’en-tête doit toujours être utilisée pour analyser les données CSV.
9.2. Format de sortie typé
Les commandes « show info » et « show stat » prennent en charge un mode où chaque valeur de sortie est accompagnée de son type et d’informations suffisantes pour déterminer comment la valeur doit être agrégée entre les processus et comment elle évolue.
Dans tous les cas, la sortie se compose d’une seule valeur par ligne, avec toutes les informations séparées en champs délimités par des deux-points (’:’).
La première colonne indique l’objet ou la métrique dont la sortie est générée. Son format est spécifique à la commande produisant cette sortie et ne sera pas décrit dans cette section. En général, il se compose d’une série d’identifiants et de noms de champs.
La deuxième colonne contient 4 caractères indiquant respectivement l’origine, la nature, la portée et l’état de persistance de la valeur signalée. Le premier caractère (l’origine) indique l’emplacement d’où la valeur a été extraite. Les caractères possibles sont :
Le deuxième caractère (la nature) indique la nature de l’information transportée par le champ afin de permettre à un agrégateur de déterminer quelle opération utiliser pour agréger plusieurs valeurs. Les caractères possibles sont :
Le troisième caractère (la portée) indique l’étendue à laquelle la valeur est représentative. Certains éléments peuvent être propres à un processus, tandis que d’autres peuvent être propres à une configuration ou à un système. Cette distinction est importante pour déterminer si une seule valeur doit être conservée lors de l’agrégation, ou si les valeurs doivent être agrégées. Les caractères suivants sont actuellement pris en charge :
Le quatrième caractère (état de persistance) indique que la valeur (la métrique) est volatile ou persistante lors des rechargements. Les caractères suivants sont attendus :
Les consommateurs de ces informations auront généralement besoin de ces 4 caractères pour déterminer avec précision comment rapporter les informations agrégées issues de plusieurs processus.
Après cette colonne, la troisième colonne indique le type du champ, parmi « s32 » (entier signé 32 bits), « s64 » (entier signé 64 bits), « u32 » (entier non signé 32 bits), « u64 » (entier non signé 64 bits), « str » (chaîne de caractères). Il est important de connaître le type avant d’analyser la valeur afin de la lire correctement. Par exemple, une chaîne ne contenant que des chiffres reste une chaîne et non un entier (par exemple, un code d’erreur extrait par une vérification).
Ensuite, la quatrième colonne est la valeur elle-même, encodée selon son type. Les chaînes sont écrites telles quelles immédiatement après les deux-points, sans espace initial. Si une chaîne contient un deux-points, il s’affiche normalement. Cela signifie que la sortie ne doit pas être divisée exclusivement autour des deux-points, sinon certaines sorties de vérification ou des adresses de serveur pourraient être tronquées.
9.3. Commandes Unix Socket
Le socket de statistiques n’est pas activé par défaut. Pour l’activer, il est nécessaire d’ajouter une ligne dans la section globale de la configuration haproxy. Une deuxième ligne est recommandée afin de définir un délai d’expiration plus élevé, toujours apprécié lors de l’émission de commandes manuellement :
Il est également possible d’ajouter plusieurs instances de socket de statistiques en répétant la ligne, et de les faire écouter sur un port TCP au lieu d’une socket UNIX. Cela n’est jamais fait par défaut car cela présente un risque, mais peut s’avérer utile dans certaines situations :
Pour accéder à la socket, une utilitaire externe tel que « socat » est nécessaire. Socat est un outil polyvalent permettant de connecter n’importe quoi à n’importe quoi. Nous l’utilisons pour connecter des terminaux à la socket, ou des canaux stdin/stdout à celle-ci pour les scripts. Les deux syntaxes principales que nous utiliserons sont les suivantes :
Le premier est utilisé avec des scripts. Il est possible d’envoyer la sortie d’un script vers HAProxy, et de transmettre la sortie d’haproxy à un autre script. Cela est utile, par exemple, pour récupérer des compteurs ou des traces d’attaque.
Le second est utile uniquement pour émettre des commandes manuellement. Il présente l’avantage que le terminal est géré par la bibliothèque readline, qui prend en charge l’édition de ligne et l’historique, ce qui est très pratique lors de l’émission de commandes répétées (par exemple : surveiller un compteur).
La socket prend en charge trois modes de fonctionnement :
- non interactif, silencieux
- interactif, silencieux
- interactif avec invite
Le mode non interactif est le mode par défaut lorsque socat se connecte à la socket. Dans ce mode, une seule ligne peut être envoyée. Elle est traitée en entier, les réponses sont renvoyées, puis la connexion se ferme après la fin de la réponse. C’est le mode utilisé par les scripts et les outils de surveillance. Il est possible d’envoyer plusieurs commandes dans ce mode, à condition de les séparer par un point-virgule (’;’). Par exemple :
Si une commande doit utiliser un point-virgule ou une barre oblique inverse (par exemple, dans une valeur), elle doit être précédée d’une barre oblique inverse (’\’).
Le mode interactif permet d’envoyer de nouvelles commandes après la fin des commandes des lignes précédentes. Il existe deux variantes : l’une silencieuse, qui fonctionne comme le mode non interactif, sauf que le socket attend une nouvelle commande au lieu de se fermer, et une autre où une invite est affichée (’>’) au début de la ligne. Le mode interactif est préféré pour les outils avancés, tandis que le mode invite est préféré pour les humains.
Le mode peut être modifié à l’aide de la commande « prompt ». Par défaut, il bascule entre les modes interactif et prompt. Saisir « prompt » en mode interactif active le mode prompt. La commande accepte optionnellement un mode spécifique parmi les suivants :
- “n” : mode non interactif (exécution d’une seule commande, puis arrêt)
- “i” : mode interactif (exécution de plusieurs commandes, sans invite)
- “p” : mode invite (exécution de plusieurs commandes avec invite)
Étant donné que le mode par défaut est non interactif, la commande « prompt » doit être utilisée en premier afin de basculer le mode, faute de quoi la commande précédente entraînera la fermeture de la connexion. Le basculement vers le mode non interactif entraîne la fermeture de la connexion après la finalisation de toutes les commandes de la même ligne.
Pour cette raison, lors du débogage manuel, il est courant de commencer par la commande « prompt » :
afficher les informations…
Les outils interactifs peuvent préférer commencer par « prompt i » pour passer en mode interactif sans le prompt.
Optionnellement, le temps de fonctionnement du processus peut être affiché dans l’invite. Pour activer cette fonctionnalité, la commande « prompt timed » active l’invite et bascule l’affichage de l’heure. Le temps de fonctionnement est affiché au format « d:hh:mm:ss », où « d » représente le nombre de jours, et « hh », « mm », « ss » le nombre d’heures, de minutes et de secondes, chacun sur deux chiffres :
[23:03:34:39]> show version 2.8-dev9-e5e622-18
[23:03:34:41]> quit
Lorsque l’invite temporelle est définie sur l’interface CLI principale, l’invite affiche le temps de fonctionnement du processus actuellement sélectionné, ce qui fonctionne pour le maître, le worker actuel ou un worker plus ancien :
Étant donné qu’il est possible d’envoyer plusieurs commandes en même temps, HAProxy utilise la ligne vide comme délimiteur pour marquer la fin de la sortie de chaque commande, et veille à ce qu’aucune commande ne produise de ligne vide en sortie. Un script peut donc parser facilement la sortie, même lorsque plusieurs commandes ont été enchaînées sur une seule ligne.
Certains commandes peuvent accepter un chargement optionnel. Pour ajouter un chargement à une commande, la première ligne doit se terminer par le motif “<<\n”. Les lignes suivantes seront traitées comme le chargement et peuvent contenir autant de lignes que nécessaire. Pour valider une commande avec un chargement, celle-ci doit se terminer par une ligne vide.
Le motif du payload peut être personnalisé afin de modifier la manière dont le payload se termine. Pour terminer un payload par autre chose qu’une ligne vide, un motif personnalisé peut être défini entre ‘<<’ et ‘\n’. Jusqu’à 64 caractères peuvent être utilisés en plus de ‘<<’, sinon cela ne sera pas considéré comme un payload. Il devrait suffire d’utiliser des motifs de payload aléatoires. Par exemple, pour utiliser un fichier PEM contenant des lignes vides et des commentaires :
Des limitations existent : le motif “<<” ne doit pas être collé au dernier mot de la ligne. La longueur d’une ligne de commande ne doit pas dépasser tune.bufsize, y compris le motif marquant le début du payload, mais en excluant le payload lui-même. La taille du payload est limitée par défaut à 128 Ko. Cette valeur peut être modifiée en configurant le paramètre global “tune.cli.max-payload-size”, avec certaines précautions. Notez que le motif marquant la fin du payload fait partie de cette limite.
Lorsqu’un payload est saisi en mode interactif, l’invite change de « > » à « + ».
Il est important de comprendre qu’en lançant plusieurs processus HAProxy sur les mêmes sockets, n’importe quel processus peut traiter la requête et produire ses propres statistiques.
La liste des commandes actuellement prises en charge sur le socket de statistiques est fournie ci-dessous. Si une commande inconnue est envoyée, HAProxy affiche le message d’utilisation, qui rappelle toutes les commandes prises en charge. Certaines commandes supportent une syntaxe plus complexe ; en cas d’erreur, le message indique généralement quelle partie de la commande est invalide.
Certaines commandes nécessitent un niveau de privilège supérieur pour fonctionner. Si vous ne disposez pas des privilèges suffisants, vous obtiendrez une erreur « Permission denied ». Veuillez consulter l’option « level » des lignes keyword « bind » dans le manuel de configuration pour plus d’informations.
abort ssl ca-file <cafile>
Abandonner et supprimer une transaction de mise à jour temporaire du fichier CA.
Voir également « set ssl ca-file » et « commit ssl ca-file ».
abort ssl cert <filename>
Annuler et supprimer une transaction de mise à jour de certificat SSL temporaire.
Voir également « set ssl cert » et « commit ssl cert ».
abort ssl crl-file <crlfile>
Abandonner et supprimer une transaction de mise à jour temporaire d’un fichier CRL.
Voir également « set ssl crl-file » et « commit ssl crl-file ».
acme renew <certificate>
Démarre une tâche de génération de certificat ACME avec le nom de certificat fourni. Le certificat doit être lié à une section acme, voir la section 12.8 « ACME » du manuel de configuration. Voir également « acme status ».
acme status
Affiche l’état de chaque certificat configuré avec ACME.
Cette commande affiche, séparés par une tabulation :
- Le nom du certificat configuré dans HAProxy
- La section acme utilisée dans la configuration
- L’état de la tâche acme, soit « Running », soit « Scheduled » ou soit « Stopped »
- La date d’expiration UTC du certificat au format ISO8601
- Le temps restant avant expiration (0d si expiré)
- La date planifiée UTC du certificat au format ISO8601
- Le temps restant avant planification (0d si Running)
Exemple :
add acl [@<ver>] <acl> <pattern>
Ajoutez une entrée dans la liste de contrôle d’accès <acl>. <acl> correspond au #<id> ou au <name> retourné par la commande « show acl ».
Cette commande ne vérifie pas si l’entrée existe déjà. Les entrées sont ajoutées à la version courante de la liste de contrôle d’accès, sauf si une version spécifique est précisée avec “@<ver>”. Ce numéro de version doit avoir été préalablement alloué par la commande « prepare acl », et se situer entre les versions indiquées dans “curr_ver” et “next_ver” dans la sortie de la commande « show acl ». Les entrées ajoutées avec un numéro de version spécifique ne seront pas prises en compte avant une opération « commit acl » sur celles-ci. Elles peuvent toutefois être consultées à l’aide de la commande « show acl @<ver> », et effacées à l’aide de la commande « clear acl @<ver> ».
Cette commande ne peut pas être utilisée si la référence <acl> est un nom également utilisé avec une carte. Dans ce cas, la commande « add map » doit être utilisée à la place.
add backend <name> from <defproxy> [mode <mode>] [guid <guid>]
Instanciez un nouveau proxy backend nommé <name>.
Seuls les proxies TCP ou HTTP peuvent être créés. Toutes les paramètres sont hérités de l’instance de proxy par défaut <defproxy>. Par défaut, il est obligatoire de préciser le mode backend via l’argument du même nom, sauf si <defproxy> le définit explicitement. Il est également possible d’utiliser un argument GUID facultatif si nécessaire.
Les serveurs peuvent être ajoutés via la commande « add server ». Le backend est initialisé dans l’état non publié. Une fois prêt à recevoir le trafic, utilisez la commande « publish backend » pour exposer l’instance nouvellement créée.
Tous les proxies par défaut nommés peuvent être utilisés, à condition qu’ils respectent les mêmes règles d’héritage appliquées lors de l’analyse de la configuration. Toutefois, certaines exceptions s’appliquent, par exemple lorsque le mode n’est ni TCP ni HTTP.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
add map [@<ver>] <map> <key> <value>
Ajoutez une entrée dans la carte <map> pour associer la valeur <value> à la clé <key>. Cette commande ne vérifie pas si l’entrée existe déjà. Elle est principalement utilisée pour remplir une carte après une opération « clear » ou « prepare ». Les entrées sont ajoutées à la version courante de la liste ACL, sauf si une version spécifique est indiquée avec « @<ver> ». Ce numéro de version doit avoir été préalablement alloué par « prepare acl », et se situe entre les versions indiquées dans “curr_ver” et “next_ver” dans la sortie de « show acl ». Les entrées ajoutées avec un numéro de version spécifique ne seront pas prises en compte avant une opération « commit map » sur celles-ci. Elles peuvent toutefois être consultées à l’aide de la commande « show map @<ver> », et effacées à l’aide de la commande « clear acl @<ver> ». Si la carte désignée est également utilisée comme une ACL, celle-ci ne correspondra qu’à la partie <key> et ignora la partie <value>. En utilisant la syntaxe du payload, il est possible d’ajouter plusieurs paires clé/valeur en les entrant sur des lignes séparées. Sur chaque nouvelle ligne, le premier mot est la clé et le reste de la ligne est considéré comme la valeur, qui peut même contenir des espaces.
Exemple :
add server <backend>/<server> [args]*
Instanciez un nouveau serveur attaché au backend <backend>.
Le nom <server> ne doit pas déjà être utilisé dans le backend. Une restriction particulière s’applique au backend, qui doit utiliser un algorithme de répartition de charge dynamique. Un sous-ensemble de mots-clés issus de l’instruction de configuration du serveur peut être utilisé pour configurer le comportement du serveur (voir « add server help » pour obtenir la liste). Notez également qu’aucun paramètre ne sera réutilisé à partir d’une éventuelle instruction « default-server » dans le même backend.
Actuellement, un serveur dynamique est initialisé de manière statique avec la méthode d’initialisation « none ». Cela signifie qu’aucune résolution ne sera effectuée si un nom FQDN est spécifié comme adresse, même si la création du serveur sera validée.
Pour prendre en charge les opérations de rechargement, il est nécessaire que le serveur créé via l’interface en ligne de commande soit également inséré manuellement dans le fichier de configuration HAProxy pertinent. Un serveur dynamique absent de la configuration ne sera pas restauré après une opération de rechargement.
Un serveur dynamique peut utiliser le mot-clé « track » pour suivre l’état de vérification d’un autre serveur défini dans la configuration. Toutefois, il n’est pas possible de suivre un autre serveur dynamique. Cela garantit que la chaîne de suivi reste cohérente, même en cas de suppression de serveurs dynamiques.
Utilisez le mot-clé « check » pour activer la prise en charge des vérifications de santé. Notez que la vérification de santé est désactivée par défaut et doit être activée indépendamment du serveur à l’aide de la commande « enable health ». Pour les vérifications d’agent, utilisez le mot-clé « agent-check » et la commande « enable agent ». Notez que, dans ce cas, le serveur peut être activé par l’agent en fonction de l’état rapporté, sans commande explicite « enable server ». Cela signifie également qu’une attention particulière est requise lors de la suppression d’un serveur dynamique avec vérification d’agent. L’agent doit d’abord être désactivé à l’aide de la commande « disable agent » afin de pouvoir placer le serveur en mode maintenance requis avant sa suppression.
Il se peut que la limite de descripteurs de fichiers (fd) soit atteinte lors de l’utilisation d’un grand nombre de serveurs dynamiques. Veuillez vous référer à la documentation du mot-clé global « u-limit » dans ce cas.
add server help
Liste des mots-clés pris en charge pour les serveurs dynamiques par la version actuelle de HAProxy. La syntaxe des mots-clés est similaire à celle de la ligne server du fichier de configuration ; reportez-vous à leur documentation respective pour plus de détails.
add ssl ca-file <cafile> <payload>
Ajoutez un nouveau certificat à un fichier ca. Cette commande est utile lorsque vous avez atteint la limite de taille de tampon sur l’interface en ligne de commande et que vous souhaitez ajouter plusieurs certificats. Au lieu d’utiliser une commande « set » avec tous les certificats, vous pouvez ajouter chaque certificat individuellement. Une commande « set ssl ca-file » réinitialise le fichier ca.
Exemple :
add ssl crt-list <crtlist> <certificate>
Ajoutez un certificat à une liste de certificats (crt-list). Cette commande peut également être utilisée avec des répertoires, puisque les répertoires sont désormais chargés de la même manière que les listes de certificats. Cette commande permet d’utiliser un nom de certificat en paramètre ; pour utiliser des options SSL ou des filtres, une ligne de crt-list doit être envoyée en charge utile au lieu de paramètre. Une seule ligne de crt-list est prise en charge dans la charge utile. Cette commande charge le certificat pour toutes les lignes bind utilisant la crt-list. Pour ajouter un nouveau certificat à HAProxy, les commandes « new ssl cert » et « set ssl cert » doivent être utilisées.
Exemple :
add ssl ech <bind> <payload>
Ajoutez une clé ECH à une ligne <bind>. Le contenu doit être au format PEM pour ECH.
(https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni
)
Le format de la ligne bind est <frontend>/@<filename>:<linenum> (exemple : frontend1/@haproxy.conf
:19)
ou <frontend>/<name> si la ligne bind a été nommée avec le mot-clé « name ».
Exige une version d’OpenSSL qui prend en charge ECH, et HAProxy doit être compilé avec USE_ECH=1. Cette commande n’est prise en charge que sur une connexion CLI en mode expérimental (voir « experimental-mode on »).
Voir également « show ssl ech » et « ech » dans la Section 5.1 du manuel de configuration.
Exemple :
add ssl jwt <filename>
Ajoutez un certificat déjà chargé à la liste des certificats pouvant être utilisés pour la validation JWT (voir le convertisseur “jwt_verify_cert”). Cette commande ne fonctionne pas sur les transactions en cours. Voir également les commandes « del ssl jwt » et « show ssl jwt ». Voir l’option de certificat « jwt » pour plus d’informations.
clear counters
Réinitialise les valeurs maximales des compteurs de statistiques dans chaque proxy (frontal et backend) et dans chaque serveur. Les compteurs accumulés ne sont pas affectés. Les compteurs d’activité internes rapportés par la commande « show activity » sont également réinitialisés. Cette commande peut être utilisée pour obtenir des compteurs propres après un incident, sans avoir à redémarrer ni à réinitialiser les compteurs de trafic. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés pour les niveaux « operator » ou « admin ».
clear counters all
Réinitialise tous les compteurs de statistiques dans chaque proxy (frontal et backend) ainsi que dans chaque serveur. Cette opération a le même effet qu’un redémarrage. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés au niveau « admin ».
clear acl [@<ver>] <acl>
Supprimez toutes les entrées de la liste de contrôle d’accès <acl>. <acl> correspond au #<id> ou au <name> retourné par la commande « show acl ». Notez que si la référence <acl> est un nom partagé avec une carte, cette dernière sera également vidée. Par défaut, seule la version courante de la liste de contrôle d’accès est vidée (celle en cours de correspondance). Toutefois, il est possible de préciser une autre version en utilisant ‘@’ suivi de cette version.
clear map [@<ver>] <map>
Supprimez toutes les entrées de la carte <map>. <map> est le #<id> ou le <name> retourné par la commande « show map ». Notez que si la référence <map> est un nom partagé avec une liste de contrôle d’accès (acl), cette dernière sera également vidée. Par défaut, seule la version actuelle de la carte est vidée (celle en cours de correspondance). Toutefois, il est possible de spécifier une autre version en utilisant ‘@’ suivi de cette version.
clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ] |
Supprimez les entrées de la table de persistance <table>.
Cela est généralement utilisé pour débloquer certains utilisateurs qui se plaignent d’avoir été abusivement privés d’accès à un service, mais cela peut aussi servir à supprimer des entrées de persistance correspondant à un serveur qui va être remplacé (voir « show table » ci-dessous pour plus de détails). Notez qu’il arrive parfois que la suppression d’une entrée soit refusée car elle est actuellement suivie par une session. Il est courant de réessayer quelques secondes plus tard, après la fin de la session.
Dans le cas où aucun argument d’option n’est fourni, toutes les entrées seront supprimées.
Lorsque le formulaire “data.” est utilisé, les entrées correspondant à un filtre appliqué à l’aide des données stockées (voir « stick-table » dans la section 4.2) sont supprimées. Un type de données stockées doit être spécifié dans <type>, et ce type de données doit être stocké dans la table, sinon une erreur est signalée. Les données sont comparées selon <operator> avec l’entier 64 bits <value>. Les opérateurs sont les mêmes qu’avec les ACLs :
- eq : correspond aux entrées dont les données sont égales à cette valeur
- ne : correspond aux entrées dont les données sont différentes de cette valeur
- le : correspond aux entrées dont les données sont inférieures ou égales à cette valeur
- ge : correspond aux entrées dont les données sont supérieures ou égales à cette valeur
- lt : correspond aux entrées dont les données sont inférieures à cette valeur
- gt : correspond aux entrées dont les données sont supérieures à cette valeur
Lorsque la forme clé est utilisée, l’entrée <key> est supprimée. La clé doit être du même type que la table, ce qui est actuellement limité à IPv4, IPv6, entier et chaîne.
Lorsque la forme ptr est utilisée, l’entrée <ptr> est supprimée. <ptr> est écrit sous la forme 0xffff et doit correspondre à l’adresse renvoyée par une commande précédente « show table ». Correspondre à une entrée à l’aide de son pointeur peut être pertinent si l’entrée ne peut pas être identifiée à l’aide de sa clé en raison d’une clé vide ou de caractères incompatibles sur le CLI.
Si data.<type> est de type tableau, on peut utiliser « [] » pour accéder à un index spécifique du tableau, comme ceci : data.gpt[1]
Exemple :
commit acl @<ver> <acl>
Validez tous les changements apportés à la version <ver> de la liste de contrôle d’accès <acl>, et supprimez toutes les versions antérieures. <acl> est le numéro #<id> ou le <name> retourné par la commande « show acl ». Le numéro de version doit être compris entre “curr_ver”+1 et “next_ver” tel que rapporté par la commande « show acl ». Le contenu à valider dans la liste de contrôle d’accès peut être consulté à l’aide de la commande « show acl @<ver> <acl> » si nécessaire. Le numéro de version spécifié a normalement été créé à l’aide de la commande « prepare acl ». La substitution est atomique. Elle consiste à mettre à jour atomiquement la version courante vers la version spécifiée, ce qui rend instantanément invisibles toutes les entrées des autres versions et rend visibles toutes les entrées de la nouvelle version. Il est également possible d’utiliser cette commande pour supprimer atomiquement toutes les entrées visibles d’une liste de contrôle d’accès en appelant d’abord « prepare acl », puis en validant sans ajouter d’entrée. Cette commande ne peut pas être utilisée si la référence <acl> est un nom également utilisé comme carte. Dans ce cas, la commande « commit map » doit être utilisée à la place.
commit map @<ver> <map>
Validez toutes les modifications apportées à la version <ver> de la carte <map>, et supprimez toutes les versions antérieures. <map> est le #<id> ou le <name> retourné par la commande « show map ». Le numéro de version doit être compris entre “curr_ver”+1 et “next_ver”, tel que rapporté par la commande « show map ». Le contenu à valider dans la carte peut être consulté à l’aide de la commande « show map @<ver> <map> », si nécessaire. Le numéro de version spécifié a normalement été créé à l’aide de la commande « prepare map ». La substitution est atomique. Elle consiste à mettre à jour atomiquement la version courante vers la version spécifiée, ce qui entraîne instantanément la disparition de toutes les entrées des autres versions, et la visibilité immédiate de toutes les entrées de la nouvelle version. Il est également possible d’utiliser cette commande pour supprimer atomiquement toutes les entrées visibles d’une carte en exécutant d’abord « prepare map », puis en validant sans ajouter d’entrée.
commit ssl ca-file <cafile>
Valider une transaction de mise à jour temporaire du fichier CA SSL.
Dans le cas d’un fichier CA existant (dans un état « Used » dans « show ssl ca-file »), la nouvelle entrée d’arbre de fichier CA est insérée dans l’arbre de fichiers CA, et toutes les instances utilisant cette entrée de fichier CA sont reconstruites, ainsi que les contextes SSL qu’elles nécessitent. Tous les contextes précédemment utilisés par les instances reconstruites sont supprimés. En cas de succès, l’entrée de fichier CA précédente est supprimée de l’arbre. En cas d’échec, rien n’est supprimé ni supprimé, et tous les contextes SSL d’origine sont conservés et utilisés. Une fois la transaction temporaire validée, elle est détruite.
Dans le cas d’un nouveau fichier CA (après une commande « new ssl ca-file » et dans un état « Unused » affiché par « show ssl ca-file »), le fichier CA sera inséré dans l’arbre des fichiers CA, mais ne sera utilisé nulle part dans HAProxy. Pour l’utiliser et générer des contextes SSL qui l’utilisent, vous devrez l’ajouter à une liste de certificats avec la commande « add ssl crt-list ».
Voir également « new ssl ca-file », « set ssl ca-file », « add ssl ca-file », « abort ssl ca-file » et « add ssl crt-list ».
commit ssl cert <filename>
Validez une transaction de mise à jour temporaire du certificat SSL.
Dans le cas d’un certificat existant (dans un état « Used » dans « show ssl cert »), génère tous les contextes SSL et les SNIs dont il a besoin, insère-les, puis supprime les anciens. Remplace en mémoire les anciens certificats SSL partout où <filename> était utilisé dans la configuration. En cas d’échec, rien n’est supprimé ni inséré. Une fois la transaction temporaire validée, elle est détruite.
Dans le cas d’un nouveau certificat (après une commande « new ssl cert » et dans un état « Unused » affiché par « show ssl cert »), le certificat sera enregistré dans un stockage de certificats, mais ne sera utilisé nulle part dans haproxy. Pour l’utiliser et générer ses SNI, il faudra l’ajouter à une liste de certificats (crt-list) ou à un répertoire via la commande « add ssl crt-list ».
Voir également « new ssl cert », « set ssl cert », « abort ssl cert » et « add ssl crt-list ».
commit ssl crl-file <crlfile>
Valider une transaction de mise à jour temporaire d’un fichier CRL SSL.
Dans le cas d’un fichier CRL existant (dans un état « Used » dans « show ssl crl-file »), la nouvelle entrée de fichier CRL est insérée dans l’arbre des fichiers CA (qui contient à la fois les fichiers CA et les fichiers CRL) et chaque instance utilisant l’entrée de fichier CRL est reconstruite, ainsi que les contextes SSL qu’elle nécessite. Tous les contextes précédemment utilisés par les instances reconstruites sont supprimés. En cas de succès, l’entrée de fichier CRL précédente est supprimée de l’arbre. En cas d’échec, rien n’est supprimé ni supprimé, et tous les contextes SSL d’origine sont conservés et utilisés. Une fois la transaction temporaire validée, elle est détruite.
Dans le cas d’un nouveau fichier CRL (après une commande « new ssl crl-file » et en état « Unused » dans « show ssl crl-file »), le fichier CRL sera inséré dans l’arbre des fichiers CRL, mais ne sera utilisé nulle part dans HAProxy. Pour l’utiliser et générer des contextes SSL qui l’utilisent, vous devrez l’ajouter à une liste de certificats avec la commande « add ssl crt-list ».
Voir également « new ssl crl-file », « set ssl crl-file », « abort ssl crl-file » et « add ssl crt-list ».
debug counters [reset|show|on|off|all|bug|chk|cnt|glt|?]*
Liste les compteurs internes placés dans le code, qui peuvent varier selon certaines options de compilation. Certains dépendent de DEBUG_STRICT, d’autres de DEBUG_COUNTERS. La commande prend une combinaison d’arguments multiples, certains définissant des actions et d’autres des filtres : - bug active l’affichage des compteurs des requêtes BUG_ON() - cnt active l’affichage des compteurs des requêtes COUNT_IF() - chk active l’affichage des compteurs des requêtes CHECK_IF() - glt active l’affichage des compteurs des requêtes COUNT_GLITCH() - all active l’affichage des compteurs qui n’ont jamais été déclenchés (valeur 0) - off action : désactive la mise à jour des compteurs COUNT_IF() - on action : active la mise à jour des compteurs COUNT_IF() - reset action : réinitialise tous les compteurs spécifiés - show action : affiche tous les compteurs spécifiés
Par défaut, l’action est « show » afin d’afficher les compteurs, et les compteurs listés sont tous des types ayant une valeur non nulle. La commande « show » est implicite lorsqu’aucune autre action n’est spécifiée, et n’est présente que pour faciliter la génération de commandes à partir de scripts.
La sortie commence par un compteur entier, suivi du type du compteur en majuscules, puis de son emplacement dans le code (fichier:ligne), du nom de la fonction, et éventuellement de « : » suivi d’une description. Veuillez noter que le format de sortie peut évoluer entre les versions majeures, et que de nouveaux types et entrées peuvent être rétroportés vers les versions stables dans le but d’améliorer les capacités de débogage. Tout suivi effectué sur ces éléments doit être réalisé de manière très permissive et ne devrait, idéalement, pas être effectué.
En règle générale, les utilisateurs finaux n’utilisent pas cette commande, mais ils peuvent être invités à la faire par un développeur cherchant à diagnostiquer une anomalie ou à rechercher des entrées CNT ou GLT. À noter que des entrées « CHK » non nulles ne devraient pas se produire et doivent être signalées aux développeurs, car elles pourraient indiquer des hypothèses incorrectes dans le code.
debug dev <command> [args]*
Appelle une commande spécifique au développeur. Prise en charge uniquement sur une connexion CLI en mode expert (voir « expert-mode on »). Ces commandes sont extrêmement dangereuses et sans tolérance ; toute utilisation incorrecte peut entraîner un plantage du processus. Elles sont destinées aux experts uniquement et doivent absolument ne pas être utilisées sauf instruction explicite. Certaines d’entre elles ne sont disponibles que lorsque haproxy est compilé avec DEBUG_DEV défini, car elles peuvent avoir des implications de sécurité. Toutes ces commandes exigent des privilèges d’administration et sont délibérément non documentées afin d’éviter d’encourager leur utilisation par des personnes non familières avec le code source.
del acl <acl> [<key>|#<ref>]
Supprimez toutes les entrées ACL de l’ACL <acl> correspondant à la clé <key>. <acl> est le #<id> ou le <name> retourné par la commande « show acl ». Si <ref> est utilisé, cette commande supprime uniquement la référence indiquée. La référence peut être trouvée en listant le contenu de l’ACL. Notez que si la référence <acl> est un nom partagé avec une map, l’entrée sera également supprimée dans la map.
del backend <name>
Supprime le proxy backend nommé <name>.
Cette opération n’est possible que pour les proxies TCP ou HTTP. Pour réussir, l’instance backend doit avoir été précédemment dépubliée. En outre, tous ses serveurs doivent avoir été supprimés en premier lieu (via la commande CLI « del server »). Enfin, aucune connexion active ne doit encore être associée à l’instance backend.
Il existe des restrictions supplémentaires qui empêchent la suppression d’un backend. Premièrement, un backend ne peut pas être supprimé s’il est explicitement référencé par des éléments de configuration, par exemple via une règle use_backend ou dans des expressions sample. Certains paramètres de proxy sont également incompatibles avec la suppression en temps d’exécution. Actuellement, cela concerne l’utilisation des options dépréciées dispatch ou transparent. En outre, un backend ne peut pas être supprimé s’il contient une table de persistance (stick-table) déclarée. Enfin, il est actuellement impossible de supprimer un backend si des serveurs QUIC étaient présents dedans.
Il peut être utile d’utiliser « wait be-removable » avant cette commande pour vérifier les prérequis mentionnés ci-dessus. Cela fournit également une méthode pour attendre la fermeture définitive des flux associés au backend cible.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
del map <map> [<key>|#<ref>]
Supprime toutes les entrées de la carte <map> correspondant à la clé <key>. <map> est le #<id> ou le <name> retourné par la commande « show map ». Si l’option <ref> est utilisée, cette commande supprime uniquement la référence indiquée. La référence peut être identifiée en listant le contenu de la carte. Notez que si la référence <map> est un nom partagé avec une liste de contrôle d’accès (acl), l’entrée sera également supprimée de la carte.
del ssl ca-file <cafile>
Supprimez une entrée d’arbre de fichier CA depuis HAProxy. Le fichier CA doit être inutilisé et retiré de toute liste crt-list. La commande « show ssl ca-file » affiche l’état des fichiers CA. La suppression ne fonctionne pas si un certificat est référencé directement via les directives « ca-file » ou « ca-verify-file » dans la configuration.
del ssl cert <certfile>
Supprimez un magasin de certificats depuis HAProxy. Le certificat doit être inutilisé (inclus pour la validation JWT) et retiré de toute liste crt-list ou répertoire. La commande « show ssl cert » affiche l’état du certificat. La suppression ne fonctionne pas avec un certificat référencé directement via la directive « crt » dans la configuration.
del ssl crl-file <crlfile>
Supprime une entrée de l’arborescence des fichiers CRL de HAProxy. Le fichier CRL doit être inutilisé et retiré de toute crt-list. La commande « show ssl crl-file » affiche l’état des fichiers CRL. La suppression ne fonctionne pas avec un certificat référencé directement par la directive « crl-file » dans la configuration.
del ssl crt-list <filename> <certfile[:line]>
Supprime une entrée dans une liste de certificats. Cette opération supprime tous les SNIs utilisés pour cette entrée dans les frontaux. Si un certificat est utilisé plusieurs fois dans une liste de certificats, vous devez préciser quelle ligne vous souhaitez supprimer. Pour afficher les numéros de ligne, utilisez la commande « show ssl crt-list -n <crtlist> ».
del ssl ech <bind>
Supprime les clés ECH d’une ligne bind.
Le format de la ligne bind est <frontend>/@<filename>:<linenum> (exemple : frontend1/@haproxy.conf
:19)
ou <frontend>/<name> si la ligne bind a été nommée avec le mot-clé « name ».
Exige une version d’OpenSSL qui prend en charge ECH, et HAProxy doit être compilé avec USE_ECH=1. Cette commande n’est prise en charge que sur une connexion CLI en mode expérimental (voir « experimental-mode on »).
Voir également « show ssl ech », « add ssl ech » et « ech » dans la Section 5.1 du manuel de configuration.
Exemple :
del ssl jwt <filename>
Supprime un certificat déjà chargé de la liste des certificats pouvant être utilisés pour la validation JWT (voir le convertisseur “jwt_verify_cert”). Cette commande ne fonctionne pas sur les transactions en cours. Voir également les commandes « add ssl jwt » et « show ssl jwt ». Voir l’option de certificat « jwt » pour plus d’informations.
del server <backend>/<server>
Supprimez un serveur supprimable attaché au backend <backend>. Un serveur supprimable est le serveur qui satisfait à toutes ces conditions :
- non référencé par d’autres éléments de configuration
- doit déjà être en maintenance (voir « disable server »)
- ne doit pas avoir de connexion active ou inactif
Si l’une de ces conditions n’est pas remplie, la commande échouera.
Les connexions actives sont celles ayant au moins une requête en cours. Il est possible d’accélérer leur fermeture en utilisant « shutdown sessions server ». Il est fortement recommandé d’utiliser « wait srv-removable » avant « del server » afin de garantir que toutes les connexions actives ou inactives sont fermées et que la commande aboutit.
disable agent <backend>/<server>
Marquez le contrôle de l’agent auxiliaire comme temporairement arrêté.
Dans le cas où une vérification d’agent est exécutée en tant que vérification auxiliaire, en raison du paramètre agent-check d’une directive server, de nouvelles vérifications ne sont initialisées que lorsque l’agent est activé. Ainsi, désactiver l’agent empêchera toute nouvelle vérification d’agent de démarrer jusqu’à ce que l’agent soit réactivé à l’aide de enable agent.
Lorsqu’un agent est désactivé, le traitement d’une vérification d’agent auxiliaire initiée pendant que l’agent était activé se déroule comme suit : toutes les valeurs qui modifieraient le poids, en particulier « drain » ou un poids retourné par l’agent, sont ignorées. Le traitement de la vérification d’agent reste inchangé dans les autres cas.
La motivation de cette fonctionnalité est de permettre de suspendre les effets de modification du poids provenant des vérifications d’agent, afin de configurer le poids d’un serveur à l’aide de set weight sans que celui-ci ne soit annulé par l’agent.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
disable dynamic-cookie backend <backend>
Désactiver la génération de cookies dynamiques pour le backend <backend>
disable frontend <frontend>
Marquez le frontal comme arrêté temporairement. Cela correspond au mode utilisé lors d’un redémarrage doux : le frontal libère le port mais peut être réactivé si nécessaire. Utilisez cette option avec précaution, car certains systèmes d’exploitation non Linux ne parviennent pas à le réactiver. Cette fonction est destinée à être utilisée dans des environnements où l’arrêt d’un proxy n’est tout simplement pas envisageable, mais où un proxy mal configuré doit tout de même être corrigé. Ainsi, il devient possible de libérer le port et de le réaffecter à un autre processus afin de restaurer les opérations. Le frontal apparaîtra avec le statut « STOP » sur la page de statistiques.
Le frontal peut être spécifié soit par son nom, soit par son identifiant numérique, précédé d’un dièse (’#’).
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
disable health <backend>/<server>
Marquez le contrôle d’état principal comme étant temporairement arrêté. Cela désactivera l’envoi des contrôles d’état, et le dernier résultat de contrôle d’état sera ignoré. Le serveur sera en état non contrôlé et considéré comme UP, sauf si un contrôle d’état auxiliaire le force à descendre.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
disable server <backend>/<server>
Marquez le serveur comme INDISPONIBLE pour maintenance. En ce mode, aucune vérification supplémentaire n’est effectuée sur le serveur jusqu’à ce qu’il quitte la maintenance. Si le serveur est suivi par d’autres serveurs, ceux-ci seront également marqués comme INDISPONIBLE pendant la maintenance.
Dans la page des statistiques, un serveur en maintenance apparaîtra avec un statut « MAINT », ses serveurs de suivi affichant quant à eux le statut « MAINT(via) ».
Le backend et le serveur peuvent chacun être spécifiés soit par leur nom, soit par leur identifiant numérique, précédé d’un dièse (’#’).
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
dump ssl cert <certfile>
Affiche un certificat chargé en mémoire HAProxy. Cela affichera le certificat au format PEM, suivi de la clé privée, puis du certificat feuille, enfin de la chaîne sera affichée. Vous pouvez également afficher une transaction en préfixant le nom de fichier par un astérisque. Cela est utile pour sauvegarder des certificats sur le système de fichiers lorsqu’ils ont été mis à jour via l’interface CLI et non sur le système de fichiers.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
Exemples :
dump stats-file
Génère un fichier de statistiques pouvant être utilisé pour charger les valeurs des compteurs HAProxy au démarrage. Consultez la section « Stats-file » pour plus de détails.
echo <text>
Affiche du texte avec l’interface en ligne de commande. Peut être utile pour écrire des commentaires entre les commandes lors de l’exportation du résultat de plusieurs commandes.
Exemple :
enable agent <backend>/<server>
Reprendre le contrôle auxiliaire de l’agent qui avait été temporairement arrêté.
Voir « désactiver l’agent » pour obtenir les détails sur l’effet de la mise en marche et de l’arrêt temporaire d’un agent auxiliaire.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
enable dynamic-cookie backend <backend>
Activez la génération de cookies dynamiques pour le backend <backend>. Une clé secrète doit également être fournie.
enable frontend <frontend>
Reprendre un frontal qui a été temporairement arrêté. Il se peut que certains ports d’écoute ne puissent plus être bindés (par exemple, si un autre processus les a pris depuis l’opération « désactiver le frontal »). Dans ce cas, une erreur est affichée. Certains systèmes d’exploitation ne peuvent pas reprendre un frontal qui a été désactivé.
Le frontal peut être spécifié soit par son nom, soit par son identifiant numérique, précédé d’un dièse (’#’).
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
enable health <backend>/<server>
Reprendre un contrôle d’état principal qui a été temporairement arrêté. Cela permettra à nouveau l’envoi de contrôles d’état. Voir « disable health » pour plus de détails.
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
enable server <backend>/<server>
Si le serveur était précédemment marqué comme DOWN pour maintenance, cela le marque comme UP et réactive les vérifications.
Le backend et le serveur peuvent chacun être spécifiés soit par leur nom, soit par leur identifiant numérique, précédé d’un dièse (’#’).
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
experimental-mode [on|off]
Sans option, cela indique si le mode expérimental est activé ou désactivé sur la connexion actuelle. En spécifiant « on », il active le mode expérimental pour la connexion CLI actuelle uniquement. Avec « off », il le désactive.
Le mode expérimental est utilisé pour accéder à des fonctionnalités supplémentaires encore en développement. Ces fonctionnalités sont actuellement instables et doivent être utilisées avec précaution. Elles peuvent faire l’objet de modifications infructueuses entre les versions.
Lorsqu’il est utilisé depuis l’interface CLI principale, cette commande ne doit pas être préfixée, car elle définira le mode pour tout worker lors de sa connexion à son interface CLI.
Exemple :
expert-mode [on|off]
Cette commande est similaire à experimental-mode, mais elle sert à activer ou désactiver le mode expert.
Le mode expert permet d’afficher des commandes experts qui peuvent être extrêmement dangereuses pour le processus et qui peuvent parfois aider les développeurs à recueillir des informations importantes sur des bogues complexes. Toute utilisation incorrecte de ces fonctionnalités entraîne probablement une panne du processus. N’utilisez pas cette option sans y être invité. Notez que cette commande est volontairement omise dans le message d’aide. Cette commande n’est accessible qu’au niveau administrateur. Passer à un autre niveau réinitialise automatiquement le mode expert.
Lorsqu’il est utilisé depuis l’interface CLI principale, cette commande ne doit pas être préfixée, car elle définira le mode pour tout worker lors de sa connexion à son interface CLI.
Exemple :
get map <map> <value>
Recherchez la valeur <value> dans la carte <map> ou dans la liste ACL <acl>. <map> ou <acl> correspondent au(s) <id> ou au <name> retourné(s) par la commande « show map » ou « show acl ». Cette commande renvoie tous les modèles correspondants associés à cette carte. Elle est utile pour le débogage des cartes et des listes ACL. Le format de sortie est composé d’une ligne par type correspondant. Chaque ligne est composée d’une série de mots séparés par des espaces.
Les deux premiers mots sont :
Les mots suivants ne sont retournés que si le motif correspond à une entrée.
`<index type>` : « tree » ou « list ». Algorithme interne de recherche.
`<case>` : « case-insensitive » ou « case-sensitive ». Interprétation de la casse.
`<entry matched>` : match="`<entry>`". Retourne le motif correspondant. Utile avec les expressions régulières.
Les deux derniers mots servent à indiquer la valeur renvoyée et son type. Dans le cas « acl », le modèle n’existe pas.
return=nothing : Aucun retour, car aucune « map » n'est définie.
return="`<value>`" : La valeur retournée au format chaîne.
return=cannot-display : La valeur ne peut pas être convertie en chaîne.
type="`<type>`": Le type de l'échantillon renvoyé.
get var <name>
Affiche l’existence, le type et le contenu de la variable globale du processus « name ». Seules les variables globales du processus sont lisibles, donc le nom doit commencer par ‘proc.’, sinon aucune variable ne sera trouvée. Cette commande nécessite les niveaux « operator » ou « admin ».
get weight <backend>/<server>
Rapporte le poids actuel et le poids initial du serveur <server> dans le backend <backend> ou une erreur si l’un des deux n’existe pas. Le poids initial est celui qui apparaît dans le fichier de configuration. Les deux sont normalement égaux sauf si le poids actuel a été modifié. Le backend et le serveur peuvent chacun être spécifiés soit par leur nom, soit par leur identifiant numérique, précédé d’un dièse (’#’).
help [<command>]
Affiche la liste des mots-clés connus ainsi que leur utilisation basique, ou les commandes correspondant à celle demandée. L’écran d’aide est également affiché pour les commandes inconnues.
httpclient [--htx] <method> <URI>
Lancez une requête HTTP et affichez la réponse sur la CLI. Pris en charge uniquement sur une connexion CLI en mode expert (voir « expert-mode on »). Destiné uniquement au débogage. L’outil httpclient est capable de résoudre un nom de serveur dans l’URL à l’aide de la section de résolution « default », qui est remplie par défaut avec les serveurs DNS de votre /etc/resolv.conf. Toutefois, il ne pourra pas résoudre un hôte provenant de /etc/hosts si vous n’utilisez pas un démon DNS local capable de résoudre ces noms.
L’option –htx permet d’utiliser la représentation interne HAProxy htx via la fonction htx_dump(), principalement utilisée pour le débogage.
new ssl ca-file <cafile>
Créez une nouvelle entrée vide dans l’arborescence de fichier de certificats CA, à remplir avec un ensemble de certificats CA et à ajouter à une liste crt. Cette commande doit être utilisée en combinaison avec « set ssl ca-file », « add ssl ca-file » et « add ssl crt-list ».
new ssl cert <filename>
Créez un nouveau magasin de certificats SSL vide à remplir avec un certificat et à ajouter à un répertoire ou à une liste de certificats. Cette commande doit être utilisée en combinaison avec « set ssl cert » et « add ssl crt-list ».
new ssl crl-file <crlfile>
Créez une nouvelle entrée vide dans l’arborescence de fichier CRL, destinée à être remplie par un ensemble de CRLs et ajoutée à une liste de certificats. Cette commande doit être utilisée en combinaison avec « set ssl crl-file » et « add ssl crt-list ».
prepare acl <acl>
Allouez un nouveau numéro de version dans la liste de contrôle d’accès <acl> pour une substitution atomique. <acl> est le #<id> ou le <name> retourné par la commande « show acl ». Le nouveau numéro de version est indiqué dans la réponse après « Nouvelle version créée : ». Ce numéro pourra ensuite être utilisé pour préparer l’ajout de nouvelles entrées dans la liste de contrôle d’accès, qui remplaceront atomiquement les entrées actuelles une fois validées. Il est indiqué comme “next_ver” dans la commande « show acl ». L’allocation de nouvelles versions n’a aucun impact, car les versions non utilisées sont automatiquement supprimées dès qu’une version plus récente est validée. Les numéros de version sont des valeurs non signées sur 32 bits, qui bouclent en fin de plage, il convient donc de porter une attention particulière lors de leur comparaison dans un programme externe. Cette commande ne peut pas être utilisée si la référence <acl> est un nom également utilisé comme carte. Dans ce cas, la commande « prepare map » doit être utilisée à la place.
prepare map <map>
Allouez un nouveau numéro de version dans la carte <map> pour une substitution atomique. <map> est le #<id> ou le <name> retourné par la commande « show map ». Le nouveau numéro de version est indiqué dans la réponse après « New version created: ». Ce numéro pourra ensuite être utilisé pour préparer l’ajout de nouvelles entrées dans la carte, qui remplaceront atomiquement les entrées actuelles une fois validées. Il est indiqué comme “next_ver” dans la commande « show map ». L’allocation de nouvelles versions n’a aucun impact, car les versions non utilisées sont automatiquement supprimées dès qu’une version plus récente est validée. Les numéros de version sont des valeurs non signées sur 32 bits, qui bouclent en fin de plage, il convient donc de porter une attention particulière lors de leur comparaison dans un programme externe.
prompt [help | n | i | p | timed]*
Modifie le comportement du mode interactif et l’invite affichée au début de la ligne en mode interactif : - « help » : affiche l’utilisation de la commande - « n » : passe en mode non interactif - « i » : passe en mode interactif - « p » : passe en mode interactif + invite - « timed » : active ou désactive l’affichage de l’heure dans l’invite
Sans option, le mode d’interaction passe successivement en mode interactif, puis en mode non interactif. En mode non interactif, la connexion est fermée après la fin de la dernière commande de la ligne courante. En mode interactif, la connexion n’est pas fermée après la fin d’une commande, afin de permettre l’entrée d’une nouvelle commande. En mode invite, le mode interactif est toujours utilisé, et une invite apparaît au début de la ligne, indiquant à l’utilisateur que l’interpréteur attend une nouvelle commande. L’invite se compose d’un angle droit suivi d’un espace « > ».
Le mode interactif convient davantage aux utilisateurs humains, le mode interactif avancé aux scripts complexes, et le mode non interactif (par défaut) aux scripts basiques. Notez que le mode non interactif n’est pas disponible pour la socket principale.
publish backend <backend>
Active le commutateur de contenu vers une instance backend. Il s’agit de l’opération inverse de la commande « unpublish backend ». Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés pour les niveaux « operator » ou « admin ».
quit
Fermer la connexion en mode interactif.
set anon [on|off] [<key>]
Cette commande permet d’activer ou de désactiver le « mode anonymisé » pour la session CLI en cours, qui remplace certains champs jugés sensibles ou confidentiels dans les sorties de commandes par des hachages conservant une cohérence suffisante entre les éléments afin d’aider les développeurs à repérer des relations entre éléments lors de la recherche de bogues, tout en disposant d’un nombre de bits faible (24) pour rendre les hachages non réversibles en raison du grand nombre de correspondances possibles. Lorsqu’il est activé, si aucune clé n’est spécifiée, la clé globale sera utilisée (soit définie dans le fichier de configuration via « anonkey », soit définie via la commande CLI « set anon global-key »). Si aucune telle clé n’a été définie, une clé aléatoire sera générée. Sinon, il est possible de spécifier la clé 32 bits à utiliser pour la session en cours, par exemple pour réutiliser la clé utilisée dans un dump précédent afin de faciliter la comparaison des sorties. Les développeurs n’auront jamais besoin de cette clé, et il est recommandé de ne jamais la partager, car elle pourrait permettre de confirmer ou infirmer certaines hypothèses sur ce que certains hachages pourraient cacher.
set dynamic-cookie-key backend <backend> <value>
Modifiez la clé secrète utilisée pour générer les cookies persistants dynamiques. Cela interrompra les sessions en cours.
set anon global-key <key>
Cela définit la clé d’anonymisation globale sur <key>, qui doit être un entier 32 bits compris entre 0 et 4294967295 (0 désactive la clé globale). Cette commande nécessite des privilèges d’administrateur.
set map <map> [<key>|#<ref>] <value>
Modifiez la valeur correspondant à chaque clé <key> dans une carte <map>. <map> est le #<id> ou <name> retourné par la commande « show map ». Si <ref> est utilisé à la place de <key>, seule l’entrée pointée par <ref> est modifiée. La nouvelle valeur est <value>.
set maxconn frontend <frontend> <value>
Modifiez dynamiquement la valeur maxconn du frontend spécifié. Toute valeur positive est autorisée, y compris zéro, mais définir une valeur supérieure à maxconn global n’a guère de sens. Si la limite est augmentée et qu’il y a des connexions en attente, celles-ci seront immédiatement acceptées. Si elle est réduite à une valeur inférieure au nombre actuel de connexions, l’acceptation de nouvelles connexions sera reportée jusqu’à atteinte du seuil. Le frontend peut être spécifié soit par son nom, soit par son identifiant numérique précédé d’un dièse (’#’).
set maxconn server <backend/server> <value>
Modifiez dynamiquement le paramètre maxconn du serveur spécifié. Toute valeur positive est autorisée, y compris zéro, mais définir une valeur supérieure au maxconn global n’a guère de sens.
set maxconn global <maxconn>
Modifiez dynamiquement le paramètre global maxconn dans la plage définie par la valeur initiale de maxconn. Si cette valeur est augmentée et qu’il y a des connexions en attente, celles-ci seront immédiatement acceptées. Si elle est réduite à une valeur inférieure au nombre actuel de connexions, l’acceptation des nouvelles connexions sera retardée jusqu’à atteinte du seuil. Une valeur nulle restaure le paramètre initial.
set profiling memory { on | off }
Active ou désactive le profilage CPU ou mémoire pour le sous-système indiqué. Cela équivaut à définir ou supprimer les paramètres « profiling » dans la section « global » du fichier de configuration. Voir également « show profiling ». Notez qu’une activation manuelle du profilage des tâches sur « on » réinitialise automatiquement les statistiques du planificateur, permettant ainsi de mesurer l’activité sur une période donnée. Le profilage mémoire est limité à certains systèmes d’exploitation (fonctionne notamment sur la cible linux-glibc) et nécessite que USE_MEMORY_PROFILING soit défini au moment de la compilation.
Pour le profilage des tâches, il est possible d’activer ou de désactiver en temps réel la collecte des mesures de verrouillage et de mémoire par tâche, mais le changement n’est pris en compte qu’à la prochaine transition du profilage de « désactivé »/« auto » vers « activé » (soit automatiquement, soit manuellement). Ainsi, lorsqu’on utilise « no-lock » pour désactiver le profilage du verrouillage par tâche et économiser des cycles CPU, il est recommandé de désactiver puis réactiver le profilage des tâches afin de valider le changement.
set rate-limit connections global <value>
Modifiez la limite de débit de connexions à l’échelle du processus, définie par le paramètre global « maxconnrate ». Une valeur nulle désactive la limitation. Cette limite s’applique à tous les frontaux et le changement prend effet immédiatement. La valeur est exprimée en nombre de connexions par seconde.
set rate-limit http-compression global <value>
Modifiez le taux maximal de compression d’entrée, défini par le paramètre global « maxcomprate ». Une valeur nulle désactive la limitation. La valeur est exprimée en kilo-octets par seconde. Elle est disponible dans la commande « show info », sur la ligne « CompressBpsRateLim », en octets.
set rate-limit sessions global <value>
Modifiez la limite de taux de sessions au niveau du processus, définie par le paramètre global « maxsessrate ». Une valeur nulle désactive la limitation. Cette limite s’applique à tous les frontaux et le changement prend effet immédiatement. La valeur est exprimée en nombre de sessions par seconde.
set rate-limit ssl-sessions global <value>
Modifiez la limite de débit des sessions SSL à l’échelle du processus, définie par le paramètre global « maxsslrate ». Une valeur nulle désactive la limitation. Cette limite s’applique à tous les frontaux et prend effet immédiatement. La valeur est exprimée en nombre de sessions par seconde envoyées à la pile SSL. Elle s’applique avant l’établissement de la connexion afin de protéger la pile contre les abus liés à l’établissement de connexion.
set server <backend>/<server> addr <ip4 or ip6 address> [port <port>]
Remplacez l’adresse IP actuelle d’un serveur par celle fournie. Le port peut éventuellement être modifié à l’aide du paramètre « port ». Notez qu’un changement de port permet également de basculer entre le mappage de port (notation avec +X ou -Y), à condition qu’un port soit configuré pour le contrôle d’état.
set server <backend>/<server> agent [ up | down ]
Forcer l’agent d’un serveur à un nouvel état. Cela peut être utile pour basculer immédiatement l’état d’un serveur, indépendamment de vérifications d’agent lentes, par exemple. Notez que le changement est propagé aux serveurs de suivi, le cas échéant.
set server <backend>/<server> agent-addr <addr> [port <port>]
Modifie l’adresse des vérifications d’agent des serveurs. Permet de migrer les vérifications d’agent vers une autre adresse en temps réel. Vous pouvez spécifier à la fois une adresse IP et un nom d’hôte, qui sera résolu. Facultativement, modifiez le port de l’agent.
set server <backend>/<server> agent-port <port>
Modifiez le port utilisé pour les vérifications de l’agent.
set server <backend>/<server> agent-send <value>
Modifie la chaîne d’agent envoyée à la cible de vérification de l’agent. Permet de mettre à jour la chaîne tout en modifiant l’adresse du serveur afin de maintenir les deux synchronisées.
set server <backend>/<server> health [ up | stopping | down ]
Forcer l’état de contrôle d’état d’un serveur à une nouvelle valeur. Cela peut être utile pour modifier immédiatement l’état d’un serveur, indépendamment de contrôles d’état lents, par exemple. Notez que le changement est propagé aux serveurs de suivi, le cas échéant.
set server <backend>/<server> check-addr <ip4 | ip6> [port <port>]
Modifiez l’adresse IP utilisée pour les contrôles d’état des serveurs. Facultativement, modifiez le port utilisé pour les contrôles d’état des serveurs.
set server <backend>/<server> check-port <port>
Modifiez le port utilisé pour le contrôle d’état en <port>
set server <backend>/<server> state [ ready | drain | maint ]
Forcer l’état administratif d’un serveur vers un nouvel état. Cela peut être utile pour désactiver la répartition de charge et/ou tout trafic vers un serveur. Définir l’état sur « ready » place le serveur en mode normal, et la commande équivaut à la commande « enable server ». Définir l’état sur « maint » désactive tout trafic vers le serveur ainsi que tout contrôle d’état. Cela équivaut à la commande « disable server ». Définir le mode sur « drain » retire uniquement le serveur de la répartition de charge, mais permet toujours son contrôle d’état et l’acceptation de nouvelles connexions persistantes. Les modifications sont propagées aux serveurs de suivi s’il y en a.
set server <backend>/<server> weight <weight>[%]
Modifie le poids d’un serveur par la valeur passée en argument. Cela correspond exactement à la commande « set weight » ci-dessous.
set server <backend>/<server> fqdn <FQDN>
Modifie le nom DNS complet (FQDN) d’un serveur par la valeur passée en argument. Cela nécessite que le résolveur DNS interne soit configuré et activé pour ce serveur.
set server <backend>/<server> ssl [ on | off ] (deprecated)
Cette option configure le chiffrement SSL des connexions sortantes vers le serveur. Lorsqu’elle est désactivée, tout le trafic devient en clair ; le chemin de contrôle d’état n’est pas modifié.
Cette commande est obsolète. Créez un serveur dynamiquement, avec ou sans SSL, à l’aide de la commande « add server » à la place.
set severity-output [ none | number | string ]
Modifie le format de sortie de la sévérité du socket de statistiques connecté pour la durée de la session en cours.
set ssl ca-file <cafile> <payload>
Cette commande fait partie d’un système de transactions : les commandes « commit ssl ca-file » et « abort ssl ca-file » peuvent être requises. Si aucune transaction en cours n’existe, une entrée de fichier CA sera créée dans l’arborescence des fichiers CA, dans laquelle les certificats contenus dans le chargement seront stockés. L’entrée de fichier CA ne sera pas conservée dans l’arborescence des fichiers CA et ne sera stockée que dans une transaction temporaire. Si une transaction portant le même nom de fichier existe déjà, l’entrée de fichier CA précédente sera supprimée et remplacée par la nouvelle. Une fois les modifications effectuées, vous devez valider la transaction à l’aide d’un appel à « commit ssl ca-file ». Si vous souhaitez ajouter plusieurs certificats séparément, vous pouvez utiliser la commande « add ssl ca-file ».
Exemple :
set ssl cert <filename> <payload>
Cette commande fait partie d’un système de transaction : les commandes « commit ssl cert » et « abort ssl cert » peuvent être nécessaires. Ce système de transaction fonctionne sur n’importe quel certificat affiché par la commande « show ssl cert », c’est-à-dire sur n’importe quel certificat frontal ou backend. Si aucune transaction en cours n’existe, elle dupliquerait le certificat <filename> en mémoire vers une transaction temporaire, puis mettrait à jour cette transaction avec le fichier PEM contenu dans le payload. Si une transaction existe déjà avec le même nom de fichier, elle mettra à jour cette transaction. Il est également possible de mettre à jour les fichiers liés à un certificat (.issuer, .sctl, .oscp, etc.). Une fois les modifications effectuées, vous devez « commit ssl cert » la transaction.
L’injection de fichiers via la ligne de commande doit se faire avec précaution, car une ligne vide est utilisée pour signaler la fin du contenu. Il est recommandé d’injecter un fichier PEM ayant été nettoyé. Une méthode simple consiste à supprimer toutes les lignes vides et à ne conserver que les sections PEM. Cette opération peut être réalisée à l’aide d’une commande sed.
Exemple :
set ssl crl-file <crlfile> <payload>
Cette commande fait partie d’un système de transactions : les commandes « commit ssl crl-file » et « abort ssl crl-file » peuvent être nécessaires. Si aucune transaction en cours n’existe, une entrée d’arborescence de fichier CRL sera créée, dans laquelle les listes de révocation contenues dans le payload seront stockées. L’entrée de fichier CRL ne sera pas conservée dans l’arborescence de fichiers CRL et ne sera stockée que dans une transaction temporaire. Si une transaction portant le même nom de fichier existe déjà, l’entrée de fichier CRL précédente sera supprimée et remplacée par la nouvelle. Une fois les modifications effectuées, vous devez valider la transaction à l’aide d’un appel à « commit ssl crl-file ».
Exemple :
set ssl ech <bind> <payload>
Remplacez les clés ECH d’une ligne bind par celle-ci. Le contenu doit être au format PEM pour ECH. (https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni )
Le format de la ligne bind est <frontend>/@<filename>:<linenum> (exemple : frontend1/@haproxy.conf
:19)
ou <frontend>/<name> si la ligne bind a été nommée avec le mot-clé « name ».
Exige une version d’OpenSSL qui prend en charge ECH, et HAProxy doit être compilé avec USE_ECH=1. Cette commande n’est prise en charge que sur une connexion CLI en mode expérimental (voir « experimental-mode on »).
Voir également « show ssl ech », « add ssl ech » et « ech » dans la Section 5.1 du manuel de configuration.
$ openssl ech -public_name foobar.com -out foobar3.com.ech
$ echo -e "experimental-mode on;
set ssl ech frontend1/@haproxy.conf:19 <<%EOF%\n$(cat foobar3.com.ech)\n%EOF%\n" | \
socat /tmp/haproxy.sock -
set new ECH configs for frontend1/@haproxy.conf:19
set ssl ocsp-response <response | payload>
Cette commande permet de mettre à jour une réponse OCSP pour un certificat (voir « crt » dans les lignes « bind »). Les mêmes contrôles sont effectués qu’à l’initialisation du chargement de la réponse. Le <response> doit être transmis sous forme d’une chaîne encodée en base64 de la réponse encodée en DER provenant du serveur OCSP. Cette commande n’est pas prise en charge avec BoringSSL.
Exemple :
set ssl tls-key <id> <tlskey>
Définissez la prochaine clé TLS pour l’écouteur <id> sur <tlskey>. Cette clé devient la clé finale, tandis que la clé précédente est utilisée pour le chiffrement (les autres ne servent qu’à déchiffrer). La clé TLS la plus ancienne présente est remplacée. <id> est soit un entier #<id>, soit <file>, renvoyé par la commande « show tls-keys ». <tlskey> est une clé de billet TLS codée en base64 sur 48 ou 80 bits (par exemple : OpenSSL rand 80 | OpenSSL base64 -A).
set table <table> key <key> [data.<data_type> <value>]*
Crée ou met à jour une entrée dans la table de persistance. Si la clé n’est pas présente, une entrée est insérée.
Consultez stick-table dans la section 4.2 pour obtenir la liste de toutes les valeurs possibles pour <data_type>. L’utilisation la plus courante consiste à insérer dynamiquement des entrées pour les adresses IP sources, avec un indicateur dans gpc0 afin de bloquer dynamiquement une adresse IP ou d’en modifier la qualité de service. Il est possible de transmettre plusieurs data_types dans un appel unique.
Une recherche par pointeur peut être utilisée à la place de la recherche par clé pour une entrée existante : <ptr> doit être spécifié sous la forme 0xffff et correspond au pointeur retourné par une commande précédente « show table ». Une correspondance par pointeur peut être pertinente si l’entrée ne peut pas être identifiée par sa clé en raison d’une clé vide ou de caractères incompatibles sur le CLI.
Si data.<data_type> est de type tableau, les crochets « [] » peuvent être utilisés pour accéder à un index spécifique du tableau, comme ceci : data.gpt[1]
set timeout cli <delay>
Modifie le délai d’expiration de l’interface CLI pour la connexion actuelle. Cela peut être utile lors de sessions de débogage longues, où l’utilisateur doit inspecter continuellement certains indicateurs sans être déconnecté. Le délai est spécifié en secondes.
set var <name> <expression>
Permet de définir ou de remplacer la variable globale « name » par le résultat de l’expression
<expression> ou de la chaîne de format <format>. Seules les variables globales peuvent être utilisées, donc le nom
doit commencer par ‘proc.’, sinon aucune variable ne sera définie. Les <expression> et <format> ne peuvent
impliquer que des mots-clés d’extraction d’échantillon « internes » et des convertisseurs, même si les plus utiles seront probablement str(‘quelque chose’), int(), des chaînes simples ou des références à d’autres variables. Notez que le parseur de ligne de commande ne connaît pas les guillemets, donc tout espace dans l’expression doit être précédé d’une barre oblique inverse. Cette commande nécessite les niveaux « operator » ou « admin ». Cette commande n’est prise en charge que sur une connexion CLI en mode expérimental (voir « experimental-mode on »).
set weight <backend>/<server> <weight>[%]
Modifie le poids d’un backend au valeur passée en argument. Si la valeur se termine par le signe ‘%’, le nouveau poids sera relatif au poids initialement configuré. Les poids absolus sont autorisés entre 0 et 256. Les poids relatifs doivent être positifs, et le poids absolu résultant est plafonné à 256. Les backends faisant partie d’une ferme utilisant un algorithme de répartition de charge statique ont des limitations plus strictes, car le poids ne peut pas être modifié une fois fixé. Pour ces backends, les seules valeurs acceptées sont 0 et 100 % (ou 0 et le poids initial). Les modifications prennent effet immédiatement, bien que certains algorithmes de répartition de charge nécessitent un certain nombre de requêtes pour prendre en compte les changements. Une utilisation typique de cette commande consiste à désactiver un backend pendant une mise à jour en lui attribuant un poids de zéro, puis à le réactiver après la mise à jour en le ramenant à 100 %. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés au niveau “admin”. Le backend et le backend peuvent être spécifiés soit par leur nom, soit par leur identifiant numérique, précédé d’un dièse (’#’).
show acl [[@<ver>] <acl>]
Informations sur les convertisseurs d’ACL. Sans argument, la liste de toutes les ACL disponibles est renvoyée. Si un <acl> est spécifié, son contenu est affiché. <acl> est le #<id> ou <name>. Par défaut, la version actuelle de l’ACL est affichée (la version actuellement en cours de correspondance et signalée comme ‘curr_ver’ dans la liste des ACL). Il est possible de plutôt afficher d’autres versions en préfixant ‘@<ver>’ à l’identifiant de l’ACL. La version agit comme un filtre et les versions inexistantes ne renvoient simplement aucun résultat. Le format de sortie est identique à celui des cartes, y compris pour les valeurs d’exemple. Les données renvoyées ne constituent pas une liste des ACL disponibles, mais la liste de tous les modèles composant n’importe quelle ACL. Beaucoup de ces modèles peuvent être partagés avec les cartes. La valeur ’entry_cnt’ représente le nombre total d’entrées ACL, pas seulement les entrées actives, ce qui signifie qu’elle inclut également les entrées actuellement en cours d’ajout.
show anon
Affiche l’état actuel du mode d’anonymisation (activé ou désactivé) ainsi que la clé de la session en cours.
show backend
Affiche la liste des backends disponibles dans le processus en cours d’exécution
show cli level
Affiche le niveau CLI de la session CLI en cours. Le résultat peut être « admin », « operator » ou « user ». Voir également les commandes « operator » et « user ».
Exemple :
operator
Réduit le niveau CLI de la session CLI en cours à opérateur. Ce niveau ne peut pas être augmenté. Désactive également les modes expert et expérimental. Voir également « show cli level ».
unpublish backend <backend>
Marque le backend comme non qualifié pour la sélection du trafic futur. En pratique, les règles use_backend / default_backend qui le référencent sont ignorées et les règles de commutation de contenu suivantes sont évaluées. Contrairement aux backends désactivés, les contrôles d’état des serveurs restent actifs. Cette commande est restreinte et ne peut être émise que sur les sockets configurés pour les niveaux « operator » ou « admin ».
user
Réduit le niveau CLI de la session CLI en cours à l’utilisateur. Ce niveau ne peut pas être augmenté. Désactive également les modes expert et expérimental. Voir également « show cli level ».
show activity [-1 | 0 | thread_num]
Rapporte certains compteurs relatifs aux événements internes qui aideront les développeurs et plus généralement toute personne suffisamment familière avec HAProxy à diagnostiquer les causes de comportements anormaux. Un exemple typique serait un processus correctement exécuté qui ne s’endort jamais et consomme 100 % du CPU. Les champs de sortie seront composés d’une ligne par métrique, avec les compteurs par thread sur la même ligne. Ces compteurs sont sur 32 bits et peuvent déborder au cours de la durée de vie du processus, ce qui n’est pas problématique car les appels à cette commande seront typiquement effectués deux fois. Les champs ne sont pas documentés intentionnellement afin que leur signification exacte soit vérifiée dans le code où les compteurs sont mis à jour. Ces valeurs sont également réinitialisées par la commande « clear counters ». Dans les déploiements multi-thread, la première colonne indiquera la valeur agrégée (ou la moyenne selon la nature de la métrique) pour tous les threads, et la liste des valeurs de chaque thread sera affichée entre crochets dans l’ordre des threads. Un numéro de thread optionnel peut être spécifié en argument. La valeur spéciale « 0 » rapportera uniquement la valeur agrégée (première colonne), et « -1 », qui est la valeur par défaut, affichera toutes les colonnes. Notez qu’à l’instar du mode mono-thread, il n’y aura pas de crochets lorsque seule une colonne est demandée.
show cli sockets
Liste les sockets CLI. Le format de sortie est composé de 3 champs séparés par des espaces. Le premier champ est l’adresse de la socket, qui peut être une socket Unix, un couple adresse IPv4:port ou une adresse IPv6. Les sockets de types autres ne seront pas affichées. Le deuxième champ décrit le niveau de la socket : « admin », « user » ou « operator ». Le dernier champ liste les processus auxquels la socket est liée, séparés par des virgules, pouvant être des numéros ou « all ».
Exemple :
show cache
Listez les caches configurés et les objets stockés dans chaque arbre de cache.
$ echo ‘show cache’ | socat stdio /tmp/sock1 0x7f6ac6c5b03a: foobar (shctx:0x7f6ac6c5b000, available blocks:3918) 1 2 3 4
- pointeur vers la structure de cache
- nom du cache
- pointeur vers la zone mmap (shctx)
- nombre de blocs disponibles pour être réutilisés dans le shctx
0x7f6ac6c5b4cc hachage:286881868 variante:0x0011223344556677 taille:39114 (39 blocs), compteur:9, expiration:237 1 2 3 4 5 6 7
- pointeur vers l’entrée du cache
- premiers 32 bits du hachage
- hachage secondaire de l’entrée en cas de variation
- taille de l’objet en octets
- nombre de blocs utilisés pour l’objet
- nombre de transactions utilisant l’entrée
- heure d’expiration, peut être négatif si déjà expiré
show dev
Cette commande a pour objectif de centraliser certaines informations que les développeurs HAProxy pourraient nécessiter pour mieux comprendre les causes d’un problème donné. Elle ne fournit généralement pas d’information utile à l’utilisateur, mais ces données permettent aux développeurs d’éliminer certaines hypothèses. Le format est approximativement une série de sections contenant des lignes indentées, une seule valeur par ligne, comme le type et la version du système d’exploitation, le type de processeur ou les limites de descripteurs d’ouverture au démarrage, par exemple. Certains champs seront omis afin d’éviter la répétition ou la pollution de la sortie lorsqu’ils ne contribuent pas à la valeur (par exemple, les valeurs illimitées). D’autres champs pourront apparaître à l’avenir, et certains pourront évoluer. Cette sortie n’est pas destinée à être analysée par des scripts, et ne doit pas être considérée avec un haut degré de fiabilité ; elle vise essentiellement à économiser du temps pour ceux qui peuvent la lire.
Techniquement parlant, ces informations sont prises telles quelles à partir d’une structure interne qui les stocke ensemble au démarrage, afin qu’elles puissent également être trouvées dans un fichier core après un plantage. Il peut donc arriver que les développeurs demandent une sortie précoce sur un processus bien comporté afin de la comparer avec ce qui est trouvé dans un dump core, ou de la comparer entre plusieurs rechargements (par exemple, certaines limites pourraient changer). Si l’anonymisation est activée, toute valeur potentiellement sensible sera également anonymisée (par exemple, le nom du nœud).
Exemple de sortie :
show env [<name>]
Affiche une ou toutes les variables d’environnement connues par le processus. Sans argument, toutes les variables sont affichées. Avec un argument, seule la variable spécifiée est affichée si elle existe. Sinon, le message « Variable non trouvée » est émis. Les variables sont affichées au format utilisé pour les stocker ou les renvoyer par l’outil « env », à savoir « <name>=<value> ». Cette commande peut être utile lors du débogage de certains fichiers de configuration utilisant abondamment des variables d’environnement afin de vérifier qu’elles contiennent les valeurs attendues. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés pour les niveaux « operator » ou « admin ».
show errors [<iid>|<proxy>] [request|response]
Dump les dernières erreurs de requête et de réponse HTTP/1.x collectées par les frontaux et les backaux. Si <iid> est spécifié, limiter le dump aux erreurs concernant soit le frontend, soit le backend dont l’ID est <iid>. L’ID de proxy “-1” provoquera le dump de toutes les instances. Si un nom de proxy est spécifié à la place, son ID sera utilisé comme filtre. Si “request” ou “response” est ajouté après le nom de proxy ou son ID, seules les erreurs de requête ou de réponse seront dumpées. Cette commande est restreinte et ne peut être exécutée que sur des sockets configurés pour les niveaux “operator” ou “admin”.
Les erreurs qui peuvent être collectées sont les erreurs de requête et de réponse ultimes provoquées par des violations de protocole, souvent dues à des caractères non valides dans les noms d’en-tête. Le rapport indique précisément quel caractère exact a violé le protocole. D’autres informations importantes, telles que la date exacte à laquelle l’erreur a été détectée, les noms du frontal et du backend, le nom du serveur (lorsqu’il est connu), l’identifiant de transaction interne et l’adresse source ayant initié la session, sont également rapportées.
Tous les caractères sont renvoyés, et les caractères non imprimables sont encodés. Les plus courants (\t = 9, \n = 10, \r = 13 et \e = 27) sont encodés sous la forme d’une lettre suivie d’une barre oblique inverse. La barre oblique inverse elle-même est encodée par ‘\\’ afin d’éviter toute confusion. Les autres caractères non imprimables sont encodés sous la forme ‘\xNN’, où NN représente la représentation hexadécimale sur deux chiffres du code ASCII du caractère.
Les lignes sont précédées de la position de leur premier caractère, à partir de 0 pour le début du tampon. Au plus une ligne d’entrée est affichée par ligne, et les lignes longues sont divisées en plusieurs lignes de sortie consécutives afin que la sortie n’excède jamais 79 caractères de large. Il est facile de détecter si une ligne a été coupée, car elle ne se termine pas par ‘\n’ et l’offset de la ligne suivante est suivi d’un signe ‘+’, indiquant qu’elle est une continuation de la ligne précédente.
Exemple :
show events [<sink>] [-w] [-n] [-0]
Sans option, cette commande liste tous les réceptacles d’événements connus ainsi que leurs types. Avec une option, elle affiche tous les événements disponibles dans le réceptacle désigné, si celui-ci est de type tampon. Si l’option “-w” est passée après le nom du réceptacle, une fois la fin du tampon atteinte, la commande attend de nouveaux événements et les affiche. Il est possible d’interrompre l’opération en saisissant une entrée (qui sera ignorée) ou en fermant la session. Enfin, l’option “-n” permet de se positionner directement à la fin du tampon, ce qui est souvent pratique lorsqu’elle est combinée à “-w” pour ne rapporter que les événements nouveaux. Pour plus de commodité, les options “-wn” ou “-nw” peuvent être utilisées pour activer les deux options simultanément. Par défaut, tous les événements sont délimités par un caractère de saut de ligne (’\n’ ou 10 ou 0x0A). Il est possible de modifier cette valeur par le caractère NUL (’\0’ ou 0) en passant l’argument “-0”.
show fd [-!plcfbsd]* [[<tgid>]/[<fd>] | <fd>]
Affiche la liste de tous les descripteurs de fichiers ou uniquement le nombre <fd> s’il est spécifié. La forme “<tgid>/<fd>” est également acceptée, où l’un des côtés peut être vide comme un joker ("/<fd>" pour le descripteur <fd> à travers les groupes de threads, “<tgid>/” pour tous les descripteurs de <tgid>). Le <tgid> est actuellement analysé mais ignoré, en attente d’une future prise en charge des tables de descripteurs par groupe de threads. Un ensemble d’indicateurs peut éventuellement être passé pour limiter le dump à certains types de FD ou en exclure d’autres. Lorsqu’on rencontre ‘-’ ou ‘!’, la sélection est inversée pour les caractères suivants dans le même argument. L’inversion est réinitialisée avant chaque mot d’argument délimité par des espaces. Les types de FD sélectionnables incluent ‘p’ pour les tubes, ’l’ pour les écouteurs, ‘c’ pour les connexions (de tout type), ‘f’ pour les connexions frontales, ‘b’ pour les connexions backend (de tout type), ’s’ pour les connexions aux serveurs, ’d’ pour les connexions à l’adresse “dispatch” ou à l’adresse transparente du backend. Avec cela, ‘b’ est un raccourci pour ‘sd’ et ‘c’ pour ‘fb’ ou ‘fsd’. ‘c!f’ est équivalent à ‘b’ (“toutes les connexions sauf les connexions frontales” sont bien des connexions backend). Cette fonction est destinée uniquement aux développeurs qui doivent observer des états internes afin de déboguer des problèmes complexes tels qu’une utilisation anormale du CPU. Un descripteur est rapporté par ligne, et pour chacun, son état dans le poller est indiqué avec des lettres majuscules pour les indicateurs activés et minuscules pour les désactivés, en utilisant “P” pour “polled”, “R” pour “ready”, “A” pour “active”, l’état des événements avec “H” pour “hangup”, “E” pour “error”, “O” pour “output”, “P” pour “priority” et “I” pour “input”, quelques autres indicateurs comme “N” pour “new” (ajouté récemment dans le cache des descripteurs), “U” pour “updated” (reçu une mise à jour dans le cache des descripteurs), “L” pour “linger_risk”, “C” pour “cloned”, puis la position de l’entrée mise en cache, le pointeur vers le propriétaire interne, le pointeur vers la fonction de rappel d’E/S et son nom lorsqu’il est connu. Lorsque le propriétaire est une connexion, les indicateurs de connexion et la cible sont rapportés (frontal, proxy ou serveur). Lorsque le propriétaire est un écouteur, l’état de l’écouteur et son frontal sont rapportés. Il n’y a aucun intérêt à utiliser cette commande sans une bonne connaissance des internes. Il convient de noter que le format de sortie peut évoluer au fil du temps, de sorte que cette sortie ne doit pas être analysée par des outils conçus pour être durables. Certains états internes peuvent sembler suspects à la fonction les listant ; dans ce cas, la ligne de sortie sera suffixée par un point d’exclamation (’!’). Cela peut aider à trouver un point de départ lors de la diagnostic d’un incident.
show info [typed|json] [desc] [float]
Affiche les informations sur l’état de haproxy dans le processus actuel. Si l’argument facultatif « typed » est fourni, les numéros de champ, les noms et les types sont également émis afin que les outils de surveillance externes puissent facilement récupérer, éventuellement agréger, puis rapporter les informations contenues dans les champs qu’ils ne connaissent pas. Chaque champ est affiché sur une ligne distincte. Si l’argument facultatif « json » est fourni, les informations fournies par la sortie « typed » sont fournies au format JSON sous forme d’une liste d’objets JSON. Par défaut, le format ne contient que deux colonnes séparées par deux points (’:’). La colonne de gauche est le nom du champ et la colonne de droite est la valeur. Il est très important de noter que, dans le format de sortie « typed », la sortie pour un objet unique est contiguë, de sorte qu’il n’est pas nécessaire pour le consommateur de stocker l’ensemble des données en même temps. Si l’argument facultatif « float » est fourni, certains champs habituellement émis sous forme d’entiers peuvent être émis sous forme de flottants pour une plus grande précision. Il n’est pas spécifié de manière explicite quels champs sont concernés, car cela pourrait évoluer au fil du temps. L’utilisation de cette option implique que le consommateur est capable de traiter les flottants. Le format de sortie utilisé est sprintf("%f").
Lorsque le format de sortie typé est utilisé, chaque ligne est composée de 4 colonnes séparées par des deux-points (’:’). La première colonne est une série de 3 éléments séparés par des points. Le premier élément est la position numérique du champ dans la liste (commençant à zéro). Cette position ne doit pas évoluer au fil du temps, mais des trous sont à prévoir, selon les options de compilation ou si certains champs sont supprimés à l’avenir. Le deuxième élément est le nom du champ tel qu’il apparaît dans la sortie par défaut de « show info ». Le troisième élément est le numéro relatif du processus, commençant à 1.
Le reste de la ligne, à partir du premier deux-points, suit le format de sortie typé décrit dans la section précédente. En résumé, la deuxième colonne (après le premier « : ») indique l’origine, la nature et la portée de la variable. La troisième colonne précise le type du champ, parmi « s32 », « s64 », « u32 », « u64 » ou « str ». La quatrième colonne contient la valeur elle-même, que le consommateur sait interpréter grâce à la colonne 3 et traiter grâce à la colonne 2.
Ainsi, le format global de ligne en mode typé est :
Lorsque « desc » est ajouté à la commande, une deuxième virgule suivie d’une chaîne entre guillemets est ajoutée pour inclure une description de la métrique. Au moment de la rédaction, cette fonctionnalité n’est prise en charge que pour les formats de sortie « typed » et par défaut.
Exemple :
Dans le format typé, la présence de l’identifiant de processus à la fin de la première colonne permet de regrouper visuellement les sorties de plusieurs processus de manière très simple. Exemple :
Le format de la sortie JSON est décrit dans un schéma qui peut être affiché à l’aide de la commande « show schema json ».
La sortie JSON ne contient aucun espace blanc supplémentaire afin de réduire le volume de sortie. Pour une lecture humaine, il peut être utile de passer la sortie through un formatteur de code. Exemple :
$ echo “show info json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
La sortie JSON ne contient aucun espace blanc supplémentaire afin de réduire le volume de sortie. Pour une lecture humaine, il peut être utile de passer la sortie through un formatteur de code. Exemple :
$ echo “show info json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
show libs
Affiche la liste des bibliothèques dynamiques partagées et des fichiers objets chargés, sur les systèmes qui le supportent. Lorsqu’elles sont disponibles, pour chaque objet partagé, la plage d’adresses virtuelles, la taille et le chemin d’accès à l’objet seront indiqués. Cette commande peut par exemple servir à estimer quelle bibliothèque fournit une fonction apparaissant dans un dump. Notez que sur de nombreux systèmes, les adresses changent à chaque redémarrage (randomisation de l’espace d’adressage), de sorte que cette liste doit être récupérée au démarrage si elle est destinée à être utilisée pour analyser un fichier core. Cette commande ne peut être exécutée que sur les sockets configurés pour les niveaux « operator » ou « admin ». Notez que le format de sortie peut varier selon les systèmes d’exploitation, les architectures et même les versions de HAProxy, et ne doit pas être utilisé dans les scripts.
show map [[@<ver>] <map>]
Informations sur les convertisseurs de cartes. Sans argument, la liste de toutes les cartes disponibles est retournée. Si un <map> est spécifié, son contenu est affiché. <map> est le numéro de <id> ou <name>. Par défaut, la version actuelle de la carte est affichée (la version actuellement utilisée pour les correspondances et signalée comme ‘curr_ver’ dans la liste des cartes). Il est possible de plutôt afficher d’autres versions en préfixant ‘@<ver>’ à l’identifiant de la carte. La version agit comme un filtre et les versions inexistantes ne renvoient simplement aucun résultat. La valeur ’entry_cnt’ représente le nombre total d’entrées de la carte, y compris celles qui ne sont pas actives, ce qui signifie qu’elle inclut également les entrées actuellement en cours d’ajout.
Dans la sortie, la première colonne est un identifiant unique d’entrée, utilisable comme référence pour les opérations « del map » et « set map ». La deuxième colonne est le motif et la troisième colonne est l’exemple, le cas échéant. Les données renvoyées ne constituent pas directement une liste des cartes disponibles, mais la liste de tous les motifs composant une carte. De nombreux de ces motifs peuvent être partagés avec les ACL.
show peers [dict|-] [<peers section>]
Informations sur les pairs configurés dans les sections « peers ». Sans argument, la liste des pairs appartenant à toutes les sections « peers » est affichée. Si <peers section> est spécifié, seules les informations relatives aux pairs appartenant à cette section « peers » sont affichées. Lorsque « dict » est précisé avant le nom de la section « peers », les caches entiers des dictionnaires Tx/Rx sont également affichés (très volumineux). L’utilisation de « - » peut être nécessaire pour afficher une section « peers » nommée « dict ».
Voici deux exemples de sorties où les pairs hostA, hostB et hostC appartiennent à la section « sharedlb ». Seulement hostA et hostB sont connectés. Seulement hostA a envoyé des données à hostB.
$ echo “show peers” | socat - /tmp/hostA 0x55deb0224320 : [15/Apr/2019:11:28:01] id=sharedlb
state=0 flags=0x3 \ resync_timeout=<PAST> task_calls=45122
0x55deb022b540 : id=hostC(remote) addr=127.0.0.12:10002 status=CONN \
reconnect=4s confirm=0 flags=0x0 0x55deb022a440 : id=hostA(local) addr=127.0.0.10:10000 status=NONE
\ reconnect=<NEVER> confirm=0 flags=0x0 0x55deb0227d70 : id=hostB(remote)
addr=127.0.0.11:10001 status=ESTA reconnect=2s confirm=0 flags=0x20000200 appctx:0x55deb028fba0
st0=7 st1=0 task_calls=14456 \ state=EST xprt=RAW src=127.0.0.1:37257
addr=127.0.0.10:10000 remote_table:0x55deb0224a10 id=stkt local_id=1 remote_id=1
last_local_table:0x55deb0224a10 id=stkt local_id=1 remote_id=1 shared tables:
$ echo “show peers” | socat - /tmp/hostB 0x55871b5ab320 : [15/Apr/2019:11:28:03] id=sharedlb
état=0 drapeaux=0x3 \ délai_d_expiration_re synchronisation=<PAST> appels_tâche=3 0x55871b5b2540 :
id=hostC(à distance) addr=127.0.0.12:10002 statut=CONN \ reconnexion=3s
confirmation=0 drapeaux=0x0 0x55871b5b1440 : id=hostB(local) addr=127.0.0.11:10001 statut=NONE
\ reconnexion=<NEVER> confirmation=0 drapeaux=0x0 0x55871b5aed70 : id=hostA(à distance)
addr=127.0.0.10:10000 statut=ESTA \ reconnexion=2s confirmation=0
drapeaux=0x20000200 contexte_application:0x7fa46800ee00 st0=7 st1=0 appels_tâche=62356 \
état=EST table_à_distance:0x55871b5ab960 id=stkt id_local=1 id_à_distance=1 dernière_table_locale:0x55871b5ab960
id=stkt id_local=1 id_à_distance=1 tables partagées :
show pools [byname|bysize|byusage] [detailed] [match <pfx>] [<nb>]
Effectue un dump de l’état des pools mémoire internes. Cela est utile pour suivre l’utilisation mémoire lorsqu’un fuite de mémoire est suspectée, par exemple. Il effectue exactement la même opération que SIGQUIT lorsqu’exécuté en mode frontal, sauf qu’il ne vide pas les pools. La sortie n’est pas triée par défaut. Si « byname » est spécifié, elle est triée par nom de pool ; si « bysize » est spécifié, elle est triée par taille d’élément dans l’ordre inverse ; si « byusage » est spécifié, elle est triée par utilisation totale dans l’ordre inverse, et seuls les éléments utilisés sont affichés. Il est également possible de limiter la sortie aux <nb> premiers éléments (par exemple, lors du tri par utilisation). Il est possible d’afficher également des détails internes supplémentaires, y compris la liste de tous les pools fusionnés, en spécifiant « detailed ». Enfin, si « match » est suivi d’un préfixe, seuls les pools dont le nom commence par ce préfixe seront affichés. Le total rapporté concerne uniquement les pools correspondant aux critères de filtrage. Exemple :
show profiling [{all | status | tasks | memory}] [byaddr|bytime|byctx|aggr|<max_lines>]*
Affiche les paramètres de profilage actuels, un par ligne, ainsi que la commande nécessaire pour les modifier. Lorsque le profilage des tâches est activé, certaines statistiques par fonction collectées par l’horloge seront également émises, accompagnées d’un résumé indiquant le nombre d’appels, le temps CPU total/moyen et la latence totale/moyenne. Lorsque le profilage mémoire est activé, certaines informations telles que le nombre d’allocations/libérations et leurs tailles seront rapportées. Il est possible de limiter la sortie à l’état de profilage uniquement, aux tâches ou au profilage mémoire en spécifiant les mots-clés correspondants ; par défaut, toutes les informations de profilage sont affichées. Il est également possible de limiter le nombre de lignes de sortie de chaque catégorie en spécifiant une limite numérique. Il est possible de demander que la sortie soit triée par adresse, par temps d’exécution total ou par contexte d’appel au lieu de l’utilisation, par exemple pour faciliter les comparaisons entre appels successifs ou vérifier ce qui doit être optimisé, et pour agréger l’activité des tâches par fonction appelée au lieu de voir les détails. Veuillez noter que le profilage est essentiellement destiné aux développeurs, car il fournit des indices sur l’endroit où les cycles CPU ou la mémoire sont gaspillés dans le code. Il n’y a rien d’utilisable à surveiller là-dedans.
show resolvers [<resolvers section id>]
Affiche les statistiques pour la section de résolveurs indiquée, ou pour toutes les sections de résolveurs si aucune section n’est fournie.
Pour chaque serveur de noms, les compteurs suivants sont rapportés :
show quic [<format>] [<filter>]
Affiche les informations sur toutes les connexions frontend QUIC actives. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés avec les niveaux « operator » ou « admin ».
Un argument facultatif peut être spécifié pour contrôler le niveau de détail. Sa valeur peut être interprétée de différentes manières. La première possibilité consiste à utiliser des valeurs prédéfinies : « oneline » pour le format par défaut, « stream » pour lister tous les flux actifs, ou « full » pour afficher toutes les informations. En alternative, une liste de champs séparés par des virgules peut être spécifiée afin de restreindre la sortie. Les valeurs actuellement prises en charge sont « tp », « sock », « pktns », « cc » et « mux ». Enfin, la valeur « help » dans le format affiche à la place un message d’aide plus détaillé.
L’argument final sert à restreindre ou étendre la liste des connexions. Par défaut, seules les connexions frontend actives sont affichées. Utilisez l’argument supplémentaire « clo » pour afficher les connexions frontend en cours de fermeture, « be » pour les connexions backend ou « all » pour toutes les catégories. Il est également possible de restreindre à une seule connexion en spécifiant son adresse hexadécimale.
show servers conn [<backend>]
Affiche l’état des connexions actives et inactives des serveurs appartenant au backend spécifié (ou de tous les backends si aucun n’est précisé). Un nom ou un identifiant de backend peut être utilisé.
La sortie se compose d’une ligne d’en-tête affichant les titres des champs, suivie d’une ligne par serveur, contenant pour chaque serveur le nom et l’ID du backend, le nom et l’ID du serveur, l’adresse, le port et une série de valeurs. Le nombre de champs varie selon le nombre de threads. Le format exact de la sortie peut légèrement varier d’une version à l’autre et selon le nombre de threads. Il est nécessaire de prêter attention à la ligne d’en-tête pour aligner correctement les colonnes lors de l’extraction des valeurs, ainsi qu’au nombre de threads, car les dernières colonnes sont par thread :
HAProxy tue une partie de <idle_cur> toutes les <purge_delay> lorsque la somme de <idle_cur> + <used_cur> dépasse l’estimation <need_est>. Cette estimation varie en fonction de l’activité des connexions.
Étant donné la nature threadée des connexions inactives, il est important de comprendre que certaines valeurs peuvent évoluer après lecture, et qu’aucune cohérence au sein d’une ligne n’est garantie. Cette sortie est principalement destinée à la débogage et ne doit pas être surveillée ni visualisée de manière régulière.
show servers state [<backend>]
Affiche l’état des serveurs présents dans la configuration en cours d’exécution. Un nom ou un identifiant de backend peut être fourni pour limiter la sortie à ce backend uniquement.
Dumper a le format suivant :
- première ligne contient la version du format (1 dans cette spécification) ;
- deuxième ligne contient les en-têtes de colonne, précédés d’un dièse (’#’) ;
- troisième ligne et les lignes suivantes contiennent les données ;
- chaque ligne commençant par un dièse (’#’) est considérée comme un commentaire.
Étant donné que plusieurs versions de la sortie peuvent coexister, voici la liste des champs et leur ordre par version de format de fichier :
show sess [<options>*]
Affiche tous les flux actifs connus (anciennement appelés « sessions »). Évitez d’exécuter cette commande sur des connexions lentes, car cela peut générer une sortie très volumineuse. Cette commande est restreinte et ne peut être exécutée que sur les sockets configurés pour les niveaux « operator » ou « admin ». Notez qu’ sur des machines avec des connexions recyclées rapidement, il se peut que la sortie affiche moins d’entrées que le nombre réellement existant, car seuls les flux existants au moment de l’entrée de la commande sont répertoriés ; ceux qui se ferment entre-temps ne seront pas inclus. Pour les options prises en charge, voir ci-dessous.
show sess [<id> | all | help] [<options>*]
Affichez beaucoup d’informations internes sur les flux correspondants. La commande connaît deux formats de sortie : un format court, qui est le par défaut lorsqu’aucun identifiant de flux spécifique n’est demandé, et un format étendu lors de la liste de flux désignés. Le format court, utilisé par défaut avec « show sess », n’affiche qu’un flux par ligne, avec quelques informations, et l’identifiant du flux au début de la ligne en format hexadécimal (il correspond à l’adresse mémoire du flux).
Dans sa forme étendue, utilisée par « show sess <id> » ou « show sess all », les flux sont affichés avec une quantité importante de détails de débogage sur plusieurs lignes (environ 20 par flux), tout en commençant toujours par leur identifiant. Le délimiteur entre les flux est l’identifiant situé au début de la ligne ; les lignes supplémentaires appartenant au même flux commencent par un ou plusieurs espaces (le flux est affiché avec un retrait). L’affichage de nombreux flux peut générer une sortie très volumineuse, prendre beaucoup de temps et être très coûteux en ressources CPU, il est donc toujours préférable de n’afficher que le minimum nécessaire. Ces informations sont inutiles pour la majorité des utilisateurs, mais peuvent être utilisées par les développeurs HAProxy pour diagnostiquer un bug complexe. Le format exact de la sortie n’est pas documenté intentionnellement afin qu’il puisse évoluer librement selon les besoins, y compris dans les branches stables. Cette sortie est destinée à être interprétée en consultant la fonction strm_dump_to_buffer() dans src/stream.c afin de comprendre la signification exacte de certains champs.
L’argument « help » affichera l’utilisation détaillée de la commande au lieu de déverser les flux.
Il est possible de définir certaines options afin de personnaliser la sauvegarde ou d’appliquer des filtres. Voici les options prises en charge : - backend <b> : n’afficher que les flux attachés à ce backend - frontend <f> : n’afficher que les flux attachés à ce frontal - older <age> : n’afficher que les flux plus anciens que <age> secondes - server <b/s> : n’afficher que les flux attachés à ce couple backend+serveur - show-uri : sauvegarder l’URI de la transaction, tel qu’il a été capturé lors de l’analyse de la requête. Il n’est affiché que s’il a été capturé. - susp : n’afficher que les flux considérés comme suspects par les développeurs, selon des critères qui peuvent évoluer dans le temps ou varier selon les versions.
show stat [domain <resolvers|proxy>] [{<iid>|<proxy>} <type> <sid>] \
Dump des statistiques. Le domaine est utilisé pour sélectionner les statistiques à afficher ; les résolveurs et les proxies sont actuellement disponibles. Par défaut, le format CSV est utilisé ; vous pouvez activer le format d’affichage étendu typé décrit dans la section précédente en passant « typed » après les autres arguments ; ou au format JSON en passant « json » après les autres arguments. En passant <id>, <type> et <sid>, il est possible de n’afficher que des éléments sélectionnés : - <iid> est un identifiant de proxy, -1 pour tout afficher. En alternative, un nom de proxy <proxy> peut être spécifié. Dans ce cas, l’identifiant de ce proxy sera utilisé comme sélecteur d’identifiant. - <type> sélectionne le type d’objets pouvant être dumpés : 1 pour les frontaux, 2 pour les backends, 4 pour les serveurs, -1 pour tout. Ces valeurs peuvent être combinées par opération OU, par exemple :
- `<sid>` est un identifiant de serveur, -1 pour exporter l'intégralité du proxy sélectionné.
Exemple :
Dans cet exemple, deux commandes ont été émises simultanément. Cela permet de déterminer facilement quel processus les statistiques concernent en mode multi-processus. Cette information n’est pas nécessaire dans le format de sortie typée, car le numéro de processus est indiqué sur chaque ligne. Notez la ligne vide suivant la sortie d’information, qui marque la fin du premier bloc. Une ligne vide similaire apparaît à la fin du second bloc (stats), afin que l’utilisateur sache que la sortie n’a pas été tronquée.
Lorsque « typed » est spécifié, le format de sortie est plus adapté aux outils de surveillance, car il fournit des positions numériques et indique le type de chaque champ de sortie. Chaque valeur apparaît sur une ligne distincte, accompagnée du numéro de processus, du numéro d’élément, de sa nature, de son origine et de son champ d’application. Ce même format est également disponible via les statistiques HTTP en ajoutant « ;typed » à l’URI. Il est très important de noter que, dans le format de sortie typé, les données d’un objet unique sont contiguës, de sorte qu’il n’est pas nécessaire pour le consommateur de stocker l’ensemble des données en même temps.
Le modificateur « up » entraîne l’affichage uniquement des serveurs signalés comme étant actifs ou non vérifiés. Les serveurs inactifs, non résolus ou en maintenance ne seront pas affichés. Cela correspond à l’option « ;up » dans les statistiques HTTP. De même, le modificateur « no-maint » agit comme le modificateur HTTP « ;no-maint » et empêche l’affichage des serveurs désactivés. La différence réside dans le fait que les serveurs activés mais inactifs ne seront pas exclus.
Lorsqu’on utilise le format de sortie typé, chaque ligne est composée de 4 colonnes séparées par des deux-points (’:’). La première colonne est une série de 5 éléments séparés par des points. Le premier élément est une lettre indiquant le type de l’objet décrit. Actuellement, les types d’objets suivants sont connus : « F » pour un frontal, « B » pour un backend, « L » pour un écouteur, et « S » pour un serveur. Le deuxième élément est un entier positif représentant l’identifiant unique du proxy auquel appartient l’objet. Il correspond à la colonne « iid » de la sortie CSV et correspond à la valeur située devant la directive optionnelle « id » présente dans la section frontal ou backend. Le troisième élément est un entier positif contenant l’identifiant unique de l’objet à l’intérieur du proxy, et correspond à la colonne « sid » de la sortie CSV. La valeur 0 est utilisée lors du dump d’un frontal ou d’un backend. Pour un écouteur ou un serveur, cela correspond à son identifiant respectif à l’intérieur du proxy. Le quatrième élément est la position numérique du champ dans la liste (comptée à partir de zéro). Cette position ne doit pas évoluer au fil du temps, mais des trous sont à prévoir, selon les options de compilation ou si certains champs sont supprimés à l’avenir. Le cinquième élément est le nom du champ tel qu’il apparaît dans la sortie CSV. Le sixième élément est un entier positif et correspond au numéro relatif du processus, commençant à 1.
Le reste de la ligne, à partir du premier deux-points, suit le format de sortie typé décrit dans la section précédente. En résumé, la deuxième colonne (après le premier « : ») indique l’origine, la nature, la portée et l’état de persistance de la variable. La troisième colonne indique le type de champ, parmi « s32 », « s64 », « u32 », « u64 », « flt » et « str ». La quatrième colonne contient la valeur elle-même, que le consommateur sait interpréter grâce à la colonne 3 et traiter grâce à la colonne 2.
Lorsque « desc » est ajouté à la commande, une deuxième virgule suivie d’une chaîne entre guillemets est ajoutée pour inclure une description de la métrique. Au moment de la rédaction, cette fonctionnalité n’est prise en charge que pour le format de sortie « typed ».
Ainsi, le format global de ligne en mode typé est :
Voici un exemple de format de sortie typé :
Dans le format typé, la présence de l’identifiant de processus à la fin de la première colonne permet de regrouper visuellement les sorties de plusieurs processus, comme illustré dans l’exemple ci-dessous où chaque ligne s’affiche pour chaque processus :
Le format de la sortie JSON est décrit dans un schéma qui peut être affiché à l’aide de la commande « show schema json ».
La sortie JSON ne contient aucun espace blanc supplémentaire afin de réduire le volume de sortie. Pour une lecture humaine, il peut être utile de passer la sortie through un formatteur de code. Exemple :
$ echo “show stat json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
La sortie JSON ne contient aucun espace blanc supplémentaire afin de réduire le volume de sortie. Pour une lecture humaine, il peut être utile de passer la sortie through un formatteur de code. Exemple :
$ echo “show stat json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
show ssl ca-file [[*][\]<cafile>[:<index>]]
Affiche la liste des fichiers de certificats autorités de certification (CA) chargés dans le processus ainsi que le nombre de certificats correspondants. Les certificats ne sont pas utilisés par aucun frontal ou backend tant que leur statut n’est pas « Utilisé ». Une entrée “@system-ca” peut apparaître dans la liste ; elle est chargée par défaut par httpclient et contient la liste des autorités de certification fiables de votre système, renvoyée par OpenSSL. Si un nom de fichier est précédé d’un astérisque, il s’agit d’une transaction non encore validée. Si un <cafile> est spécifié sans <index>, il affichera l’état du fichier CA (“Utilisé”/“Non utilisé”) suivi des détails de tous les certificats contenus dans ce fichier. Les détails affichés pour chaque certificat sont identiques à ceux affichés par la commande “show ssl cert”. Si un <cafile> est spécifié suivi d’un <index>, seuls les détails du certificat ayant l’index spécifié seront affichés. Les index commencent à 1. Si l’index est invalide (par exemple trop élevé), rien ne sera affiché. Cette commande peut être utile pour vérifier qu’un fichier CA a été correctement mis à jour. Vous pouvez également afficher les détails d’une transaction en cours en précédant le nom de fichier par un ‘’. Si le premier caractère du nom de fichier est un ‘’, il peut être échappé avec ‘\*’.
Exemple :
show ssl cert [[*][\]<filename>]
Affiche la liste des certificats chargés dans le processus. Ils ne sont pas utilisés par aucun frontal ou backend tant que leur statut n’est pas « Utilisé ». Si un nom de fichier est précédé d’un astérisque, il s’agit d’une transaction non encore validée. Si un nom de fichier est spécifié, les détails concernant le certificat seront affichés. Cette commande peut être utile pour vérifier qu’un certificat a bien été mis à jour. Vous pouvez également afficher les détails d’une transaction en précédant le nom de fichier par un ‘’. Si le premier caractère du nom de fichier est un ‘’, il peut être échappé avec ‘\*’. Cette commande peut également être utilisée pour afficher les détails de la réponse OCSP d’un certificat en ajoutant à la fin du nom de fichier une extension “.ocsp”. Elle fonctionne aussi bien pour les certificats validés que pour les transactions en cours. Pour un certificat validé, cette commande est équivalente à l’appel de « show ssl ocsp-response » avec l’identifiant correspondant de la réponse OCSP.
Exemple :
show ssl crl-file [[*][\]<crlfile>[:<index>]]
Affiche la liste des fichiers CRL chargés dans le processus. Ils ne sont pas utilisés par aucun frontal ou backend tant que leur statut n’est pas « Utilisé ». Si un nom de fichier est précédé d’un astérisque, il s’agit d’une transaction non encore validée. Si un <crlfile> est spécifié sans <index>, il affiche l’état du fichier CRL (“Utilisé”/“Non utilisé”) suivi des détails relatifs à toutes les listes de révocation contenues dans le fichier CRL. Les détails affichés pour chaque liste sont basés sur la sortie de la commande « openssl crl -text -noout -in <file> ». Si un <crlfile> est spécifié suivi d’un <index>, seul le détail de la liste ayant l’index spécifié est affiché. Les index commencent à 1. Si l’index est invalide (par exemple trop élevé), rien n’est affiché. Cette commande peut être utile pour vérifier qu’un fichier CRL a été correctement mis à jour. Vous pouvez également afficher les détails d’une transaction en cours en précédant le nom de fichier d’un ‘’. Si le premier caractère du nom de fichier est un ‘’, il peut être échappé avec ‘\*’.
Exemple :
show ssl crt-list [-n] [<filename>]
Affiche la liste des crt-list et des répertoires utilisés dans la configuration HAProxy. Si un nom de fichier est spécifié, affiche le contenu d’un crt-list ou d’un répertoire. Une fois affiché, la sortie peut être utilisée comme fichier crt-list. L’option ‘-n’ permet d’afficher le numéro de ligne, ce qui est utile lors de l’utilisation combinée avec l’option ‘del ssl crt-list’ en cas de duplication d’entrée. La sortie avec l’option ‘-n’ n’est pas compatible avec le format crt-list et ne peut pas être chargée par HAProxy.
Exemple :
show ssl ech [<name>]
Affichez la liste des clés ECH chargées dans le processus HAProxy.
Lorsque <name> est spécifié, affiche les clés correspondant à une ligne de liaison spécifique. Le format de la ligne de liaison est
<frontend>/@<filename>:<linenum> (par exemple : frontend1/@haproxy.conf
:19) ou
<frontend>/<name> si la ligne de liaison a été nommée à l’aide du mot-clé « name ».
L’entrée « age » représente le temps, en secondes, écoulé depuis que la clé a été chargée dans la ligne bind. Cette valeur est réinitialisée lors du démarrage, du rechargement ou de la redémarrage de HAProxy.
Exige une version d’OpenSSL qui prend en charge ECH, et HAProxy doit être compilé avec USE_ECH=1. Cette commande n’est prise en charge que sur une connexion CLI en mode expérimental (voir « experimental-mode on »).
Voir également « ech » dans la Section 5.1 du manuel de configuration.
Exemple :
show ssl jwt
Affiche la liste des certificats pouvant être utilisés pour la validation JWT. Voir également les commandes « add ssl jwt » et « del ssl jwt ». Voir l’option de certificat « jwt » pour plus d’informations.
Exemple :
show ssl ocsp-response [[text|base64] <id|path>]
Affichez les identifiants des entrées de l’arbre OCSP correspondant à toutes les réponses OCSP utilisées par HAProxy, ainsi que le chemin du certificat frontal correspondant, le nom de l’autorité émettrice et son hachage de clé, et le numéro de série du certificat pour lequel la réponse OCSP a été générée. Si un <id> valide ou le <path> d’un certificat frontal valide est fourni, affichez le contenu de la réponse OCSP correspondante. Lorsqu’un <id> est fourni, il est possible de définir le format dans lequel les données sont exportées. L’option « text » est la valeur par défaut et permet d’afficher des informations détaillées sur la réponse OCSP de la même manière qu’avec une commande « OpenSSL ocsp -respin <ocsp-response> -text ». Le format « base64 » permet d’exporter le contenu d’une réponse OCSP au format base64.
Exemple :
show ssl ocsp-updates
Affiche des informations sur les entrées concernées par le mécanisme de mise à jour OCSP. La commande affiche une ligne par réponse OCSP et inclut l’heure prévue de mise à jour de la réponse, ainsi que l’heure de la dernière mise à jour réussie et les compteurs de mises à jour réussies et échouées. Elle indique également le statut de la dernière mise à jour (réussie ou non) sous forme numérique et textuelle. Consultez la liste complète des erreurs possibles ci-dessous. Les lignes sont triées par heure croissante de « Next Update ». Chaque ligne contient également le chemin vers le premier certificat frontal utilisant la réponse OCSP. Pour plus d’informations sur la mise à jour automatique OCSP, reportez-vous à la commande « show ssl ocsp-response » et à l’option « ocsp-update ».
Les codes d’erreur et les chaînes d’erreur de mise à jour peuvent être les suivants :
Exemple :
show ssl providers
Affiche les noms des fournisseurs chargés par OpenSSL lors de l’initialisation. Le chargement des fournisseurs peut effectivement être configuré via le fichier de configuration OpenSSL, et cette option permet de vérifier que les bons fournisseurs ont été chargés. Cette commande n’est disponible que sous OpenSSL v3.
Exemple :
show ssl sni [-f <frontend>] [-A] [-t <offset>]
Affiche chaque SNI configuré pour le frontal désigné, ou tous les frontaux si aucun frontal n’a été spécifié. Cela permet de visualiser quels SNI sont proposés pour un frontal, et d’identifier si un SNI est défini plusieurs fois par plusieurs certificats pour le même frontal.
L’option -A permet de filtrer la liste et n’affiche que les certificats dont la date notAfter est dépassée, permettant ainsi d’afficher uniquement les certificats expirés.
L’option -t prend un décalage en secondes, ou avec une unité de temps (s, m, h, d), qui est ajouté à l’heure courante, permettant de vérifier quels certificats ont expiré après le décalage lorsqu’elle est combinée avec -A.. Par exemple, si vous souhaitez vérifier quels certificats seraient expirés dans 30d, il suffit d’exécuter « show ssl sni -A -t 30d ».
Les colonnes sont séparées par un unique \t, permettant une analyse simple.
La colonne « Frontend/Bind » indique le nom du frontal suivi de la position de la ligne de liaison dans la configuration (frontend/fichier:numero_ligne).
La colonne « SNI » affiche le SNI, qui peut être un CN, un SAN ou un filtre provenant d’une liste de certificats (crt-list). Les certificats par défaut d’une ligne bind (qui sont soit déclarés explicitement via default-crt, soit implicites, à savoir le premier certificat d’une ligne bind lorsque strict-sni n’est pas utilisé) affichent le caractère « * » dans la colonne SNI.
La colonne « Filtrage négatif » contient la liste des filtres négatifs associés à un joker. Elle affiche tous les filtres négatifs présents sur la même ligne de la liste crt. Un trait de soulignement est affiché s’il n’y en a aucun.
La colonne « Type » indique le type d’algorithme de chiffrement, qui peut être « rsa », « ecdsa » ou « dsa ».
La colonne « Filename » peut être soit un nom de fichier provenant de la configuration, soit un alias déclaré dans un crt-store.
Les colonnes « NotAfter » et « NotBefore » sont extraites directement du certificat X509 feuille.
Exemple :
show startup-logs
Affiche tous les messages émis pendant le démarrage du processus HAProxy actuel, chaque tampon startup-logs étant unique à son worker HAProxy.
Ce mot-clé existe également sur l’interface CLI principale, qui affiche la dernière tentative de démarrage ou de rechargement.
show table
Affiche des informations générales sur toutes les tables de persistance connues. Leur nom est retourné (le nom du proxy qui les contient), leur type (actuellement toujours zéro, toujours IP), leur taille maximale en nombre d’entrées possible, ainsi que le nombre d’entrées actuellement utilisées.
Exemple :
show table <name> [ data.<type> <operator> <value> [data.<type> ...]] |
Affiche le contenu de la table de persistance <name>. En ce mode, une première ligne d’information générique sur la table est affichée, comme avec la commande « show table », suivie de l’affichage de toutes les entrées. Étant donné que cela peut être très lourd, il est possible de spécifier un filtre afin de préciser les entrées à afficher.
Lorsque le formulaire “data.” est utilisé, le filtre s’applique aux données stockées (voir « stick-table » dans la section 4.2). Un type de données stockées doit être spécifié dans <type>, et ce type de données doit être stocké dans la table, sinon une erreur est signalée. Les données sont comparées selon <operator> avec l’entier 64 bits <value>. Les opérateurs sont les mêmes qu’avec les ACLs :
- eq : correspond aux entrées dont les données sont égales à cette valeur
- ne : correspond aux entrées dont les données sont différentes de cette valeur
- le : correspond aux entrées dont les données sont inférieures ou égales à cette valeur
- ge : correspond aux entrées dont les données sont supérieures ou égales à cette valeur
- lt : correspond aux entrées dont les données sont inférieures à cette valeur
- gt : correspond aux entrées dont les données sont supérieures à cette valeur
Dans cette forme, vous pouvez utiliser plusieurs entrées de filtre de données, jusqu’à un maximum défini au moment de la compilation (4 par défaut).
Lorsque la forme clé est utilisée, l’entrée <key> est affichée. La clé doit être du même type que la table, ce qui est actuellement limité à IPv4, IPv6, entier et chaîne.
Lorsque la forme ptr est utilisée, l’entrée <ptr> est affichée. <ptr> est écrite sous la forme 0xffff et doit correspondre à l’adresse renvoyée par une commande précédente « show table ». Correspondre à une entrée à l’aide de son pointeur peut être pertinent si l’entrée ne peut pas être identifiée à l’aide de sa clé en raison d’une clé vide ou de caractères incompatibles sur le CLI.
Si data.<type> est de type tableau, on peut utiliser « [] » pour accéder à un index spécifique du tableau, comme ceci : data.gpt[1]
Exemple :
Lorsque le critère de données s’applique à une valeur dynamique dépendante du temps, comme un débit en octets, la valeur est calculée dynamiquement pendant l’évaluation de l’entrée afin de déterminer si elle doit être envoyée ou non. Cela signifie qu’un tel filtre peut correspondre pendant une certaine période, puis ne plus correspondre, car au fil du temps, le débit moyen des événements diminue.
Il est possible d’utiliser cette fonctionnalité pour extraire des listes d’adresses IP abuseuses du service, afin de les surveiller ou même de les bloquer dans un pare-feu. Exemple :
Lorsque la table de persistance est synchronisée avec une section peers prenant en charge le fractionnement, le numéro de fraction sera affiché pour chaque clé (sinon, « 0 » est indiqué). Cela permet de savoir quels peers recevront cette clé. Exemple :
show tasks
Affiche le nombre de tâches actuellement dans la file d’exécution, le nombre d’occurrences pour chaque fonction, ainsi que leur latence moyenne lorsqu’elle est connue (pour les tâches pures avec le profilage des tâches activé). La capture est un instantané de l’instant où elle est effectuée, et peut présenter des variations selon les tâches restantes dans la file au moment de l’opération, notamment en mode mono-thread où il y a moins de chances que les opérations d’E/S reconstituent la file (sauf si celle-ci est pleine). Cette commande accède exclusivement au processus et peut provoquer des latences mineures mais mesurables lorsqu’elle est exécutée sur un processus fortement sollicité, elle ne doit donc pas être utilisée de manière abusive par des bots de surveillance.
show threads
Affiche certains états internes et structures pour chaque thread, ce qui peut aider les développeurs à comprendre un problème. La sortie est conçue pour être lisible en affichant un bloc par thread. Lorsque HAProxy est compilé avec USE_THREAD_DUMP=1, un mécanisme avancé de dump utilisant des signaux de thread est employé afin que chaque thread puisse afficher son propre état tour à tour. Sans cette option, le thread traitant la commande affiche tous ses détails, tandis que les autres sont moins détaillés. Un astérisque (’*’) est affiché devant le thread gérant la commande. Un angle droit (’>’) peut également être affiché devant les threads qui n’ont fait aucune progression depuis la dernière invocation de cette commande, indiquant un bogue dans le code qui doit absolument être signalé. Lorsque cela se produit entre deux threads, cela indique généralement un blocage. Si un seul thread est concerné, il s’agit d’un autre type de bogue, comme une liste corrompue. Dans tous les cas, le processus n’est plus entièrement fonctionnel et doit être redémarré.
Le format de sortie n’est pas documenté intentionnellement afin de permettre une évolution facile en fonction des besoins identifiés, sans devoir maintenir une compatibilité descendante, tout comme pour « show activity », les valeurs n’ont pas de sens sans le code à portée de main.
show tls-keys [id|*]
Affiche toutes les références de clés TLS chargées. L’identifiant de référence de la clé de ticket TLS et le fichier à partir duquel les clés ont été chargées sont indiqués. Ces deux éléments peuvent être utilisés pour mettre à jour les clés TLS à l’aide de la commande « set ssl tls-key ». Si un identifiant est spécifié en paramètre, les tickets correspondants seront affichés ; en utilisant *, tous les tickets de toutes les références seront affichés.
show schema json
Affichez le schéma utilisé pour la sortie de « show info json » et « show stat json ».
Il ne contient aucun espace supplémentaire afin de réduire le volume de sortie. Pour une lecture humaine, passer la sortie through un formatteur élégant peut être utile. Exemple :
$ echo “show schema json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
Le schéma suit la spécification « JSON Schema » (json-schema.org), et les vérificateurs peuvent ainsi être utilisés pour valider la sortie des commandes « show info json » et « show stat json » par rapport au schéma.
show trace [<source>]
Affiche l’état actuel du traçage. Pour chaque source, une ligne est affichée avec un caractère unique indiquant si le traçage est arrêté, en attente ou en cours. Le réceptacle de sortie utilisé par le traçage est indiqué (ou « none » s’il n’a pas été défini), suivi du nombre d’événements perdus dans ce réceptacle, puis d’une brève description de la source. Si un nom de source est spécifié, une liste détaillée de tous les événements pris en charge par la source est affichée, ainsi que leur état pour chaque action (report, start, pause, stop), indiqué par un “+” s’ils sont activés, ou un “-” sinon. Tous ces événements sont indépendants, et un événement peut déclencher un démarrage sans être rapporté, et inversement.
show version
Affiche la version du processus HAProxy en cours d’exécution. Cette fonctionnalité est disponible depuis l’interface CLI du processus principal et des processus workers. Exemple :
shutdown frontend <frontend>
Supprime complètement le frontal spécifié. Toutes les ports auxquels il était lié seront libérées. Il ne sera plus possible d’activer ce frontal après cette opération. Cette fonction est destinée à être utilisée dans des environnements où l’arrêt d’un proxy n’est tout simplement pas envisageable, mais où un proxy mal configuré doit être corrigé. Ainsi, il devient possible de libérer le port et de le réaffecter à un autre processus afin de restaurer les opérations. Une fois terminé, le frontal n’apparaîtra plus du tout sur la page de statistiques.
Le frontal peut être spécifié soit par son nom, soit par son identifiant numérique, précédé d’un dièse (’#’).
Cette commande est restreinte et ne peut être émise que sur les sockets configurés au niveau « admin ».
shutdown session <id>
Interrompre immédiatement le flux correspondant à l’identifiant de flux spécifié. Cet identifiant est le premier champ au début des lignes des dumps de la commande « show sess » (il correspond au pointeur de flux). Cette commande peut être utilisée pour interrompre un flux en cours depuis longtemps sans attendre l’expiration du délai d’expiration, ou lorsqu’une transmission infinie est en cours. Les flux ainsi interrompus sont signalés dans les journaux avec un indicateur « K ».
shutdown sessions server <backend>/<server>
Interrompre immédiatement tous les flux associés au serveur spécifié. Cette fonction peut être utilisée pour interrompre les flux longs après qu’un serveur a été placé en mode maintenance, par exemple. Les flux ainsi interrompus sont signalés dans les journaux avec un indicateur « K ».
Les connexions backend restent en état inactif, sauf si le serveur est déjà en mode maintenance, auquel cas elles seront immédiatement planifiées pour suppression.
trace
La commande « trace » seule affiche les sources de traçage, leur état actuel et leurs courtes descriptions. Elle n’est destinée qu’à servir de menu pour accéder aux niveaux suivants ; consultez les autres commandes « trace » ci-dessous.
trace 0
Arrête immédiatement toutes les traces. Cette commande est destinée à être utilisée comme solution rapide pour terminer une session de débogage ou comme action d’urgence en cas d’activation de traces complexes sur plusieurs sources ayant un impact sur le service.
trace <source> [<args...>]
Configure les traces pour la source <source>. Sans argument, cela affiche la liste de toutes les commandes secondaires prises en charge par la source donnée. Plusieurs commandes secondaires peuvent être enchaînées. Les commandes suivantes sont prises en charge :
event [ [+|-|!]<name> ] Sans argument, cette commande affiche la liste de tous les événements pris en charge par la source désignée. Ils sont précédés d’un “-” si ils ne sont pas activés, ou d’un “+” s’ils sont activés. Il est important de noter qu’une seule trace peut être étiquetée avec plusieurs événements, et tant qu’un des événements activés correspond à l’un des événements étiquetés sur la trace, cet événement sera transmis au sous-système de traçage. Par exemple, la réception d’un cadre HTTP/2 de type HEADERS peut déclencher un événement cadre et un événement flux, car le cadre crée un nouveau flux. Si l’événement cadre ou l’événement flux est activé pour cette source, le cadre sera transmis au cadre de traçage.
Avec un argument, il est possible de basculer l'état de chaque événement et de les activer ou désactiver individuellement. Deux mots-clés spéciaux sont pris en charge : « none », qui ne correspond à aucun événement et est utilisé pour désactiver tous les événements en une seule fois, et « any », qui correspond à tous les événements et est utilisé pour activer tous les événements en une seule fois. Les autres événements sont spécifiques à la source d'événements. Il est possible d'activer un événement en spécifiant son nom, éventuellement précédé du signe « + » pour une meilleure lisibilité. Il est possible de désactiver un événement en spécifiant son nom précédé du signe « - » ou « ! ».
Une façon de désactiver complètement une source de traçage consiste à passer « event none », et cette source sera instantanément entièrement ignorée.
suivre <other_source> Cela permet à la source <source> d’émettre également des traces lorsque la source autre <other_source> est verrouillée sur un critère et que le même critère correspond également à la source actuelle. Par exemple, si une source est verrouillée sur une session, suivre cette source depuis une autre en fera émettre des traces pour toutes les occurrences liées à cette session. Cela peut être utilisé, dans une certaine mesure, pour suivre les requêtes backend associées aux connexions frontend. La source « session » facilite cette opération en fournissant des événements « new » et « end » utilisables pour le traitement de verrouillage. Notez que la source <source> n’a pas besoin d’avoir ses traces activées dans ce cas, et son état de traçage ne sera pas non plus affecté. Il se peut toutefois que certains événements soient manquants s’ils ne contiennent pas d’informations permettant de les corrélater avec l’élément suivi. Le meta-source « all » peut également être utilisé avec cette commande : dans ce cas, toutes les sources suivront <other_source>.
Exemple :
niveau [<level>] Sans argument, cette commande affiche tous les niveaux de traçage pour cette source, le niveau actuel étant indiqué par une étoile (’*’) placée en tête. Avec un argument, ce niveau de traçage est modifié en fonction du niveau spécifié. Les niveaux de détail constituent une forme de filtres appliqués avant la remontée des événements. Ces filtres permettent d’inclure ou d’exclure sélectivement les événements selon leur niveau d’importance. Par exemple, un développeur peut avoir besoin de connaître précisément l’emplacement dans le code où un en-tête HTTP a été jugé invalide, tandis qu’un utilisateur final peut ne pas s’intéresser du tout à la validité de cet en-tête. Actuellement, il existe 5 niveaux distincts de traçage :
Il est fortement recommandé d'utiliser uniquement le niveau « user » et de ne passer à d'autres niveaux que si un développeur vous y invite. Il est également conseillé de configurer les événements en premier lieu avant de passer à des niveaux supérieurs, afin d'éviter d'obtenir de nombreuses lignes si aucune filtration n'est appliquée. Le meta-source « all » peut également être utilisé avec cette commande : dans ce cas, le niveau sera appliqué à toutes les sources existantes simultanément.
lock [critère] Sans argument, cette commande affiche la liste de tous les critères pris en charge par cette source pour le traitement en verrouillage, et indique le choix actuel par une étoile (’*’) en tête de celui-ci. Le verrouillage signifie que la source se concentre sur le premier événement correspondant et ne conserve que le critère qui a déclenché cet événement, tout en ignorant les autres jusqu’à l’arrêt de la trace. Cela permet par exemple de capturer une trace sur une connexion unique ou sur un flux unique. Les critères suivants sont pris en charge par certaines traces, pas nécessairement par toutes, car certains pourraient ne pas être disponibles pour la source :
En complément de cela, chaque source peut fournir jusqu'à 4 critères spécifiques, tels que des états internes ou des identifiants de connexion. Par exemple, dans HTTP/2, il est possible de s'ancrer sur un flux H2 et d'ignorer les autres flux une fois qu'une trace a commencé.
Lorsqu'un critère est passé en argument, celui-ci est utilisé à la place des autres, et tout suivi existant est immédiatement interrompu afin de pouvoir redémarrer avec le nouveau critère. Le mot-clé spécial « nothing » est pris en charge par toutes les sources pour désactiver définitivement le suivi.
{ pause | start | stop } [ [+|-|!]événement ] Sans argument, cette commande affiche la liste des événements activés pour mettre automatiquement en pause, démarrer ou arrêter une trace pour cette source. Ces événements sont spécifiques à chaque source de trace. Avec un argument, elle active l’événement pour l’action indiquée (si précédé optionnellement par un ‘+’) ou le désactive (si précédé d’un ‘-’ ou d’un ‘!’). Le mot-clé spécial « now » n’est pas un événement et demande d’exécuter l’action immédiatement. Les mots-clés « none » et « any » sont pris en charge de la même manière qu’avec « trace event ».
Les trois actions prises en charge sont respectivement « pause », « start » et « stop ».
L’action « pause » énumère les événements qui feront arrêter une trace en cours et attendront un nouvel événement de démarrage pour la reprendre.
L’action « start » énumère les événements qui mettent la trace en mode d’attente jusqu’à l’apparition d’un de ces événements de démarrage.
L’action « stop » énumère les événements qui arrêtent définitivement la trace jusqu’à ce qu’elle soit réactivée manuellement.
En pratique, il est pertinent de démarrer manuellement une trace avec « start now » sans tenir compte des événements, et de l’arrêter avec « stop now ».
Pour capturer des séquences d’événements plus subtiles, il est utile de définir « start » sur un événement normal (comme la réception d’une requête HTTP) et « stop » sur un événement très rare (comme l’émission d’une erreur spécifique), afin de garantir que les derniers événements capturés correspondent aux critères souhaités.
L’événement « pause » est utile pour détecter la fin d’une séquence, désactiver le verrouillage et attendre une nouvelle opportunité de capturer.
Dans ce cas, il peut être pertinent d’activer le verrouillage pour ne repérer qu’un critère spécifique (par exemple, un flux), de définir « start » sur n’importe quel événement qui déclenche ce critère (par exemple, tous les événements qui créent un flux), « stop » sur l’anomalie attendue, et « pause » sur n’importe quel événement qui met fin à ce critère (par exemple, n’importe quel événement de fin de flux).
Dans ce cas, le journal de trace contiendra des séquences complètes de séries parfaitement propres affectant un seul objet, jusqu’à la dernière séquence contenant tout, depuis le début jusqu’à l’anomalie.
sink [<sink>] Sans argument, cette commande affiche la liste de tous les réceptacles d’événements disponibles pour cette source, et le réceptacle actuellement configuré est précédé d’une étoile (’*’). Le réceptacle « none » est toujours disponible et signifie que tous les événements sont simplement ignorés, bien que leur traitement ne soit pas ignoré (par exemple, les verrous sont toujours appliqués). D’autres réceptacles sont disponibles selon la configuration et les options de compilation, mais en général « stdout » et « stderr » sont utilisables en mode débogage, et des tampons en mémoire en anneau devraient également être disponibles. Lorsqu’un nom est spécifié, le réceptacle est immédiatement changé pour la source indiquée. Les événements ne sont pas modifiés pendant un changement de réceptacle. Dans le pire des cas, certains peuvent être perdus si un réceptacle invalide (ou « none ») est utilisé, mais les opérations continuent vers une destination différente. Le meta-réceptacle « all » peut également être utilisé avec cette commande : dans ce cas, le réceptacle est appliqué à toutes les sources existantes en même temps.
verbosity [<level>] Sans argument, cette commande affiche tous les niveaux de verbosité disponibles pour cette source, le niveau actuel étant indiqué par une étoile (’*’) placée devant. Avec un argument, cette commande change le niveau de verbosité vers celui spécifié.
Les niveaux de verbosité indiquent jusqu'où le décodeur de trace doit aller pour fournir des informations détaillées. Cela dépend de la source de trace, car certaines sources ne fournissent même pas de décodeur spécifique. Le niveau « quiet » est toujours disponible et désactive toute décodage. Il peut être utile pour comprendre ce qui se passe avant d'analyser les détails, car il a un impact très faible sur les performances et la taille de la trace. Lorsqu'une source ne déclare aucun niveau de verbosité, le niveau « default » est disponible et entraîne l'appel d'un décodeur lorsqu'il est spécifié dans les traces. Il s'agit d'un décodage opportuniste. Lorsque la source déclare des niveaux de verbosité, ceux-ci sont listés avec une description de leur signification. Dans ce cas, le décodeur de trace fourni par la source sera aussi précis que possible, en fonction des informations disponibles au point de trace. Le premier niveau au-dessus de « quiet » est défini par défaut.
update ssl ocsp-response <certfile>
Créez une requête OCSP pour le <certfile> spécifié et envoyez-la au répondant OCSP dont l’URI doit être indiqué dans la section « Authority Information Access » du certificat. Seul le premier URI est pris en compte. La réponse OCSP reçue en retour est ensuite vérifiée et insérée dans l’arbre local des réponses OCSP. Cette commande ne fonctionne que pour les certificats qui ont déjà une réponse OCSP stockée, soit parce qu’elle a été fournie lors de l’initialisation, soit si elle a été définie précédemment à l’aide des commandes « set ssl cert » ou « set ssl ocsp-response ». Si la réponse OCSP reçue est valide et a été correctement insérée dans l’arbre local, son contenu est affiché sur la sortie standard. Le format est identique à celui décrit dans « show ssl ocsp-response ».
wait { -h | <delay> } [<condition> [<args>...]]
Dans sa forme la plus simple, sans condition, cette directive attend simplement le délai demandé avant de poursuivre. Elle peut être utilisée pour collecter des métriques sur un intervalle spécifique.
Avec une condition et des arguments facultatifs, la commande attend que la condition spécifiée soit remplie, qu’elle échoue de manière irréversible, ou qu’elle reste non remplie pendant toute la durée <delay>. Les conditions prises en charge sont :
be-removable
<proxy>: attend que le backend proxy spécifié soit supprimable par la commande « del backend ». Certaines conditions ne seront jamais acceptées (par exemple, un backend non encore désindexé ou comportant des serveurs) et entraîneront l’affichage d’un message d’erreur précis indiquant la condition non remplie. Si tout est correct avant l’expiration du délai, un succès est retourné et l’opération est terminée.srv-removable
<proxy>/<server>: cette directive attend que le serveur spécifié soit éligible à la suppression par la commande « del server », c’est-à-dire qu’il soit en maintenance et ne possède plus aucune connexion (ni active ni inactif). Certaines conditions ne seront jamais acceptées (par exemple, le serveur non en maintenance) et entraîneront la remontée d’un message d’erreur spécifique indiquant la condition non remplie. Le serveur pourrait même avoir été supprimé en parallèle et ne plus exister. Si tout est correct avant l’expiration du délai, un succès est retourné et l’opération est terminée.
L’unité par défaut pour le délai est les millisecondes, bien que d’autres unités soient acceptées si elles sont suffixées par les unités de temporisation usuelles (us, ms, s, m, h, d). Lorsqu’il est utilisé avec l’utilitaire ‘socat’, n’oubliez pas d’élargir le délai d’expiration de socat afin de couvrir le temps d’attente. Passer “-h” en premier ou en second argument fournit la syntaxe de la commande. Exemple :
9.4. CLI principale
L’interface CLI principale est une socket liée au processus principal en mode principal-worker. Cette interface CLI permet d’accéder aux commandes de socket Unix depuis tous les processus en cours d’exécution ou en cours de terminaison, et permet une supervision basique de ces processus.
L’interface CLI principale ne peut être configurée qu’à partir des arguments du programme HAProxy, via l’option -S. Cette option accepte également des options bind, séparées par des virgules.
Exemple :
9.4.1. Commandes CLI principales
@<[!]pid>
L’interface CLI principale utilise une notation de préfixe spéciale pour accéder aux processus multiples. Cette notation est facilement identifiable car elle commence par un @.
Un préfixe @ peut être suivi d’un numéro de processus relatif ou d’un point d’exclamation suivi d’un PID. (Par exemple : @1 ou @!1271). Un @ seul peut être utilisé pour spécifier le processus principal. Les processus restants ne sont accessibles qu’avec le PID comme numéro de processus relatif, et ne sont utilisables qu’avec les processus actuels.
Ce préfixe peut être utilisé comme enveloppe avant une commande, indiquant que cette commande uniquement sera envoyée au processus désigné. Dans ce cas, la commande complète se termine à la fin de la ligne ou à la point-virgule, comme toute commande régulière.
Bugs : le protocole sockpair@ utilisé pour implémenter la communication entre le processus principal et le worker est connu pour ne pas être fiable sous macOS en raison d’un problème dans l’implémentation de sendmsg(2) de macOS. Une commande pourrait ne pas obtenir de réponse à cause de cela.
Exemples :
Le préfixe peut également être utilisé comme commande autonome pour basculer le contexte d’exécution par défaut vers le processus désigné, indiquant que toutes les commandes ultérieures seront exécutées dans ce processus, jusqu’à ce qu’une nouvelle commande ‘@’ change à nouveau le contexte d’exécution.
Exemples :
Remarque sur les limitations : quelques rares commandes modifient l’état d’une session CLI (par exemple, « set anon », « set timeout ») et peuvent ne pas se comporter exactement de la même manière lorsqu’elles sont exécutées depuis la CLI principale, en raison de l’envoi individuel des commandes sur des sessions CLI distinctes. De même, quelques rares commandes (« show events », « wait ») surveillent activement l’entrée ou la fermeture de la CLI et sont immédiatement interrompues lorsque la CLI est fermée. Ces commandes ne fonctionneront pas comme prévu via la CLI principale, car l’entrée de la commande est fermée après chaque exécution. Dans de tels cas rares, la variante « @@ » ci-dessous pourrait être plus adaptée.
@@<[!]pid> [command...]
Ce préfixe ou commande est très similaire au préfixe “@” documenté ci-dessus, à ceci près qu’il entre dans le processus worker, transmet la ligne de commande entière tel quelle à ce dernier et reste connecté jusqu’à la fin de l’exécution de la commande. Les points-virgules sont également transmis, permettant d’exécuter une commande en pipeline complète dans un processus worker. La connexion avec le worker reste ouverte jusqu’à la fin de l’exécution de la liste des commandes. Toute donnée envoyée après les commandes sera acheminée vers l’interface CLI du worker et pourra être consommée par les commandes en cours d’exécution, mais sera perdue pour l’interface CLI du master, offrant ainsi une connexion véritablement bidirectionnelle avec le processus worker. En conséquence, les utilisateurs de ces commandes doivent être extrêmement prudents et attendre la fin de l’exécution d’une commande avant d’envoyer de nouvelles commandes à l’interface CLI du master.
Au lieu d’exécuter une seule commande, il est également possible d’ouvrir une session entièrement interactive sur le processus worker en ne spécifiant aucune commande (c’est-à-dire « @@1 » sur une ligne seule). Cette session peut être terminée soit en fermant la connexion, soit en quittant le processus worker (à l’aide de la commande « quit »). Dans ce cas, le mode d’invite du socket principal (interactif, invite, temporisé) est propagé au processus worker.
Bugs : le protocole sockpair@ utilisé pour implémenter la communication entre le processus principal et le worker est connu pour ne pas être fiable sous macOS en raison d’un problème dans l’implémentation de sendmsg(2) de macOS. Une commande pourrait ne pas obtenir de réponse à cause de cela.
Exemples :
expert-mode [on|off]
Cette commande active le mode « expert » pour chaque worker accédé depuis l’interface CLI principale. En combinaison avec « mcli-debug-mode », elle active également la commande sur le maître. Affiche le drapeau « e » dans l’invite de l’interface CLI principale.
Voir également « expert-mode » dans Section 9.3 et « mcli-debug-mode » dans 9.4.1.
experimental-mode [on|off]
Cette commande active le mode expérimental pour chaque worker accédé depuis l’interface CLI principale. En combinaison avec « mcli-debug-mode », elle active également la commande sur le maître. Affiche le drapeau « x » dans l’invite de l’interface CLI principale.
Voir également « experimental-mode » dans Section 9.3 et « mcli-debug-mode » dans 9.4.1.
hard-reload
Cette commande agit de la même manière que la commande « reload » sur l’interface CLI principale, à ceci près qu’elle effectue une interruption brutale (-st) au lieu d’une interruption douce (-sf) du processus précédent. Cela signifie que le processus précédent ne s’arrête pas en attendant la réalisation de quoi que ce soit, de sorte que toutes les connexions seront fermées.
Voir également la commande « reload ».
mcli-debug-mode [on|off]
Ce mot-clé permet d’activer un mode spécial dans l’interface CLI principale, qui permet d’utiliser sur l’interface CLI principale toutes les commandes destinées à l’interface CLI des workers, ce qui permet de déboguer le processus principal. Une fois activé, listez les nouvelles commandes disponibles à l’aide de « help ». En combinaison avec « experimental-mode » ou « expert-mode », il active encore plus de commandes. Affichez le drapeau « d » dans l’invite de l’interface CLI principale.
prompt
Lorsque l’invite est activée (via la commande « prompt »), le contexte sur lequel le CLI opère est affiché dans l’invite. Le processus principal est identifié par la chaîne « master », tandis que les autres processus sont identifiés par leur PID. En cas d’échec du dernier rechargement, l’invite du processus principal est modifiée en « master[ReloadFailed]> », afin de rendre visible le fait que le processus continue de fonctionner avec la configuration précédente et que la nouvelle configuration n’est pas opérationnelle.
L’invite de la CLI principale est capable d’afficher plusieurs indicateurs correspondant aux modes activés. « d » pour mcli-debug-mode, « e » pour expert-mode, « x » pour experimental-mode.
Exemple :
reload
Vous pouvez également recharger le processus principal HAProxy à l’aide de la commande « reload », qui produit le même effet qu’un kill -USR2 sur le processus principal, à condition que l’utilisateur dispose au moins des privilèges « operator » ou « admin ».
Cette commande permet d’effectuer un rechargement synchrone ; la commande renvoie un statut de rechargement une fois celui-ci effectué. Prenez garde au délai d’expiration si un outil est utilisé pour l’analyser, car il n’est renvoyé qu’après analyse de la configuration et création du nouveau processus worker. La commande « socat » utilise un délai d’expiration par défaut de 0,5 s, donc elle se termine avant d’afficher le message si le rechargement dure trop longtemps. « ncat » ne dispose pas de délai d’expiration par défaut. Lorsqu’il est compilé avec USE_SHM_OPEN=1, la commande de rechargement peut également exporter les journaux de démarrage du processus principal.
Exemple :
La commande reload est la dernière exécutée sur l’interface CLI principale ; toutes les autres commandes suivantes sont ignorées. Dès que la commande reload a renvoyé son statut, la connexion à l’interface CLI est fermée.
Notez qu’un rechargement fermera toutes les connexions vers l’interface CLI principale. Voir également la commande « hard-reload ».
show proc [debug]
L’interface CLI principale introduit une commande « show proc » pour surveiller les processus.
Exemple :
Dans cet exemple, le maître a été rechargé 5 fois, mais un des anciens workers est toujours en cours d’exécution et a survécu à 3 rechargements. Vous pouvez accéder à l’interface CLI de ce worker pour comprendre ce qui se passe.
Le paramètre « debug » est utile pour afficher les détails de débogage ; il affiche actuellement les descripteurs de fichiers (FDs) utilisés pour la communication IPC. Notez que la sortie de débogage n’est pas garantie stable entre les versions de HAProxy.
show startup-logs
HAProxy doit être compilé avec USE_SHM_OPEN=1 pour être utilisé correctement sur l’interface CLI principale ou tous les messages ne seront pas visibles.
Comme son homologue sur la socket de statistiques, cette commande est capable d’afficher les messages de démarrage de HAProxy. Toutefois, elle ne fournit pas les messages de démarrage du worker actuel, mais ceux de la dernière initialisation ou rechargement, ce qui permet de récupérer les messages d’analyse d’un rechargement échoué.
Ces messages sont également affichés avec la commande « reload ».
9.5. Fichier de statistiques
Un fichier appelé stats-file peut être utilisé pour charger au démarrage du processus des compteurs internes de HAProxy avec des valeurs non nulles. Son usage principal consiste à préserver les statistiques des processus workers lors des rechargements. Seule une partie des statistiques exposées par HAProxy est présente dans un fichier stats-file, car il n’a de sens que de charger des valeurs de type métrique.
Pour l’instant, seuls les compteurs de proxy sont pris en charge dans stats-file. Cela permet de précharger des valeurs pour les frontaux, les backends, les serveurs et les écouteurs. Toutefois, seuls les objets dont l’identifiant GUID n’est pas vide sont stockés dans un fichier stats-file. Cela garantit que les valeurs seront préchargées pour les objets ayant un type et un GUID correspondants, même si d’autres paramètres diffèrent.
La commande CLI « dump stats-file » a pour but de générer un fichier de statistiques. Le format de ce fichier est défini internement et peut faire l’objet de modifications ou d’extensions futures sans préavis. Il est conçu pour être compatible au moins entre les versions stables adjacentes de HAProxy, mais peut nécessiter une configuration optionnelle supplémentaire lors du chargement d’un fichier de statistiques dans un processus exécutant une version plus ancienne.