9. Statistiken und Überwachung
Der Status von HAProxy lässt sich abfragen. Am häufigsten wird dafür die HTTP-Statistikseite verwendet. Diese Seite bietet zusätzlich ein CSV-Ausgabeformat für Überwachungswerkzeuge. Dasselbe Format steht über den Unix-Socket zur Verfügung.
Die Statistiken sind in Kategorien zusammengefasst, die als Domänen bezeichnet werden und den verschiedenen Komponenten von HAProxy entsprechen. Zwei Domänen stehen zur Verfügung: proxy und resolvers. Ohne ausdrückliche Angabe wird die Domäne proxy ausgewählt. Beachten Sie, dass auf der HTTP-Seite nur die Proxy-Statistiken ausgegeben werden.
9.1. CSV-Format
Die Statistiken können entweder über den Unix-Socket oder über die HTTP-Seite abgefragt werden. Beide Wege liefern ein CSV-Format mit den nachfolgend beschriebenen Feldern. Die erste Zeile beginnt mit einem Rautezeichen (’#’) und enthält für jedes durch Komma getrennte Feld ein Wort als Spaltentitel. Alle weiteren Zeilen ab der zweiten verwenden ein klassisches CSV-Format mit Komma als Trennzeichen und dem doppelten Anführungszeichen (’"’) als optionalem Textbegrenzer. Dieser wird nur verwendet, wenn der eingeschlossene Text mehrdeutig ist, also ein Anführungszeichen oder ein Komma enthält. Doppelte Anführungszeichen (’"’) innerhalb des Textes werden verdoppelt (’""’); dieses Format erkennen die meisten Werkzeuge. Fügen Sie vor diesen Spalten keine weiteren ein, damit Werkzeuge mit fest kodierten Spaltenpositionen weiterhin funktionieren.
Bei den Proxy-Statistiken stehen hinter jedem Feldnamen in Klammern die Typen, für die dieses Feld einen Wert enthalten kann. Die Typen sind L (Listener), F (Frontends), B (Backends) und S (Server). Es gibt einen festen Satz statischer Felder, die stets in derselben Reihenfolge vorhanden sind. Eine Spalte mit dem Zeichen ‘-’ markiert das Ende der statischen Felder. Für die darauf folgenden Felder sind weder Vorhandensein noch Reihenfolge garantiert.
Die statischen Felder der Statistikdomäne proxy sind:
Für alle anderen Statistikdomänen sind weder das Vorhandensein noch die Reihenfolge der Felder garantiert. In diesem Fall sollte zum Auswerten der CSV-Daten immer die Kopfzeile verwendet werden.
9.2. Typisiertes Ausgabeformat
Sowohl “show info” als auch “show stat” unterstützen einen Modus, in dem jeder Ausgabewert zusammen mit seinem Typ und ausreichenden Informationen ausgegeben wird, um zu erkennen, wie der Wert über mehrere Prozesse hinweg aggregiert werden soll und wie er sich verändert.
In allen Fällen enthält die Ausgabe genau einen Wert pro Zeile. Sämtliche Informationen sind in Felder aufgeteilt, die durch Doppelpunkte (’:’) getrennt werden.
Die erste Spalte bezeichnet das ausgegebene Objekt oder die Metrik. Ihr Format hängt vom ausgebenden Befehl ab und wird in diesem Abschnitt nicht beschrieben. Üblicherweise besteht sie aus einer Folge von Kennungen und Feldnamen.
Die zweite Spalte enthält 4 Zeichen, die in dieser Reihenfolge Herkunft, Art, Gültigkeitsbereich und Persistenzstatus des gemeldeten Werts angeben. Das erste Zeichen (die Herkunft) gibt an, woher der Wert stammt. Mögliche Zeichen sind:
Das zweite Zeichen (die Art) beschreibt die Art der im Feld enthaltenen Information, damit ein Aggregator entscheiden kann, mit welcher Operation mehrere Werte zusammenzufassen sind. Mögliche Zeichen sind:
Das dritte Zeichen (der Gültigkeitsbereich) gibt an, auf welchen Bereich sich der Wert bezieht. Manche Angaben gelten pro Prozess, andere pro Konfiguration oder für das gesamte System. Diese Unterscheidung ist wichtig, um zu entscheiden, ob bei der Aggregation ein einzelner Wert beibehalten werden sollte oder mehrere Werte zusammengefasst werden müssen. Derzeit werden folgende Zeichen unterstützt:
Das vierte Zeichen (der Persistenzstatus) gibt an, ob der Wert (die Metrik) flüchtig ist oder über Neuladungen hinweg erhalten bleibt. Folgende Zeichen sind vorgesehen:
Für die Nutzer dieser Informationen reichen diese 4 Zeichen in der Regel aus, um zu bestimmen, wie aggregierte Informationen über mehrere Prozesse hinweg korrekt dargestellt werden können.
Die darauf folgende dritte Spalte gibt den Feldtyp an: “s32” (vorzeichenbehaftete 32-Bit-Ganzzahl), “s64” (vorzeichenbehaftete 64-Bit-Ganzzahl), “u32” (vorzeichenlose 32-Bit-Ganzzahl), “u64” (vorzeichenlose 64-Bit-Ganzzahl) oder “str” (Zeichenkette). Der Typ muss vor dem Parsen des Werts bekannt sein, damit dieser korrekt gelesen wird. Beispielsweise bleibt eine Zeichenkette, die nur Ziffern enthält, eine Zeichenkette und ist keine Ganzzahl, etwa ein bei einer Prüfung extrahierter Fehlercode.
Die vierte Spalte enthält anschließend den Wert selbst, entsprechend seinem Typ kodiert. Zeichenketten werden unverändert unmittelbar nach dem Doppelpunkt ohne führendes Leerzeichen ausgegeben. Enthält eine Zeichenkette einen Doppelpunkt, erscheint dieser ganz normal. Die Ausgabe sollte daher nicht ausschließlich an Doppelpunkten aufgeteilt werden, da sonst manche Prüfausgaben oder Serveradressen abgeschnitten werden könnten.
9.3. Unix-Socket-Befehle
Der Statistik-Socket ist standardmäßig nicht aktiviert. Zum Aktivieren muss im Abschnitt global der haproxy-Konfiguration eine Zeile hinzugefügt werden. Eine zweite Zeile wird empfohlen, um eine längere Wartezeit festzulegen, was bei der manuellen Befehlseingabe hilfreich ist:
Durch Wiederholen der Zeile lassen sich auch mehrere Statistik-Sockets hinzufügen und an einen TCP-Port statt an einen UNIX-Socket binden. Dies wird wegen der damit verbundenen Gefahr nie standardmäßig eingerichtet, kann aber in manchen Situationen praktisch sein:
Für den Zugriff auf den Socket wird ein externes Werkzeug wie “socat” benötigt. Socat ist ein vielseitiges Werkzeug zum Verbinden beliebiger Ein- und Ausgaben. Hier wird es verwendet, um Terminals oder für Skripte ein Paar stdin/stdout-Pipes mit dem Socket zu verbinden. Hauptsächlich werden die folgenden beiden Aufrufformen verwendet:
Die erste Form wird mit Skripten verwendet. Die Ausgabe eines Skripts kann an haproxy gesendet und die Ausgabe von haproxy an ein anderes Skript weitergereicht werden. Das ist beispielsweise zum Abrufen von Zählern oder Angriffsspuren nützlich.
Die zweite Form dient ausschließlich der manuellen Befehlseingabe. Dabei wird das Terminal von der readline-Bibliothek verwaltet, die Zeilenbearbeitung und einen Befehlsverlauf unterstützt. Das ist bei wiederholten Befehlen sehr praktisch, etwa zum Beobachten eines Zählers.
Der Socket unterstützt drei Betriebsarten:
- nicht interaktiv, ohne Eingabeaufforderung
- interaktiv, ohne Eingabeaufforderung
- interaktiv mit Eingabeaufforderung
Wenn socat eine Verbindung zum Socket herstellt, ist standardmäßig der nicht interaktive Modus aktiv. In diesem Modus kann eine einzelne Zeile gesendet werden. Sie wird als Ganzes verarbeitet, die Antworten werden zurückgesendet und nach dem Ende der Antwort wird die Verbindung geschlossen. Skripte und Überwachungswerkzeuge verwenden diesen Modus. Darin können mehrere Befehle gesendet werden, wenn sie durch ein Semikolon (’;’) getrennt sind. Beispiel:
Wenn ein Befehl ein Semikolon oder einen umgekehrten Schrägstrich benötigt, etwa innerhalb eines Werts, muss diesem Zeichen ein umgekehrter Schrägstrich (’\’) vorangestellt werden.
Im interaktiven Modus können neue Befehle gesendet werden, nachdem die Befehle der vorherigen Zeilen abgeschlossen sind. Es gibt zwei Varianten: eine ohne Eingabeaufforderung, die wie der nicht interaktive Modus funktioniert, aber auf einen neuen Befehl wartet, statt den Socket zu schließen; und eine, bei der am Zeilenanfang eine Eingabeaufforderung (’>’) erscheint. Der interaktive Modus eignet sich für anspruchsvollere Werkzeuge, der Modus mit Eingabeaufforderung für die manuelle Bedienung.
Der Modus lässt sich mit dem Befehl “prompt” ändern. Standardmäßig schaltet er zwischen dem interaktiven Modus und dem Modus mit Eingabeaufforderung um. Die Eingabe von “prompt” im interaktiven Modus aktiviert die Eingabeaufforderung. Optional akzeptiert der Befehl einen bestimmten Modus:
- “n”: nicht interaktiver Modus (ein einzelner Befehl, dann Ende)
- “i”: interaktiver Modus (mehrere Befehle, ohne Eingabeaufforderung)
- “p”: Modus mit Eingabeaufforderung (mehrere Befehle mit Eingabeaufforderung)
Da standardmäßig der nicht interaktive Modus aktiv ist, muss “prompt” als erster Befehl verwendet werden, um ihn zu ändern. Andernfalls bewirkt der vorherige Befehl das Schließen der Verbindung. Beim Wechsel in den nicht interaktiven Modus wird die Verbindung geschlossen, sobald alle Befehle derselben Zeile abgeschlossen sind.
Aus diesem Grund beginnt man bei der manuellen Fehlersuche häufig mit dem Befehl “prompt”:
show info …
Interaktive Werkzeuge können mit “prompt i” beginnen, um in den interaktiven Modus ohne Eingabeaufforderung zu wechseln.
Optional kann die Laufzeit des Prozesses in der Eingabeaufforderung angezeigt werden. Der Befehl “prompt timed” aktiviert die Eingabeaufforderung und schaltet die Zeitanzeige um. Die Laufzeit wird im Format “d:hh:mm:ss” angezeigt, wobei “d” die Anzahl der Tage und “hh”, “mm” und “ss” die Anzahl der Stunden, Minuten beziehungsweise Sekunden mit jeweils zwei Ziffern angeben:
[23:03:34:39]> show version 2.8-dev9-e5e622-18
[23:03:34:41]> quit
Wenn die Laufzeitanzeige an der Master-CLI aktiviert ist, zeigt die Eingabeaufforderung die Laufzeit des aktuell ausgewählten Prozesses an. Dies funktioniert also für den Master, den aktuellen Worker oder einen älteren Worker:
Da mehrere Befehle gleichzeitig eingegeben werden können, verwendet haproxy eine Leerzeile als Trennzeichen für das Ende der Ausgabe jedes Befehls. Dabei wird sichergestellt, dass kein Befehl selbst eine Leerzeile ausgeben kann. Ein Skript kann die Ausgabe dadurch auch dann leicht auswerten, wenn mehrere Befehle in einer einzigen Zeile übermittelt wurden.
Manche Befehle akzeptieren optionale Nutzdaten. Um einem Befehl Nutzdaten hinzuzufügen, muss die erste Zeile mit dem Muster “<<\n” enden. Die folgenden Zeilen werden als Nutzdaten behandelt; es können beliebig viele Zeilen sein. Zum Bestätigen eines Befehls mit Nutzdaten muss die Eingabe mit einer Leerzeile enden.
Das Nutzdatenmuster kann angepasst werden, um das Ende der Nutzdaten anders zu kennzeichnen. Sollen Nutzdaten mit etwas anderem als einer Leerzeile enden, kann zwischen ‘<<’ und ‘\n’ ein eigenes Muster festgelegt werden. Zusätzlich zu ‘<<’ sind bis zu 64 Zeichen zulässig; andernfalls wird die Eingabe nicht als Nutzdaten erkannt. Dies sollte für zufällige Nutzdatenmuster ausreichen. Beispiel für eine PEM-Datei mit Leerzeilen und Kommentaren:
Es gibt Einschränkungen: Das Muster “<<” darf nicht unmittelbar an das letzte Wort der Zeile angehängt werden. Die Länge einer Befehlszeile darf tune.bufsize nicht überschreiten. Dabei wird das Muster, das die Nutzdaten einleitet, mitgezählt, die Nutzdaten selbst jedoch nicht. Die Nutzdatengröße ist standardmäßig auf 128KB begrenzt. Dies kann mit dem globalen Parameter “tune.cli.max-payload-size” unter Beachtung einiger Vorsichtsmaßnahmen geändert werden. Beachten Sie, dass das Muster zum Beenden der Nutzdaten in diese Grenze einbezogen wird.
Während der Eingabe von Nutzdaten im interaktiven Modus wechselt die Eingabeaufforderung von “> " zu “+ “.
Beachten Sie, dass bei mehreren haproxy-Prozessen, die auf denselben Sockets gestartet wurden, jeder beliebige Prozess die Anfrage annehmen kann und seine eigenen Statistiken ausgibt.
Die derzeit auf dem Statistik-Socket unterstützten Befehle sind unten aufgeführt. Bei einem unbekannten Befehl zeigt haproxy eine Bedienungshilfe mit allen unterstützten Befehlen an. Einige Befehle haben eine komplexere Syntax; bei einem Fehler wird in der Regel erläutert, welcher Teil des Befehls ungültig ist.
Manche Befehle erfordern höhere Berechtigungen. Reichen Ihre Berechtigungen nicht aus, erhalten Sie den Fehler “Permission denied”. Weitere Informationen finden Sie bei der Option “level” der “bind”-Zeilen im Konfigurationshandbuch.
abort ssl ca-file <cafile>
Bricht eine temporäre Aktualisierungstransaktion für eine CA-Datei ab und verwirft sie.
Siehe auch “set ssl ca-file” und “commit ssl ca-file”.
abort ssl cert <filename>
Bricht eine temporäre Aktualisierungstransaktion für ein SSL-Zertifikat ab und verwirft sie.
Siehe auch “set ssl cert” und “commit ssl cert”.
abort ssl crl-file <crlfile>
Bricht eine temporäre Aktualisierungstransaktion für eine CRL-Datei ab und verwirft sie.
Siehe auch “set ssl crl-file” und “commit ssl crl-file”.
acme renew <certificate>
Startet eine ACME-Aufgabe zur Zertifikatserzeugung mit dem angegebenen Zertifikatsnamen. Das Zertifikat muss einem acme-Abschnitt zugeordnet sein; siehe Abschnitt 12.8 „ACME“ des Konfigurationshandbuchs. Siehe auch “acme status”.
acme status
Zeigt den Status aller Zertifikate an, die mit ACME konfiguriert wurden.
Dieser Befehl gibt folgende Werte, durch Tabulatoren getrennt, aus:
- Den Namen des in HAProxy konfigurierten Zertifikats
- Den in der Konfiguration verwendeten acme-Abschnitt
- Den Status der acme-Aufgabe: “Running”, “Scheduled” oder “Stopped”
- Das UTC-Ablaufdatum des Zertifikats im ISO8601-Format
- Die relative Zeit bis zum Ablauf (0d, falls abgelaufen)
- Den geplanten UTC-Termin des Zertifikats im ISO8601-Format
- Die relative Zeit bis zum geplanten Termin (0d bei Running)
Beispiel:
add acl [@<ver>] <acl> <pattern>
Fügt der ACL <acl> einen Eintrag hinzu. <acl> ist die von “show acl” zurückgegebene #<id> oder der zurückgegebene <name>. Dieser Befehl prüft nicht, ob der Eintrag bereits vorhanden ist. Einträge werden der aktuellen Version der ACL hinzugefügt, sofern nicht mit “@<ver>” eine bestimmte Version angegeben wird. Diese Versionsnummer muss zuvor mit “prepare acl” zugewiesen worden sein und liegt zwischen den Versionen, die in der Ausgabe von “show acl” als “curr_ver” und “next_ver” gemeldet werden. Einträge, die mit einer bestimmten Versionsnummer hinzugefügt wurden, ergeben erst nach einer “commit acl”-Operation einen Treffer. Sie können jedoch mit dem Befehl “show acl @<ver>” eingesehen und mit “clear acl @<ver>” gelöscht werden. Dieser Befehl kann nicht verwendet werden, wenn die Referenz <acl> ein Name ist, der auch für eine Map verwendet wird. In diesem Fall muss stattdessen der Befehl “add map” verwendet werden.
add backend <name> from <defproxy> [mode <mode>] [guid <guid>]
Erzeugt eine neue Backend-Proxy-Instanz mit dem Namen <name>.
Es können nur TCP- oder HTTP-Proxys erzeugt werden. Alle Einstellungen werden von der Standard-Proxy-Instanz <defproxy> geerbt. Standardmäßig muss der Backend-Modus über das gleichnamige Argument angegeben werden, sofern <defproxy> ihn nicht bereits ausdrücklich festlegt. Bei Bedarf kann auch ein optionales GUID-Argument verwendet werden.
Server können mit dem Befehl “add server” hinzugefügt werden. Das Backend wird im unveröffentlichten Zustand initialisiert. Sobald es für den Datenverkehr bereit ist, kann die neu erzeugte Instanz mit “publish backend” verfügbar gemacht werden.
Alle benannten Standard-Proxys können verwendet werden, sofern sie dieselben Vererbungsregeln erfüllen, die beim Einlesen der Konfiguration gelten. Es gibt jedoch Ausnahmen, etwa wenn der Modus weder TCP noch HTTP ist.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
add map [@<ver>] <map> <key> <value>
Fügt der Map <map> einen Eintrag hinzu, der dem Schlüssel <key> den Wert <value> zuordnet. Dieser Befehl prüft nicht, ob der Eintrag bereits vorhanden ist. Er dient hauptsächlich dazu, eine Map nach einer “clear”- oder “prepare”-Operation zu füllen. Einträge werden der aktuellen Version der ACL hinzugefügt, sofern nicht mit “@<ver>” eine bestimmte Version angegeben wird. Diese Versionsnummer muss zuvor mit “prepare acl” zugewiesen worden sein und liegt zwischen den Versionen, die in der Ausgabe von “show acl” als “curr_ver” und “next_ver” gemeldet werden. Einträge, die mit einer bestimmten Versionsnummer hinzugefügt wurden, ergeben erst nach einer “commit map”-Operation einen Treffer. Sie können jedoch mit dem Befehl “show map @<ver>” eingesehen und mit “clear acl @<ver>” gelöscht werden. Wird die bezeichnete Map auch als ACL verwendet, berücksichtigt die ACL nur den Teil <key> und ignoriert den Teil <value>. Mit der Nutzdatensyntax können mehrere Schlüssel-Wert-Paare hinzugefügt werden, indem jedes Paar in einer eigenen Zeile eingegeben wird. In jeder neuen Zeile ist das erste Wort der Schlüssel; der Rest der Zeile wird als Wert betrachtet und kann auch Leerzeichen enthalten.
Beispiel:
add server <backend>/<server> [args]*
Erzeugt eine neue Serverinstanz im Backend <backend>.
Der Name <server> darf im Backend noch nicht verwendet werden. Für das Backend gilt die besondere Einschränkung, dass es einen dynamischen Lastverteilungsalgorithmus verwenden muss. Eine Teilmenge der Schlüsselwörter der server-Anweisung in der Konfigurationsdatei kann zur Konfiguration des Serververhaltens verwendet werden (“add server help” listet sie auf). Einstellungen einer eventuell vorhandenen ‘default-server’-Anweisung im selben Backend werden nicht übernommen.
Derzeit wird ein dynamischer Server statisch mit der init-addr-Methode “none” initialisiert. Das bedeutet, dass keine Namensauflösung erfolgt, wenn als Adresse ein FQDN angegeben wird, auch wenn die Servererzeugung akzeptiert wird.
Damit Neuladevorgänge unterstützt werden, wird erwartet, dass der über die CLI erzeugte Server auch manuell in die entsprechende HAProxy-Konfigurationsdatei eingetragen wird. Ein dynamischer Server, der nicht in der Konfiguration vorhanden ist, wird nach einem Neuladevorgang nicht wiederhergestellt.
Ein dynamischer Server kann mit dem Schlüsselwort “track” den Prüfstatus eines anderen Servers aus der Konfiguration verfolgen. Es ist jedoch nicht möglich, einen anderen dynamischen Server zu verfolgen. Dadurch bleibt die Verfolgungskette auch dann konsistent, wenn dynamische Server gelöscht werden.
Mit dem Schlüsselwort “check” wird die Unterstützung für Health Checks aktiviert. Der Health Check ist standardmäßig deaktiviert und muss unabhängig vom Server mit dem Befehl “enable health” aktiviert werden. Für Agent-Prüfungen dienen das Schlüsselwort “agent-check” und der Befehl “enable agent”. In diesem Fall kann der Agent den Server je nach gemeldetem Status aktivieren, ohne dass ausdrücklich “enable server” ausgeführt wird. Daher ist beim Entfernen eines dynamischen Servers mit Agent-Prüfung besondere Vorsicht erforderlich. Der Agent sollte zuerst mit “disable agent” deaktiviert werden, damit der Server vor dem Entfernen in den erforderlichen Wartungsmodus versetzt werden kann.
Bei einer großen Anzahl dynamischer Server kann die fd-Grenze erreicht werden. Siehe in diesem Fall die Dokumentation des globalen Schlüsselworts “u-limit”.
add server help
Listet die Schlüsselwörter auf, die die aktuelle HAProxy-Version für dynamische Server unterstützt. Die Syntax der Schlüsselwörter ähnelt der server-Zeile der Konfigurationsdatei; Einzelheiten stehen in der jeweiligen Dokumentation.
add ssl ca-file <cafile> <payload>
Fügt einer ca-file ein neues Zertifikat hinzu. Dieser Befehl ist nützlich, wenn die Puffergrößengrenze der CLI erreicht wurde und mehrere Zertifikate hinzugefügt werden sollen. Statt mit “set” alle Zertifikate auf einmal zu setzen, kann jedes Zertifikat einzeln hinzugefügt werden. “set ssl ca-file” setzt die ca-file zurück.
Beispiel:
add ssl crt-list <crtlist> <certificate>
Fügt einer crt-list ein Zertifikat hinzu. Der Befehl kann auch für Verzeichnisse verwendet werden, da Verzeichnisse inzwischen auf dieselbe Weise wie crt-lists geladen werden. Mit diesem Befehl kann ein Zertifikatsname als Parameter angegeben werden. Für SSL-Optionen oder Filter muss stattdessen eine crt-list-Zeile als Nutzdaten gesendet werden. Die Nutzdaten unterstützen nur eine einzige crt-list-Zeile. Der Befehl lädt das Zertifikat für alle bind-Zeilen, die die crt-list verwenden. Um ein neues Zertifikat an HAProxy zu übertragen, müssen die Befehle “new ssl cert” und “set ssl cert” verwendet werden.
Beispiel:
add ssl ech <bind> <payload>
Fügt einer <bind>-Zeile einen ECH-Schlüssel hinzu. Die Nutzdaten müssen im PEM-for-ECH-Format vorliegen.
(https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni
)
Das Format der bind-Zeile ist <frontend>/@<filename>:<linenum> (Beispiel: frontend1/@haproxy.conf
:19) oder <frontend>/<name>, wenn die bind-Zeile mit dem Schlüsselwort “name” benannt wurde.
Erfordert eine OpenSSL-Version mit ECH-Unterstützung. HAProxy muss mit USE_ECH=1 kompiliert sein. Dieser Befehl wird nur auf einer CLI-Verbindung im experimentellen Modus unterstützt (siehe “experimental-mode on”).
Siehe auch “show ssl ech” und “ech” in Abschnitt 5.1 des Konfigurationshandbuchs.
Beispiel:
add ssl jwt <filename>
Fügt ein bereits geladenes Zertifikat der Liste der Zertifikate hinzu, die für die JWT-Validierung verwendet werden können (siehe Konverter “jwt_verify_cert”). Dieser Befehl funktioniert nicht bei laufenden Transaktionen. Siehe auch die Befehle “del ssl jwt” und “show ssl jwt”. Weitere Informationen stehen bei der Zertifikatsoption “jwt”.
clear counters
Setzt die Höchstwerte der Statistikzähler in jedem Proxy (Frontend und Backend) und in jedem Server zurück. Die kumulierten Zähler bleiben unverändert. Die von “show activity” gemeldeten internen Aktivitätszähler werden ebenfalls zurückgesetzt. Damit lassen sich nach einem Vorfall die Zähler zurücksetzen, ohne neu starten oder die Verkehrszähler löschen zu müssen. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
clear counters all
Setzt alle Statistikzähler in jedem Proxy (Frontend und Backend) und in jedem Server zurück. Dies hat dieselbe Wirkung wie ein Neustart. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
clear acl [@<ver>] <acl>
Entfernt alle Einträge aus der ACL <acl>. <acl> ist die von “show acl” zurückgegebene #<id> oder der zurückgegebene <name>. Wenn die Referenz <acl> ein Name ist, der auch für eine Map verwendet wird, wird diese Map ebenfalls geleert. Standardmäßig wird nur die aktuelle Version der ACL geleert (die Version, gegen die geprüft wird). Es kann jedoch eine andere Version angegeben werden, indem auf ‘@’ die Versionsnummer folgt.
clear map [@<ver>] <map>
Entfernt alle Einträge aus der Map <map>. <map> ist die von “show map” zurückgegebene #<id> oder der zurückgegebene <name>. Wenn die Referenz <map> ein Name ist, der auch für eine ACL verwendet wird, wird diese ACL ebenfalls geleert. Standardmäßig wird nur die aktuelle Version der Map geleert (die Version, gegen die geprüft wird). Es kann jedoch eine andere Version angegeben werden, indem auf ‘@’ die Versionsnummer folgt.
clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ] |
Entfernt Einträge aus der Stick Table <table>.
Dies wird üblicherweise verwendet, um die Sperre für Benutzer aufzuheben, die sich über einen ungerechtfertigt verweigerten Zugriff auf einen Dienst beschweren. Es können aber auch Einträge zur Sitzungsbindung gelöscht werden, die einem zu ersetzenden Server zugeordnet sind (Einzelheiten siehe “show table” weiter unten). Manchmal wird das Entfernen eines Eintrags verweigert, weil er gerade von einer Sitzung verfolgt wird. Üblicherweise genügt es, einige Sekunden später nach dem Ende der Sitzung einen neuen Versuch zu unternehmen.
Werden keine Optionsargumente angegeben, werden alle Einträge entfernt.
Bei der Form “data.” werden Einträge entfernt, auf die ein Filter anhand der gespeicherten Daten zutrifft (siehe “stick-table” in Abschnitt 4.2). In <type> muss ein gespeicherter Datentyp angegeben werden. Dieser Datentyp muss in der Tabelle gespeichert sein, andernfalls wird ein Fehler gemeldet. Die Daten werden gemäß <operator> mit der 64-Bit-Ganzzahl <value> verglichen. Es gelten dieselben Operatoren wie bei ACLs:
- eq: erfasst Einträge, deren Daten diesem Wert entsprechen
- ne: erfasst Einträge, deren Daten diesem Wert nicht entsprechen
- le: erfasst Einträge, deren Daten kleiner oder gleich diesem Wert sind
- ge: erfasst Einträge, deren Daten größer oder gleich diesem Wert sind
- lt: erfasst Einträge, deren Daten kleiner als dieser Wert sind
- gt: erfasst Einträge, deren Daten größer als dieser Wert sind
Bei der key-Form wird der Eintrag <key> entfernt. Der Schlüssel muss denselben Typ wie die Tabelle haben; derzeit sind nur IPv4, IPv6, Ganzzahl und Zeichenfolge möglich.
Bei der ptr-Form wird der Eintrag <ptr> entfernt. <ptr> wird in der Form 0xffff geschrieben und muss der Adresse entsprechen, die ein zuvor ausgeführter “show table”-Befehl zurückgegeben hat. Das Identifizieren eines Eintrags über seinen Zeiger kann sinnvoll sein, wenn dies über den Schlüssel wegen eines leeren Schlüssels oder mit der CLI inkompatibler Zeichen nicht möglich ist.
Wenn data.<type> ein Array-Typ ist, kann mit “[]” auf einen bestimmten Index im Array zugegriffen werden, etwa so: data.gpt[1]
Beispiel:
commit acl @<ver> <acl>
Übernimmt alle Änderungen an Version <ver> der ACL <acl> und löscht alle früheren Versionen. <acl> ist die von “show acl” zurückgegebene #<id> oder der zurückgegebene <name>. Die Versionsnummer muss zwischen “curr_ver”+1 und “next_ver” liegen, wie von “show acl” gemeldet. Der zu übernehmende ACL-Inhalt kann bei Bedarf mit “show acl @<ver> <acl>” eingesehen werden. Die angegebene Versionsnummer wurde normalerweise mit dem Befehl “prepare acl” erzeugt. Die Ersetzung erfolgt atomar: Die aktuelle Version wird atomar auf die angegebene Version gesetzt. Dadurch werden alle Einträge anderer Versionen sofort unsichtbar und alle Einträge der neuen Version sichtbar. Mit diesem Befehl können auch sämtliche sichtbaren Einträge einer ACL atomar entfernt werden, indem zuerst “prepare acl” aufgerufen wird und anschließend die Version übernommen wird, ohne Einträge hinzuzufügen. Dieser Befehl kann nicht verwendet werden, wenn die Referenz <acl> ein Name ist, der auch für eine Map verwendet wird. In diesem Fall muss stattdessen der Befehl “commit map” verwendet werden.
commit map @<ver> <map>
Übernimmt alle Änderungen an Version <ver> der Map <map> und löscht alle früheren Versionen. <map> ist die von “show map” zurückgegebene #<id> oder der zurückgegebene <name>. Die Versionsnummer muss zwischen “curr_ver”+1 und “next_ver” liegen, wie von “show map” gemeldet. Der zu übernehmende Map-Inhalt kann bei Bedarf mit “show map @<ver> <map>” eingesehen werden. Die angegebene Versionsnummer wurde normalerweise mit dem Befehl “prepare map” erzeugt. Die Ersetzung erfolgt atomar: Die aktuelle Version wird atomar auf die angegebene Version gesetzt. Dadurch werden alle Einträge anderer Versionen sofort unsichtbar und alle Einträge der neuen Version sichtbar. Mit diesem Befehl können auch sämtliche sichtbaren Einträge einer Map atomar entfernt werden, indem zuerst “prepare map” aufgerufen wird und anschließend die Version übernommen wird, ohne Einträge hinzuzufügen.
commit ssl ca-file <cafile>
Übernimmt eine temporäre Transaktion zur Aktualisierung einer SSL-CA-Datei.
Bei einer bestehenden CA-Datei (Status “Used” in “show ssl ca-file”) wird der neue CA-Dateieintrag in den CA-Dateibaum eingefügt. Jede Instanz, die den CA-Dateieintrag verwendet hat, wird zusammen mit den benötigten SSL-Kontexten neu aufgebaut. Alle zuvor von den neu aufgebauten Instanzen verwendeten Kontexte werden entfernt. Bei Erfolg wird der bisherige CA-Dateieintrag aus dem Baum entfernt. Bei einem Fehlschlag wird nichts entfernt oder gelöscht; alle ursprünglichen SSL-Kontexte bleiben erhalten und werden weiterhin verwendet. Sobald die temporäre Transaktion übernommen wurde, wird sie zerstört.
Bei einer neuen CA-Datei (nach “new ssl ca-file”, Status “Unused” in “show ssl ca-file”) wird die CA-Datei in den CA-Dateibaum eingefügt, aber nirgendwo in HAProxy verwendet. Um sie zu verwenden und SSL-Kontexte zu erzeugen, die sie nutzen, muss sie mit “add ssl crt-list” einer crt-list hinzugefügt werden.
Siehe auch “new ssl ca-file”, “set ssl ca-file”, “add ssl ca-file”, “abort ssl ca-file” und “add ssl crt-list”.
commit ssl cert <filename>
Übernimmt eine temporäre Transaktion zur Aktualisierung eines SSL-Zertifikats.
Bei einem bestehenden Zertifikat (Status “Used” in “show ssl cert”) werden alle benötigten SSL-Kontexte und SNIs erzeugt und eingefügt; die bisherigen werden entfernt. Die bisherigen SSL-Zertifikate werden im Speicher überall dort ersetzt, wo <filename> in der Konfiguration verwendet wurde. Bei einem Fehlschlag wird nichts entfernt oder eingefügt. Sobald die temporäre Transaktion übernommen wurde, wird sie zerstört.
Bei einem neuen Zertifikat (nach “new ssl cert”, Status “Unused” in “show ssl cert”) wird das Zertifikat in einen Zertifikatsspeicher übernommen, aber nirgendwo in HAProxy verwendet. Um es zu verwenden und seine SNIs zu erzeugen, muss es mit “add ssl crt-list” einer crt-list oder einem Verzeichnis hinzugefügt werden.
Siehe auch “new ssl cert”, “set ssl cert”, “abort ssl cert” und “add ssl crt-list”.
commit ssl crl-file <crlfile>
Übernimmt eine temporäre Transaktion zur Aktualisierung einer SSL-CRL-Datei.
Bei einer bestehenden CRL-Datei (Status “Used” in “show ssl crl-file”) wird der neue CRL-Dateieintrag in den CA-Dateibaum eingefügt, der sowohl CA-Dateien als auch CRL-Dateien enthält. Jede Instanz, die den CRL-Dateieintrag verwendet hat, wird zusammen mit den benötigten SSL-Kontexten neu aufgebaut. Alle zuvor von den neu aufgebauten Instanzen verwendeten Kontexte werden entfernt. Bei Erfolg wird der bisherige CRL-Dateieintrag aus dem Baum entfernt. Bei einem Fehlschlag wird nichts entfernt oder gelöscht; alle ursprünglichen SSL-Kontexte bleiben erhalten und werden weiterhin verwendet. Sobald die temporäre Transaktion übernommen wurde, wird sie zerstört.
Bei einer neuen CRL-Datei (nach “new ssl crl-file”, Status “Unused” in “show ssl crl-file”) wird die CRL-Datei in den CRL-Dateibaum eingefügt, aber nirgendwo in HAProxy verwendet. Um sie zu verwenden und SSL-Kontexte zu erzeugen, die sie nutzen, muss sie mit “add ssl crt-list” einer crt-list hinzugefügt werden.
Siehe auch “new ssl crl-file”, “set ssl crl-file”, “abort ssl crl-file” und “add ssl crt-list”.
debug counters [reset|show|on|off|all|bug|chk|cnt|glt|?]*
Listet interne, im Code platzierte Zähler auf, die je nach Build-Optionen unterschiedlich sein können. Einige hängen von DEBUG_STRICT ab, andere von DEBUG_COUNTERS. Der Befehl akzeptiert eine Kombination mehrerer Argumente, von denen manche Aktionen und andere Filter festlegen: - bug aktiviert die Auflistung der Zähler für BUG_ON()-Anweisungen - cnt aktiviert die Auflistung der Zähler für COUNT_IF()-Anweisungen - chk aktiviert die Auflistung der Zähler für CHECK_IF()-Anweisungen - glt aktiviert die Auflistung der Zähler für COUNT_GLITCH()-Anweisungen - all zeigt auch Zähler an, die nie ausgelöst wurden (Wert 0) - Aktion off: deaktiviert die Aktualisierung der COUNT_IF()-Zähler - Aktion on: aktiviert die Aktualisierung der COUNT_IF()-Zähler - Aktion reset: setzt alle angegebenen Zähler zurück - Aktion show: zeigt alle angegebenen Zähler an
Standardmäßig gilt die Aktion “show”, um Zähler anzuzeigen; aufgelistet werden alle Zählertypen mit einem Wert ungleich null. Der Befehl “show” gilt implizit, wenn keine andere Aktion angegeben ist. Er ist nur vorhanden, um das Erzeugen von Befehlen aus Skripten zu erleichtern.
Die Ausgabe beginnt mit einem ganzzahligen Zähler, gefolgt vom Zählertyp in Großbuchstaben, seiner Position im Code (file:line), dem Funktionsnamen und optional “: " samt einer Beschreibung. Das Ausgabeformat kann sich zwischen Hauptversionen ändern. Neue Typen und Einträge können zur Verbesserung der Fehlerdiagnose in stabile Versionen zurückportiert werden. Eine Überwachung dieser Zähler sollte nur mit sehr großzügiger und toleranter Auswertung erfolgen, vorzugsweise überhaupt nicht.
Normalerweise verwenden Endbenutzer diesen Befehl nicht. Ein Entwickler, der die Ursache eines Problems ermittelt und nach CNT- oder GLT-Einträgen sucht, kann sie jedoch darum bitten. “CHK”-Einträge mit einem Wert ungleich null sollten nicht auftreten und sollten den Entwicklern gemeldet werden, da sie auf falsche Annahmen im Code hindeuten können.
debug dev <command> [args]*
Ruft einen entwicklerspezifischen Befehl auf. Dies wird nur auf einer CLI-Verbindung im Expertenmodus unterstützt (siehe “expert-mode on”). Solche Befehle sind äußerst gefährlich und verzeihen keine Fehler; jede Fehlanwendung kann den Prozess zum Absturz bringen. Sie sind ausschließlich für Experten vorgesehen und dürfen keinesfalls verwendet werden, sofern keine entsprechende Anweisung vorliegt. Einige sind nur verfügbar, wenn HAProxy mit definiertem DEBUG_DEV gebaut wurde, da sie Auswirkungen auf die Sicherheit haben können. Alle diese Befehle erfordern admin-Berechtigungen. Sie sind bewusst nicht dokumentiert, um ihre Verwendung durch Personen zu vermeiden, die mit dem Quellcode nicht vertraut sind.
del acl <acl> [<key>|#<ref>]
Löscht alle Einträge der ACL <acl>, die dem Schlüssel <key> entsprechen. <acl> ist die von “show acl” zurückgegebene #<id> oder der zurückgegebene <name>. Wenn <ref> verwendet wird, löscht dieser Befehl nur die angegebene Referenz. Die Referenz lässt sich durch Auflisten des ACL-Inhalts ermitteln. Wenn die Referenz <acl> ein Name ist, der auch für eine Map verwendet wird, wird der Eintrag auch aus der Map gelöscht.
del backend <name>
Entfernt den Backend-Proxy mit dem Namen <name>.
Diese Operation ist nur für TCP- oder HTTP-Proxys möglich. Damit sie gelingt, muss zuvor die Veröffentlichung der Backend-Instanz aufgehoben worden sein. Außerdem müssen zuerst alle ihre Server entfernt werden (über den CLI-Befehl “del server”). Schließlich darf kein Stream mehr mit der Backend-Instanz verbunden sein.
Weitere Einschränkungen verhindern das Entfernen eines Backends. Ein Backend kann nicht entfernt werden, wenn Konfigurationselemente ausdrücklich darauf verweisen, etwa eine use_backend-Regel oder Sample-Ausdrücke. Manche Proxy-Optionen sind ebenfalls mit dem Löschen zur Laufzeit inkompatibel. Derzeit gilt dies, wenn das veraltete dispatch oder option transparent verwendet wird. Ein Backend kann auch nicht entfernt werden, wenn darin eine stick-table deklariert ist. Schließlich ist es derzeit unmöglich, ein Backend zu entfernen, in dem QUIC-Server vorhanden waren.
Es kann sinnvoll sein, vor diesem Befehl “wait be-removable” zu verwenden, um die genannten Voraussetzungen zu prüfen. Damit lässt sich auch auf das endgültige Schließen der Streams warten, die mit dem Ziel-Backend verbunden sind.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
del map <map> [<key>|#<ref>]
Löscht alle Einträge der Map <map>, die dem Schlüssel <key> entsprechen. <map> ist die von “show map” zurückgegebene #<id> oder der zurückgegebene <name>. Wenn <ref> verwendet wird, löscht dieser Befehl nur die angegebene Referenz. Die Referenz lässt sich durch Auflisten des Map-Inhalts ermitteln. Wenn die Referenz <map> ein Name ist, der auch für eine ACL verwendet wird, wird der Eintrag auch aus der Map gelöscht.
del ssl ca-file <cafile>
Löscht einen CA-Dateibaumeintrag aus HAProxy. Die CA-Datei muss unbenutzt und aus allen crt-lists entfernt sein. “show ssl ca-file” zeigt den Status der CA-Dateien an. Das Löschen funktioniert nicht bei einem Zertifikat, auf das in der Konfiguration direkt mit den Direktiven “ca-file” oder “ca-verify-file” verwiesen wird.
del ssl cert <certfile>
Löscht einen Zertifikatsspeicher aus HAProxy. Das Zertifikat muss unbenutzt sein (auch für die JWT-Validierung) und aus allen crt-lists oder Verzeichnissen entfernt sein. “show ssl cert” zeigt den Status des Zertifikats an. Das Löschen funktioniert nicht bei einem Zertifikat, auf das in der Konfiguration direkt mit der Direktive “crt” verwiesen wird.
del ssl crl-file <crlfile>
Löscht einen CRL-Dateibaumeintrag aus HAProxy. Die CRL-Datei muss unbenutzt und aus allen crt-lists entfernt sein. “show ssl crl-file” zeigt den Status der CRL-Dateien an. Das Löschen funktioniert nicht bei einem Zertifikat, auf das in der Konfiguration direkt mit der Direktive “crl-file” verwiesen wird.
del ssl crt-list <filename> <certfile[:line]>
Löscht einen Eintrag aus einer crt-list. Dabei werden alle in den Frontends für diesen Eintrag verwendeten SNIs gelöscht. Wird ein Zertifikat mehrmals in einer crt-list verwendet, muss angegeben werden, welche Zeile gelöscht werden soll. Die Zeilennummern werden mit “show ssl crt-list -n <crtlist>” angezeigt.
del ssl ech <bind>
Löscht die ECH-Schlüssel einer bind-Zeile.
Das Format der bind-Zeile ist <frontend>/@<filename>:<linenum> (Beispiel: frontend1/@haproxy.conf
:19) oder <frontend>/<name>, wenn die bind-Zeile mit dem Schlüsselwort “name” benannt wurde.
Erfordert eine OpenSSL-Version mit ECH-Unterstützung. HAProxy muss mit USE_ECH=1 kompiliert sein. Dieser Befehl wird nur auf einer CLI-Verbindung im experimentellen Modus unterstützt (siehe “experimental-mode on”).
Siehe auch “show ssl ech”, “add ssl ech” und “ech” in Abschnitt 5.1 des Konfigurationshandbuchs.
Beispiel:
del ssl jwt <filename>
Entfernt ein bereits geladenes Zertifikat aus der Liste der Zertifikate, die für die JWT-Validierung verwendet werden können (siehe Konverter “jwt_verify_cert”). Dieser Befehl funktioniert nicht bei laufenden Transaktionen. Siehe auch die Befehle “add ssl jwt” und “show ssl jwt”. Weitere Informationen stehen bei der Zertifikatsoption “jwt”.
del server <backend>/<server>
Löscht einen entfernbaren Server aus dem Backend <backend>. Ein Server ist entfernbar, wenn er alle folgenden Bedingungen erfüllt:
- Andere Konfigurationselemente verweisen nicht auf ihn
- Er muss bereits im Wartungsmodus sein (siehe “disable server”)
- Er darf keine aktiven oder inaktiven Verbindungen haben
Ist eine dieser Bedingungen nicht erfüllt, schlägt der Befehl fehl.
Aktive Verbindungen haben mindestens eine laufende Anfrage. Ihr Beenden lässt sich mit “shutdown sessions server” beschleunigen. Es wird dringend empfohlen, vor “del server” den Befehl “wait srv-removable” zu verwenden, um sicherzustellen, dass alle aktiven oder inaktiven Verbindungen geschlossen sind und der Befehl gelingt.
disable agent <backend>/<server>
Kennzeichnet die zusätzliche Agent-Prüfung als vorübergehend angehalten.
Wird aufgrund des Parameters agent-check einer server-Direktive eine Agent-Prüfung als zusätzliche Prüfung ausgeführt, werden neue Prüfungen nur initialisiert, wenn der Agent aktiviert ist. Daher verhindert disable agent das Starten neuer Agent-Prüfungen, bis der Agent mit enable agent wieder aktiviert wird.
Wenn ein Agent deaktiviert wird, werden zusätzliche Agent-Prüfungen, die noch bei aktiviertem Agenten gestartet wurden, wie folgt verarbeitet: Alle Ergebnisse, die das Gewicht ändern würden, insbesondere “drain” oder ein vom Agenten zurückgegebenes Gewicht, werden ignoriert. Ansonsten bleibt die Verarbeitung der Agent-Prüfung unverändert.
Diese Funktion soll die gewichtsändernde Wirkung der Agent-Prüfungen anhalten, damit das Gewicht eines Servers mit set weight eingestellt werden kann, ohne vom Agenten überschrieben zu werden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
disable dynamic-cookie backend <backend>
Deaktiviert die Erzeugung dynamischer Cookies für das Backend <backend>
disable frontend <frontend>
Kennzeichnet das Frontend als vorübergehend angehalten. Dies entspricht dem bei einem sanften Neustart verwendeten Modus: Das Frontend gibt den Port frei, kann bei Bedarf aber wieder aktiviert werden. Dies sollte mit Vorsicht verwendet werden, da einige Betriebssysteme außer Linux es nicht wieder aktivieren können. Diese Funktion ist für Umgebungen vorgesehen, in denen das Anhalten eines Proxys undenkbar ist, aber ein falsch konfigurierter Proxy korrigiert werden muss. So lässt sich der Port freigeben und von einem anderen Prozess binden, um den Betrieb wiederherzustellen. Das Frontend wird auf der Statistikseite mit dem Status “STOP” angezeigt.
Das Frontend kann entweder über seinen Namen oder über seine numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
disable health <backend>/<server>
Kennzeichnet den primären Health Check als vorübergehend angehalten. Dadurch werden keine Health Checks mehr gesendet, und das Ergebnis des letzten Health Checks wird ignoriert. Der Server befindet sich im ungeprüften Zustand und gilt als UP, sofern eine zusätzliche Agent-Prüfung ihn nicht auf DOWN setzt.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
disable server <backend>/<server>
Kennzeichnet den Server für Wartungsarbeiten als DOWN. In diesem Modus werden keine weiteren Prüfungen auf dem Server ausgeführt, bis er den Wartungsmodus verlässt. Wird der Server von anderen Servern verfolgt, werden auch diese während der Wartung auf DOWN gesetzt.
Auf der Statistikseite wird ein wegen Wartung auf DOWN gesetzter Server mit dem Status “MAINT” angezeigt; Server, die ihn verfolgen, erscheinen mit “MAINT(via)”.
Sowohl das Backend als auch der Server können entweder über ihren Namen oder über ihre numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
dump ssl cert <certfile>
Gibt ein in den HAProxy-Speicher geladenes Zertifikat aus. Die Ausgabe erfolgt im PEM-Format: zuerst der private Schlüssel, dann das Endzertifikat und schließlich die Zertifikatskette. Auch eine Transaktion kann ausgegeben werden, indem dem Dateinamen ein Sternchen vorangestellt wird. Dies ist nützlich, um Zertifikate im Dateisystem zu speichern, wenn sie über die CLI und nicht im Dateisystem aktualisiert wurden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
Beispiele:
dump stats-file
Erzeugt eine Statistikdatei (stats-file), mit der die HAProxy-Zählerwerte beim Start vorgeladen werden können. Weitere Einzelheiten stehen im Abschnitt „Statistikdatei“.
echo <text>
Gibt Text über die CLI aus. Dies kann nützlich sein, um Kommentare zwischen Befehlen auszugeben, wenn die Ergebnisse mehrerer Befehle ausgegeben werden.
Beispiel:
enable agent <backend>/<server>
Setzt eine vorübergehend angehaltene zusätzliche Agent-Prüfung fort.
Einzelheiten zu den Auswirkungen des vorübergehenden Startens und Anhaltens eines zusätzlichen Agenten stehen unter “disable agent”.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
enable dynamic-cookie backend <backend>
Aktiviert die Erzeugung dynamischer Cookies für das Backend <backend>. Außerdem muss ein geheimer Schlüssel bereitgestellt werden.
enable frontend <frontend>
Setzt ein vorübergehend angehaltenes Frontend fort. Einige der lauschenden Ports können möglicherweise nicht mehr gebunden werden (etwa wenn ein anderer Prozess sie seit der Operation ‘disable frontend’ belegt hat). In diesem Fall wird ein Fehler angezeigt. Manche Betriebssysteme können ein deaktiviertes Frontend möglicherweise nicht wieder aktivieren.
Das Frontend kann entweder über seinen Namen oder über seine numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
enable health <backend>/<server>
Setzt einen vorübergehend angehaltenen primären Health Check fort. Dadurch werden wieder Health Checks gesendet. Einzelheiten stehen unter “disable health”.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
enable server <backend>/<server>
Wenn der Server zuvor für Wartungsarbeiten als DOWN gekennzeichnet wurde, wird er als UP gekennzeichnet und die Prüfungen werden wieder aktiviert.
Sowohl das Backend als auch der Server können entweder über ihren Namen oder über ihre numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
experimental-mode [on|off]
Ohne Optionen zeigt dieser Befehl an, ob der experimentelle Modus für die aktuelle Verbindung aktiviert oder deaktiviert ist. Mit “on” wird der experimentelle Modus nur für die aktuelle CLI-Verbindung aktiviert, mit “off” deaktiviert.
Der experimentelle Modus ermöglicht den Zugriff auf zusätzliche Funktionen, die sich noch in Entwicklung befinden. Diese Funktionen sind derzeit nicht stabil und sollten mit Vorsicht verwendet werden. Zwischen Versionen können inkompatible Änderungen auftreten.
Bei Verwendung über die Master-CLI sollte dieser Befehl kein Präfix erhalten, da er den Modus für jeden Worker setzt, wenn eine Verbindung zu dessen CLI hergestellt wird.
Beispiel:
expert-mode [on|off]
Dieser Befehl ähnelt experimental-mode, schaltet jedoch den Expertenmodus um.
Der Expertenmodus zeigt Expertenbefehle an, die für den Prozess äußerst gefährlich sein können und Entwicklern gelegentlich helfen, wichtige Informationen über komplexe Fehler zu sammeln. Eine Fehlanwendung dieser Funktionen führt wahrscheinlich zu einem Prozessabsturz. Diese Option darf nur nach entsprechender Aufforderung verwendet werden. Dieser Befehl wird bewusst nicht in der Hilfemeldung aufgelistet. Er ist nur auf der Berechtigungsstufe admin zugänglich. Ein Wechsel auf eine andere Stufe setzt den Expertenmodus automatisch zurück.
Bei Verwendung über die Master-CLI sollte dieser Befehl kein Präfix erhalten, da er den Modus für jeden Worker setzt, wenn eine Verbindung zu dessen CLI hergestellt wird.
Beispiel:
get map <map> <value>
Sucht den Wert <value> in der Map <map> oder in der ACL <acl>. <map> oder <acl> stehen für die von “show map” oder “show acl” zurückgegebene #<id> oder den zurückgegebenen <name>. Dieser Befehl gibt alle übereinstimmenden Muster zurück, die dieser Map zugeordnet sind. Dies ist bei der Fehlerdiagnose von Maps und ACLs nützlich. Das Ausgabeformat besteht aus einer Zeile pro Abgleichstyp. Jede Zeile besteht aus einer Folge von Wörtern, die durch Leerzeichen getrennt sind.
Die ersten beiden Wörter sind:
Die folgenden Wörter werden nur zurückgegeben, wenn das Muster auf einen Eintrag zutrifft.
`<index type>`: "tree" oder "list". Der interne Suchalgorithmus.
`<case>`: "case-insensitive" oder "case-sensitive". Die
Berücksichtigung der Groß-/Kleinschreibung.
`<entry matched>`: match="`<entry>`". Gibt das übereinstimmende Muster zurück.
Dies ist bei regulären Ausdrücken nützlich.
Die letzten beiden Wörter zeigen den zurückgegebenen Wert und seinen Typ an. Im Fall “acl” existiert das Muster nicht.
return=nothing: Keine Rückgabe, da es keine "map" gibt.
return="`<value>`": Der als Zeichenfolge zurückgegebene Wert.
return=cannot-display: Der Wert kann nicht in eine Zeichenfolge umgewandelt werden.
type="`<type>`": Der Typ des zurückgegebenen Samples.
get var <name>
Zeigt Existenz, Typ und Inhalt der prozessweiten Variablen ’name’ an. Nur prozessweite Variablen sind lesbar, daher muss der Name mit ‘proc.’ beginnen; andernfalls wird keine Variable gefunden. Dieser Befehl erfordert die Berechtigungsstufe “operator” oder “admin”.
get weight <backend>/<server>
Meldet das aktuelle und das anfängliche Gewicht des Servers <server> im Backend <backend>, oder einen Fehler, wenn eines von beiden nicht existiert. Das anfängliche Gewicht ist das in der Konfigurationsdatei angegebene. Beide sind normalerweise gleich, sofern das aktuelle Gewicht nicht geändert wurde. Sowohl das Backend als auch der Server können entweder über ihren Namen oder über ihre numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
help [<command>]
Gibt die Liste bekannter Schlüsselwörter und ihrer grundlegenden Verwendung oder die zum angeforderten Befehl passenden Befehle aus. Dieselbe Hilfeanzeige erscheint auch bei unbekannten Befehlen.
httpclient [--htx] <method> <URI>
Startet eine HTTP-Client-Anfrage und gibt die Antwort über die CLI aus. Dies wird nur auf einer CLI-Verbindung im Expertenmodus unterstützt (siehe “expert-mode on”) und ist ausschließlich für die Fehlerdiagnose vorgesehen. Der httpclient kann einen Servernamen in der URL über den resolvers-Abschnitt “default” auflösen, der standardmäßig mit den DNS-Servern aus /etc/resolv.conf befüllt wird. Einen Host aus /etc/hosts kann er jedoch nicht auflösen, sofern kein lokaler dns-Daemon verwendet wird, der solche Namen auflösen kann.
Die Option –htx ermöglicht es, mit der Funktion htx_dump() die interne htx-Darstellung von HAProxy zu verwenden, die hauptsächlich der Fehlerdiagnose dient.
new ssl ca-file <cafile>
Erzeugt einen neuen leeren CA-Dateibaumeintrag, der mit einem Satz von CA-Zertifikaten befüllt und einer crt-list hinzugefügt werden soll. Dieser Befehl sollte in Kombination mit “set ssl ca-file”, “add ssl ca-file” und “add ssl crt-list” verwendet werden.
new ssl cert <filename>
Erzeugt einen neuen leeren SSL-Zertifikatsspeicher, der mit einem Zertifikat befüllt und einem Verzeichnis oder einer crt-list hinzugefügt werden soll. Dieser Befehl sollte in Kombination mit “set ssl cert” und “add ssl crt-list” verwendet werden.
new ssl crl-file <crlfile>
Erzeugt einen neuen leeren CRL-Dateibaumeintrag, der mit einem Satz von CRLs befüllt und einer crt-list hinzugefügt werden soll. Dieser Befehl sollte in Kombination mit “set ssl crl-file” und “add ssl crt-list” verwendet werden.
prepare acl <acl>
Weist in der ACL <acl> eine neue Versionsnummer für eine atomare Ersetzung zu. <acl> ist die von “show acl” zurückgegebene #<id> oder der zurückgegebene <name>. Die neue Versionsnummer wird in der Antwort nach “New version created:” angezeigt. Mit dieser Nummer lässt sich anschließend das Hinzufügen neuer ACL-Einträge vorbereiten, die nach ihrer Übernahme die aktuellen Einträge atomar ersetzen. Sie wird in “show acl” als “next_ver” gemeldet. Das Zuweisen neuer Versionen hat keine Auswirkungen, da ungenutzte Versionen automatisch entfernt werden, sobald eine neuere Version übernommen wird. Versionsnummern sind vorzeichenlose 32-Bit-Werte, die am Ende ihres Wertebereichs wieder am Anfang beginnen; beim Vergleich in einem externen Programm ist daher Vorsicht erforderlich. Dieser Befehl kann nicht verwendet werden, wenn die Referenz <acl> ein Name ist, der auch für eine Map verwendet wird. In diesem Fall muss stattdessen der Befehl “prepare map” verwendet werden.
prepare map <map>
Weist in der Map <map> eine neue Versionsnummer für eine atomare Ersetzung zu. <map> ist die von “show map” zurückgegebene #<id> oder der zurückgegebene <name>. Die neue Versionsnummer wird in der Antwort nach “New version created:” angezeigt. Mit dieser Nummer lässt sich anschließend das Hinzufügen neuer Map-Einträge vorbereiten, die nach ihrer Übernahme die aktuellen Einträge atomar ersetzen. Sie wird in “show map” als “next_ver” gemeldet. Das Zuweisen neuer Versionen hat keine Auswirkungen, da ungenutzte Versionen automatisch entfernt werden, sobald eine neuere Version übernommen wird. Versionsnummern sind vorzeichenlose 32-Bit-Werte, die am Ende ihres Wertebereichs wieder am Anfang beginnen; beim Vergleich in einem externen Programm ist daher Vorsicht erforderlich.
prompt [help | n | i | p | timed]*
Ändert das Verhalten des interaktiven Modus und die am Zeilenanfang angezeigte Eingabeaufforderung: - “help”: zeigt die Verwendung des Befehls an - “n”: wechselt in den nicht interaktiven Modus - “i”: wechselt in den interaktiven Modus - “p”: wechselt in den interaktiven Modus mit Eingabeaufforderung - “timed”: schaltet die Zeitanzeige in der Eingabeaufforderung um
Ohne Option wird zwischen dem Modus mit Eingabeaufforderung und dem nicht interaktiven Modus gewechselt. Im nicht interaktiven Modus wird die Verbindung geschlossen, sobald der letzte Befehl der aktuellen Zeile abgeschlossen ist. Im interaktiven Modus wird die Verbindung nach Abschluss eines Befehls nicht geschlossen, sodass ein weiterer eingegeben werden kann. Im Modus mit Eingabeaufforderung bleibt der interaktive Modus aktiv; am Zeilenanfang erscheint eine Eingabeaufforderung, die anzeigt, dass der Interpreter auf einen neuen Befehl wartet. Die Eingabeaufforderung besteht aus einer schließenden spitzen Klammer mit nachfolgendem Leerzeichen “> “.
Der Modus mit Eingabeaufforderung eignet sich eher für menschliche Benutzer, der interaktive Modus für fortgeschrittene Skripte und der nicht interaktive Modus (Standard) für einfache Skripte. Der nicht interaktive Modus ist für den Master-Socket nicht verfügbar.
publish backend <backend>
Aktiviert die Weiterleitung von Inhalten zu einer Backend-Instanz. Dies ist die Umkehrung des Befehls “unpublish backend”. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
quit
Schließt die Verbindung im interaktiven Modus.
set anon [on|off] [<key>]
Dieser Befehl aktiviert oder deaktiviert den „anonymisierten Modus“ für die aktuelle CLI-Sitzung. Dabei werden bestimmte als sensibel oder vertraulich eingestufte Felder in Befehlsausgaben durch Hashes ersetzt. Diese erhalten genügend Konsistenz zwischen den Elementen, damit Entwickler bei der Fehlersuche Beziehungen zwischen ihnen erkennen können. Zugleich ist ihre Bitzahl (24) niedrig genug, um sie wegen der großen Anzahl möglicher Treffer nicht umkehrbar zu machen. Wird der Modus ohne Angabe eines Schlüssels aktiviert, wird der globale Schlüssel verwendet (entweder in der Konfigurationsdatei mit “anonkey” angegeben oder über den CLI-Befehl “set anon global-key” gesetzt). Wurde kein solcher Schlüssel gesetzt, wird ein zufälliger erzeugt. Andernfalls kann der für die aktuelle Sitzung zu verwendende 32-Bit-Schlüssel angegeben werden, etwa um den Schlüssel einer früheren Ausgabe wiederzuverwenden und Ausgaben leichter zu vergleichen. Entwickler benötigen diesen Schlüssel nie. Es wird empfohlen, ihn niemals weiterzugeben, da er es ermöglichen könnte, Vermutungen darüber zu bestätigen oder zu widerlegen, was bestimmte Hashes verbergen.
set dynamic-cookie-key backend <backend> <value>
Ändert den geheimen Schlüssel, der zur Erzeugung dynamischer Cookies für die Sitzungsbindung verwendet wird. Dadurch werden bestehende Sitzungen unterbrochen.
set anon global-key <key>
Setzt den globalen Anonymisierungsschlüssel auf <key>. Dieser muss eine 32-Bit-Ganzzahl zwischen 0 und 4294967295 sein (0 deaktiviert den globalen Schlüssel). Dieser Befehl erfordert admin-Berechtigungen.
set map <map> [<key>|#<ref>] <value>
Ändert den Wert, der jedem Schlüssel <key> in einer Map <map> entspricht. <map> ist die von “show map” zurückgegebene #<id> oder der zurückgegebene <name>. Wird anstelle von <key> die Referenz <ref> verwendet, wird nur der Eintrag geändert, auf den <ref> verweist. Der neue Wert ist <value>.
set maxconn frontend <frontend> <value>
Ändert die maxconn-Einstellung des angegebenen Frontends dynamisch. Jeder positive Wert einschließlich null ist zulässig; Werte oberhalb des globalen maxconn sind jedoch wenig sinnvoll. Wird die Grenze erhöht und warten Verbindungen, werden sie sofort angenommen. Wird sie auf einen Wert unterhalb der aktuellen Verbindungszahl gesenkt, wird die Annahme neuer Verbindungen verzögert, bis der Schwellenwert erreicht ist. Das Frontend kann entweder über seinen Namen oder über seine numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
set maxconn server <backend/server> <value>
Ändert die maxconn-Einstellung des angegebenen Servers dynamisch. Jeder positive Wert einschließlich null ist zulässig; Werte oberhalb des globalen maxconn sind jedoch wenig sinnvoll.
set maxconn global <maxconn>
Ändert die globale maxconn-Einstellung dynamisch innerhalb des Bereichs, den die anfängliche globale maxconn-Einstellung vorgibt. Wird sie erhöht und warten Verbindungen, werden sie sofort angenommen. Wird sie auf einen Wert unterhalb der aktuellen Verbindungszahl gesenkt, wird die Annahme neuer Verbindungen verzögert, bis der Schwellenwert erreicht ist. Der Wert null stellt die anfängliche Einstellung wieder her.
set profiling memory { on | off }
Aktiviert oder deaktiviert CPU- oder Speicher-Profiling für das angegebene Teilsystem. Dies entspricht dem Setzen oder Löschen der “profiling”-Einstellungen im Abschnitt “global” der Konfigurationsdatei. Siehe auch “show profiling”. Wird das Aufgaben-Profiling manuell auf “on” gesetzt, werden die Scheduler-Statistiken automatisch zurückgesetzt. So lässt sich die Aktivität über ein bestimmtes Zeitintervall prüfen. Das Speicher-Profiling ist auf bestimmte Betriebssysteme beschränkt (funktioniert bekanntermaßen auf dem Ziel linux-glibc) und erfordert, dass USE_MEMORY_PROFILING beim Kompilieren gesetzt ist.
Beim Aufgaben-Profiling lässt sich das Erfassen der Sperr- und Speicherzeiten pro Aufgabe zur Laufzeit aktivieren oder deaktivieren. Die Änderung wird jedoch erst berücksichtigt, wenn das Profiling das nächste Mal von off/auto auf on wechselt (automatisch oder manuell). Wird mit “no-lock” das Sperr-Profiling pro Aufgabe deaktiviert, um CPU-Zyklen zu sparen, wird daher empfohlen, das Aufgaben-Profiling aus- und wieder einzuschalten, um die Änderung zu übernehmen.
set rate-limit connections global <value>
Ändert die prozessweite Begrenzung der Verbindungsrate, die durch die globale Einstellung ‘maxconnrate’ festgelegt wird. Der Wert null deaktiviert die Begrenzung. Diese Grenze gilt für alle Frontends, und die Änderung wirkt sofort. Der Wert wird als Anzahl der Verbindungen pro Sekunde angegeben.
set rate-limit http-compression global <value>
Ändert die maximale Eingangsrate der Komprimierung, die durch die globale Einstellung ‘maxcomprate’ festgelegt wird. Der Wert null deaktiviert die Begrenzung. Der Wert wird in Kilobytes pro Sekunde angegeben. In “show info” ist er in der Zeile “CompressBpsRateLim” in Bytes verfügbar.
set rate-limit sessions global <value>
Ändert die prozessweite Begrenzung der Sitzungsrate, die durch die globale Einstellung ‘maxsessrate’ festgelegt wird. Der Wert null deaktiviert die Begrenzung. Diese Grenze gilt für alle Frontends, und die Änderung wirkt sofort. Der Wert wird als Anzahl der Sitzungen pro Sekunde angegeben.
set rate-limit ssl-sessions global <value>
Ändert die prozessweite Begrenzung der SSL-Sitzungsrate, die durch die globale Einstellung ‘maxsslrate’ festgelegt wird. Der Wert null deaktiviert die Begrenzung. Diese Grenze gilt für alle Frontends, und die Änderung wirkt sofort. Der Wert wird als Anzahl der pro Sekunde an den SSL-Stack übergebenen Sitzungen angegeben. Die Begrenzung greift vor dem Handshake, um den Stack vor Handshake-Missbrauch zu schützen.
set server <backend>/<server> addr <ip4 or ip6 address> [port <port>]
Ersetzt die aktuelle IP-Adresse eines Servers durch die angegebene. Optional kann mit dem Parameter ‘port’ auch der Port geändert werden. Eine Portänderung unterstützt auch den Wechsel zur oder von der Portzuordnung (Schreibweise mit +X oder -Y), allerdings nur, wenn für den Health Check ein Port konfiguriert ist.
set server <backend>/<server> agent [ up | down ]
Erzwingt einen neuen Status für den Agenten eines Servers. Dies kann beispielsweise nützlich sein, um den Serverstatus sofort unabhängig von langsamen Agent-Prüfungen zu ändern. Die Änderung wird gegebenenfalls an Server weitergegeben, die diesen Server verfolgen.
set server <backend>/<server> agent-addr <addr> [port <port>]
Ändert die Adresse für Agent-Prüfungen eines Servers. Dadurch können Agent-Prüfungen zur Laufzeit auf eine andere Adresse umgestellt werden. Es können sowohl eine IP-Adresse als auch ein Hostname angegeben werden; letzterer wird aufgelöst. Optional kann auch der Agent-Port geändert werden.
set server <backend>/<server> agent-port <port>
Ändert den für Agent-Prüfungen verwendeten Port.
set server <backend>/<server> agent-send <value>
Ändert die Zeichenfolge, die an das Ziel der Agent-Prüfung gesendet wird. Damit kann die Zeichenfolge zusammen mit der Serveradresse aktualisiert werden, sodass beide weiterhin zusammenpassen.
set server <backend>/<server> health [ up | stopping | down ]
Erzwingt einen neuen Gesundheitsstatus für einen Server. Dies kann beispielsweise nützlich sein, um den Serverstatus sofort unabhängig von langsamen Health Checks zu ändern. Die Änderung wird gegebenenfalls an Server weitergegeben, die diesen Server verfolgen.
set server <backend>/<server> check-addr <ip4 | ip6> [port <port>]
Ändert die IP-Adresse für die Health Checks des Servers. Optional kann auch der für diese Health Checks verwendete Port geändert werden.
set server <backend>/<server> check-port <port>
Ändert den für Health Checks verwendeten Port auf <port>
set server <backend>/<server> state [ ready | drain | maint ]
Erzwingt einen neuen administrativen Status für einen Server. Dies kann nützlich sein, um die Lastverteilung und/oder jeglichen Datenverkehr zu einem Server zu deaktivieren. Der Status “ready” versetzt den Server in den normalen Modus; dies entspricht dem Befehl “enable server”. Der Status “maint” deaktiviert jeglichen Datenverkehr zum Server und sämtliche Health Checks; dies entspricht dem Befehl “disable server”. Der Modus “drain” nimmt den Server nur aus der Lastverteilung heraus, erlaubt aber weiterhin Prüfungen und neue Verbindungen mit Sitzungsbindung. Änderungen werden gegebenenfalls an Server weitergegeben, die diesen Server verfolgen.
set server <backend>/<server> weight <weight>[%]
Ändert das Gewicht eines Servers auf den als Argument angegebenen Wert. Dies entspricht genau dem weiter unten beschriebenen Befehl “set weight”.
set server <backend>/<server> fqdn <FQDN>
Ändert den FQDN eines Servers auf den als Argument angegebenen Wert. Dafür muss der zur Laufzeit verwendete interne DNS-Resolver für diesen Server konfiguriert und aktiviert sein.
set server <backend>/<server> ssl [ on | off ] (deprecated)
Diese Option konfiguriert die SSL-Verschlüsselung ausgehender Verbindungen zum Server. Wird sie ausgeschaltet, wird der gesamte Datenverkehr als Klartext übertragen; der Pfad der Health Checks bleibt unverändert.
Dieser Befehl ist veraltet. Stattdessen mit dem Befehl “add server” dynamisch einen neuen Server mit oder ohne SSL erzeugen.
set severity-output [ none | number | string ]
Ändert für die Dauer der aktuellen Sitzung das Format der Schweregradangabe in der Ausgabe des verbundenen Statistik-Sockets.
set ssl ca-file <cafile> <payload>
Dieser Befehl ist Teil eines Transaktionssystems; die Befehle “commit ssl ca-file” und “abort ssl ca-file” können erforderlich sein. Wenn keine Transaktion läuft, wird ein CA-Dateibaumeintrag erzeugt, in dem die in den Nutzdaten enthaltenen Zertifikate gespeichert werden. Der CA-Dateieintrag wird nicht im CA-Dateibaum gespeichert, sondern nur in einer temporären Transaktion gehalten. Existiert bereits eine Transaktion mit demselben Dateinamen, wird der bisherige CA-Dateieintrag gelöscht und durch den neuen ersetzt. Sobald die Änderungen abgeschlossen sind, muss die Transaktion mit “commit ssl ca-file” übernommen werden. Um mehrere Zertifikate einzeln hinzuzufügen, kann der Befehl “add ssl ca-file” verwendet werden.
Beispiel:
set ssl cert <filename> <payload>
Dieser Befehl ist Teil eines Transaktionssystems; die Befehle “commit ssl cert” und “abort ssl cert” können erforderlich sein. Das gesamte Transaktionssystem funktioniert mit jedem Zertifikat, das vom Befehl “show ssl cert” angezeigt wird, also mit jedem Frontend- oder Backend-Zertifikat. Wenn keine Transaktion läuft, wird das Zertifikat <filename> im Speicher in eine temporäre Transaktion dupliziert. Diese Transaktion wird anschließend mit der PEM-Datei aus den Nutzdaten aktualisiert. Existiert eine Transaktion mit demselben Dateinamen, wird sie aktualisiert. Auch mit einem Zertifikat verknüpfte Dateien (.issuer, .sctl, .ocsp usw.) können aktualisiert werden. Sobald die Änderungen abgeschlossen sind, muss die Transaktion mit “commit ssl cert” übernommen werden.
Dateien müssen über die CLI mit Vorsicht eingespielt werden, da eine Leerzeile das Ende der Nutzdaten signalisiert. Es wird empfohlen, eine bereinigte PEM-Datei einzuspielen. Eine einfache Methode ist, alle Leerzeilen zu entfernen und nur den Inhalt der PEM-Abschnitte beizubehalten. Dies lässt sich mit einem sed-Befehl erreichen.
Beispiel:
set ssl crl-file <crlfile> <payload>
Dieser Befehl ist Teil eines Transaktionssystems; die Befehle “commit ssl crl-file” und “abort ssl crl-file” können erforderlich sein. Wenn keine Transaktion läuft, wird ein CRL-Dateibaumeintrag erzeugt, in dem die in den Nutzdaten enthaltenen Sperrlisten gespeichert werden. Der CRL-Dateieintrag wird nicht im CRL-Dateibaum gespeichert, sondern nur in einer temporären Transaktion gehalten. Existiert bereits eine Transaktion mit demselben Dateinamen, wird der bisherige CRL-Dateieintrag gelöscht und durch den neuen ersetzt. Sobald die Änderungen abgeschlossen sind, muss die Transaktion mit “commit ssl crl-file” übernommen werden.
Beispiel:
set ssl ech <bind> <payload>
Ersetzt die ECH-Schlüssel einer bind-Zeile durch diesen Schlüssel. Die Nutzdaten müssen im PEM-for-ECH-Format vorliegen. (https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni )
Das Format der bind-Zeile ist <frontend>/@<filename>:<linenum> (Beispiel: frontend1/@haproxy.conf
:19) oder <frontend>/<name>, wenn die bind-Zeile mit dem Schlüsselwort “name” benannt wurde.
Erfordert eine OpenSSL-Version mit ECH-Unterstützung. HAProxy muss mit USE_ECH=1 kompiliert sein. Dieser Befehl wird nur auf einer CLI-Verbindung im experimentellen Modus unterstützt (siehe “experimental-mode on”).
Siehe auch “show ssl ech”, “add ssl ech” und “ech” in Abschnitt 5.1 des Konfigurationshandbuchs.
$ 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>
Dieser Befehl aktualisiert eine OCSP-Antwort für ein Zertifikat (siehe “crt” in “bind”-Zeilen). Dabei werden dieselben Prüfungen durchgeführt wie beim erstmaligen Laden der Antwort. <response> muss als base64-kodierte Zeichenfolge der DER-kodierten Antwort des OCSP-Servers übergeben werden. Dieser Befehl wird mit BoringSSL nicht unterstützt.
Beispiel:
set ssl tls-key <id> <tlskey>
Setzt den nächsten TLS-Schlüssel für den Listener <id> auf <tlskey>. Dieser Schlüssel wird zum letzten Schlüssel, während der vorletzte zur Verschlüsselung verwendet wird (die anderen dienen nur der Entschlüsselung). Der älteste vorhandene TLS-Schlüssel wird überschrieben. <id> ist entweder eine numerische #<id> oder der von “show tls-keys” zurückgegebene <file>. <tlskey> ist ein base64-kodierter TLS-Ticket-Schlüssel mit 48 oder 80 Bytes (z. B. openssl rand 80 | openssl base64 -A).
set table <table> key <key> [data.<data_type> <value>]*
Erzeugt oder aktualisiert einen Stick-Table-Eintrag in der Tabelle. Ist der Schlüssel nicht vorhanden, wird ein Eintrag eingefügt. Alle möglichen Werte für <data_type> stehen unter stick-table in Abschnitt 4.2. Die wahrscheinlich häufigste Verwendung ist das dynamische Eintragen von Quell-IP-Adressen mit einem Flag in gpc0, um eine IP-Adresse dynamisch zu sperren oder ihre Dienstqualität zu beeinflussen. In einem einzigen Aufruf können mehrere data_types übergeben werden.
Für einen bestehenden Eintrag kann optional statt der Suche über den Schlüssel eine Suche über ptr verwendet werden: <ptr> wird in der Form 0xffff geschrieben und muss der Adresse entsprechen, die ein zuvor ausgeführter “show table”-Befehl zurückgegeben hat. Das Identifizieren eines Eintrags über seinen Zeiger kann sinnvoll sein, wenn dies über den Schlüssel wegen eines leeren Schlüssels oder mit der CLI inkompatibler Zeichen nicht möglich ist.
Wenn data.<data_type> ein Array-Typ ist, kann mit “[]” auf einen bestimmten Index im Array zugegriffen werden, etwa so: data.gpt[1]
set timeout cli <delay>
Ändert die Zeitüberschreitung der CLI-Schnittstelle für die aktuelle Verbindung. Dies kann bei langen Diagnosesitzungen nützlich sein, in denen fortlaufend bestimmte Indikatoren geprüft werden müssen, ohne dass die Verbindung getrennt wird. Die Dauer wird in Sekunden angegeben.
set var <name> <expression>
Ermöglicht es, die prozessweite Variable ’name’ mit dem Ergebnis des Ausdrucks <expression> oder der Formatzeichenfolge <format> zu setzen oder zu überschreiben. Nur prozessweite Variablen können verwendet werden, daher muss der Name mit ‘proc.’ beginnen; andernfalls wird keine Variable gesetzt. <expression> und <format> dürfen nur „interne“ Sample-Abruf-Schlüsselwörter und Konverter enthalten. Am ehesten nützlich sind dabei str(‘something’), int(), einfache Zeichenfolgen oder Verweise auf andere Variablen. Der Befehlszeilenparser berücksichtigt keine Anführungszeichen, daher muss jedem Leerzeichen im Ausdruck ein umgekehrter Schrägstrich vorangestellt werden. Dieser Befehl erfordert die Berechtigungsstufe “operator” oder “admin”. Er wird nur auf einer CLI-Verbindung im experimentellen Modus unterstützt (siehe “experimental-mode on”).
set weight <backend>/<server> <weight>[%]
Ändert das Gewicht eines Servers auf den als Argument angegebenen Wert. Endet der Wert mit dem Zeichen ‘%’, ist das neue Gewicht relativ zum ursprünglich konfigurierten Gewicht. Absolute Gewichte zwischen 0 und 256 sind zulässig. Relative Gewichte müssen positiv sein; das resultierende absolute Gewicht wird begrenzt auf 256. Für Server einer Servergruppe mit statischem Lastverteilungsalgorithmus gelten strengere Einschränkungen, da das einmal gesetzte Gewicht nicht mehr geändert werden kann. Für diese Server sind daher nur die Werte 0 und 100% zulässig (oder 0 und das anfängliche Gewicht). Änderungen wirken sofort, manche LB-Algorithmen benötigen jedoch eine bestimmte Anzahl von Anfragen, um die Änderungen zu berücksichtigen. Typischerweise wird mit diesem Befehl ein Server während einer Aktualisierung deaktiviert, indem sein Gewicht auf null gesetzt wird. Nach der Aktualisierung wird er wieder aktiviert, indem das Gewicht auf 100% zurückgesetzt wird. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind. Sowohl das Backend als auch der Server können entweder über ihren Namen oder über ihre numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
show acl [[@<ver>] <acl>]
Gibt Informationen über ACL-Konverter aus. Ohne Argument wird die Liste aller verfügbaren ACLs zurückgegeben. Wird eine <acl> angegeben, wird ihr Inhalt ausgegeben. <acl> ist die #<id> oder der <name>. Standardmäßig wird die aktuelle Version der ACL angezeigt (die Version, gegen die derzeit geprüft wird und die in der ACL-Liste als ‘curr_ver’ gemeldet wird). Andere Versionen können ausgegeben werden, indem ‘@<ver>’ vor den ACL-Bezeichner gesetzt wird. Die Version wirkt als Filter; nicht vorhandene Versionen liefern einfach kein Ergebnis. Das Ausgabeformat ist dasselbe wie bei Maps, auch für die Sample-Werte. Die zurückgegebenen Daten sind keine Liste verfügbarer ACLs, sondern eine Liste aller Muster, aus denen ACLs bestehen. Viele dieser Muster können auch von Maps verwendet werden. Der Wert ’entry_cnt’ zählt alle ACL-Einträge, nicht nur die aktiven. Er enthält daher auch Einträge, die gerade hinzugefügt werden.
show anon
Zeigt den aktuellen Zustand des anonymisierten Modus (aktiviert oder deaktiviert) und den Schlüssel der aktuellen Sitzung an.
show backend
Gibt die Liste der im laufenden Prozess verfügbaren Backends aus
show cli level
Zeigt die CLI-Berechtigungsstufe der aktuellen CLI-Sitzung an. Das Ergebnis kann ‘admin’, ‘operator’ oder ‘user’ sein. Siehe auch die Befehle ‘operator’ und ‘user’.
Beispiel:
operator
Senkt die CLI-Berechtigungsstufe der aktuellen CLI-Sitzung auf operator. Sie kann nicht erhöht werden. Außerdem werden Expertenmodus und experimenteller Modus deaktiviert. Siehe auch “show cli level”.
unpublish backend <backend>
Schließt das Backend von der Auswahl für künftigen Datenverkehr aus. Dadurch werden use_backend- / default_backend-Regeln, die darauf verweisen, ignoriert und die nächsten Regeln zur inhaltsabhängigen Weiterleitung ausgewertet. Anders als bei deaktivierten Backends bleiben die Health Checks der Server aktiv. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
user
Senkt die CLI-Berechtigungsstufe der aktuellen CLI-Sitzung auf user. Sie kann nicht erhöht werden. Außerdem werden Expertenmodus und experimenteller Modus deaktiviert. Siehe auch “show cli level”.
show activity [-1 | 0 | thread_num]
Meldet einige Zähler zu internen Ereignissen, die Entwicklern und allgemein Personen mit ausreichender HAProxy-Kenntnis helfen, die Ursachen gemeldeten ungewöhnlichen Verhaltens einzugrenzen. Ein typisches Beispiel wäre ein korrekt laufender Prozess, der nie schläft und 100% der CPU beansprucht. Die Ausgabe enthält eine Zeile pro Metrik mit den Zählern der einzelnen Threads in derselben Zeile. Diese Zähler haben 32 Bit und laufen während der Prozesslebensdauer über, was kein Problem ist, da dieser Befehl normalerweise zweimal aufgerufen wird. Die Felder sind bewusst nicht dokumentiert, damit ihre genaue Bedeutung im Code geprüft wird, der die Zähler aktualisiert. Diese Werte werden auch durch den Befehl “clear counters” zurückgesetzt. Bei Bereitstellungen mit mehreren Threads gibt die erste Spalte die Summe aller Threads an (oder je nach Art der Metrik den Durchschnitt). Die Werte aller Threads folgen in Thread-Reihenfolge in eckigen Klammern. Optional kann die Nummer des auszugebenden Threads als Argument angegeben werden. Der Sonderwert “0” meldet den aggregierten Wert (erste Spalte); “-1”, der Standardwert, zeigt alle Spalten an. Wie im Modus mit einem einzelnen Thread werden keine Klammern ausgegeben, wenn nur eine Spalte angefordert wird.
show cli sockets
Listet CLI-Sockets auf. Das Ausgabeformat besteht aus 3 durch Leerzeichen getrennten Feldern. Das erste Feld ist die Socket-Adresse: ein Unix-Socket, ein Paar aus ipv4-Adresse und Port oder ein entsprechendes ipv6-Paar. Sockets anderer Typen werden nicht ausgegeben. Das zweite Feld beschreibt die Berechtigungsstufe des Sockets: ‘admin’, ‘user’ oder ‘operator’. Das letzte Feld listet die Prozesse, an die der Socket gebunden ist, durch Kommas getrennt auf; es kann Nummern oder ‘all’ enthalten.
Beispiel:
show cache
Listet die konfigurierten Caches und die in jedem Cache-Baum gespeicherten Objekte auf.
$ echo ‘show cache’ | socat stdio /tmp/sock1 0x7f6ac6c5b03a: foobar (shctx:0x7f6ac6c5b000, available blocks:3918) 1 2 3 4
- Zeiger auf die Cache-Struktur
- Cache-Name
- Zeiger auf den mmap-Bereich (shctx)
- Anzahl der im shctx zur Wiederverwendung verfügbaren Blöcke
0x7f6ac6c5b4cc hash:286881868 vary:0x0011223344556677 size:39114 (39 blocks), refcount:9, expire:237 1 2 3 4 5 6 7
- Zeiger auf den Cache-Eintrag
- Die ersten 32 Bit des Hashes
- Sekundärer Hash des Eintrags bei vary
- Größe des Objekts in Bytes
- Anzahl der für das Objekt verwendeten Blöcke
- Anzahl der Transaktionen, die den Eintrag verwenden
- Ablaufzeit; kann negativ sein, wenn der Eintrag bereits abgelaufen ist
show dev
Dieser Befehl bündelt Informationen, die HAProxy-Entwickler benötigen könnten, um die Ursachen eines bestimmten Problems besser zu verstehen. Für den Benutzer sind sie im Allgemeinen nicht nützlich, ermöglichen Entwicklern aber das Ausschließen bestimmter Hypothesen. Das Format besteht ungefähr aus einer Reihe von Abschnitten mit eingerückten Zeilen und jeweils einem Element pro Zeile, etwa Betriebssystemtyp und -version, CPU-Typ oder FD-Grenzen beim Start. Manche Felder werden weggelassen, um Wiederholungen oder unnötige Ausgaben zu vermeiden, wenn sie keinen Mehrwert liefern (z. B. unbegrenzte Werte). Künftig können weitere Felder hinzukommen oder sich einige ändern. Diese Ausgabe ist nicht zur Auswertung durch Skripte gedacht und sollte nicht als besonders zuverlässig angesehen werden. Sie soll im Wesentlichen denen Zeit sparen, die sie lesen können.
Technisch werden diese Informationen unverändert aus einer internen Struktur entnommen, die sie beim Start zusammen speichert, damit sie auch nach einem Absturz in einer Core-Datei zu finden sind. Daher können Entwickler um eine frühzeitige Ausgabe eines normal arbeitenden Prozesses bitten, um sie mit einem Core-Dump oder zwischen mehreren Neuladevorgängen zu vergleichen (beispielsweise können sich manche Grenzwerte ändern). Ist die Anonymisierung aktiviert, werden auch alle möglicherweise sensiblen Werte anonymisiert (z. B. der Knotenname).
Beispielausgabe:
show env [<name>]
Gibt eine oder alle dem Prozess bekannten Umgebungsvariablen aus. Ohne Argument werden alle Variablen ausgegeben. Mit einem Argument wird nur die angegebene Variable ausgegeben, sofern sie existiert. Andernfalls erscheint “Variable not found”. Die Variablen werden in demselben Format ausgegeben, in dem sie gespeichert oder vom Dienstprogramm “env” zurückgegeben werden, also “<name>=<value>”. Dies kann bei der Fehlerdiagnose von Konfigurationsdateien mit vielen Umgebungsvariablen hilfreich sein, um sicherzustellen, dass diese die erwarteten Werte enthalten. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
show errors [<iid>|<proxy>] [request|response]
Gibt die zuletzt bekannten, von Frontends und Backends erfassten HTTP/1.x-Anfrage- und Antwortfehler aus. Wird <iid> angegeben, beschränkt sich die Ausgabe auf Fehler des Frontends oder Backends mit der ID <iid>. Die Proxy-ID “-1” bewirkt die Ausgabe aller Instanzen. Wird stattdessen ein Proxy-Name angegeben, wird dessen ID als Filter verwendet. Wird nach dem Proxy-Namen oder der ID “request” oder “response” hinzugefügt, werden nur Anfrage- oder Antwortfehler ausgegeben. Dieser Befehl ist eingeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
Erfasst werden können die letzten Anfrage- und Antwortfehler durch Protokollverletzungen, häufig aufgrund ungültiger Zeichen in Header-Namen. Der Bericht gibt genau an, welches Zeichen das Protokoll verletzt hat. Weitere wichtige Informationen werden ebenfalls gemeldet: der genaue Zeitpunkt der Fehlererkennung, die Namen von Frontend und Backend, der Servername (falls bekannt), die interne Transaktions-ID und die Quelladresse, von der die Sitzung gestartet wurde.
Alle Zeichen werden zurückgegeben; nicht druckbare Zeichen werden kodiert. Die häufigsten (\t = 9, \n = 10, \r = 13 und \e = 27) werden als ein Buchstabe nach einem umgekehrten Schrägstrich kodiert. Der umgekehrte Schrägstrich selbst wird als ‘\\’ kodiert, um Verwechslungen zu vermeiden. Andere nicht druckbare Zeichen werden als ‘\xNN’ kodiert, wobei NN die zweistellige hexadezimale Darstellung des ASCII-Codes des Zeichens ist.
Den Zeilen wird die Position ihres ersten Zeichens vorangestellt, beginnend bei 0 für den Pufferanfang. Pro Ausgabezeile wird höchstens eine Eingabezeile ausgegeben. Lange Zeilen werden auf mehrere aufeinanderfolgende Ausgabezeilen verteilt, sodass die Ausgabe nie breiter als 79 Zeichen ist. Ein solcher Zeilenumbruch ist leicht zu erkennen: Die Zeile endet nicht mit ‘\n’, und auf den Offset der nächsten Zeile folgt ein ‘+’-Zeichen, das die Fortsetzung der vorherigen Zeile kennzeichnet.
Beispiel:
show events [<sink>] [-w] [-n] [-0] [-s]
Ohne Option werden alle bekannten Ereignissenken und ihre Typen aufgelistet. Mit einer Option werden alle verfügbaren Ereignisse der angegebenen Senke ausgegeben, sofern sie vom Typ buffer ist. Wird nach dem Namen der Senke die Option “-w” übergeben, wartet der Befehl nach Erreichen des Pufferendes auf neue Ereignisse und zeigt sie an. Die Operation kann durch eine beliebige Eingabe (die verworfen wird) oder durch Schließen der Sitzung beendet werden. Die Option “-n” springt direkt an das Pufferende. Dies ist oft in Kombination mit “-w” nützlich, um nur neue Ereignisse zu melden. Der Einfachheit halber können mit “-wn” oder “-nw” beide Optionen gleichzeitig aktiviert werden. Standardmäßig werden alle Ereignisse durch ein Zeilenvorschubzeichen (’\n’ oder 10 oder 0x0A) getrennt. Mit dem Argument “-0” kann stattdessen das NUL-Zeichen (’\0’ oder 0) verwendet werden. Die Option “-s” bereinigt die Ausgabe, damit Binärinhalte aus erfassten oder dekodierten Daten die Darstellung im Terminal nicht verändern. Leerraumzeichen (Leerzeichen und Tabulator) werden durch ein Leerzeichen ersetzt, sodass jeder Datensatz auf einer Zeile bleibt. Andere Steuerzeichen (0x00 bis 0x1F und 0x7F) sowie Nicht-ASCII-Zeichen (0x80 und darüber) werden durch ein ‘?’ ersetzt. Die Ausgabelänge bleibt erhalten. So können beim Ausgeben eines Rings weder ANSI-Escape-Sequenzen noch Codes für die Schreibrichtung in das Terminal des Operators eingeschleust werden. Dies ist nützlich beim Ausgeben in ein Terminal oder an ein Programm, dessen Eingabe nicht als Sonderzeichen interpretiert werden darf, etwa Überwachungsskripte, deren Ausgabe unverändert in Berichte übernommen wird.
show fd [-!plcfbsd]* [[<tgid>]/[<fd>] | <fd>]
Gibt entweder die Liste aller offenen Dateideskriptoren oder nur den Dateideskriptor mit der Nummer <fd> aus, wenn diese angegeben ist. Auch die Form “<tgid>/<fd>” ist zulässig. Dabei kann jede Seite als Platzhalter leer bleiben (”/<fd>” für fd <fd> über alle Thread-Gruppen hinweg, “<tgid>/” für alle fds von <tgid>). <tgid> wird derzeit eingelesen, aber ignoriert, bis künftig fd-Tabellen pro Thread-Gruppe unterstützt werden. Optional kann ein Satz von Flags übergeben werden, um die Ausgabe auf bestimmte FD-Typen zu beschränken oder bestimmte FD-Typen auszuschließen. Bei ‘-’ oder ‘!’ wird die Auswahl für die folgenden Zeichen desselben Arguments umgekehrt. Vor jedem durch Leerraum getrennten Argumentwort wird diese Umkehrung zurückgesetzt. Wählbare FD-Typen sind ‘p’ für Pipes, ’l’ für Listener, ‘c’ für Verbindungen (jeden Typs), ‘f’ für Frontend-Verbindungen, ‘b’ für Backend-Verbindungen (jeden Typs), ’s’ für Verbindungen zu Servern und ’d’ für Verbindungen zur “dispatch”-Adresse oder zur transparenten Adresse des Backends. Dabei ist ‘b’ eine Kurzform für ‘sd’ und ‘c’ für ‘fb’ oder ‘fsd’. ‘c!f’ entspricht ‘b’ (alle Verbindungen außer Frontend-Verbindungen sind tatsächlich Backend-Verbindungen). Dies richtet sich ausschließlich an Entwickler, die interne Zustände beobachten müssen, um komplexe Probleme wie ungewöhnliche CPU-Auslastung zu untersuchen. Pro Zeile wird ein fd gemeldet. Sein Zustand im Poller wird mit Großbuchstaben für aktivierte und Kleinbuchstaben für deaktivierte Flags ausgegeben: “P” für „abgefragt“, “R” für „bereit“ und “A” für „aktiv“. Der Ereignisstatus verwendet “H” für „Verbindungsende“, “E” für „Fehler“, “O” für „Ausgabe“, “P” für „Priorität“ und “I” für „Eingabe“. Weitere Flags sind etwa “N” für „neu“ (gerade dem fd-Cache hinzugefügt), “U” für „aktualisiert“ (eine Aktualisierung im fd-Cache erhalten), “L” für “linger_risk” und “C” für „geklont“. Anschließend folgen die Position des Cache-Eintrags, der Zeiger auf den internen Eigentümer sowie der Zeiger auf den I/O-Callback und dessen Name, falls bekannt. Ist der Eigentümer eine Verbindung, werden die Verbindungsflags und das Ziel gemeldet (Frontend, Proxy oder Server). Ist der Eigentümer ein Listener, werden dessen Zustand und Frontend gemeldet. Ohne gute Kenntnis der Interna ist die Verwendung dieses Befehls nicht sinnvoll. Das Ausgabeformat kann sich im Laufe der Zeit weiterentwickeln, daher darf diese Ausgabe nicht von Werkzeugen ausgewertet werden, die dauerhaft funktionieren sollen. Manche internen Strukturzustände können der auflistenden Funktion verdächtig erscheinen; in diesem Fall wird der Ausgabezeile ein Ausrufezeichen (’!’) angehängt. Dies kann bei der Diagnose eines Vorfalls einen Ausgangspunkt liefern.
show info [typed|json] [desc] [float]
Gibt Informationen über den HAProxy-Status im aktuellen Prozess aus. Wird “typed” als optionales Argument übergeben, werden auch Feldnummern, -namen und -typen ausgegeben. So können externe Überwachungsprodukte Informationen aus ihnen unbekannten Feldern leicht abrufen, gegebenenfalls aggregieren und anschließend melden. Jedes Feld wird in einer eigenen Zeile ausgegeben. Wird “json” als optionales Argument übergeben, werden die Informationen der “typed”-Ausgabe im JSON-Format als Liste von JSON-Objekten bereitgestellt. Standardmäßig enthält das Format nur zwei durch einen Doppelpunkt (’:’) getrennte Spalten: links den Feldnamen, rechts den Wert. Im typisierten Ausgabeformat ist die Ausgabe eines einzelnen Objekts zusammenhängend, sodass der Empfänger nicht alles auf einmal speichern muss. Dies ist besonders zu beachten. Wird “float” als optionales Argument übergeben, können einige normalerweise als Ganzzahlen ausgegebene Felder für höhere Genauigkeit als Gleitkommazahlen ausgegeben werden. Welche Felder betroffen sind, ist bewusst nicht festgelegt, da sich dies im Laufe der Zeit ändern kann. Die Verwendung dieser Option setzt voraus, dass der Empfänger Gleitkommazahlen verarbeiten kann. Das verwendete Ausgabeformat ist sprintf("%f”).
Beim typisierten Ausgabeformat besteht jede Zeile aus 4 durch Doppelpunkte (’:’) getrennten Spalten. Die erste Spalte enthält eine durch Punkte getrennte Folge von 3 Elementen. Das erste Element ist die numerische Position des Felds in der Liste (beginnend bei null). Diese Position darf sich im Laufe der Zeit nicht ändern. Je nach Build-Optionen oder wenn künftig Felder gelöscht werden, sind jedoch Lücken zu erwarten. Das zweite Element ist der Feldname, wie er in der Standardausgabe von “show info” erscheint. Das dritte Element ist die relative Prozessnummer, beginnend bei 1.
Der Rest der Zeile nach dem ersten Doppelpunkt folgt dem weiter oben beschriebenen „typisierten Ausgabeformat“. Die zweite Spalte (nach dem ersten ‘:’) gibt Herkunft, Art und Geltungsbereich der Variablen an. Die dritte Spalte enthält den Feldtyp, einen der Werte “s32”, “s64”, “u32”, “u64” und “str”. Die vierte Spalte enthält den Wert selbst, den der Empfänger anhand von Spalte 3 einlesen und anhand von Spalte 2 verarbeiten kann.
Damit lautet das gesamte Zeilenformat im typisierten Modus:
Wird “desc” an den Befehl angehängt, folgen ein weiterer Doppelpunkt und eine Zeichenfolge in Anführungszeichen mit einer Beschreibung der Metrik. Zum Zeitpunkt der Erstellung wird dies nur für das Ausgabeformat “typed” und das Standardformat unterstützt.
Beispiel:
Im typisierten Format erleichtert die Prozess-ID am Ende der ersten Spalte das visuelle Zusammenführen der Ausgaben mehrerer Prozesse. Beispiel:
Das Format der JSON-Ausgabe ist in einem Schema beschrieben, das mit “show schema json” ausgegeben werden kann.
Die JSON-Ausgabe enthält keinen zusätzlichen Leerraum, um den Umfang der Ausgabe zu verringern. Für die menschliche Lesbarkeit kann es hilfreich sein, die Ausgabe durch ein Formatierungsprogramm zu leiten. Beispiel:
$ echo “show info json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
Die JSON-Ausgabe enthält keinen zusätzlichen Leerraum, um den Umfang der Ausgabe zu verringern. Für die menschliche Lesbarkeit kann es hilfreich sein, die Ausgabe durch ein Formatierungsprogramm zu leiten. Beispiel:
$ echo “show info json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
show libs
Gibt auf Systemen, die dies unterstützen, die Liste geladener gemeinsam genutzter dynamischer Bibliotheken und Objektdateien aus. Soweit verfügbar, werden für jedes gemeinsam genutzte Objekt der Bereich virtueller Adressen, die Größe und der Pfad zum Objekt angegeben. So lässt sich beispielsweise abschätzen, welche Bibliothek eine in einer Ausgabe erscheinende Funktion bereitstellt. Auf vielen Systemen ändern sich die Adressen bei jedem Neustart (Adressraumrandomisierung). Diese Liste müsste daher beim Start abgerufen werden, wenn sie zur Analyse einer Core-Datei verwendet werden soll. Dieser Befehl kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind. Das Ausgabeformat kann zwischen Betriebssystemen, Architekturen und sogar HAProxy-Versionen variieren; Skripte sollten sich nicht darauf verlassen.
show map [[@<ver>] <map>]
Gibt Informationen über Map-Konverter aus. Ohne Argument wird die Liste aller verfügbaren Maps zurückgegeben. Wird eine <map> angegeben, wird ihr Inhalt ausgegeben. <map> ist die #<id> oder der <name>. Standardmäßig wird die aktuelle Version der Map angezeigt (die Version, gegen die derzeit geprüft wird und die in der Map-Liste als ‘curr_ver’ gemeldet wird). Andere Versionen können ausgegeben werden, indem ‘@<ver>’ vor den Map-Bezeichner gesetzt wird. Die Version wirkt als Filter; nicht vorhandene Versionen liefern einfach kein Ergebnis. Der Wert ’entry_cnt’ zählt alle Map-Einträge, nicht nur die aktiven. Er enthält daher auch Einträge, die gerade hinzugefügt werden.
In der Ausgabe ist die erste Spalte eine eindeutige Eintragskennung, die als Referenz für die Operationen “del map” und “set map” verwendet werden kann. Die zweite Spalte ist das Muster, die dritte das Sample, sofern verfügbar. Die zurückgegebenen Daten sind keine unmittelbare Liste verfügbarer Maps, sondern eine Liste aller Muster, aus denen Maps bestehen. Viele dieser Muster können auch von ACLs verwendet werden.
show peers [dict|-] [<peers section>]
Gibt Informationen über die in “peers”-Abschnitten konfigurierten Peers aus. Ohne Argument werden die Peers aus allen “peers”-Abschnitten aufgelistet. Wird <peers section> angegeben, werden nur Informationen über die Peers dieses “peers”-Abschnitts ausgegeben. Wird vor dem Namen des peers-Abschnitts “dict” angegeben, werden auch die vollständigen Tx/Rx-Wörterbuch-Caches ausgegeben (sehr umfangreich). Um einen peers-Abschnitt namens “dict” auszugeben, muss möglicherweise “-” übergeben werden.
Hier folgen zwei Beispielausgaben, in denen die Peers hostA, hostB und hostC zu “sharedlb”-peers-Abschnitten gehören. Nur hostA und hostB sind verbunden. Nur hostA hat Daten an hostB gesendet.
$ 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
state=0 flags=0x3 \ resync_timeout=<PAST> task_calls=3 0x55871b5b2540:
id=hostC(remote) addr=127.0.0.12:10002 status=CONN \ reconnect=3s
confirm=0 flags=0x0 0x55871b5b1440: id=hostB(local) addr=127.0.0.11:10001 status=NONE
\ reconnect=<NEVER> confirm=0 flags=0x0 0x55871b5aed70: id=hostA(remote)
addr=127.0.0.10:10000 status=ESTA \ reconnect=2s confirm=0
flags=0x20000200 appctx:0x7fa46800ee00 st0=7 st1=0 task_calls=62356 \
state=EST remote_table:0x55871b5ab960 id=stkt local_id=1 remote_id=1 last_local_table:0x55871b5ab960
id=stkt local_id=1 remote_id=1 shared tables:
show pools [byname|bysize|byusage] [detailed] [match <pfx>] [<nb>]
Den Status der internen Speicherpools ausgeben. Dies ist beispielsweise hilfreich, um bei Verdacht auf ein Speicherleck die Speichernutzung zu verfolgen. Der Befehl bewirkt genau dasselbe wie SIGQUIT im Vordergrundbetrieb, leert jedoch die Pools nicht. Standardmäßig wird die Ausgabe nicht sortiert. Bei Angabe von “byname” wird nach Poolnamen sortiert; bei “bysize” nach der Größe der Elemente in absteigender Reihenfolge; bei “byusage” nach der Gesamtnutzung in absteigender Reihenfolge, wobei nur verwendete Einträge angezeigt werden. Die Ausgabe kann auch auf die ersten <nb> Einträge beschränkt werden (beispielsweise beim Sortieren nach Nutzung). Mit “detailed” lassen sich weitere interne Details ausgeben, einschließlich der Liste aller zusammengeführten Pools. Wird schließlich “match” mit einem nachfolgenden Präfix angegeben, werden nur Pools angezeigt, deren Name mit diesem Präfix beginnt. Die angegebene Gesamtsumme bezieht sich nur auf Pools, die den Filterkriterien entsprechen. Beispiel:
show profiling [{all | status | tasks | memory}] [byaddr|bytime|byctx|aggr|<max_lines>]*
Die aktuellen Profiling-Einstellungen zeilenweise sowie den zu ihrer Änderung erforderlichen Befehl ausgeben. Wenn das Task-Profiling aktiviert ist, werden auch einige vom Scheduler erfasste Statistiken je Funktion ausgegeben, zusammen mit einer Zusammenfassung der Anzahl der Aufrufe, der gesamten und durchschnittlichen CPU-Zeit sowie der gesamten und durchschnittlichen Latenz. Wenn das Speicher-Profiling aktiviert ist, werden beispielsweise die Anzahl der Speicherzuweisungen und -freigaben sowie ihre Größen gemeldet. Mit den entsprechenden Schlüsselwörtern kann die Ausgabe auf den Profiling-Status, die Tasks oder das Speicher-Profiling beschränkt werden; standardmäßig werden sämtliche Profiling-Informationen ausgegeben. Mit einem numerischen Grenzwert lässt sich auch die Anzahl der Ausgabezeilen je Kategorie beschränken. Die Ausgabe kann nach Adresse, gesamter Ausführungszeit oder Aufrufkontext statt nach Nutzung sortiert werden, etwa um aufeinanderfolgende Aufrufe leichter zu vergleichen oder Optimierungsbedarf zu ermitteln. Außerdem lässt sich die Task-Aktivität nach aufgerufener Funktion zusammenfassen, statt die Details anzuzeigen. Profiling richtet sich hauptsächlich an Entwickler, da es Hinweise darauf liefert, wo der Code CPU-Zyklen oder Speicher verschwendet. Für die Überwachung liefert diese Ausgabe keine nützlichen Informationen.
show resolvers [<resolvers section id>]
Statistiken für den angegebenen resolvers-Abschnitt ausgeben, oder für alle resolvers-Abschnitte, wenn kein Abschnitt angegeben wird.
Für jeden Nameserver werden die folgenden Zähler ausgegeben:
show quic [<format>] [<filter>]
Informationen zu allen aktiven QUIC-Frontend-Verbindungen ausgeben. Dieser Befehl ist zugriffsbeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind.
Ein optionales Argument steuert den Detailgrad der Ausgabe. Sein Wert lässt sich auf verschiedene Weise interpretieren. Als erste Möglichkeit können vordefinierte Werte verwendet werden: “oneline” für das Standardformat, “stream” für die Auflistung aller aktiven Streams und “full” für die Anzeige sämtlicher Informationen. Alternativ kann eine kommagetrennte Liste von Feldern angegeben werden, um die Ausgabe zu beschränken. Derzeit werden die Werte “tp”, “sock”, “pktns”, “cc” und “mux” unterstützt. Schließlich zeigt “help” im Formatargument stattdessen eine ausführlichere Hilfe an.
Das letzte Argument beschränkt oder erweitert die Verbindungsliste. Standardmäßig werden nur aktive Frontend-Verbindungen angezeigt. Mit dem zusätzlichen Argument “clo” werden stattdessen Frontend-Verbindungen angezeigt, die gerade geschlossen werden, mit “be” Backend-Verbindungen und mit “all” alle Kategorien. Durch Angabe der hexadezimalen Adresse kann die Ausgabe auch auf eine einzelne Verbindung beschränkt werden.
show servers conn [<backend>]
Den Zustand der aktuellen und ungenutzten Verbindungen der Server ausgeben, die zum angegebenen Backend gehören (oder zu allen Backends, wenn keines angegeben wird). Es kann ein Backendname oder eine Kennung verwendet werden.
Die Ausgabe besteht aus einer Kopfzeile mit den Feldbezeichnungen und anschließend einer Zeile je Server mit Backendname und -ID, Servername und -ID, Adresse, Port sowie einer Reihe von Werten. Die Anzahl der Felder hängt von der Anzahl der Threads ab. Das genaue Ausgabeformat kann sich je nach Version und Threadanzahl geringfügig unterscheiden. Beim Extrahieren von Ausgabewerten muss die Kopfzeile beachtet werden, um die Spalten zuzuordnen. Auch die Threadanzahl ist zu berücksichtigen, da die letzten Spalten Werte je Thread enthalten:
HAProxy beendet alle <purge_delay> einen Teil von <idle_cur>, wenn die Summe aus <idle_cur> und <used_cur> den Schätzwert <need_est> überschreitet. Dieser Schätzwert ändert sich abhängig von der Verbindungsaktivität.
Da ungenutzte Verbindungen auf mehrere Threads verteilt sind, können sich einige Werte bereits nach dem Lesen ändern. Daher ist die Konsistenz innerhalb einer Zeile nicht gewährleistet. Diese Ausgabe dient hauptsächlich der Fehlersuche und eignet sich weder für die regelmäßige Überwachung noch für die grafische Darstellung.
show servers state [<backend>]
Den Zustand der Server ausgeben, die in der laufenden Konfiguration enthalten sind. Mit einem Backendnamen oder einer Kennung kann die Ausgabe auf dieses Backend beschränkt werden.
Die Ausgabe hat das folgende Format:
- Die erste Zeile enthält die Formatversion (1 in dieser Spezifikation);
- die zweite Zeile enthält die Spaltenüberschriften mit einem vorangestellten Rautezeichen (’#’);
- die dritte und alle weiteren Zeilen enthalten Daten;
- jede Zeile, die mit einem Rautezeichen (’#’) beginnt, gilt als Kommentar.
Da mehrere Ausgabeversionen nebeneinander existieren können, sind nachfolgend die Felder und ihre Reihenfolge je Dateiformatversion aufgeführt:
show sess [<options>*]
Alle bekannten aktiven Streams ausgeben (früher als „Sitzungen“ bezeichnet). Dies bei langsamen Verbindungen vermeiden, da die Ausgabe sehr groß sein kann. Dieser Befehl ist zugriffsbeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufen “operator” oder “admin” konfiguriert sind. Auf Rechnern, deren Verbindungen schnell erneuert werden, kann die Ausgabe weniger Einträge enthalten, als tatsächlich vorhanden sind: Ausgegeben werden alle bestehenden Streams bis zu dem letzten, der vor der Befehlseingabe angelegt wurde; Streams, die zwischenzeitlich beendet werden, erscheinen nicht. Die unterstützten Optionen sind weiter unten aufgeführt.
show sess [<id> | all | help] [<options>*]
Viele interne Informationen zu den passenden Streams anzeigen. Der Befehl kennt zwei Ausgabeformate: ein kurzes, das standardmäßig verwendet wird, wenn keine bestimmte Streamkennung angefordert wird, und ein erweitertes für die Auflistung bestimmter Streams. Das kurze Format, das “show sess” standardmäßig verwendet, gibt nur einen Stream je Zeile mit wenigen Informationen aus. Am Zeilenanfang steht die Streamkennung in hexadezimaler Form (sie entspricht dem Zeiger auf den Stream).
In der erweiterten Form, die “show sess <id>” oder “show sess all” verwendet, werden Streams mit sehr vielen Details zur Fehlersuche über mehrere Zeilen ausgegeben (jeweils etwa 20), weiterhin beginnend mit ihrer Kennung. Als Trennzeichen zwischen Streams dient hier die Kennung am Zeilenanfang; zusätzliche Zeilen desselben Streams beginnen mit einem oder mehreren Leerzeichen (die Streamausgabe ist eingerückt). Die Ausgabe vieler Streams kann sehr groß werden, viel Zeit beanspruchen und die CPU stark belasten. Daher ist es stets besser, nur das erforderliche Minimum auszugeben. Für die meisten Benutzer sind diese Informationen nutzlos, HAProxy-Entwickler können sie jedoch zur Untersuchung komplexer Fehler verwenden. Das genaue Ausgabeformat ist absichtlich nicht dokumentiert, damit es sich entsprechend den Anforderungen frei weiterentwickeln kann, auch in stabilen Entwicklungszweigen. Zur Interpretation dieser Ausgabe soll die Funktion strm_dump_to_buffer() in src/stream.c herangezogen werden, um die genaue Bedeutung bestimmter Felder zu ermitteln.
Das Argument “help” zeigt ausführliche Hinweise zur Verwendung des Befehls an, statt Streams auszugeben.
Mit Optionen lässt sich die Ausgabe anpassen oder filtern. Folgende Optionen werden unterstützt: - backend <b> zeigt nur Streams an, die diesem Backend zugeordnet sind - frontend <f> zeigt nur Streams an, die diesem Frontend zugeordnet sind - older <age> zeigt nur Streams an, die älter als <age> Sekunden sind - server <b/s> zeigt nur Streams an, die dieser Kombination aus Backend und Server zugeordnet sind - show-uri gibt die URI der Transaktion aus, wie sie während der Anfrageanalyse erfasst wurde. Sie wird nur angezeigt, wenn sie erfasst wurde. - susp zeigt nur Streams an, die Entwickler anhand von Kriterien als verdächtig einstufen, die sich im Laufe der Zeit oder zwischen Versionen ändern können.
show stat [domain <resolvers|proxy>] [{<iid>|<proxy>} <type> <sid>] \
Statistiken ausgeben. Die Domäne bestimmt, welche Statistiken ausgegeben werden; derzeit stehen resolvers und proxy zur Verfügung. Standardmäßig wird das CSV-Format verwendet. Das oben beschriebene erweiterte typisierte Ausgabeformat lässt sich aktivieren, indem “typed” nach den übrigen Argumenten angegeben wird; mit “json” nach den übrigen Argumenten erfolgt die Ausgabe in JSON. Durch Angabe von <id>, <type> und <sid> lassen sich nur ausgewählte Elemente ausgeben: - <iid> ist eine Proxy-ID; -1 gibt alles aus. Alternativ kann ein Proxyname <proxy> angegeben werden. In diesem Fall dient die ID dieses Proxys zur Auswahl. - <type> wählt den Typ der ausgebbaren Objekte: 1 für Frontends, 2 für Backends, 4 für Server, -1 für alles. Diese Werte können durch ein bitweises ODER verknüpft werden, beispielsweise:
- `<sid>` ist eine Server-ID; -1 gibt alles aus dem ausgewählten Proxy aus.
Beispiel:
In diesem Beispiel wurden zwei Befehle gleichzeitig ausgeführt. So lässt sich im Mehrprozessbetrieb leicht erkennen, auf welchen Prozess sich die Statistiken beziehen. Beim typisierten Ausgabeformat ist dies nicht erforderlich, da die Prozessnummer in jeder Zeile ausgegeben wird. Die Leerzeile nach der Informationsausgabe kennzeichnet das Ende des ersten Blocks. Eine ähnliche Leerzeile erscheint am Ende des zweiten Blocks (Statistiken), damit erkennbar ist, dass die Ausgabe nicht abgeschnitten wurde.
Mit “typed” eignet sich das Ausgabeformat besser für Überwachungswerkzeuge, da es numerische Positionen liefert und den Typ jedes Ausgabefelds angibt. Jeder Wert steht in einer eigenen Zeile mit Prozessnummer, Elementnummer, Art, Herkunft und Geltungsbereich. Dasselbe Format ist über die HTTP-Statistiken verfügbar, indem “;typed” an die URI angehängt wird. Besonders zu beachten ist, dass beim typisierten Ausgabeformat die Daten eines einzelnen Objekts zusammenhängend ausgegeben werden, sodass ein verarbeitendes Programm nicht alles gleichzeitig speichern muss.
Mit dem Modifikator “up” werden nur Server aufgelistet, die als verfügbar gemeldet oder nicht geprüft werden. Nicht verfügbare Server sowie solche mit nicht aufgelöster Adresse oder im Wartungsmodus werden nicht aufgelistet. Dies entspricht der Option “;up” der HTTP-Statistiken. Ebenso verhält sich der Modifikator “no-maint” wie der HTTP-Modifikator “;no-maint” und schließt deaktivierte Server aus der Liste aus. Der Unterschied besteht darin, dass aktivierte, aber nicht verfügbare Server weiterhin aufgeführt werden.
Beim typisierten Ausgabeformat besteht jede Zeile aus 4 durch Doppelpunkte (’:’) getrennten Spalten. Die erste Spalte ist eine durch Punkte getrennte Folge von 5 Elementen. Das erste Element ist ein Buchstabe, der den Typ des beschriebenen Objekts angibt. Derzeit sind folgende Objekttypen bekannt: ‘F’ für ein Frontend, ‘B’ für ein Backend, ‘L’ für einen Listener und ‘S’ für einen Server. Das zweite Element ist eine positive Ganzzahl, die die eindeutige Kennung des Proxys darstellt, zu dem das Objekt gehört. Es entspricht der Spalte “iid” der CSV-Ausgabe und stimmt mit dem Wert der optionalen Direktive “id” im Frontend- oder Backend-Abschnitt überein. Das dritte Element ist eine positive Ganzzahl mit der eindeutigen Objektkennung innerhalb des Proxys und entspricht der Spalte “sid” der CSV-Ausgabe. Bei der Ausgabe eines Frontends oder Backends wird die ID 0 gemeldet. Bei einem Listener oder Server entspricht sie dessen jeweiliger ID innerhalb des Proxys. Das vierte Element ist die numerische Position des Felds in der Liste (beginnend bei null). Diese Position darf sich im Laufe der Zeit nicht ändern; abhängig von den Build-Optionen oder bei einer künftigen Entfernung von Feldern sind jedoch Lücken zu erwarten. Das fünfte Element ist der Feldname, wie er in der CSV-Ausgabe erscheint. Das sechste Element ist eine positive Ganzzahl und gibt die relative Prozessnummer an, beginnend bei 1.
Der Rest der Zeile nach dem ersten Doppelpunkt folgt dem oben beschriebenen „typisierten Ausgabeformat“. Die zweite Spalte (nach dem ersten ‘:’) gibt Herkunft, Art, Geltungsbereich und Persistenzstatus der Variablen an. Die dritte Spalte gibt den Feldtyp an: “s32”, “s64”, “u32”, “u64”, “flt” oder “str”. Die vierte Spalte enthält den Wert selbst, den ein verarbeitendes Programm anhand von Spalte 3 parsen und anhand von Spalte 2 verarbeiten kann.
Wird “desc” an den Befehl angehängt, werden ein weiterer Doppelpunkt und eine Zeichenkette in Anführungszeichen mit einer Beschreibung der Metrik angefügt. Zum Zeitpunkt der Erstellung dieser Dokumentation wird dies nur für das Ausgabeformat “typed” unterstützt.
Das gesamte Zeilenformat im typisierten Modus lautet somit:
Ein Beispiel für das typisierte Ausgabeformat:
Im typisierten Format erleichtert die Prozess-ID am Ende der ersten Spalte das visuelle Zusammenführen der Ausgaben mehrerer Prozesse. Dies zeigt das folgende Beispiel, in dem jede Zeile für jeden Prozess erscheint:
Das Format der JSON-Ausgabe ist in einem Schema beschrieben, das mit “show schema json” ausgegeben werden kann.
Die JSON-Ausgabe enthält keine zusätzlichen Leerraumzeichen, um ihr Volumen zu verringern. Für das Lesen durch Menschen kann es hilfreich sein, die Ausgabe durch ein Werkzeug zur lesbaren Formatierung zu leiten. Beispiel:
$ echo “show stat json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
Die JSON-Ausgabe enthält keine zusätzlichen Leerraumzeichen, um ihr Volumen zu verringern. Für das Lesen durch Menschen kann es hilfreich sein, die Ausgabe durch ein Werkzeug zur lesbaren Formatierung zu leiten. Beispiel:
$ echo “show stat json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
show ssl ca-file [[*][\]<cafile>[:<index>]]
Die Liste der in den Prozess geladenen CA-Dateien und die jeweilige Anzahl ihrer Zertifikate anzeigen. Die Zertifikate werden von keinem Frontend oder Backend verwendet, solange ihr Status nicht “Used” lautet. In der Liste kann ein Eintrag “@system-ca” erscheinen, den der httpclient standardmäßig lädt. Er enthält die von OpenSSL zurückgegebene Liste der vertrauenswürdigen CAs des Systems. Ist einem Dateinamen ein Sternchen vorangestellt, handelt es sich um eine noch nicht festgeschriebene Transaktion. Wird eine <cafile> ohne <index> angegeben, werden der Status der CA-Datei (“Used”/“Unused”) und anschließend Details zu allen in der CA-Datei enthaltenen Zertifikaten angezeigt. Die angezeigten Details entsprechen für jedes Zertifikat denen des Befehls “show ssl cert”. Wird eine <cafile> mit einem nachfolgenden <index> angegeben, werden nur die Details des Zertifikats mit dem angegebenen Index angezeigt. Die Indizes beginnen bei 1. Ist der Index ungültig (beispielsweise zu groß), wird nichts angezeigt. Dieser Befehl kann helfen zu prüfen, ob eine CA-Datei korrekt aktualisiert wurde. Die Details einer laufenden Transaktion lassen sich ebenfalls anzeigen, indem dem Dateinamen ein ‘’ vorangestellt wird. Ist das erste Zeichen des Dateinamens ein ‘’, kann es mit ‘\*’ maskiert werden.
Beispiel:
show ssl cert [[*][\]<filename>]
Die Liste der in den Prozess geladenen Zertifikate anzeigen. Sie werden von keinem Frontend oder Backend verwendet, solange ihr Status nicht “Used” lautet. Ist einem Dateinamen ein Sternchen vorangestellt, handelt es sich um eine noch nicht festgeschriebene Transaktion. Wird ein Dateiname angegeben, werden Details zum Zertifikat angezeigt. Dieser Befehl kann helfen zu prüfen, ob ein Zertifikat korrekt aktualisiert wurde. Details zu einer Transaktion lassen sich ebenfalls anzeigen, indem dem Dateinamen ein ‘’ vorangestellt wird. Ist das erste Zeichen des Dateinamens ein ‘’, kann es mit ‘\*’ maskiert werden. Mit diesem Befehl lassen sich auch die Details der OCSP-Antwort eines Zertifikats anzeigen, indem die Erweiterung “.ocsp” an den Dateinamen angehängt wird. Dies funktioniert sowohl für bereits festgeschriebene als auch für laufende Transaktionen. Bei einem Zertifikat aus einer festgeschriebenen Transaktion entspricht dieser Befehl dem Aufruf von “show ssl ocsp-response” mit der zugehörigen OCSP-Antwort-ID des Zertifikats.
Beispiel:
show ssl crl-file [[*][\]<crlfile>[:<index>]]
Die Liste der in den Prozess geladenen CRL-Dateien anzeigen. Sie werden von keinem Frontend oder Backend verwendet, solange ihr Status nicht “Used” lautet. Ist einem Dateinamen ein Sternchen vorangestellt, handelt es sich um eine noch nicht festgeschriebene Transaktion. Wird eine <crlfile> ohne <index> angegeben, werden der Status der CRL-Datei (“Used”/“Unused”) und anschließend Details zu allen in der CRL-Datei enthaltenen Sperrlisten angezeigt. Die Details jeder Liste beruhen auf der Ausgabe von “openssl crl -text -noout -in <file>”. Wird eine <crlfile> mit einem nachfolgenden <index> angegeben, werden nur die Details der Liste mit dem angegebenen Index angezeigt. Die Indizes beginnen bei 1. Ist der Index ungültig (beispielsweise zu groß), wird nichts angezeigt. Dieser Befehl kann helfen zu prüfen, ob eine CRL-Datei korrekt aktualisiert wurde. Die Details einer laufenden Transaktion lassen sich ebenfalls anzeigen, indem dem Dateinamen ein ‘’ vorangestellt wird. Ist das erste Zeichen des Dateinamens ein ‘’, kann es mit ‘\*’ maskiert werden.
Beispiel:
show ssl crt-list [-n] [<filename>]
Die Liste der crt-list-Dateien und Verzeichnisse anzeigen, die in der HAProxy-Konfiguration verwendet werden. Wird ein Dateiname angegeben, wird der Inhalt einer crt-list-Datei oder eines Verzeichnisses ausgegeben. Die Ausgabe kann anschließend als crt-list-Datei verwendet werden. Mit der Option ‘-n’ lassen sich die Zeilennummern anzeigen. Dies ist zusammen mit der Option ‘del ssl crt-list’ hilfreich, wenn ein Eintrag mehrfach vorkommt. Die Ausgabe mit der Option ‘-n’ ist mit dem crt-list-Format nicht kompatibel und kann von haproxy nicht geladen werden.
Beispiel:
show ssl ech [<name>]
Die Liste der im HAProxy-Prozess geladenen ECH-Schlüssel anzeigen.
Wird <name> angegeben, werden die Schlüssel für eine bestimmte bind-Zeile angezeigt. Das Format der bind-Zeile lautet <frontend>/@<filename>:<linenum> (Beispiel: frontend1/@haproxy.conf
:19) oder <frontend>/<name>, wenn die bind-Zeile mit dem Schlüsselwort “name” benannt wurde.
Der Eintrag ‘age’ gibt die Zeit in Sekunden an, die seit dem Laden des Schlüssels in die bind-Zeile vergangen ist. Dieser Wert wird beim Starten, Neuladen oder Neustarten von HAProxy zurückgesetzt.
Eine OpenSSL-Version mit ECH-Unterstützung ist erforderlich, und HAProxy muss mit USE_ECH=1 kompiliert werden. Dieser Befehl wird nur auf einer CLI-Verbindung im experimentellen Modus unterstützt (siehe “experimental-mode on”).
Siehe auch “ech” in Abschnitt 5.1 des Konfigurationshandbuchs.
Beispiel:
show ssl jwt
Die Liste der Zertifikate anzeigen, die zur JWT-Validierung verwendet werden können. Siehe auch die Befehle “add ssl jwt” und “del ssl jwt”. Weitere Informationen enthält die Zertifikatsoption “jwt”.
Beispiel:
show ssl ocsp-response [[text|base64] <id|path>]
Die IDs der OCSP-Baumeinträge für alle in HAProxy verwendeten OCSP-Antworten anzeigen, zusammen mit dem Pfad des zugehörigen Frontend-Zertifikats, dem Namen und Schlüssel-Hash des Ausstellers sowie der Seriennummer des Zertifikats, für das die OCSP-Antwort erstellt wurde. Wird eine gültige <id> oder der <path> eines gültigen Frontend-Zertifikats angegeben, wird der Inhalt der zugehörigen OCSP-Antwort angezeigt. Bei Angabe einer <id> kann das Ausgabeformat der Daten festgelegt werden. Die Standardoption ’text’ zeigt detaillierte Informationen zur OCSP-Antwort wie bei einem Aufruf von “openssl ocsp -respin <ocsp-response> -text”. Das Format ‘base64’ gibt den Inhalt einer OCSP-Antwort in base64 aus.
Beispiel:
show ssl ocsp-updates
Informationen zu den Einträgen anzeigen, die der OCSP-Aktualisierungsmechanismus betrifft. Der Befehl gibt eine Zeile je OCSP-Antwort aus. Sie enthält den erwarteten Aktualisierungszeitpunkt der Antwort, den Zeitpunkt der letzten erfolgreichen Aktualisierung sowie Zähler für erfolgreiche und fehlgeschlagene Aktualisierungen. Auch der Status der letzten Aktualisierung (erfolgreich oder nicht) wird numerisch und als Text angegeben. Eine vollständige Liste der möglichen Fehler folgt weiter unten. Die Zeilen werden aufsteigend nach dem Zeitpunkt ‘Next Update’ sortiert. Sie enthalten außerdem den Pfad des ersten Frontend-Zertifikats, das die OCSP-Antwort verwendet. Weitere Informationen zur automatischen OCSP-Aktualisierung enthalten der Befehl “show ssl ocsp-response” und die Option “ocsp-update”.
Folgende Fehlercodes und Fehlermeldungen sind für die Aktualisierung möglich:
Beispiel:
show ssl providers
Die Namen der Provider anzeigen, die OpenSSL bei der Initialisierung geladen hat. Das Laden von Providern kann über die OpenSSL-Konfigurationsdatei konfiguriert werden. Mit dieser Option lässt sich prüfen, ob die richtigen Provider geladen wurden. Dieser Befehl ist nur mit OpenSSL v3 verfügbar.
Beispiel:
show ssl sni [-f <frontend>] [-A] [-t <offset>]
Alle für das angegebene Frontend konfigurierten SNIs ausgeben, oder für alle Frontends, wenn keines angegeben wird. So lässt sich erkennen, welche SNIs ein Frontend anbietet und ob eine SNI für dasselbe Frontend durch mehrere Zertifikate mehrfach definiert ist.
Die Option -A filtert die Liste so, dass nur Zertifikate angezeigt werden, deren notAfter-Datum überschritten ist, also nur abgelaufene Zertifikate.
Die Option -t akzeptiert einen Zeitversatz in Sekunden oder mit einer Zeiteinheit (s, m, h, d), der zur aktuellen Zeit addiert wird. Zusammen mit -A lässt sich damit prüfen, welche Zertifikate nach Anwendung des Zeitversatzes abgelaufen sind. Um beispielsweise zu prüfen, welche Zertifikate in 30d abgelaufen wären, genügt “show ssl sni -A -t 30d”.
Die Spalten sind durch ein einzelnes \t getrennt und lassen sich daher einfach parsen.
Die Spalte ‘Frontend/Bind’ zeigt den Frontendnamen, gefolgt von der Position der bind-Zeile in der Konfiguration (frontend/file:linenum).
Die Spalte ‘SNI’ zeigt die SNI; sie kann ein CN, ein SAN oder ein Filter aus einer crt-list sein. Für die Standardzertifikate einer bind-Zeile (entweder ausdrücklich mit ‘default-crt’ deklariert oder, wenn kein ‘strict-sni’ verwendet wird, implizit das erste Zertifikat der bind-Zeile) wird das Zeichen ‘*’ in der Spalte SNI angezeigt.
Die Spalte ‘Negative Filter’ enthält die Liste der negativen Filter, die einem Platzhaltermuster zugeordnet sind. Sie zeigt alle negativen Filter derselben crt-list-Zeile. Sind keine vorhanden, wird ein Bindestrich angezeigt.
Die Spalte ‘Type’ zeigt den Typ des Verschlüsselungsalgorithmus: “rsa”, “ecdsa” oder “dsa”.
Die Spalte ‘Filename’ kann entweder einen Dateinamen aus der Konfiguration oder einen in einem crt-store deklarierten Alias enthalten.
Die Spalten ‘NotAfter’ und ‘NotBefore’ werden direkt aus dem X509-Endzertifikat ausgelesen.
Beispiel:
show startup-logs
Alle beim Start des aktuellen haproxy-Prozesses ausgegebenen Meldungen ausgeben. Jeder startup-logs-Puffer gehört ausschließlich zu seinem jeweiligen haproxy-Worker.
Dieses Schlüsselwort ist auch auf der Master-CLI verfügbar und zeigt dort den letzten Start- oder Neuladeversuch an.
show table
Allgemeine Informationen zu allen bekannten Stick Tables ausgeben: ihren Namen (den Namen des Proxys, der sie enthält), ihren Typ (derzeit null, immer IP), ihre Größe als maximal mögliche Anzahl von Einträgen sowie die Anzahl der derzeit verwendeten Einträge.
Beispiel:
show table <name> [ data.<type> <operator> <value> [data.<type> ...]] |
Den Inhalt der Stick Table <name> ausgeben. In diesem Modus werden wie bei “show table” zunächst allgemeine Informationen zur Tabelle in einer Zeile ausgegeben, anschließend alle Einträge. Da dies sehr aufwendig sein kann, lässt sich mit einem Filter festlegen, welche Einträge angezeigt werden.
Bei Verwendung der Form “data.” wird der Filter auf die gespeicherten Daten angewendet (siehe “stick-table” in Abschnitt 4.2). In <type> muss ein gespeicherter Datentyp angegeben werden. Dieser Datentyp muss in der Tabelle gespeichert sein, sonst wird ein Fehler gemeldet. Die Daten werden gemäß <operator> mit der 64-Bit-Ganzzahl <value> verglichen. Es gelten dieselben Operatoren wie bei ACLs:
- eq: Einträge auswählen, deren Daten diesem Wert entsprechen
- ne: Einträge auswählen, deren Daten diesem Wert nicht entsprechen
- le: Einträge auswählen, deren Daten kleiner oder gleich diesem Wert sind
- ge: Einträge auswählen, deren Daten größer oder gleich diesem Wert sind
- lt: Einträge auswählen, deren Daten kleiner als dieser Wert sind
- gt: Einträge auswählen, deren Daten größer als dieser Wert sind
In dieser Form können mehrere Datenfilter angegeben werden, bis zu einer beim Kompilieren festgelegten Höchstzahl (standardmäßig 4).
Bei Verwendung der key-Form wird der Eintrag <key> angezeigt. Der Schlüssel muss denselben Typ wie die Tabelle haben; zulässig sind derzeit nur IPv4, IPv6, Ganzzahlen und Zeichenketten.
Bei Verwendung der ptr-Form wird der Eintrag <ptr> angezeigt. <ptr> wird in der Form 0xffff geschrieben und muss der Adresse entsprechen, die ein vorheriger Befehl “show table” zurückgegeben hat. Die Auswahl eines Eintrags über seinen Zeiger kann hilfreich sein, wenn der Eintrag wegen eines leeren Schlüssels oder mit der CLI inkompatibler Zeichen nicht über den Schlüssel ausgewählt werden kann.
Wenn data.<type> ein Arraytyp ist, kann “[]” verwendet werden, um auf einen bestimmten Index im Array zuzugreifen, beispielsweise so: data.gpt[1]
Beispiel:
Bezieht sich das Datenkriterium auf einen dynamischen, zeitabhängigen Wert wie eine Byterate, wird der Wert bei der Auswertung des Eintrags dynamisch berechnet, um zu entscheiden, ob er ausgegeben werden muss. Ein solcher Filter kann daher eine Zeit lang zutreffen und anschließend nicht mehr, da die durchschnittliche Ereignisrate mit der Zeit sinkt.
Damit lassen sich Listen von IP-Adressen extrahieren, die den Dienst missbräuchlich nutzen, um sie zu überwachen oder sogar in einer Firewall zu sperren. Beispiel:
Wenn die Stick Table mit einem peers-Abschnitt synchronisiert wird, der Sharding unterstützt, wird für jeden Schlüssel die Shardnummer angezeigt (andernfalls wird ‘0’ gemeldet). So lässt sich erkennen, welche Peers diesen Schlüssel erhalten. Beispiel:
show tasks
Die Anzahl der derzeit in der Ausführungswarteschlange befindlichen Tasks ausgeben, zusammen mit der Anzahl der Vorkommen je Funktion und ihrer durchschnittlichen Latenz, sofern bekannt (bei reinen Tasks mit aktiviertem Task-Profiling). Die Ausgabe ist eine Momentaufnahme zum Zeitpunkt ihrer Erstellung. Sie kann abhängig davon variieren, welche Tasks in diesem Moment noch in der Warteschlange stehen. Dies gilt besonders im Einzelthreadbetrieb, da E/A-Vorgänge die Warteschlange seltener wieder füllen können (außer wenn die Warteschlange voll ist). Dieser Befehl greift exklusiv auf den Prozess zu und kann bei einem stark ausgelasteten Prozess geringe, aber messbare Latenzen verursachen. Daher darf er von automatischen Überwachungswerkzeugen nicht übermäßig verwendet werden.
show threads
Einige interne Zustände und Strukturen je Thread ausgeben, die Entwicklern helfen können, ein Problem zu verstehen. Für eine lesbare Darstellung wird je Thread ein Block ausgegeben. Wenn haproxy mit USE_THREAD_DUMP=1 gebaut wurde, kommt ein erweiterter Ausgabemechanismus mit Threadsignalen zum Einsatz, damit jeder Thread nacheinander seinen eigenen Zustand ausgeben kann. Ohne diese Option zeigt der Thread, der den Befehl verarbeitet, alle eigenen Details an; die anderen Threads werden weniger detailliert dargestellt. Vor dem Thread, der den Befehl bearbeitet, steht ein Sternchen (’*’). Vor Threads, die seit dem letzten Aufruf dieses Befehls keinen Fortschritt gemacht haben, kann außerdem eine schließende Winkelklammer (’>’) erscheinen. Dies weist auf einen Fehler im Code hin, der unbedingt gemeldet werden muss. Tritt dies zwischen zwei Threads auf, weist es gewöhnlich auf einen Deadlock hin. Ist ein Thread allein betroffen, handelt es sich um einen anderen Fehler, etwa eine beschädigte Liste. In jedem Fall ist der Prozess nicht mehr vollständig funktionsfähig und muss neu gestartet werden.
Das Ausgabeformat ist absichtlich nicht dokumentiert, damit es sich bei neuem Bedarf leicht weiterentwickeln kann, ohne irgendeine Form von Abwärtskompatibilität gewährleisten zu müssen. Wie bei “show activity” sind die Werte ohne den zugehörigen Code nicht aussagekräftig.
show tls-keys [id|*]
Alle geladenen Referenzen auf TLS-Ticketschlüssel ausgeben. Angezeigt werden die Referenz-ID des TLS-Ticketschlüssels und die Datei, aus der die Schlüssel geladen wurden. Beide können verwendet werden, um die TLS-Schlüssel mit “set ssl tls-key” zu aktualisieren. Wird eine ID als Parameter angegeben, werden die Tickets ausgegeben; mit * werden alle Schlüssel aller Referenzen ausgegeben.
show schema json
Das Schema ausgeben, das für die Ausgabe von “show info json” und “show stat json” verwendet wird.
Die Ausgabe enthält keine zusätzlichen Leerraumzeichen, um ihr Volumen zu verringern. Für das Lesen durch Menschen kann es hilfreich sein, die Ausgabe durch ein Werkzeug zur lesbaren Formatierung zu leiten. Beispiel:
$ echo “show schema json” | socat /var/run/haproxy.sock stdio | \ python -m json.tool
Das Schema folgt “JSON Schema” (json-schema.org). Entsprechende Prüfwerkzeuge können daher die Ausgabe von “show info json” und “show stat json” anhand des Schemas überprüfen.
show trace [<source>]
Den aktuellen Tracestatus anzeigen. Für jede Quelle wird eine Zeile mit einem Status aus einem einzelnen Zeichen ausgegeben, der angibt, ob der Trace gestoppt ist, wartet oder läuft. Angezeigt werden das vom Trace verwendete Ausgabeziel (oder “none”, wenn keines festgelegt wurde) und die Anzahl der dort verworfenen Ereignisse, gefolgt von einer kurzen Beschreibung der Quelle. Wird ein Quellenname angegeben, erscheint eine detaillierte Liste aller von dieser Quelle unterstützten Ereignisse sowie ihres Status für jede Aktion (report, start, pause, stop): “+” bedeutet aktiviert, “-” bedeutet deaktiviert. Alle diese Ereignisse sind unabhängig voneinander. Ein Ereignis kann daher einen Start auslösen, ohne gemeldet zu werden, und umgekehrt.
show version
Die Version des aktuellen HAProxy-Prozesses anzeigen. Dieser Befehl ist auf der Master- und der Worker-CLI verfügbar. Beispiel:
shutdown frontend <frontend>
Das angegebene Frontend vollständig löschen. Alle Ports, an die es gebunden war, werden freigegeben. Nach diesem Vorgang lässt sich das Frontend nicht mehr aktivieren. Dies ist für Umgebungen vorgesehen, in denen das Anhalten eines Proxys ausgeschlossen ist, eine fehlerhafte Proxykonfiguration aber korrigiert werden muss. Auf diese Weise kann der Port freigegeben und in einem anderen Prozess gebunden werden, um den Betrieb wiederherzustellen. Nach seiner Beendigung erscheint das Frontend überhaupt nicht mehr auf der Statistikseite.
Das Frontend kann entweder durch seinen Namen oder durch seine numerische ID mit vorangestelltem Rautezeichen (’#’) angegeben werden.
Dieser Befehl ist zugriffsbeschränkt und kann nur über Sockets ausgeführt werden, die für die Berechtigungsstufe “admin” konfiguriert sind.
shutdown session <id>
Den Stream mit der angegebenen Streamkennung sofort beenden. Diese Kennung steht als erstes Feld am Zeilenanfang der Ausgaben von “show sess” (sie entspricht dem Zeiger auf den Stream). Damit lässt sich ein lang laufender Stream beenden, ohne auf eine Zeitüberschreitung zu warten, oder eine endlose Übertragung abbrechen. Auf diese Weise beendete Streams werden in den Protokollen mit einem ‘K’-Flag gekennzeichnet.
shutdown sessions server <backend>/<server>
Alle dem angegebenen Server zugeordneten Streams sofort beenden. Damit lassen sich beispielsweise lang laufende Streams beenden, nachdem ein Server in den Wartungsmodus versetzt wurde. Auf diese Weise beendete Streams werden in den Protokollen mit einem ‘K’-Flag gekennzeichnet.
Backend-Verbindungen bleiben im Leerlauf, außer wenn sich der Server bereits im Wartungsmodus befindet. In diesem Fall werden sie sofort zur Löschung vorgemerkt.
trace
Der Befehl “trace” ohne weitere Argumente listet die Tracequellen, ihren aktuellen Status und ihre kurzen Beschreibungen auf. Er dient nur als Menü für den Einstieg in die nächsten Ebenen; siehe die weiteren “trace”-Befehle unten.
trace 0
Alle Traces sofort stoppen. Dies ist als schnelle Möglichkeit zum Beenden einer Sitzung zur Fehlersuche gedacht oder als Notfallmaßnahme, wenn komplexe Traces für mehrere Quellen aktiviert wurden und den Dienst beeinträchtigen.
trace <source> [<args...>]
Traces für die Quelle <source> konfigurieren. Ohne Argument werden alle von dieser Quelle unterstützten Unterbefehle aufgelistet. Mehrere Unterbefehle können verkettet werden. Folgende Unterbefehle werden unterstützt:
event [ [+|-|!]<name> ] Ohne Argument werden alle Ereignisse aufgelistet, die die angegebene Quelle unterstützt. Ihnen wird ein “-” vorangestellt, wenn sie deaktiviert sind, oder ein “+”, wenn sie aktiviert sind. Zu beachten ist, dass ein einzelner Trace mit mehreren Ereignissen gekennzeichnet sein kann. Sobald eines der aktivierten Ereignisse mit einem der Ereignisse am Trace übereinstimmt, wird das Ereignis an das Trace-Subsystem übergeben. Beispielsweise kann der Empfang eines HTTP/2-Frames vom Typ HEADERS ein Frameereignis und ein Streamereignis auslösen, da der Frame einen neuen Stream erzeugt. Ist entweder das Frameereignis oder das Streamereignis für diese Quelle aktiviert, wird der Frame an das Trace-Framework übergeben.
Mit einem Argument lässt sich der Zustand jedes Ereignisses umschalten,
um es einzeln zu aktivieren oder zu deaktivieren. Zwei spezielle Schlüsselwörter
werden unterstützt: "none" passt auf kein Ereignis und deaktiviert alle
Ereignisse gleichzeitig; "any" passt auf alle Ereignisse und aktiviert sie
gleichzeitig. Andere Ereignisse hängen von der Ereignisquelle ab. Ein Ereignis
lässt sich durch Angabe seines Namens aktivieren, optional mit einem
vorangestellten '+' zur besseren Lesbarkeit. Zur Deaktivierung wird sein
Name mit einem vorangestellten '-' oder '!' angegeben.
Eine Tracequelle lässt sich vollständig deaktivieren, indem "event none"
angegeben wird. Die Quelle wird dann sofort vollständig ignoriert.
follow <other_source> Damit kann die Quelle <source> auch dann Traces ausgeben, wenn die andere Quelle <other_source> auf ein Kriterium fixiert ist und dasselbe Kriterium auch auf die aktuelle Quelle zutrifft. Ist beispielsweise eine Quelle auf eine Sitzung fixiert, bewirkt das Folgen dieser Quelle von einer anderen Quelle aus, dass die andere Quelle Traces für alle Ereignisse dieser Sitzung ausgibt. Damit lassen sich in gewissem Umfang Backend-Anfragen zusammen mit den zugehörigen Frontend-Verbindungen verfolgen. Die Quelle “session” erleichtert dies mit den Ereignissen “new” und “end”, die zur Verarbeitung der Fixierung verwendet werden können. Die Traces der Quelle <source> müssen in diesem Fall nicht aktiviert sein; ihr Tracestatus wird ebenfalls nicht beeinflusst. Einige Ereignisse können jedoch fehlen, wenn sie keine Informationen enthalten, die eine Zuordnung zum verfolgten Element ermöglichen. Mit diesem Befehl kann auch die Metaquelle “all” verwendet werden: Dann folgen alle Quellen <other_source>.
Beispiel:
level [<level>] Ohne Argument werden alle Tracestufen dieser Quelle aufgelistet; die aktuelle Stufe wird durch ein vorangestelltes Sternchen (’*’) gekennzeichnet. Mit einem Argument wird die Tracestufe auf die angegebene Stufe geändert. Detailstufen sind eine Form von Filtern, die vor der Meldung der Ereignisse angewendet werden. Diese Filter schließen Ereignisse je nach ihrer Bedeutung gezielt ein oder aus. Ein Entwickler muss beispielsweise möglicherweise genau wissen, an welcher Stelle im Code ein HTTP-Header als ungültig angesehen wurde, während seine Gültigkeit für den Endbenutzer vielleicht überhaupt nicht relevant ist. Derzeit gibt es 5 verschiedene Tracestufen:
Es wird dringend empfohlen, stets nur die Stufe "user" zu verwenden und
nur auf Anweisung eines Entwicklers zu anderen Stufen zu wechseln. Außerdem
ist es sinnvoll, vor dem Wechsel zu höheren Stufen zunächst die Ereignisse
zu konfigurieren, um die Ausgabe vieler Zeilen ohne angewendeten Filter zu
vermeiden. Mit diesem Befehl kann auch die Metaquelle "all" verwendet werden:
Dann wird die Stufe gleichzeitig auf alle vorhandenen Quellen angewendet.
lock [criterion] Ohne Argument werden alle Kriterien aufgelistet, die diese Quelle für die Fixierung unterstützt. Die aktuelle Auswahl wird durch ein vorangestelltes Sternchen (’*’) angezeigt. Fixierung bedeutet, dass sich die Quelle auf das erste passende Ereignis konzentriert und nur an dem Kriterium festhält, das dieses Ereignis ausgelöst hat; alles andere wird ignoriert, bis der Trace stoppt. So lässt sich beispielsweise ein Trace für eine einzelne Verbindung oder einen einzelnen Stream erfassen. Einige Traces unterstützen die folgenden Kriterien, jedoch nicht unbedingt alle, da manche Kriterien der Quelle möglicherweise nicht zur Verfügung stehen:
Zusätzlich kann jede Quelle bis zu 4 spezifische Kriterien bereitstellen,
etwa interne Zustände oder Verbindungs-IDs. Bei HTTP/2 lässt sich beispielsweise
auf den H2-Stream fixieren und andere Streams ignorieren, sobald ein Trace startet.
Wird ein Kriterium als Argument übergeben, wird es anstelle der anderen
verwendet. Jede bestehende Verfolgung wird sofort beendet, damit sie mit dem
neuen Kriterium neu starten kann. Alle Quellen unterstützen das spezielle
Schlüsselwort "nothing", um die Verfolgung dauerhaft zu deaktivieren.
{ pause | start | stop } [ [+|-|!]event] Ohne Argument werden die Ereignisse aufgelistet, die für das automatische Pausieren, Starten oder Stoppen eines Traces dieser Quelle aktiviert sind. Diese Ereignisse hängen von der jeweiligen Tracequelle ab. Mit einem Argument wird das Ereignis entweder für die angegebene Aktion aktiviert (optional mit vorangestelltem ‘+’) oder deaktiviert (mit vorangestelltem ‘-’ oder ‘!’). Das spezielle Schlüsselwort “now” ist kein Ereignis, sondern fordert die sofortige Ausführung der Aktion an. Die Schlüsselwörter “none” und “any” werden wie bei “trace event” unterstützt.
Die 3 unterstützten Aktionen sind "pause", "start" und "stop". Die Aktion
"pause" zählt Ereignisse auf, die einen laufenden Trace anhalten und auf ein
neues Startereignis warten lassen, um ihn erneut zu starten. Die Aktion
"start" zählt Ereignisse auf, die den Trace in den Wartemodus versetzen, bis
eines der Startereignisse auftritt. Die Aktion "stop" zählt Ereignisse auf,
die den Trace endgültig stoppen, bis er wieder manuell aktiviert wird. In der
Praxis ist es sinnvoll, einen Trace mit "start now" manuell zu starten, ohne
sich um Ereignisse zu kümmern, und ihn mit "stop now" zu stoppen. Um subtilere
Ereignisfolgen zu erfassen, kann "start" auf ein gewöhnliches Ereignis gesetzt
werden (etwa den Empfang einer HTTP-Anfrage) und "stop" auf ein sehr seltenes
Ereignis wie die Ausgabe eines bestimmten Fehlers. Dadurch entsprechen die
zuletzt erfassten Ereignisse den gewünschten Kriterien. Das Pausenereignis
ist hilfreich, um das Ende einer Folge zu erkennen, die Fixierung aufzuheben
und auf eine weitere Gelegenheit zur Erfassung zu warten. In diesem Fall kann
es sinnvoll sein, die Fixierung zu aktivieren, um nur ein bestimmtes Kriterium
(etwa einen Stream) zu verfolgen. "start" wird auf alles gesetzt, was dieses
Kriterium beginnen lässt (etwa alle Ereignisse, die einen Stream erzeugen),
"stop" auf die erwartete Anomalie und "pause" auf alles, was dieses Kriterium
beendet (etwa jedes Ereignis zum Streamende). Das Traceprotokoll enthält dann
vollständige Folgen fehlerfreier Serien, die jeweils ein einzelnes Objekt
betreffen, bis zur letzten Folge mit allem vom Beginn bis zur Anomalie.
sink [<sink>] Ohne Argument werden alle für diese Quelle verfügbaren Ereignisausgabeziele aufgelistet; das aktuell konfigurierte wird durch ein vorangestelltes Sternchen (’*’) gekennzeichnet. Das Ausgabeziel “none” ist immer verfügbar und bedeutet, dass alle Ereignisse einfach verworfen werden. Ihre Verarbeitung wird jedoch nicht ignoriert (beispielsweise findet eine Fixierung statt). Andere Ausgabeziele stehen abhängig von Konfiguration und Build-Optionen zur Verfügung; typischerweise sind “stdout” und “stderr” im Debugmodus nutzbar, und Ringpuffer im Speicher sollten ebenfalls verfügbar sein. Wird ein Name angegeben, ändert sich das Ausgabeziel für die angegebene Quelle sofort. Ein Wechsel des Ausgabeziels ändert die Ereignisse nicht. Im schlimmsten Fall gehen einige verloren, wenn ein ungültiges Ausgabeziel (oder “none”) verwendet wird; die Vorgänge werden jedoch an einem anderen Ziel fortgesetzt. Mit diesem Befehl kann auch die Metaquelle “all” verwendet werden: Dann wird das Ausgabeziel gleichzeitig auf alle vorhandenen Quellen angewendet.
verbosity [<level>] Ohne Argument werden alle Stufen des Detailgrads dieser Quelle aufgelistet; die aktuelle wird durch ein vorangestelltes Sternchen (’*’) gekennzeichnet. Mit einem Argument wird der Detailgrad auf die angegebene Stufe geändert.
Die Stufen des Detailgrads geben an, wie weit der Tracedekoder gehen sollte,
um detaillierte Informationen bereitzustellen. Dies hängt von der Tracequelle
ab, da einige Quellen nicht einmal einen spezifischen Dekoder bereitstellen.
Die Stufe "quiet" ist immer verfügbar und deaktiviert jede Dekodierung. Sie
kann helfen, zunächst festzustellen, was geschieht, bevor die Details
untersucht werden, da sie Leistung und Tracegröße nur sehr wenig beeinflusst.
Deklariert eine Quelle keine Stufen des Detailgrads, steht die Stufe "default"
zur Verfügung. Sie bewirkt den Aufruf eines Dekoders, wenn dies in den Traces
angegeben ist. Dies ist eine opportunistische Dekodierung. Deklariert
eine Quelle Stufen des Detailgrads, werden diese mit einer Beschreibung ihrer
Bedeutung aufgelistet. In diesem Fall arbeitet der von der Quelle
bereitgestellte Tracedekoder anhand der am Tracepunkt verfügbaren Informationen
so genau wie möglich. Standardmäßig ist die erste Stufe oberhalb von "quiet"
eingestellt.
update ssl ocsp-response <certfile>
Eine OCSP-Anfrage für die angegebene <certfile> erstellen und an den OCSP-Responder senden, dessen URI im Abschnitt “Authority Information Access” des Zertifikats angegeben sein sollte. Nur die erste URI wird berücksichtigt. Die als Antwort erwartete OCSP-Antwort wird anschließend geprüft und in den lokalen OCSP-Antwortbaum eingefügt. Dieser Befehl funktioniert nur für Zertifikate, für die bereits eine OCSP-Antwort gespeichert war, entweder bei der Initialisierung bereitgestellt oder zuvor über die Befehle “set ssl cert” oder “set ssl ocsp-response” gesetzt. Ist die empfangene OCSP-Antwort gültig und wurde sie korrekt in den lokalen Baum eingefügt, wird ihr Inhalt auf der Standardausgabe angezeigt. Das Format entspricht dem unter “show ssl ocsp-response” beschriebenen.
wait { -h | <delay> } [<condition> [<args>...]]
In der einfachsten Form ohne Bedingung wartet der Befehl lediglich die angegebene Zeit, bevor er fortfährt. Damit lassen sich Metriken über ein bestimmtes Zeitintervall erfassen.
Mit einer Bedingung und optionalen Argumenten wartet der Befehl, bis die angegebene Bedingung erfüllt ist, endgültig fehlschlägt oder während der gesamten Dauer <delay> unerfüllt bleibt. Folgende Bedingungen werden unterstützt:
-
be-removable
<proxy>: Wartet, bis das angegebene Proxybackend mit dem Befehl “del backend” entfernt werden kann. Manche Zustände werden niemals akzeptiert (beispielsweise ein noch veröffentlichtes Backend oder eines mit Servern darin). Sie führen zu einer spezifischen Fehlermeldung, die angibt, welche Bedingung nicht erfüllt ist. Ist vor Ablauf der Wartezeit alles OK, wird Erfolg zurückgegeben und der Vorgang beendet. -
srv-removable
<proxy>/<server>: Wartet, bis der angegebene Server mit dem Befehl “del server” entfernt werden kann, also im Wartungsmodus ist und keine Verbindungen mehr hat (weder aktive noch ungenutzte). Manche Zustände werden niemals akzeptiert (beispielsweise ein Server außerhalb des Wartungsmodus). Sie führen zu einer spezifischen Fehlermeldung, die angibt, welche Bedingung nicht erfüllt ist. Der Server kann sogar parallel bereits entfernt worden sein und nicht mehr existieren. Ist vor Ablauf der Wartezeit alles OK, wird Erfolg zurückgegeben und der Vorgang beendet.
Standardmäßig wird die Wartezeit in Millisekunden angegeben. Andere Einheiten werden ebenfalls akzeptiert, wenn sie mit den üblichen Zeiteinheiten (us, ms, s, m, h, d) als Suffix angegeben werden. Bei Verwendung mit dem Werkzeug ‘socat’ muss dessen Zeitüberschreitung zum Schließen verlängert werden, damit sie die Wartezeit abdeckt. Mit “-h” als erstem oder zweitem Argument werden Hinweise zur Verwendung des Befehls angezeigt. Beispiel:
9.4. Master-CLI
Die Master-CLI ist ein Socket, der im Master-Worker-Modus an den Masterprozess gebunden ist. Diese CLI ermöglicht den Zugriff auf die Unix-Socket-Befehle aller laufenden oder sich beendenden Prozesse und eine grundlegende Überwachung dieser Prozesse.
Die Master-CLI lässt sich ausschließlich über die Programmargumente von haproxy mit der Option -S konfigurieren. Diese Option akzeptiert auch kommagetrennte bind-Optionen.
Beispiel:
9.4.1. Befehle der Master-CLI
@<[!]pid>
Die Master-CLI verwendet eine besondere Präfixnotation, um auf die verschiedenen Prozesse zuzugreifen. Diese Notation ist leicht erkennbar, da sie mit einem @ beginnt.
Auf ein @-Präfix kann eine relative Prozessnummer oder ein Ausrufezeichen mit einer PID folgen (beispielsweise @1 oder @!1271). Ein einzelnes @ kann den Master angeben. Sich beendende Prozesse sind nur über die PID erreichbar, da relative Prozessnummern nur für die aktuellen Prozesse verwendbar sind.
Dieses Präfix kann einem Befehl vorangestellt werden, um anzugeben, dass dieser und nur dieser Befehl an den bezeichneten Prozess gesendet wird. In diesem Fall endet der vollständige Befehl wie jeder reguläre Befehl am Zeilenende oder an einem Semikolon.
Fehler: Das Protokoll sockpair@ zur Kommunikation zwischen Master und Worker ist auf macOS bekanntermaßen unzuverlässig, da die macOS-Implementierung von sendmsg(2) fehlerhaft ist. Ein Befehl kann daher ohne Antwort bleiben.
Beispiele:
Das Präfix kann auch als eigenständiger Befehl verwendet werden, um den Standardausführungskontext auf den bezeichneten Prozess umzuschalten. Alle nachfolgenden Befehle werden dann in diesem Prozess ausgeführt, bis ein neuer ‘@’-Befehl den Ausführungskontext erneut ändert.
Beispiele:
Hinweis zu Einschränkungen: Einige wenige Befehle ändern den Zustand einer CLI-Sitzung (beispielsweise “set anon”, “set timeout”) und verhalten sich bei einem Aufruf über die Master-CLI möglicherweise nicht genau gleich, da die Befehle einzeln in jeweils einer eigenen CLI-Sitzung gesendet werden. Ebenso überwachen einige wenige Befehle (“show events”, “wait”) die CLI aktiv auf Eingaben oder das Schließen der Verbindung und werden sofort unterbrochen, wenn die CLI geschlossen wird. Diese Befehle funktionieren über die Master-CLI nicht wie erwartet, da die Befehlseingabe nach jedem Befehl geschlossen wird. Für solche seltenen Fälle kann die unten beschriebene Variante “@@” besser geeignet sein.
@@<[!]pid> [command...]
Dieses Präfix beziehungsweise dieser Befehl ähnelt dem oben dokumentierten Präfix “@”, wechselt jedoch in den Workerprozess, übergibt ihm die gesamte Befehlszeile unverändert und bleibt dort, bis der Befehl endet. Auch Semikolons werden übergeben, sodass eine vollständige verkettete Befehlsfolge in einem Workerprozess ausgeführt werden kann. Die Verbindung zum Worker bleibt offen, bis die Befehlsliste abgeschlossen ist. Alle nach den Befehlen gesendeten Daten werden an die CLI des Workerprozesses weitergeleitet. Sie können von den ausgeführten Befehlen verarbeitet werden und gehen für die CLI des Masterprozesses verloren. So entsteht eine tatsächlich bidirektionale Verbindung mit dem Workerprozess. Bei Verwendung solcher Befehle muss daher sehr sorgfältig auf deren Abschluss gewartet werden, bevor neue Befehle an die Master-CLI gesendet werden.
Statt einen einzelnen Befehl auszuführen, kann auch eine vollständig interaktive Sitzung auf dem Workerprozess geöffnet werden, indem kein Befehl angegeben wird (also “@@1” in einer eigenen Zeile). Diese Sitzung lässt sich entweder durch Schließen der Verbindung oder durch Verlassen der CLI des Workerprozesses (mit dem Befehl “quit”) beenden. In diesem Fall wird der Eingabeaufforderungsmodus des Mastersockets (interactive, prompt, timed) an den Workerprozess weitergegeben.
Fehler: Das Protokoll sockpair@ zur Kommunikation zwischen Master und Worker ist auf macOS bekanntermaßen unzuverlässig, da die macOS-Implementierung von sendmsg(2) fehlerhaft ist. Ein Befehl kann daher ohne Antwort bleiben.
Beispiele:
expert-mode [on|off]
Dieser Befehl aktiviert “expert-mode” für jeden Worker, auf den über die Master-CLI zugegriffen wird. Zusammen mit “mcli-debug-mode” aktiviert er den Befehl auch auf dem Master. Er zeigt das Flag “e” in der Eingabeaufforderung der Master-CLI an.
Siehe auch “expert-mode” in Abschnitt 9.3 und “mcli-debug-mode” in 9.4.1.
experimental-mode [on|off]
Dieser Befehl aktiviert “experimental-mode” für jeden Worker, auf den über die Master-CLI zugegriffen wird. Zusammen mit “mcli-debug-mode” aktiviert er den Befehl auch auf dem Master. Er zeigt das Flag “x” in der Eingabeaufforderung der Master-CLI an.
Siehe auch “experimental-mode” in Abschnitt 9.3 und “mcli-debug-mode” in 9.4.1.
hard-reload
Dieser Befehl verhält sich wie der Befehl “reload” über die Master-CLI, beendet den vorherigen Prozess jedoch sofort (-st), statt ihn geordnet anzuhalten (-sf). Der vorherige Prozess wartet also vor dem Beenden auf keinen Abschluss, sodass alle Verbindungen geschlossen werden.
Siehe auch den Befehl “reload”.
mcli-debug-mode [on|off]
Dieses Schlüsselwort ermöglicht einen besonderen Modus der Master-CLI, der dort alle für eine Worker-CLI vorgesehenen Schlüsselwörter aktiviert und so die Fehlersuche im Masterprozess ermöglicht. Nach der Aktivierung lassen sich die neu verfügbaren Schlüsselwörter mit “help” auflisten. Zusammen mit “experimental-mode” oder “expert-mode” werden noch weitere Schlüsselwörter aktiviert. Das Flag “d” wird in der Eingabeaufforderung der Master-CLI angezeigt.
prompt
Wenn die Eingabeaufforderung aktiviert ist (über den Befehl “prompt”), zeigt sie den Kontext an, in dem die CLI arbeitet. Der Master wird durch die Zeichenkette “master” gekennzeichnet, andere Prozesse durch ihre PID. Ist das letzte Neuladen fehlgeschlagen, wird die Eingabeaufforderung des Masters zu “master[ReloadFailed]>” geändert. Dadurch wird sichtbar, dass der Prozess weiterhin mit der vorherigen Konfiguration läuft und die neue Konfiguration nicht betriebsbereit ist.
Die Eingabeaufforderung der Master-CLI kann mehrere Flags anzeigen, die die aktivierten Modi kennzeichnen: “d” für mcli-debug-mode, “e” für expert-mode und “x” für experimental-mode.
Beispiel:
reload
Der HAProxy-Masterprozess kann auch mit dem Befehl “reload” neu geladen werden. Dies entspricht einem kill -USR2 auf den Masterprozess, sofern der Benutzer mindestens über die Berechtigungsstufe “operator” oder “admin” verfügt.
Dieser Befehl ermöglicht ein synchrones Neuladen und gibt nach dessen Ausführung den Status zurück. Wenn die Ausgabe mit einem Werkzeug geparst wird, ist die Zeitüberschreitung zu beachten: Der Status wird erst zurückgegeben, nachdem die Konfiguration geparst und der neue Worker durch fork erzeugt wurde. Der Befehl “socat” verwendet standardmäßig eine Zeitüberschreitung von 0.5s. Dauert das Neuladen zu lange, beendet er sich daher, bevor die Meldung angezeigt wird. “ncat” hat standardmäßig keine Zeitüberschreitung. Bei Kompilierung mit USE_SHM_OPEN=1 kann der Befehl reload außerdem die startup-logs des Masters ausgeben.
Beispiel:
Der Befehl reload ist der letzte, der auf der Master-CLI ausgeführt wird; alle nachfolgenden Befehle werden ignoriert. Sobald der Befehl reload seinen Status zurückgibt, schließt er die Verbindung zur CLI.
Ein Neuladen schließt alle Verbindungen zur Master-CLI. Siehe auch den Befehl “hard-reload”.
show proc [debug]
Die Master-CLI stellt den Befehl ‘show proc’ zur Überwachung der Prozesse bereit.
Beispiel:
In diesem Beispiel wurde der Master 5 Mal neu geladen, aber einer der alten Worker läuft noch und hat 3 Neuladevorgänge überlebt. Über die CLI dieses Workers lässt sich untersuchen, was geschieht.
Der Parameter ‘debug’ zeigt Details zur Fehlersuche an, derzeit die FDs der IPC-Kommunikation. Zwischen haproxy-Versionen ist die Stabilität der Debugausgabe nicht gewährleistet.
show startup-logs
Für die korrekte Verwendung auf der Master-CLI muss HAProxy mit USE_SHM_OPEN=1 kompiliert werden; andernfalls sind nicht alle Meldungen sichtbar.
Wie sein Gegenstück auf dem Statistiksocket kann dieser Befehl die Startmeldungen von HAProxy anzeigen. Er gibt jedoch nicht die Startmeldungen des aktuellen Workers aus, sondern die des letzten Start- oder Neuladeversuchs. Damit kann er auch die Parsingmeldungen eines fehlgeschlagenen Neuladens ausgeben.
Diese Meldungen werden auch mit dem Befehl “reload” ausgegeben.
9.5. Statistikdatei (Stats-file)
Eine sogenannte Statistikdatei (stats-file) kann verwendet werden, um interne haproxy-Zähler beim Prozessstart mit Werten ungleich null vorzubelegen. Ihr Hauptzweck ist es, Statistiken von Workerprozessen über Neuladevorgänge hinweg zu erhalten. Eine stats-file enthält nur einen Teil aller von haproxy bereitgestellten Statistiken, da nur das Vorbelegen von Metrikwerten sinnvoll ist.
Derzeit unterstützt stats-file nur Proxyzähler. So lassen sich Werte für Frontends, Backends, Server und Listener vorbelegen. In einer stats-file werden jedoch nur Objektinstanzen mit einer nicht leeren GUID gespeichert. Dies stellt sicher, dass Werte für Objekte mit übereinstimmendem Typ und übereinstimmender GUID vorbelegt werden, auch wenn andere Parameter abweichen.
Der CLI-Befehl “dump stats-file” dient dazu, eine stats-file zu erzeugen. Das Format der stats-file ist intern definiert und kann künftig frei geändert und erweitert werden. Es ist auf Kompatibilität mindestens zwischen aufeinanderfolgenden stabilen haproxy-Versionszweigen ausgelegt. Wird eine stats-file in einen Prozess geladen, der eine ältere Version ausführt, kann jedoch eine optionale zusätzliche Konfiguration erforderlich sein.