HAProxy 3.4.6-66 Dokumentation

• 1: Grundlagen der Lastverteilung
• 2: Was HAProxy ist und wie es funktioniert
• 3: Grundfunktionen
• 4: Standardfunktionen
• 5: Erweiterte Funktionen
• 6: Dimensionierung und Leistung
• 7: Versionen, Pakete und Upgrades
• 8: Ergänzende Produkte und Alternativen
• 9: Dokumentation und Community
• 10: 1. Kurzer Überblick über HTTP
• 11: 2. HAProxy konfigurieren
• 12: 3. Globaler Abschnitt
• 13: 4. Proxys
• 14: 5. Bind- und Server-Optionen
• 15: 6. Cache
• 16: 7. ACLs und Sample-Abruf
• 17: 8. Protokollierung
• 18: 9. Unterstützte Filter
• 19: 10. FastCGI-Anwendungen
• 20: 11. Stick Tables und Peers
• 21: 12. Weitere Abschnitte
• 22: 1. Voraussetzungen
• 23: 2. HAProxy-Architektur
• 24: 3. HAProxy starten
• 25: 4. HAProxy stoppen und neu starten
• 26: 5. Grenzen für Dateideskriptoren
• 27: 6. Speicherverwaltung
• 28: 7. CPU-Auslastung
• 29: 8. Protokollierung
• 30: 9. Statistiken und Überwachung
• 31: 10. Einfachere Konfigurationsverwaltung
• 32: 11. Bekannte Fallstricke vermeiden
• 33: 12. Fehlerdiagnose und Leistungsprobleme
• 34: 13. Sicherheitsaspekte

1 - Grundlagen der Lastverteilung

Dieses Dokument führt in HAProxy ein, sowohl für neue Nutzer als auch für diejenigen, die ältere Versionen kennen und sich erneut damit vertraut machen möchten. Es liefert vor allem die Informationen, mit denen sich beurteilen lässt, ob HAProxy für die eigenen Anforderungen geeignet ist. Erfahrene Nutzer finden hier möglicherweise Lösungsansätze für bisherige Ideen, weil ihnen eine neue Funktion noch nicht bekannt war. Darüber hinaus behandelt das Dokument die Dimensionierung und den Produktlebenszyklus und vergleicht HAProxy mit Produkten, deren Funktionen sich teilweise überschneiden.

Das Dokument bietet keine Hilfe oder Hinweise zur Konfiguration, verweist aber auf die dafür geeignete Dokumentation. Der Leitfaden ist in der HAProxy-Seitenleiste als flache Folge von Themenseiten angeordnet.

Lastverteilung fasst mehrere Komponenten so zusammen, dass ihre gesamte Verarbeitungskapazität die Kapazität jeder einzelnen übersteigt. Dies erfolgt skalierbar und ohne Eingriff des Endnutzers. In der Zeit, die eine Komponente für eine Operation benötigt, können dadurch mehrere Operationen gleichzeitig ausgeführt werden. Eine einzelne Operation läuft jedoch weiterhin jeweils auf nur einer Komponente und wird durch die Lastverteilung nicht schneller. Um alle Komponenten zu nutzen und vollständig von der Lastverteilung zu profitieren, müssen stets mindestens so viele Operationen wie Komponenten sowie ein effizientes Verteilungsverfahren vorhanden sein. Ein anschauliches Beispiel sind mehrere Fahrspuren einer Autobahn: In derselben Zeit können mehr Autos passieren, ohne dass sich ihre individuelle Geschwindigkeit erhöht.

Beispiele für Lastverteilung:

• Prozessplanung in Mehrprozessorsystemen
• Lastverteilung auf Verbindungen, etwa EtherChannel oder Bonding
• Lastverteilung über IP-Adressen, etwa ECMP oder DNS-Round-Robin
• Lastverteilung auf Server durch Load-Balancer

Das Verfahren oder die Komponente, die die Last verteilt, heißt Load-Balancer. In Webumgebungen spricht man von einem Netzwerk-Load-Balancer oder meist einfach von einem Load-Balancer, da dies der mit Abstand bekannteste Anwendungsfall der Lastverteilung ist.

Ein Load-Balancer kann auf verschiedenen Ebenen arbeiten:

• auf Verbindungsebene: Er wählt aus, über welche Netzwerkverbindung ein Paket gesendet wird;

• auf Netzwerkebene: Er bestimmt die Route, der eine Folge von Paketen folgt;

• auf Serverebene: Er entscheidet, welcher Server eine Verbindung oder Anfrage verarbeitet.

Es gibt zwei unterschiedliche Technologien für verschiedene, teilweise überlappende Anforderungen. In beiden Fällen ist zu beachten, dass Lastverteilung den Datenverkehr von seinem natürlichen Weg ablenkt. Dies verlangt stets eine gewisse Sorgfalt, damit alle Routingentscheidungen ausreichend konsistent bleiben.

Die erste Technologie arbeitet auf Paketebene und verarbeitet Pakete mehr oder weniger einzeln. Zwischen eingehenden und ausgehenden Paketen besteht eine 1:1-Beziehung, sodass sich der Datenverkehr auf beiden Seiten des Load-Balancers mit einem gewöhnlichen Netzwerkmitschnitt verfolgen lässt. Dieses Verfahren kann sehr günstig und extrem schnell sein. Meist wird es in Hardware mit ASICs umgesetzt und erreicht Leitungsgeschwindigkeit, etwa in Switches mit ECMP. Gewöhnlich ist es zustandslos, kann aber auch die Sitzung berücksichtigen, zu der ein Paket gehört, und damit zustandsbehaftet arbeiten; dies wird als layer4-LB oder L4 bezeichnet. Wenn die Pakete unverändert bleiben, kann DSR unterstützt werden: Der Server antwortet direkt, ohne erneut den LB zu durchlaufen. Den Inhalt kennt dieses Verfahren jedoch kaum. Es eignet sich sehr gut zur Lastverteilung auf Netzwerkebene, wird aber gelegentlich auch für sehr einfache, schnelle Lastverteilung auf Server verwendet.

Die zweite Technologie verarbeitet den Inhalt von Sitzungen. Dazu muss sie eingehende Datenströme zusammensetzen und als Ganzes verarbeiten. Der Inhalt kann geändert werden; der ausgehende Datenstrom wird anschließend in neue Pakete zerlegt. Deshalb übernehmen meist Proxys diese Aufgabe, die oft Load-Balancer für Schicht 7 oder L7 genannt werden. Auf beiden Seiten bestehen getrennte Verbindungen. Zwischen Größe und Anzahl der eingehenden und ausgehenden Pakete gibt es keinen Zusammenhang. Clients und Server müssen nicht dasselbe Protokoll verwenden, etwa IPv4 statt IPv6 oder Klartext statt SSL. Die Verarbeitung ist immer zustandsbehaftet, und der Rückverkehr muss den Load-Balancer durchlaufen. Der zusätzliche Aufwand kann verhindern, dass Leitungsgeschwindigkeit erreicht wird, besonders bei kleinen Paketen. Dafür bietet das Verfahren viele Möglichkeiten und wird meist vollständig in Software umgesetzt, auch innerhalb von Hardware-Appliances. Es eignet sich sehr gut zur Lastverteilung auf Server.

Paketbasierte Load-Balancer werden meist im Durchleitungsmodus eingesetzt: Sie liegen auf dem normalen Verkehrsweg und lenken Pakete gemäß ihrer Konfiguration um. Der Rückverkehr muss sie nicht zwingend passieren. Wird jedoch die Netzwerkzieladresse geändert, um den Datenverkehr zum richtigen Ziel zu führen, muss der Rückverkehr durch den Load-Balancer laufen. Erlaubt das Routing dies nicht, kann der Load-Balancer zusätzlich die Quelladresse der Pakete durch seine eigene ersetzen und den Rückweg dadurch erzwingen.

Proxy-basierte Load-Balancer werden ohne Architekturänderung als Server mit eigenen IP-Adressen und Ports eingesetzt. Manchmal müssen Anwendungen angepasst werden, damit Clients die IP-Adresse des Load-Balancers statt direkt die des Servers verwenden. Dafür müssen manche Load-Balancer Serverantworten verändern, etwa das HTTP-Headerfeld Location bei HTTP-Weiterleitungen. Einige Proxy-basierte Load-Balancer können auch Datenverkehr für fremde Adressen abfangen und beim Verbindungsaufbau zum Server die Clientadresse verwenden. Dadurch lassen sie sich wie gewöhnliche Router oder Firewalls im Durchleitungsmodus einsetzen, ähnlich paketbasierten Load-Balancern. Dies ist besonders bei Produkten beliebt, die Paket- und Proxy-Modus kombinieren. DSR ist dabei selbstverständlich weiterhin nicht möglich; der Rückverkehr muss zum Load-Balancer geroutet werden.

Ein sehr gut skalierbarer Schichtenaufbau kann mit einem vorgeschalteten Router beginnen, der Datenverkehr über mehrere lastverteilte Verbindungen empfängt. Über ECMP verteilt er diesen auf eine erste Schicht mehrerer zustandsbehafteter, paketbasierter L4-Load-Balancer. Diese L4-Load-Balancer leiten ihn an eine noch größere Anzahl Proxy-basierter L7-Load-Balancer weiter, die den Inhalt auswerten und den endgültigen Zielserver bestimmen.

Mit der Anzahl der Komponenten und möglichen Verkehrswege steigt das Ausfallrisiko. In sehr großen Umgebungen ist es sogar normal, dass ständig einige defekte Komponenten repariert oder ersetzt werden. Lastverteilung ohne Kenntnis des Zustands des gesamten Systems verschlechtert die Verfügbarkeit erheblich. Jeder sinnvoll ausgelegte Load-Balancer prüft deshalb, ob seine Zielkomponenten noch aktiv und erreichbar sind, und sendet keinen Datenverkehr mehr an fehlerhafte Komponenten. Dafür gibt es verschiedene Verfahren.

Am häufigsten werden regelmäßig Prüfanfragen gesendet, um die Funktionsfähigkeit einer Komponente festzustellen. Diese Prüfungen heißen Health Checks und müssen die zu erkennenden Fehler abbilden. Ein Ping erkennt beispielsweise nicht, dass ein Webserver abgestürzt ist und nicht mehr auf einem Port lauscht. Ein Verbindungsversuch zu diesem Port erkennt dies dagegen. Eine weitergehende Anfrage kann sogar prüfen, ob der Server noch funktioniert und auf seine Datenbank zugreifen kann. Health Checks wiederholen die Prüfung oft einige Male, um gelegentliche Messfehler abzufangen. Das Prüfintervall muss kurz genug sein, damit eine fehlerhafte Komponente nach einem Ausfall nicht zu lange weiterverwendet wird.

Andere Verfahren beobachten Stichproben des an ein Ziel gesendeten Produktionsverkehrs und entfernen Komponenten, die unpassende Antworten liefern. Dabei wird allerdings ein Teil des Produktionsverkehrs beeinträchtigt, was nicht immer akzeptabel ist. Die Kombination beider Verfahren verbindet ihre Vorteile: Beide erkennen Fehler, aber nur Health Checks erkennen deren Behebung. Ein weiteres Verfahren nutzt zentrale Zustandsmeldungen. Ein zentraler Überwachungsagent informiert alle Load-Balancer regelmäßig über den Zustand sämtlicher Komponenten. Alle erhalten damit eine Gesamtsicht auf die Infrastruktur, allerdings mitunter weniger genau oder verzögert. Dieses Verfahren eignet sich besonders für Umgebungen mit vielen Load-Balancern und Servern.

Load-Balancer für Schicht 7 müssen außerdem Sitzungspersistenz gewährleisten, auch als Stickiness bezeichnet. Mehrere aufeinanderfolgende Anfragen oder Verbindungen derselben Quelle, etwa eines Endnutzers, müssen dabei meist dasselbe Ziel erreichen. Das bekannteste Beispiel ist der Warenkorb eines Onlineshops. Erzeugt jeder Klick eine neue Verbindung, muss der Nutzer stets zu dem Server gelangen, auf dem sein Warenkorb liegt. Die Auswertung des Inhalts erleichtert es, Merkmale der Anfrage zur Bestimmung des Zielservers zu verwenden, reicht aber nicht immer aus. Wird beispielsweise die Quelladresse als Schlüssel verwendet, kann ein Hash-Verfahren jede IP-Adresse anhand einer Division durch die Anzahl verfügbarer Server stets demselben Server zuordnen. Fällt jedoch ein Server aus, ändert sich das Ergebnis. Plötzlich gelangen alle Nutzer zu einem anderen Server und verlieren ihren Warenkorb. Die Lösung besteht darin, das gewählte Ziel zu speichern und denselben Besucher unabhängig von der Anzahl verfügbarer Server immer dorthin zu leiten. Diese Information kann im Speicher des Load-Balancers liegen und muss bei mehreren Load-Balancern gegebenenfalls repliziert werden. Alternativ kann sie auf verschiedene Weise beim Client gespeichert werden, sofern dieser sie bei jeder Anfrage wieder übermittelt, etwa durch eingefügte Cookies oder eine Weiterleitung auf eine Subdomain. Zusätzlich entfällt damit die Abhängigkeit von instabilen oder ungleich verteilten Merkmalen wie der Quell-IP-Adresse. Dies ist der wichtigste Grund für einen Load-Balancer auf Schicht 7 statt auf Schicht 4.

Um Cookies, das Host-Headerfeld, URLs oder andere Informationen auszulesen, muss ein Load-Balancer SSL/TLS-Datenverkehr möglicherweise entschlüsseln und beim Weiterleiten an den Server wieder verschlüsseln. Dieser hohe Aufwand erklärt, weshalb manche stark ausgelasteten Infrastrukturen sehr viele Load-Balancer benötigen.

Ein Load-Balancer für Schicht 7 führt zahlreiche komplexe Operationen aus, etwa Entschlüsselung, Auswertung und Änderung des Inhalts, Cookie-Abgleich und Serverauswahl. Dabei kann er durchaus Probleme verursachen. Häufig wird er jedoch für Probleme verantwortlich gemacht, die er lediglich sichtbar gemacht hat. Oft stellt sich heraus, dass Server instabil sind und regelmäßig ausfallen, dass Webseiten fest eingebaute Links enthalten, die Clients am Load-Balancer vorbei direkt zu einem bestimmten Server führen, oder dass Server unter hoher Last so langsam antworten, dass Zeitüberschreitungen entstehen. Deshalb ist die Protokollierung bei Lastverteilung auf Schicht 7 äußerst wichtig. Sobald ein Problem gemeldet wird, ist es wichtig zu klären, ob der Load-Balancer falsch entschieden hat und gegebenenfalls warum, damit es nicht erneut passiert.

2 - Was HAProxy ist und wie es funktioniert

Die Schreibweise “HAProxy” bezeichnet das Produkt, “haproxy” dagegen das ausführbare Programm, das Softwarepaket oder einen Prozess. Häufig werden beide Schreibweisen jedoch für beide Bedeutungen verwendet; ausgesprochen werden sie H-A-Proxy. Ursprünglich stand “haproxy” für „High Availability Proxy“, und der Name wurde in zwei getrennten Wörtern geschrieben. Heute bedeutet er ausschließlich “HAProxy”.

3.1. Was HAProxy ist und was nicht

HAProxy ist:

• ein TCP-Proxy: Er nimmt TCP-Verbindungen über einen lauschenden Socket an, verbindet sich mit einem Server und verknüpft beide Sockets für die bidirektionale Datenübertragung. Auf beiden Seiten werden IPv4, IPv6 und sogar UNIX-Sockets unterstützt. Dadurch lassen sich Adressen verschiedener Familien einfach ineinander überführen.

• ein HTTP-Reverse-Proxy, in der HTTP-Terminologie ein „Gateway“: Er tritt als Server auf, empfängt HTTP-Anfragen über Verbindungen eines lauschenden TCP-Sockets und leitet sie über andere Verbindungen an Server weiter. Auf beiden Seiten ist jede Kombination aus HTTP/1.x und HTTP/2 möglich. Bei ALPN über TLS erkennt er das verwendete Protokoll auf jeder Seite automatisch.

• ein System zum Terminieren, Initiieren und Auslagern von SSL: SSL/TLS kann auf der Verbindung vom Client, auf der Verbindung zum Server oder auf beiden verwendet werden. Viele Einstellungen lassen sich je Name über SNI festlegen und ohne Neustart zur Laufzeit ändern. Solche Konfigurationen skalieren sehr gut; es gibt Berichte über Zehntausende bis Hunderttausende eingesetzte Zertifikate.

• ein TCP-Normalisierer: Da das Betriebssystem die Verbindungen lokal terminiert, besteht kein Zusammenhang zwischen beiden Seiten. Ungültige Pakete, Flag-Kombinationen, Fensterankündigungen, Sequenznummern, unvollständige Verbindungen bei SYN-Floods und anderer ungewöhnlicher Datenverkehr gelangen daher nicht auf die Gegenseite. Dies schützt anfällige TCP-Stacks vor Protokollangriffen und erlaubt eine Optimierung der Verbindung zum Client, ohne den TCP-Stack der Server anzupassen.

• ein HTTP-Normalisierer: Bei aktivierter HTTP-Verarbeitung leitet er nur gültige, vollständige Anfragen weiter und schützt damit vor vielen Protokollangriffen. Außerdem korrigiert er Abweichungen, für die die Spezifikation Toleranz vorsieht, etwa mehrzeilige Header, damit sie auf den Servern keine Probleme verursachen.

• ein Werkzeug zur Korrektur von HTTP: Er kann die URL sowie beliebige Anfrage- oder Antwort-Header ändern, korrigieren, ergänzen, entfernen oder umschreiben. Das hilft bei Interoperabilitätsproblemen in komplexen Umgebungen.

• ein inhaltsabhängiger Verteiler: Anhand beliebiger Merkmale einer Anfrage entscheidet er, an welchen Server die Anfrage oder Verbindung geht. So können mehrere Protokolle wie HTTP, HTTPS und SSH über denselben Port verarbeitet werden.

• ein Load-Balancer für Server: Er verteilt TCP-Verbindungen und HTTP-Anfragen. Im TCP-Modus gilt die Entscheidung für die gesamte Verbindung, im HTTP-Modus für jede einzelne Anfrage.

• ein Regler für den Datenverkehr: Er begrenzt Raten an verschiedenen Stellen, schützt Server vor Überlastung und passt Prioritäten anhand des Inhalts an. Durch Paketmarkierungen kann er diese Informationen sogar an niedrigere Schichten und externe Netzwerkkomponenten weitergeben.

• ein Schutz gegen DDoS und Dienstmissbrauch: Er führt zahlreiche Statistiken etwa je IP-Adresse, URL oder Cookie, erkennt Missbrauch und reagiert darauf, indem er Verursacher verlangsamt, blockiert oder auf veraltete Inhalte umleitet.

• ein Beobachtungspunkt für die Netzwerkdiagnose: Die präzisen Protokollangaben werden häufig verwendet, um Netzwerkprobleme einzugrenzen.

• ein System zum Auslagern der HTTP-Komprimierung: Er komprimiert Antworten, die der Server unkomprimiert liefert, und verkürzt dadurch die Ladezeit bei schlechter Anbindung oder in Mobilfunknetzen mit hoher Latenz.

• ein Proxy mit Cache: Er kann Antworten im RAM zwischenspeichern. Solange ein Objekt vorhanden und gültig ist, entfällt bei weiteren Anfragen die erneute Netzwerkübertragung vom Server. Auf dauerhaftem Speicher legt er jedoch keine Objekte ab. Diese Cache-Funktion ist wartungsfrei ausgelegt und soll ausschließlich die wertvollen Ressourcen von haproxy schonen, nicht die des Servers. Caches zur Serveroptimierung benötigen erheblich mehr Einstellmöglichkeiten und Flexibilität. Wird ein solcher umfassender Cache benötigt, sollte Varnish Cache verwendet werden. Es lässt sich besonders bei SSL/TLS auf einer der beiden Seiten hervorragend mit haproxy kombinieren.

• ein FastCGI-Gateway: FastCGI lässt sich als andere Darstellung von HTTP auffassen. HAProxy kann deshalb die Last direkt auf eine beliebige Kombination von FastCGI-Anwendungsservern verteilen, ohne eine weitere Gateway-Schicht einzufügen. Das spart Ressourcen und senkt den Wartungsaufwand.

HAProxy ist nicht:

• ein expliziter HTTP-Proxy, über den Browser auf das Internet zugreifen. Dafür gibt es sehr gute Open-Source-Programme wie Squid. HAProxy kann jedoch davor eingesetzt werden, um Lastverteilung und Hochverfügbarkeit bereitzustellen.

• ein Werkzeug zur Bereinigung von Daten: Es ändert weder Anfrage- noch Antwortkörper.

• ein Server für statische Webseiten: Beim Start isoliert es sich in einer chroot-Umgebung und gibt Berechtigungen ab. Danach greift es nicht mehr auf das Dateisystem zu und kann deshalb nicht als statischer Webserver eingesetzt werden. Dynamische Server werden jedoch über FastCGI unterstützt. Für statische Inhalte gibt es sehr gute Open-Source-Programme wie Apache oder NGINX. HAProxy lässt sich einfach davor einsetzen, um Lastverteilung, Hochverfügbarkeit und Beschleunigung bereitzustellen.

• ein paketbasierter Load-Balancer: Es sieht weder IP-Pakete noch UDP-Datagramme und führt weder NAT noch DSR aus. Das sind Aufgaben niedrigerer Schichten. Kernel-Komponenten wie IPVS, Linux Virtual Server, erledigen dies bereits sehr gut und ergänzen HAProxy hervorragend.

3.2. Wie HAProxy arbeitet

HAProxy arbeitet ereignisgesteuert und nicht blockierend. Es verbindet eine sehr schnelle I/O-Schicht mit einem prioritätsgesteuerten Scheduler für mehrere Threads. Seine auf Datenweiterleitung ausgerichtete Architektur bewegt Daten mit möglichst wenigen Operationen so schnell wie möglich. Um CPU-Caches effizient zu nutzen, bleiben Verbindungen möglichst lange derselben CPU zugeordnet. Ein Schichtenmodell mit Umgehungsmöglichkeiten auf jeder Ebene sorgt dafür, dass Daten höhere Ebenen nur bei Bedarf erreichen. Der Großteil der Verarbeitung findet im Kernel statt. HAProxy unterstützt ihn dabei durch Hinweise und verzichtet auf manche Operationen, wenn sie voraussichtlich später zusammengefasst werden können. Typischerweise entfallen daher im TCP- oder HTTP-Close-Modus 15% der Verarbeitungszeit auf HAProxy und 85% auf den Kernel; im HTTP-Keep-Alive-Modus sind es etwa 30% für HAProxy und 70% für den Kernel.

Ein einzelner Prozess kann viele Proxy-Instanzen ausführen. Berichten zufolge funktionieren selbst Konfigurationen mit 300000 verschiedenen Proxys in einem Prozess problemlos. Ein System mit einer CPU und einem Kern reicht für mehr als 99% der Nutzer deutlich aus. Für Container und virtuelle Maschinen werden deshalb die kleinstmöglichen Images empfohlen, um Betriebskosten zu sparen und die Fehlerbehebung zu vereinfachen. Der Rechner, auf dem HAProxy läuft, darf jedoch niemals auslagern. Seine CPU darf weder künstlich gedrosselt werden, etwa durch Zuweisung eines CPU-Anteils im Hypervisor, noch mit rechenintensiven Prozessen geteilt werden, die eine hohe Latenz bei Kontextwechseln verursachen.

Mit einem Thread pro CPU-Kern kann HAProxy die gesamte verfügbare Rechenleistung nutzen. Dies ist vor allem für SSL oder Weiterleitungsraten über 40 Gbps hilfreich. Dabei muss Kommunikation zwischen mehreren physischen CPUs unbedingt vermieden werden, da sie starke Engpässe im Netzwerk-Stack und in HAProxy selbst verursachen kann. Auch wenn es zunächst widersprüchlich erscheint, sollte bei Leistungsproblemen oft zuerst die Anzahl der von HAProxy verwendeten CPUs reduziert werden.

Zum Betrieb benötigt HAProxy nur die ausführbare Datei haproxy und eine Konfigurationsdatei. Für die Protokollierung werden ein korrekt eingerichteter syslog-Daemon und eine Protokollrotation dringend empfohlen. Protokolle können auch an stdout/stderr gesendet werden, was in Containern nützlich ist. HAProxy liest die Konfigurationsdateien vor dem Start ein und versucht anschließend, alle lauschenden Sockets zu binden. Scheitert etwas, verweigert er den Start. Danach kann HAProxy nicht mehr fehlschlagen. Es treten also keine Laufzeitfehler auf: Wenn HAProxy startet, arbeitet es, bis es gestoppt wird.

Nach dem Start erledigt HAProxy genau 3 Aufgaben:

• eingehende Verbindungen verarbeiten;

• regelmäßig den Zustand der Server prüfen, die sogenannten Health Checks;

• Informationen mit anderen haproxy-Knoten austauschen.

Die Verarbeitung eingehender Verbindungen ist wegen der vielen Konfigurationsmöglichkeiten mit Abstand die komplexeste Aufgabe. Sie lässt sich aber in die folgenden 9 Schritte zusammenfassen:

• Eingehende Verbindungen über lauschende Sockets annehmen. Diese gehören zu einer Konfigurationseinheit namens “frontend”, die eine oder mehrere lauschende Adressen referenziert;

• die Regeln des Frontends auf diese Verbindungen anwenden. Dabei können Verbindungen blockiert, Header geändert oder Verbindungen für interne Applets wie die Statistikseite oder CLI abgefangen werden;

• die eingehenden Verbindungen an eine weitere Konfigurationseinheit namens “backend” übergeben. Sie stellt eine Serverfarm dar und enthält deren Serverliste und Lastverteilungsstrategie;

• die Regeln des Backends auf diese Verbindungen anwenden;

• anhand der Lastverteilungsstrategie den Zielserver für die Verbindung wählen;

• die Regeln des Backends auf die Antwortdaten anwenden;

• die Regeln des Frontends auf die Antwortdaten anwenden;

• den Ablauf detailliert protokollieren;

• bei HTTP zum zweiten Schritt zurückkehren und auf eine neue Anfrage warten, andernfalls die Verbindung schließen.

Frontends und Backends werden manchmal als halbe Proxys betrachtet, weil sie jeweils nur eine Seite einer durchgehenden Verbindung abdecken: Das Frontend kümmert sich um die Clients, das Backend um die Server. HAProxy unterstützt außerdem vollständige Proxys, die Frontend und Backend exakt vereinen. Für HTTP wird die Konfiguration meist in Frontends und Backends aufgeteilt. Da jedes Frontend eine Verbindung an jedes Backend übergeben kann, eröffnet dies viele Möglichkeiten. Bei reinen TCP-Proxys bringt diese Trennung selten Vorteile; vollständige Proxys können die Konfiguration dann übersichtlicher machen.

3 - Grundfunktionen

Dieser Abschnitt beschreibt Funktionen von HAProxy. Manche werden von jedem modernen Load-Balancer erwartet, andere ergeben sich unmittelbar aus der Architektur von HAProxy. Weitergehende Funktionen behandelt der nächste Abschnitt.

3.3.1. Grundfunktionen: Proxy-Betrieb

Im Proxy-Betrieb werden Daten über zwei unabhängige Verbindungen zwischen Client und Server übertragen. Dafür und für die Verbindungsverwaltung unterstützt HAProxy folgende Grundfunktionen:

• Eine bereinigte Verbindung zum Server schützt ihn vor Fehlern und Angriffen auf der Clientseite;

• Lauschen auf mehreren IP-Adressen und/oder Ports, auch auf Portbereichen;

• transparentes Annehmen: Abfangen von Datenverkehr für beliebige IP-Adressen, die nicht einmal zum lokalen System gehören müssen;

• der Serverport muss nicht dem lauschenden Port entsprechen. Er kann auch um einen festen Wert verschoben werden, was bei Portbereichen nützlich ist;

• transparenter Verbindungsaufbau: Beim Verbinden mit dem Server kann bei Bedarf die IP-Adresse des Clients oder eine beliebige andere verwendet werden;

• Bereitstellung einer zuverlässigen IP-Adresse für den Rückweg bei Load-Balancern (LBs) an mehreren Standorten;

• Entlastung der Server durch Puffer und gegebenenfalls kurzlebige Verbindungen, wodurch die Zahl gleichzeitiger Verbindungen und der Speicherbedarf sinken;

• Optimierung von TCP-Stacks, etwa SACK, und der Überlastungssteuerung sowie Verringerung der Auswirkungen der RTT;

• Unterstützung unterschiedlicher Protokollfamilien auf beiden Seiten, etwa IPv4/IPv6/Unix;

• Durchsetzung von Zeitüberschreitungen auf mehreren Ebenen je nach Verbindungsphase, damit ausgefallene Clients oder Server sowie Angreifer Ressourcen nicht zu lange belegen;

• Protokollprüfung: HTTP, SSL oder Nutzdaten werden untersucht. Ungültige Protokollelemente werden zurückgewiesen, sofern ihre Annahme nicht ausdrücklich angeordnet wurde;

• Durchsetzung von Richtlinien, damit nur erlaubter Datenverkehr weitergeleitet wird;

• eingehende und ausgehende Verbindungen können auf bestimmte Netzwerk-Namespaces beschränkt werden, nur unter Linux. So lässt sich leicht ein mandantenfähiger Load-Balancer für mehrere Container aufbauen;

• das PROXY-Protokoll übermittelt die Client-IP-Adresse auch bei Nicht-HTTP-Datenverkehr an den Server. Diese HAProxy-Erweiterung wurde inzwischen von mehreren Drittanbieterprodukten übernommen, zum Zeitpunkt der Erstellung mindestens von folgenden:

  • Client: haproxy, stud, stunnel, exaproxy, ELB, squid
  • Server: haproxy, stud, postfix, exim, NGINX, squid, node.js, varnish

3.3.2. Grundfunktionen: SSL

Nach Einschätzung von Google-Ingenieuren zählt der SSL-Stack von HAProxy zu den funktionsreichsten (http://istlsfastyet.com/ ). Zu den häufig genutzten Funktionen gehören:

• Leistungsfähiges SNI-basiertes Hosting mehrerer Websites ohne Begrenzung ihrer Anzahl. Mindestens eine bekannte Installation betreibt 50000 Domains mit eigenen Zertifikaten;

• Wildcard-Zertifikate verringern die Anzahl benötigter Zertifikate;

• zertifikatsbasierte Clientauthentifizierung mit konfigurierbaren Regeln für den Fall, dass kein gültiges Zertifikat vorgelegt wird. So kann beispielsweise eine andere Serverfarm bereitgestellt werden, über die das Clientzertifikat erneuert wird;

• die Authentifizierung des Backend-Servers stellt sicher, dass tatsächlich der richtige Server und kein zwischengeschalteter Angreifer angesprochen wird;

• die Authentifizierung gegenüber dem Backend-Server bestätigt diesem, dass sich der erwartete haproxy-Knoten verbindet;

• die TLS-Erweiterungen NPN und ALPN ermöglichen es, die Verarbeitung von SPDY/HTTP2-Verbindungen zuverlässig auszulagern und die Daten unverschlüsselt an Backend-Server weiterzugeben;

• OCSP-Stapling verkürzt die erste Seitenladezeit weiter, indem eine OCSP-Antwort direkt mitgeliefert wird, wenn der Client eine Certificate Status Request anfordert;

• dynamische Record-Größen bieten zugleich hohe Leistung und geringe Latenz. Sie verkürzen die Seitenladezeit deutlich, da der Browser bereits weitere Objekte abrufen kann, während noch Pakete unterwegs sind;

• alle relevanten Informationen der SSL/TLS-Schicht stehen jederzeit für Protokollierung, Zugriffskontrolle, Berichte und andere Zwecke bereit. Sie können in HTTP-Header oder als PROXY-Protokollerweiterung eingebettet werden. Der entlastete Server erhält damit alle Informationen, die er auch bei eigener SSL-Terminierung hätte.

• bestimmte bekannte Angriffe werden selbst bei anfälligen SSL-Bibliotheken erkannt, protokolliert und blockiert, etwa Heartbleed gegen bestimmte OpenSSL-Versionen.

• zustandslose Sitzungswiederaufnahme nach RFC 5077 mit der TLS-Ticket-Erweiterung. TLS-Tickets können über die CLI aktualisiert werden. Häufiger Ticketwechsel ermöglicht damit Perfect Forward Secrecy.

3.3.3. Grundfunktionen: Überwachung

HAProxy legt großen Wert auf Verfügbarkeit. Deshalb überwacht es den Serverzustand und meldet anderen Netzwerkkomponenten seinen eigenen Zustand:

• Der Serverzustand wird kontinuierlich mit serverspezifischen Parametern überwacht. Damit wird geprüft, ob der Weg zum Server für gewöhnlichen Datenverkehr funktioniert;

• Health Checks verwenden getrennte Hysteresen für den Wechsel in den verfügbaren und den ausgefallenen Zustand, um ständige Zustandswechsel zu vermeiden;

• Prüfungen können eine andere Adresse, einen anderen Port oder ein anderes Protokoll verwenden. So lässt sich ein einzelner Dienst prüfen, der als repräsentativ für mehrere Dienste gilt, etwa der HTTPS-Port eines HTTP+HTTPS-Servers.

• Server können den Zustand anderer Server übernehmen und gleichzeitig als ausgefallen gelten. Dadurch können Server mit mehreren Diensten als Ganzes aus der Verteilung genommen werden, und niemand gelangt zu einem nur teilweise funktionsfähigen Server;

• Agenten auf dem Server können Last und Zustand überwachen. Ein Server kann seine Last, seinen Betriebszustand und seinen administrativen Zustand unabhängig von den Health Checks melden. Ein einfacher Agent ermöglicht es, diese Selbsteinschätzung zusätzlich zu den Prüfungen des gesamten Zugriffswegs zu berücksichtigen;

• verschiedene Prüfverfahren stehen zur Verfügung: TCP-Verbindungsaufbau, HTTP-Anfrage, SMTP-Hello, SSL-Hello, LDAP, SQL, Redis und send/expect-Skripte, jeweils mit oder ohne SSL;

• Zustandsänderungen erscheinen mit Fehlerursache in den Protokollen und auf der Statistikseite, etwa mit der beim Erkennen des Fehlers empfangenen HTTP-Antwort. Außerdem kann eine E-Mail an eine konfigurierbare Adresse gesendet werden;

• die Statistikschnittstelle meldet ebenfalls den Serverzustand. Er kann für Routingentscheidungen genutzt werden, um den Datenverkehr je nach Größe und/oder Zustand auf verschiedene Farmen zu verteilen, etwa beim Ausfall einer Verbindung zwischen Rechenzentren (DC);

• HAProxy kann über Health-Check-Anfragen Informationen wie Servernamen, Gewicht oder Anzahl anderer Server der Farm übermitteln. Die Server können damit ihre Antworten und Entscheidungen anpassen, beispielsweise Backups verschieben, um mehr CPU-Leistung freizuhalten;

• Server können über Health Checks mehr als nur „an“ oder „aus“ melden, etwa den Wunsch, herunterzufahren und deshalb keine neuen Besucher mehr zu erhalten;

• HAProxy selbst kann externen Komponenten wie Routern oder anderen Load-Balancern seinen Zustand melden. So lassen sich umfassende Infrastrukturen mit mehreren Pfaden und Schichten aufbauen.

3.3.4. Grundfunktionen: Hochverfügbarkeit

Wie jeder für den ernsthaften Einsatz ausgelegte Load-Balancer legt HAProxy großen Wert auf Verfügbarkeit, um eine möglichst hohe Dienstkontinuität zu gewährleisten:

• Nur funktionsfähige Server werden verwendet; die übrigen werden automatisch aus den Serverfarmen ausgeschlossen. Unter bestimmten Bedingungen kann ihre Verwendung dennoch erzwungen werden;

• geordnetes Herunterfahren erlaubt es, Server ohne Beeinträchtigung bestehender Verbindungen aus einer Farm zu nehmen;

• fallen aktive Server aus, übernehmen automatisch Backup-Server. So gehen Sitzungen nach Möglichkeit nicht verloren. Dies ermöglicht außerdem mehrere Wege zum selben Server, etwa über verschiedene Schnittstellen;

• fallen zu viele Server aus, kann für die gesamte Farm ein Fehlerzustand gemeldet werden. Zusammen mit den Überwachungsfunktionen kann eine vorgeschaltete Komponente dadurch für einen Dienst einen anderen Load-Balancer-Knoten (LB) wählen;

• die zustandslose Architektur erleichtert den Clusteraufbau. HAProxy gewährleistet möglichst hohe Dienstkontinuität, ohne Informationen speichern zu müssen, die bei einem Ausfall verloren gehen könnten. Eine Übernahme erfolgt dadurch möglichst nahtlos;

• gute Integration mit dem üblichen VRRP-Daemon keepalived: HAProxy meldet ihm problemlos seinen Zustand und unterstützt wechselnde virtuelle IP-Adressen sehr gut. Hinweis: Ausschließlich IP-Redundanzprotokolle wie VRRP/CARP anstelle von Cluster-Lösungen wie Heartbeat verwenden. Sie bieten den schnellsten, nahtlosesten und zuverlässigsten Switchover.

3.3.5. Grundfunktionen: Lastverteilung

HAProxy bietet umfangreiche Funktionen zur Lastverteilung, die leider bei vielen anderen Produkten fehlen:

• Mindestens 10 Lastverteilungsverfahren werden unterstützt. Manche verwenden Eingabedaten und eröffnen dadurch unbegrenzt viele Möglichkeiten. Häufig verwendet werden round-robin, das bei kurzen Verbindungen reihum jeden Server auswählt; leastconn, das bei langen Verbindungen unter den Servern mit der kleinsten Verbindungszahl den am längsten nicht verwendeten auswählt; source, das für SSL- oder Terminalserver-Farmen direkt von der Clientquelladresse abhängt; URI, das für HTTP-Caches direkt die HTTP-URI verwendet; hdr, das den Inhalt eines bestimmten HTTP-Headerfelds verwendet; und first, das bei kurzlebigen virtuellen Maschinen alle Verbindungen auf möglichst wenige Server konzentriert, damit ungenutzte Server ausgeschaltet werden können;

• alle genannten Verfahren unterstützen serverspezifische Gewichte. So können verschiedene Servergenerationen in einer Farm kombiniert oder kleine Anteile des Datenverkehrs gezielt an bestimmte Server gesendet werden, etwa für Diagnosezwecke oder eine neue Softwareversion;

• round-robin, leastconn und konsistentes Hashing unterstützen dynamische Gewichte. Diese können zur Laufzeit über die CLI oder sogar durch einen Agenten auf dem Server geändert werden;

• überall dort, wo dynamische Gewichte unterstützt werden, ist auch slow-start verfügbar. Damit übernimmt ein Server schrittweise Datenverkehr. Dies ist wichtig für empfindliche Anwendungsserver, die Klassen zur Laufzeit kompilieren müssen, sowie für kalte Caches, die vor der vollen Auslastung zunächst gefüllt werden müssen;

• Hashing kann unter anderem die Clientquelladresse, URL-Bestandteile, Elemente der Abfragezeichenfolge, Headerfeldwerte, POST-Parameter oder RDP-Cookies verwenden;

• konsistentes Hashing verhindert eine umfangreiche Neuverteilung, wenn Server zur Farm hinzugefügt oder daraus entfernt werden. Das ist für große Cache-Farmen besonders wichtig und ermöglicht die schrittweise Füllung kalter Caches mit slow-start;

• interne Messwerte wie Verbindungszahlen je Server und Backend oder freie Verbindungsplätze eines Backends ermöglichen sehr ausgefeilte Lastverteilungsstrategien.

3.3.6. Grundfunktionen: Sitzungspersistenz

Lastverteilung für Anwendungen wäre ohne Sitzungspersistenz nutzlos. HAProxy bietet umfassende Möglichkeiten, Besucher auch beim Hinzufügen oder Entfernen von Servern sowie bei Ausfällen und Wiederanläufen demselben Server zuzuordnen. Einige Verfahren kommen ohne Replikation aus und funktionieren deshalb auch bei weit voneinander entfernten Load-Balancer-Knoten:

• Informationen zur Sitzungspersistenz können bei Bedarf an unterschiedlichen Stellen abgeglichen und erlernt werden. Beispielsweise kann JSESSIONID sowohl in einem Cookie als auch in der URL abgeglichen werden. Bis zu 8 Quellen können gleichzeitig erlernt werden; jede kann auf eine andere Stick Table verweisen;

• Persistenzinformationen können aus beliebigen sichtbaren Merkmalen einer Anfrage oder Antwort stammen, etwa Quelladresse, Position und Länge von TCP-Nutzdaten, HTTP-Abfrageparametern, Headerfeldwerten oder Cookies.

• Stick Tables werden im Multi-Master-Verfahren zwischen allen Knoten repliziert;

• häufig benötigte Merkmale wie SSL-ID oder RDP-Cookies für TSE-Farmen sind direkt zugänglich und dadurch einfach zu verwenden;

• alle Persistenzregeln können dynamisch durch ACLs bedingt werden;

• bestimmte Server, etwa Backup-Server, können von der dauerhaften Zuordnung ausgeschlossen werden. Sobald der reguläre Server wieder verfügbar ist, übernimmt er die Last automatisch zurück. Dies wird häufig in Umgebungen mit mehreren Pfaden eingesetzt;

• bei HTTP wird häufig auf das Erlernen verzichtet und stattdessen ein eigenes Persistenz-Cookie verwendet. Es kann erkannt, umgeschrieben, eingefügt oder mit einem Präfix versehen werden, damit sich der Client den zugewiesenen Server merkt;

• der Server kann das Persistenz-Cookie bei der Abmeldung ändern oder löschen. Besucher, die die Anwendung verlassen, werden dadurch automatisch vom Server gelöst;

• ACL-Regeln können die Sitzungspersistenz unabhängig vom Serverzustand gezielt ignorieren oder erzwingen. Zusammen mit erweiterten Health Checks lässt sich so prüfen, ob ein gerade eingerichteter Server funktioniert, bevor er öffentlich freigegeben wird;

• ein neuartiges Verfahren begrenzt die maximale Leerlaufzeit und Gesamtdauer von Cookies. So kann die Persistenz auch auf nie ausgeschalteten Geräten wie Smartphones, TV-Geräten und Haushaltsgeräten geordnet beendet werden, ohne die Cookies dauerhaft speichern zu müssen;

• mehrere Servereinträge können dieselben Persistenzschlüssel verwenden. Dadurch bleibt die Zuordnung in Umgebungen mit mehreren Pfaden erhalten, wenn ein Pfad ausfällt;

• soft-stop sorgt dafür, dass nur Nutzer mit vorhandenen Persistenzinformationen weiterhin ihren zugewiesenen Server erreichen. Neue Nutzer gelangen nicht mehr dorthin.

3.3.7. Grundfunktionen: Protokollierung

Die Protokollierung ist für einen Load-Balancer äußerst wichtig. Einerseits wird er oft zu Unrecht für Probleme verantwortlich gemacht, die er lediglich sichtbar macht. Andererseits sitzt er an einem zentralen Punkt der Infrastruktur, an dem normale und ungewöhnliche Aktivitäten ausgewertet und mit anderen Komponenten in Beziehung gesetzt werden müssen.

HAProxy erstellt sehr detaillierte Protokolle mit Millisekundengenauigkeit und dem genauen Zeitpunkt der Verbindungsannahme. Dieser lässt sich in Firewall-Protokollen wiederfinden, etwa zur NAT-Zuordnung. Schon standardmäßig enthalten TCP- und HTTP-Protokolle alle wesentlichen Angaben zur Fehlerbehebung: Quell-IP-Adresse und -Port, Frontend, Backend, Server, Zeitmessungen für Anfrageempfang, Warteschlange, Verbindungsaufbau, Antwort-Header und Datenübertragung, globalen Prozesszustand, Verbindungszahlen, Warteschlangenzustand, Anzahl der Wiederholungsversuche, genaue Persistenzaktionen, Gründe für Verbindungsabbrüche und erfasste Header mit sicherer Ausgabekodierung. Das Format lässt sich erweitern oder ersetzen, um beliebige abgerufene Daten, Variablen und erfasste Werte aufzunehmen. So können etwa die kumulierte Anzahl von Anfragen oder die Anzahl verschiedener von einem Client besuchter URLs protokolliert werden.

Die Protokollstufe kann mit gewöhnlichen ACLs je Anfrage angepasst werden. So lassen sich störende Meldungen automatisch unterdrücken und bei ungewöhnlichem Verhalten eines kleinen Teils des Datenverkehrs stattdessen Warnungen ausgeben, etwa bei zu vielen URLs oder HTTP-Fehlern einer Quelladresse. Verwaltungsereignisse werden ebenfalls mit eigenen Stufen protokolliert, beispielsweise der Ausfall oder die Wiederherstellung eines Servers.

Jedes Frontend und Backend kann mehrere unabhängige Protokollziele verwenden, was den Mandantenbetrieb erleichtert. Meldungen werden vorzugsweise über UDP gesendet, gegebenenfalls JSON-kodiert. Zur Sicherstellung der Zustellung werden sie nach einer konfigurierbaren Zeilenlänge abgeschnitten. Alternativ können sie an stdout/stderr, einen beliebigen Dateideskriptor oder einen Ringpuffer gesendet werden, den ein Client zum Abrufen der Meldungen abonnieren kann.

3.3.8. Grundfunktionen: Statistiken

HAProxy bietet eine webbasierte Statistikschnittstelle mit Authentifizierung, Sicherheitsstufen und Geltungsbereichen. Jeder Hosting-Kunde kann so eine eigene Seite erhalten, die nur seine Instanzen zeigt. Diese Seite kann unter einer verborgenen URL der regulären Website liegen, sodass kein zusätzlicher Port geöffnet werden muss. Sie kann auch die Verfügbarkeit anderer HAProxy-Knoten anzeigen, damit auf einen Blick erkennbar ist, ob alles wie erwartet funktioniert. Die Übersicht bietet zahlreiche Details, etwa Fehlerursachen, Zeit seit dem letzten Zugriff oder der letzten Änderung. Die Daten sind auch als CSV-Tabelle verfügbar, die andere Werkzeuge zur Diagrammerstellung importieren können. Die Seite kann sich automatisch aktualisieren und als Überwachungsanzeige auf einem großen Bildschirm dienen. Im Administrationsmodus lässt sich außerdem der Serverzustand ändern, um Wartungsarbeiten zu erleichtern.

Zusätzlich steht ein Prometheus-Exporter bereit, damit die Statistiken je nach Bereitstellung in einem anderen Format genutzt werden können.

4 - Standardfunktionen

Dieser Abschnitt stellt einige Funktionen vor, die in HAProxy sehr häufig verwendet werden, aber nicht unbedingt in anderen Load-Balancern vorhanden sind.

3.4.1. Standardfunktionen: Informationen abrufen und konvertieren

HAProxy unterstützt den Abruf von Informationen mit zahlreichen „Sample-Abruffunktionen“. Dabei werden einzelne Informationen, sogenannte Samples, zur unmittelbaren Verwendung extrahiert. Dies dient der Sitzungsbindung, dem Aufbau von Bedingungen, der Ausgabe von Informationen in Protokollen oder der Ergänzung von HTTP-Headern.

Samples lassen sich aus verschiedenen Quellen abrufen:

• Konstanten: Ganzzahlen, Zeichenketten, IP-Adressen, Binärblöcke;

• dem Prozess: Datum, Umgebungsvariablen, Zustand von Server/Frontend/Backend/Prozess, Byte- und Verbindungszähler sowie -raten, Warteschlangenlänge, Zufallsgenerator, …

• Variablen: Variablen je Sitzung, Anfrage oder Antwort;

• der Clientverbindung: Quell- und Zieladressen sowie -ports und alle zugehörigen Statistikzähler;

• der SSL-Clientsitzung: Protokoll, Version, Algorithmus, Cipher, Schlüssellänge, Sitzungs-ID, alle Felder der Client- und Serverzertifikate, Zertifikatsseriennummer, SNI, ALPN, NPN, Unterstützung bestimmter Erweiterungen durch den Client;

• dem Inhalt der Anfrage- und Antwortpuffer: beliebige Nutzdaten anhand von Offset und Länge, Datenlänge, RDP-Cookie, Dekodierung des SSL-Hello-Typs, Dekodierung von TLS-SNI;

• HTTP (Anfrage und Antwort): Methode, URI, Pfad, Query-String-Argumente, Statuscode, Header-Werte, Header-Wert an einer bestimmten Position, Cookies, erfasste Werte, Authentifizierung, Elemente des Nachrichtenkörpers;

Ein Sample kann anschließend mehrere Operatoren, sogenannte „Konverter“, zur Umwandlung durchlaufen. Ein Konverter nimmt ein Sample entgegen und erzeugt ein neues, möglicherweise mit einem völlig anderen Typ. Beispielsweise kann ein Konverter nur die ganzzahlige Länge der Eingabezeichenkette zurückgeben oder eine Zeichenkette in Großbuchstaben umwandeln. Vor der endgültigen Verwendung eines Samples lassen sich beliebig viele Konverter nacheinander anwenden. Von den verfügbaren Sample-Konvertern werden folgende besonders häufig verwendet:

• Arithmetische und logische Operatoren ermöglichen komplexe Berechnungen mit den Eingabedaten, etwa Verhältnisse und Prozentsätze oder einfache Umrechnungen zwischen Einheiten;

• IP-Adressmasken sind nützlich, um Adressen zu größeren Netzen zusammenzufassen;

• Datendarstellung: URL-Dekodierung, base64, hex, JSON-Zeichenketten, Hashing;

• Zeichenkettenumwandlung: Teilzeichenketten an festen Positionen und mit fester Länge extrahieren, bestimmte Felder anhand von Trennzeichen oder bestimmte Wörter extrahieren, Groß-/Kleinschreibung ändern, Ersetzungen anhand regulärer Ausdrücke vornehmen;

• Datumsumwandlung: in das HTTP-Datumsformat konvertieren, Ortszeit in UTC umrechnen und umgekehrt, einen Offset addieren oder subtrahieren;

• einen Eintrag in einer Stick Table nachschlagen, um Statistiken oder den zugewiesenen Server zu ermitteln;

• einen Schlüssel anhand einer Map-Datei in einen Wert umwandeln (vor allem für Geolokalisierung).

3.4.2. Standardfunktionen: Maps

Maps sind leistungsfähige Konverter: Beim Start wird eine Datei mit zwei Spalten in den Speicher geladen. Anschließend wird jedes Eingabe-Sample in der ersten Spalte gesucht. Wird der Eintrag gefunden, liefert die Map das zugehörige Muster aus der zweiten Spalte, andernfalls einen Standardwert. Die Ausgabe ist ebenfalls ein Sample und lässt sich daher weiter umwandeln, auch durch zusätzliche Map-Abfragen. Maps werden am häufigsten eingesetzt, um die IP-Adresse eines Clients einer AS-Nummer oder einem Ländercode zuzuordnen, da sie für Netzwerkadressen die längste Übereinstimmung unterstützen. Sie lassen sich aber auch für zahlreiche andere Zwecke verwenden.

Eine ihrer Stärken ist die Aktualisierbarkeit im laufenden Betrieb: über die CLI oder über bestimmte Aktionen, die andere Samples verwenden. Damit können Maps Informationen zwischen aufeinanderfolgenden Zugriffen speichern und wieder abrufen. Eine weitere Stärke ist die Indexierung mit Binärbäumen. Dadurch bleiben sie selbst mit Hunderttausenden von Einträgen äußerst schnell, sodass sich Geolokalisierung mit geringem Aufwand und Ressourcenbedarf einrichten lässt.

3.4.3. Standardfunktionen: ACLs und Bedingungen

Die meisten Vorgänge in HAProxy können an Bedingungen geknüpft werden. Bedingungen entstehen durch Verknüpfen mehrerer ACLs mit logischen Operatoren (AND, OR, NOT). Jede ACL besteht aus einer Reihe von Prüfungen mit folgenden Elementen:

• einer Sample-Abrufmethode, die das zu prüfende Element abruft;

• einer optionalen Folge von Konvertern, die das Element umwandeln;

• einer Liste von Mustern für den Abgleich;

• einer Abgleichmethode, die festlegt, wie die Muster mit dem Sample verglichen werden

Beispielsweise kann das Sample aus dem HTTP-Header “Host” stammen, dann in Kleinbuchstaben umgewandelt und schließlich mit der Methode für reguläre Ausdrücke gegen mehrere entsprechende Muster geprüft werden.

Technisch basieren ACLs und Maps auf demselben Kern. Sie verwenden genau dieselbe interne Struktur und dieselben Musterabgleichmethoden und bieten dieselbe Leistung. Der einzige wesentliche Unterschied ist, dass ACLs statt eines Samples lediglich „gefunden“ oder „nicht gefunden“ zurückgeben. ACL-Muster können direkt in der Konfigurationsdatei angegeben werden und benötigen keine eigene Datei. ACLs lassen sich benennen, um ihre Verwendung zu vereinfachen oder Konfigurationen verständlicher zu machen. Eine benannte ACL kann mehrmals definiert werden; ihre Definitionen werden nacheinander ausgewertet, bis eine davon zutrifft.

Es stehen etwa 13 verschiedene Musterabgleichmethoden bereit, darunter IP-Adressmasken, Ganzzahlbereiche, Teilzeichenketten und reguläre Ausdrücke. Sie arbeiten wie Funktionen. Wie in einer Programmiersprache wird nur das Nötige ausgewertet: Ist eine mit OR verknüpfte Bedingung bereits wahr, werden die folgenden nicht mehr ausgewertet. Ist eine mit AND verknüpfte Bedingung bereits falsch, wird der Rest der Bedingung ebenfalls nicht mehr ausgewertet.

Die Anzahl definierter ACLs ist praktisch unbegrenzt; einige häufig verwendete ACLs sind bereits vorgegeben. Die Erfahrung zeigt jedoch, dass die Fehlerbehebung bei Konfigurationen mit vielen benannten ACLs recht schwierig ist. Mitunter sind anonyme, direkt angegebene ACLs einfacher, weil weniger Verweise außerhalb des gerade untersuchten Abschnitts verfolgt werden müssen.

3.4.4. Standardfunktionen: Inhaltsabhängige Weiterleitung

HAProxy unterstützt einen Mechanismus zur inhaltsabhängigen Weiterleitung. Eine Verbindung oder Anfrage trifft an einem Frontend ein, und die darin enthaltenen Informationen werden verarbeitet. Mit ACL-basierten Bedingungen lässt sich anhand dieser Informationen entscheiden, welches Backend die Anfrage bearbeitet. Der Datenverkehr wird somit je nach Anfrageinhalt an das eine oder andere Backend geleitet. Am häufigsten wird anhand des Host-Headers und/oder von Pfadbestandteilen (Unterverzeichnissen oder Dateiendungen) entschieden, ob eine HTTP-Anfrage ein statisches Objekt oder die Anwendung betrifft. Zugriffe auf statische Objekte gehen an ein Backend mit schnellen, schlanken Servern, alle übrigen an einen komplexeren Anwendungsserver. So entsteht eine fein abgestufte Lösung für virtuelles Hosting. Damit können mehrere Technologien bequem innerhalb einer Gesamtlösung zusammenarbeiten.

Ein weiterer Anwendungsfall der inhaltsabhängigen Weiterleitung ist die Wahl verschiedener Lastverteilungsalgorithmen anhand unterschiedlicher Kriterien. Ein Cache kann beispielsweise einen URI-Hash verwenden, während eine Anwendung Round-Robin nutzt.

Außerdem können mehrere Kunden jeweils einen kleinen Anteil einer gemeinsamen Ressource nutzen, indem Verbindungsgrenzen je Backend und damit je Kunde durchgesetzt werden.

Regeln zur inhaltsabhängigen Weiterleitung skalieren sehr gut, wobei ihre Leistung von Anzahl und Komplexität der verwendeten ACLs abhängen kann. Es lassen sich aber auch dynamische Regeln schreiben, bei denen ein Sample-Wert unmittelbar zum Backend-Namen wird und überhaupt keine ACLs nötig sind. Solche Konfigurationen funktionieren Berichten zufolge im Produktivbetrieb mit mindestens 300000 Backends problemlos.

3.4.5. Standardfunktionen: Stick Tables

Stick Tables speichern üblicherweise Informationen zur Sitzungsbindung, also einen Verweis auf den Server, an den ein bestimmter Besucher geleitet wurde. Als Schlüssel dient die dem Besucher zugeordnete Kennung (seine Quelladresse, die SSL-ID der Verbindung, ein HTTP- oder RDP-Cookie, die aus der URL oder den Nutzdaten extrahierte Kundennummer, …). Der gespeicherte Wert ist die Kennung des Servers.

Stick Tables können 3 verschiedene Sample-Typen als Schlüssel verwenden: Ganzzahlen, Zeichenketten und Adressen. In einem Proxy kann nur eine Stick Table referenziert werden; sie wird überall mit dem Namen des Proxys bezeichnet. Bis zu 8 Schlüssel lassen sich parallel verfolgen. Die Serverkennung wird während der Verarbeitung der Anfrage oder Antwort eingetragen, sobald sowohl Schlüssel als auch Server bekannt sind.

Der Inhalt einer Stick Table kann im Aktiv/Aktiv-Betrieb mit anderen HAProxy-Knoten, den sogenannten „Peers“, sowie beim Neuladen mit dem neuen Prozess repliziert werden. Dadurch verfügen alle Lastverteilungsknoten über dieselben Informationen und treffen dieselbe Weiterleitungsentscheidung, wenn die Anfragen eines Clients auf mehrere Knoten verteilt werden.

Da Stick Tables nach einem Merkmal zur Erkennung des Clients indiziert sind, speichern sie oft zusätzliche Informationen, etwa Statistiken je Client. Diese zusätzlichen Statistiken benötigen weiteren Speicherplatz und müssen ausdrücklich deklariert werden. Gespeichert werden können beispielsweise ein- und ausgehende Bandbreite, Anzahl gleichzeitiger Verbindungen, Verbindungsrate und -anzahl innerhalb eines Zeitraums, Anzahl und Häufigkeit von Fehlern sowie bestimmte Markierungen und Zähler. Damit solche Informationen ohne Bindung an einen bestimmten Server geführt werden können, gibt es eine spezielle Funktion zur Nachverfolgung. Sie verfolgt unabhängig von den Regeln zur Sitzungsbindung bis zu 3 Schlüssel aus verschiedenen Tabellen gleichzeitig. Jede gespeicherte Statistik lässt sich über die CLI suchen, ausgeben und löschen. Dies erweitert die Möglichkeiten zur Fehlerbehebung im laufenden Betrieb.

Mit diesem Mechanismus können wiederkehrende Besucher bevorzugt oder die bereitgestellte Dienstqualität an gutes oder schlechtes Verhalten angepasst werden. Meist dient er jedoch der Bekämpfung von Dienstmissbrauch und allgemein von DDoS-Angriffen, da sich damit komplexe Modelle erstellen lassen, die bestimmtes Fehlverhalten mit hoher Verarbeitungsgeschwindigkeit erkennen.

3.4.6. Standardfunktionen: Formatierte Zeichenketten

HAProxy muss an vielen Stellen Zeichenketten verarbeiten, etwa in Protokollen, Weiterleitungen oder beim Hinzufügen von Headern. Für größtmögliche Flexibilität wurden formatierte Zeichenketten eingeführt, ursprünglich für die Protokollierung. Daher heißen sie weiterhin “log-format”. Diese Zeichenketten enthalten Escape-Zeichen, über die sich verschiedene dynamische Daten wie Variablen und Sample-Abrufausdrücke einfügen lassen. Auch die Kodierung kann beim Umwandeln des Ergebnisses in eine Zeichenkette angepasst werden, etwa durch Hinzufügen von Anführungszeichen. Damit lassen sich Header-Inhalte, Antwortdaten und sogar Antwortvorlagen erzeugen oder Protokollzeilen anpassen. Damit häufig benötigte Zeichenketten einfach aufgebaut werden können, stehen außerdem etwa 50 spezielle Kürzel für oft protokollierte Informationen bereit.

3.4.7. Standardfunktionen: HTTP-Umschreiben und -Weiterleiten

Einen Load-Balancer vor eine dafür nicht vorgesehene Anwendung zu setzen, kann ohne geeignete Werkzeuge schwierig sein. Häufig müssen Anfrage- und Antwort-Header angepasst werden, damit der Load-Balancer als Ursprungsserver erscheint und fest codierte Angaben korrigiert werden. Dazu gehören Änderungen am Anfragepfad (von denen dringend abgeraten wird), am Host-Header-Feld, am Location-Header-Feld von Weiterleitungsantworten sowie an den Attributen für Pfad und Domain von Cookies. Manche Server geben in ihren Antworten auch zu viele Informationen preis und werden dadurch anfälliger für gezielte Angriffe. Theoretisch ist es zwar nicht Aufgabe eines Load-Balancers, dies zu bereinigen; praktisch befindet er sich jedoch an der günstigsten Stelle der Infrastruktur, um eine vollständige Bereinigung sicherzustellen.

Gelegentlich muss der Load-Balancer auch Anfragen abfangen und mit einer Weiterleitung an eine neue Ziel-URL beantworten. Weiterleiten und Umschreiben werden zwar mitunter verwechselt, sind aber völlig unterschiedliche Konzepte: Beim Umschreiben sehen Client und Server unterschiedliche Inhalte und sind sich über den Ort der besuchten Seite uneinig. Eine Weiterleitung fordert den Client dagegen auf, die neue URL aufzurufen, sodass er denselben Ort wie der Server sieht.

HAProxy bietet dafür verschiedene Möglichkeiten zum Umschreiben und Weiterleiten, darunter:

• Umschreiben von URLs und Headern in Anfragen und Antworten anhand regulärer Ausdrücke. Reguläre Ausdrücke sind das häufigste Werkzeug zum Ändern von Header-Werten, weil sie sich leicht handhaben lassen und gut verstanden werden;

• Header lassen sich auch anhand formatierter Zeichenketten anhängen, löschen oder ersetzen. Dadurch können Informationen wie der clientseitige TLS-Algorithmus und Cipher übermittelt werden;

• HTTP-Weiterleitungen können jeden 3xx-Code mit einer relativen, absoluten oder vollständig dynamischen URI (formatierte Zeichenkette) verwenden;

• HTTP-Weiterleitungen unterstützen zusätzliche Optionen, etwa das Setzen oder Löschen eines bestimmten Cookies, das Entfernen des Query-Strings oder das Ergänzen eines fehlenden Schrägstrichs;

• Eine leistungsfähige “return”-Direktive ermöglicht es, jeden Teil einer Antwort wie Status, Header oder Nachrichtenkörper mit dynamischen Inhalten oder sogar Vorlagendateien anzupassen.

• Alle Vorgänge unterstützen ACL-basierte Bedingungen;

3.4.8. Standardfunktionen: Serverschutz

HAProxy unternimmt viel, um die Verfügbarkeit von Diensten zu maximieren. Dazu schützt er Server umfassend vor Überlastung und Angriffen. Der erste und wichtigste Punkt ist, dass nur vollständige und gültige Anfragen an die Server weitergeleitet werden. Zum einen muss HAProxy die Protokollelemente finden, die er zur Synchronisierung mit dem Bytestrom benötigt. Zum anderen lässt sich erst bei einer vollständigen Anfrage feststellen, ob einzelne Elemente ihre Bedeutung verändern. Der unmittelbare Vorteil ist, dass die Server keinen ungültigen oder unvollständigen Anfragen ausgesetzt sind. Dies schützt sehr wirksam vor Slowloris-Angriffen, die auf HAProxy fast keine Auswirkungen haben.

Ein weiterer wichtiger Punkt sind die Puffer für Anfragen und Antworten in HAProxy. Eine Anfrage wird erst dann an den Server gesendet, wenn sie vollständig vorliegt; die gesamte Antwort wird sehr schnell aus dem lokalen Netzwerk gelesen. Dadurch wird die serverseitige Verbindung nur sehr kurz genutzt, was die Serverressourcen möglichst weitgehend schont.

Darauf aufbauend kann HAProxy die Zahl gleichzeitiger Verbindungen oder ausstehender Anfragen an einen Server gezielt begrenzen. So wird der Server nie überlastet, selbst wenn er bei Verkehrsspitzen durchgehend mit 100% seiner Kapazität arbeitet. Überschüssige Anfragen warten einfach in einer Warteschlange, bis ein Platz frei wird. Diese erhebliche Ressourcenersparnis verkürzt die Antwortzeiten meist so stark, dass die Verarbeitung letztlich tatsächlich schneller ist als bei Überlastung des Servers. Wartende Anfragen können an andere Server umverteilt oder bereits in der Warteschlange abgebrochen werden, wenn der Client abbricht. Dies schützt die Server auch vor dem „Neuladeeffekt“: Klickt ein Besucher bei einer langsam ladenden Seite auf „Neu laden“, entsteht gewöhnlich bei jedem Klick eine weitere Anfrage, die den Server im überlasteten Zustand hält.

Der Slow-Start-Mechanismus schützt außerdem neu startende Server vor hohem Verkehrsaufkommen, solange sie noch ihren Start abschließen oder Klassen kompilieren.

Für den Schutz auf Protokollebene kann der HTTP-Parser so gelockert werden, dass er nicht standardkonforme, aber harmlose Anfragen oder Antworten akzeptiert und sogar korrigiert. Fehlerhafte Anwendungen bleiben dadurch erreichbar, während eine Korrektur entwickelt wird. Gleichzeitig werden die betreffenden Nachrichten vollständig erfasst und mit einem ausführlichen Bericht versehen, der Entwicklern hilft, den Fehler in der Anwendung zu finden. Die gefährlichsten Protokollverstöße werden zuverlässig erkannt, behandelt und behoben. So werden fehlerhafte Anfragen oder Antworten mit zwei Content-length-Headern korrigiert, wenn deren Werte exakt übereinstimmen. Unterscheiden sie sich, werden die Nachrichten abgewiesen, da daraus ein Sicherheitsproblem entsteht. Die Protokollprüfung ist nicht auf HTTP beschränkt, sondern auch für andere Protokolle wie TLS oder RDP verfügbar.

Wird ein Protokollverstoß oder ein Angriff erkannt, gibt es verschiedene Reaktionsmöglichkeiten: die übliche Antwort “HTTP 400 bad request”, das Schließen der Verbindung mit einem TCP-Reset oder das Vortäuschen eines Fehlers nach langer Verzögerung (“tarpit”), um den Angreifer zu verwirren. All dies schützt die Server, weil der angreifende Client von einem Angriff abgehalten wird, dessen Fortsetzung sehr aufwendig wird.

HAProxy bietet außerdem weitergehende Möglichkeiten zum Schutz vor versehentlichen Datenlecks und der Vermischung von Sitzungen. Er kann verdächtige Serverantworten protokollieren und protokolliert außerdem Antworten, die die Vertraulichkeit eines Besuchers beeinträchtigen könnten; optional kann er sie auch blockieren. Ein Beispiel ist ein zwischenspeicherbares Cookie in einer zwischenspeicherbaren Antwort. Ein zwischengeschalteter Cache könnte es an einen anderen Besucher ausliefern, sodass beide versehentlich dieselbe Sitzung verwenden.

5 - Erweiterte Funktionen

3.5.1. Erweiterte Funktionen: Verwaltung

HAProxy ist für einen äußerst stabilen Betrieb und eine sichere Verwaltung in üblichen Produktionsumgebungen ausgelegt. Er wird als einzelne ausführbare Datei bereitgestellt und benötigt keinen Installationsvorgang. Mehrere Versionen können problemlos nebeneinander bestehen. Instanzen lassen sich daher nach ihrer Wichtigkeit schrittweise aktualisieren, statt alle gleichzeitig umzustellen; dieses Vorgehen wird empfohlen. Konfigurationsdateien können leicht versioniert werden. Die Konfigurationsprüfung erfolgt unabhängig vom laufenden Betrieb, ohne einen Dienst neu starten zu müssen, der anschließend möglicherweise nicht mehr startet. Dabei lassen sich auch komplexere Fehler erkennen, etwa eine Regel, die eine andere verdeckt, oder eine nicht funktionierende Sitzungspersistenz. Ausführliche Warnungen und Konfigurationshinweise helfen bei der Behebung. Die Rückwärtskompatibilität von Konfigurationsdateien reicht weit zurück: Version 1.5 unterstützt noch vollständig Konfigurationen für Version 1.1, die 13 Jahre zuvor geschrieben wurden. Version 1.6 entfernt lediglich kaum verwendete, veraltete Schlüsselwörter, deren Aufgaben anders gelöst werden können. Das Aktualisieren von Konfiguration und Software erfolgt ohne Betriebsunterbrechung, indem alte und neue Prozesse nebeneinander laufen und jeweils ihre eigenen Verbindungen bedienen. Beim Start werden Systemzustand, Build-Optionen und Bibliothekskompatibilität gemeldet.

Erweiterte Funktionen erlauben es Anwendungsadministratoren, einen Server geordnet außer Betrieb zu nehmen: Sie können feststellen, wann keine Aktivität mehr vorhanden ist, ihn aus dem Betrieb nehmen, stoppen und aktualisieren, dabei sicherstellen, dass er keinen Datenverkehr erhält, und ihn anschließend über den normalen Zugriffspfad testen, ohne ihn bereits öffentlich freizugeben. Dafür muss HAProxy nicht verändert werden. So können selbst komplexe Arbeiten im Produktionsbetrieb während der Geschäftszeiten durchgeführt werden, wenn alle technischen Ressourcen verfügbar sind.

Der Prozess geht möglichst sparsam mit Ressourcen um. Speicherpools verkürzen die Zuteilungszeit und begrenzen Fragmentierung. Nutzdatenpuffer werden freigegeben, sobald ihr Inhalt gesendet ist. Außerdem lassen sich feste Speichergrenzen erzwingen: Bei Erreichen der Grenze müssen Verbindungen auf einen freien Puffer warten, statt weiteren Speicher zuzuteilen. Damit lässt sich der Speicherverbrauch in Umgebungen mit strengen Vorgaben begrenzen.

Eine Befehlszeilenschnittstelle (CLI) steht über einen UNIX- oder TCP-Socket bereit, um Operationen auszuführen und Diagnoseinformationen abzurufen. Alle Aktionen über diesen Socket kommen ohne Konfigurationsänderung aus und dienen deshalb vorwiegend vorübergehenden Anpassungen. Über die Schnittstelle lassen sich Adresse, Gewicht und Status eines Servers ändern, Statistiken abfragen und Zähler zurücksetzen, Tabellen zur Sitzungspersistenz ausgeben und leeren, bei Bedarf anhand von Schlüsselkriterien gezielt auswählen, Verbindungen auf Client- und Serverseite ausgeben und beenden sowie erfasste Fehler mit genauer Ursachen- und Positionsanalyse anzeigen. Außerdem können ACL- und Map-Einträge ausgegeben, hinzugefügt und entfernt, gemeinsame TLS-Geheimnisse aktualisiert und Verbindungs- sowie Ratenbegrenzungen für beliebige Frontends zur Laufzeit angewendet werden, was bei gemeinsam genutztem Hosting nützlich ist. Ein einzelnes Frontend kann deaktiviert werden, um einen lauschenden Port freizugeben, etwa wenn tagsüber keine Betriebsänderungen erlaubt sind, aber dennoch eine Korrektur nötig ist. Auch Zertifikate und ihre Konfiguration lassen sich zur Laufzeit aktualisieren. Zudem können Traces aller Verarbeitungsschritte des Datenverkehrs aktiviert und eingesehen werden.

Für Umgebungen, die SNMP verlangen, gibt es mindestens zwei Agenten. Einer wird mit dem HAProxy-Quellcode geliefert und verwendet das Perl-Modul Net-SNMP. Ein weiterer gehört zu den kommerziellen Paketen und benötigt kein Perl. Ihr Funktionsumfang ist ungefähr gleich.

Häufig wird empfohlen, auf dem Rechner mit HAProxy 4 Werkzeuge zu installieren:

• socat für den Zugriff auf die CLI; manche netcat-Varianten können dies ebenfalls in gewissem Umfang;

• halog aus der neuesten HAProxy-Version: Das Werkzeug analysiert native TCP- und HTTP-Protokolle äußerst schnell, mit 1 bis 2 GB pro Sekunde. Es gewinnt daraus Informationen und Statistiken, etwa Anfragen pro URL oder Quelladresse, nach Antwortzeit oder Fehlerrate sortierte URLs und Abschlusscodes. Es wurde für Produktionsserver entwickelt, um Probleme im laufenden Betrieb zu untersuchen, und muss deshalb bereits einsatzbereit installiert sein;

• tcpdump wird dringend empfohlen, um Netzwerkmitschnitte für die Untersuchung von Problemen anzufertigen, die in den Protokollen sichtbar wurden. Irgendwann können sich die Sicht der Anwendung und die Analyse von haproxy widersprechen. Dann zeigen nur Netzwerkmitschnitte, welche Seite recht hat. Auch Fehler in Netzwerk-Stacks und Hypervisoren werden häufig mit tcpdump aufgedeckt;

• strace ergänzt tcpdump. Es zeigt, was HAProxy tatsächlich sieht, und hilft, Ursachen im Betriebssystem von Ursachen in HAProxy zu unterscheiden. Bei einem vermuteten HAProxy-Fehler wird häufig eine strace-Ausgabe angefordert;

3.5.2. Erweiterte Funktionen: Systemspezifische Fähigkeiten

Je nach Betriebssystem stehen zusätzliche Funktionen zur Verfügung oder werden benötigt. HAProxy unterstützt mehrere Plattformen, wird aber hauptsächlich unter Linux entwickelt. Deshalb sind einige Funktionen nur dort verfügbar.

Transparente Bindung und Verbindungsherstellung, die Bindung von Verbindungen an eine bestimmte Netzwerkschnittstelle sowie das Binden mehrerer Prozesse an dieselbe IP-Adresse und dieselben Ports stehen nur unter Linux und BSD zur Verfügung. Nur Linux verteilt eingehende Anfragen jedoch im Kernel auf die verfügbaren Prozesse.

Unter Linux gibt es weitere Funktionen und Optimierungen. Netzwerk-Namespaces, auch „Container“ genannt, erlauben es HAProxy, als Gateway zwischen allen Containern zu arbeiten. Für clientseitige Verbindungen können MSS, Netfilter-Markierungen und das IP-TOS-Feld gesetzt werden. Auf der lauschenden Seite wird TCP FastOpen unterstützt. TCP-User-Timeouts erlauben dem Kernel, Verbindungen schnell zu beenden, wenn er vor Ablauf der konfigurierten Zeitüberschreitung erkennt, dass der Client nicht mehr erreichbar ist. TCP-Splicing lässt den Kernel Daten zwischen den beiden Seiten einer Verbindung weiterleiten und vermeidet dadurch mehrere Kopien im Speicher. Mit der Bind-Option “defer-accept” wird eine eingehende Verbindung erst gemeldet, wenn Daten in den Kernel-Puffern vorliegen. Die Option “tcp-smart-connect” ermöglicht es, die Anfrage zusammen mit dem ACK zu senden, das den Verbindungsaufbau bestätigt; dies wird manchmal „Piggybacking“ genannt. Unter Linux steuert HAProxy zudem verzögerte TCP-ACKs sorgfältig, um möglichst viele Netzwerkpakete einzusparen.

Manche Systeme haben eine unzuverlässige Uhr, die vor- und zurückspringt. Früher trat dies bei einigen NUMA-Systemen auf, deren Prozessoren nicht dieselbe Uhrzeit sahen. In jüngerer Zeit ist es in virtualisierten Umgebungen häufiger geworden, in denen die virtuelle Uhr keinen Bezug zur tatsächlichen Uhr hat. Dadurch entstehen große Zeitsprünge, gelegentlich wurden bis zu 30 Sekunden beobachtet. Das verursacht generell erhebliche Probleme bei der Durchsetzung von Zeitüberschreitungen. HAProxy führt deshalb eine eigene monotone Uhr auf Grundlage der Systemuhr, misst aber deren Abweichungen und gleicht sie aus. Selbst mit einer sehr schlechten Systemuhr bleiben Timer so hinreichend genau, und Zeitüberschreitungen funktionieren weiterhin. Das Problem betrifft sämtliche Software auf solchen Systemen und ist nicht HAProxy-spezifisch. Typische Folgen sind unbegründete Zeitüberschreitungen oder eingefrorene Anwendungen. Wird dieses Verhalten festgestellt, muss es behoben werden, auch wenn HAProxy sich selbst dagegen schützt.

Unter Linux kann ein neu startender Prozess mit seinem Vorgänger kommunizieren und dessen lauschende Dateideskriptoren übernehmen. Dadurch werden die lauschenden Sockets beim Austausch des Prozesses zu keinem Zeitpunkt unterbrochen.

3.5.3. Erweiterte Funktionen: Skripte

HAProxy kann mit Unterstützung für die eingebettete Sprache Lua gebaut werden. Damit eröffnen sich viele Möglichkeiten für komplexe Änderungen an Anfragen und Antworten, Routingentscheidungen, Statistikverarbeitung und mehr. Mit Lua lassen sich sogar parallele Verbindungen zu anderen Servern aufbauen, um Informationen auszutauschen. So kann beispielsweise ein Authentifizierungssystem entwickelt werden, auch wenn dies aufwendig ist. Weitere Informationen zur Verwendung von Lua stehen in der Dokumentation in “doc/lua-api/index.rst”.

3.5.4. Erweiterte Funktionen: Tracing

Administratoren können sich jederzeit über die CLI verbinden und Tracing für verschiedene interne Teilsysteme aktivieren. Mehrere voreingestellte Detailstufen erlauben in der Praxis Ausgaben von einer Zeile bis zu 500 Zeilen pro Anfrage. Filter und ein automatischer Mechanismus zum Starten, Stoppen und Pausieren der Erfassung ermöglichen es, gezielt auf ein Ereignis zu warten und es im Detail zu beobachten. Das ist besonders hilfreich bei Protokollverstößen fehlerhafter Server und Clients sowie bei Denial-of-Service-Angriffen.

6 - Dimensionierung und Leistung

Typischerweise entfallen im TCP- oder HTTP-Close-Modus 15% der Verarbeitungszeit auf HAProxy und 85% auf den Kernel. Im HTTP-Keep-Alive-Modus sind es etwa 30% für HAProxy und 70% für den Kernel. Betriebssystem und Systemoptimierung beeinflussen die Gesamtleistung daher stark.

Die Anforderungen unterscheiden sich erheblich: Manche Nutzer konzentrieren sich auf Bandbreite, andere auf Anfragerate, gleichzeitige Verbindungen oder SSL-Leistung. Dieser Abschnitt gibt einige Anhaltspunkte für die Planung.

Jede Operation verursacht Aufwand, der sich zum Aufwand der übrigen Operationen addiert. Unter bestimmten Umständen ist er vernachlässigbar, unter anderen kann er überwiegen.

Für die Verarbeitung von Anfragen einer Verbindung gilt:

• Das Weiterleiten von Daten kostet weniger als das Auswerten von Anfrage- oder Antwort-Headern;

• das Auswerten von Anfrage- oder Antwort-Headern kostet weniger als der Aufbau und anschließende Abbau einer Verbindung zu einem Server;

• Aufbau und Abbau einer Verbindung kosten weniger als die Wiederaufnahme einer TLS-Sitzung;

• die Wiederaufnahme einer TLS-Sitzung kostet weniger als ein vollständiger TLS-Handshake mit Schlüsselberechnung;

• eine untätige Verbindung benötigt weniger CPU-Leistung als eine Verbindung mit Daten in ihren Puffern;

• ein TLS-Kontext benötigt noch mehr Speicher als eine Verbindung mit Daten;

In der Praxis ist die Verarbeitung von Nutzdatenbytes somit günstiger als die von Headerbytes. Hohe Netzwerkbandbreiten lassen sich deshalb mit großen Objekten, also wenigen Anfragen pro Datenmenge, leichter erreichen als mit kleinen Objekten und entsprechend vielen Anfragen. Daher wird die maximale Bandbreite immer mit großen Objekten gemessen, die Anfrage- und Verbindungsraten dagegen mit kleinen.

Manche Operationen skalieren gut über mehrere Prozesse auf mehreren CPUs, andere weniger gut. Die Netzwerkbandbreite lässt sich nur begrenzt steigern, da bei großen Objekten selten die CPU den Engpass bildet. Meist begrenzen die Netzwerkbandbreite und die Datenbusse zu den Netzwerkschnittstellen. Die Verbindungsrate skaliert wegen einiger Sperren beim Zugriff auf die lokale Porttabelle des Systems schlecht über mehrere Prozessoren. Die Anfragerate über dauerhafte Verbindungen skaliert dagegen sehr gut: Sie benötigt wenig Speicher und Netzwerkbandbreite und keinen Zugriff auf gesperrte Strukturen. Auch die TLS-Schlüsselberechnung skaliert sehr gut, da sie vollständig CPU-gebunden ist. Die Wiederaufnahme von TLS-Sitzungen skaliert mäßig gut und erreicht ihre Grenzen bei etwa 4 Prozessen. Danach gleicht der Aufwand für den Zugriff auf die gemeinsame Tabelle die geringen zusätzlichen Leistungsgewinne aus.

Ein sehr gut optimiertes System erreicht ungefähr die folgenden Leistungswerte. Sie sind als Größenordnungen zu verstehen. Je nach Prozessor, IRQ-Einstellungen, Speichertyp, Netzwerkschnittstelle, Betriebssystemoptimierung und weiteren Faktoren sind erhebliche Abweichungen in beide Richtungen zu erwarten.

Die folgenden Werte wurden mit einem Core i7 bei 3.7 GHz, einer Netzwerkkarte (NIC) mit zwei 10-Gbps-Ports, Linux-Kernel 3.10, HAProxy 1.6 und OpenSSL 1.0.2 ermittelt. HAProxy lief als einzelner Prozess auf einem exklusiv zugewiesenen CPU-Kern; zwei weitere Kerne waren für Netzwerk-Interrupts reserviert:

• 20 Gbps maximale Netzwerkbandbreite bei unverschlüsselter Übertragung von Objekten ab 256 kB, 10 Gbps bei Objekten ab 41kB;

• 4.6 Gbps TLS-Datenverkehr mit AES256-GCM und großen Objekten;

• 83000 TCP-Verbindungen pro Sekunde vom Client zum Server;

• 82000 HTTP-Verbindungen pro Sekunde vom Client zum Server;

• 97000 HTTP-Anfragen pro Sekunde im Server-Close-Modus, also Keep-Alive zum Client und Schließen der Verbindung zum Server;

• 243000 HTTP-Anfragen pro Sekunde mit durchgehendem Keep-Alive;

• 300000 gefilterte TCP-Verbindungen pro Sekunde zur DDoS-Abwehr

• 160000 HTTPS-Anfragen pro Sekunde im Keep-Alive-Modus über dauerhafte TLS-Verbindungen;

• 13100 HTTPS-Anfragen pro Sekunde mit wiederaufgenommenen TLS-Verbindungen;

• 1300 HTTPS-Verbindungen pro Sekunde mit jeweils neu ausgehandeltem TLS und RSA2048;

• 20000 gleichzeitige, voll ausgelastete Verbindungen pro GB RAM einschließlich des Speichers für Systempuffer; mit sorgfältiger Optimierung sind bessere Werte möglich, dieser Wert ist jedoch leicht zu erreichen.

• etwa 8000 gleichzeitige TLS-Verbindungen nur auf der Clientseite pro GB RAM einschließlich des Speichers für Systempuffer;

• etwa 5000 gleichzeitige durchgehende TLS-Verbindungen auf beiden Seiten pro GB RAM einschließlich des Speichers für Systempuffer;

Ein neuerer Benchmark mit HAProxy 2.4 im Mehrthreadbetrieb auf einem ARM-Graviton2-Prozessor mit 64 Kernen bei AWS erreichte 2 Millionen HTTPS-Anfragen pro Sekunde bei Antwortzeiten unter einer Millisekunde und 100 Gbps Datenverkehr:

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

Als Faustregel sinkt die Anfragerate von TLS-Keep-Alive zur TLS-Wiederaufnahme sowie von der TLS-Wiederaufnahme zur TLS-Neuaushandlung jeweils um den Faktor 10. Zwischen HTTP-Keep-Alive und HTTP-Close sinkt sie dagegen nur um den Faktor 3. Eine weitere Faustregel: Ein hoch getakteter Kern mit AES-Befehlen schafft etwa 20 Gbps AES-GCM pro Kern.

Eine weitere nützliche Faustregel ist, dass HAProxy auf derselben Serverhardware etwa folgende Anzahl von Servern vollständig auslasten kann:

• etwa 5-10 Server für statische Dateien oder Caching-Proxys;

• etwa 100 Antivirus-Proxys;

• etwa 100-1000 Anwendungsserver, abhängig von der verwendeten Technologie.

7 - Versionen, Pakete und Upgrades

HAProxy ist ein Open-Source-Projekt unter der GPLv2-Lizenz. Jeder darf es weiterverbreiten, sofern auf Anfrage auch Zugang zum Quellcode gewährt wird, insbesondere wenn Änderungen vorgenommen wurden.

Die Entwicklung von HAProxy erfolgt im Hauptzweig “master”, auch “mainline” genannt. Sobald der Code als stabil gilt, werden daraus neue Zweige abgeleitet. Viele Websites setzen freiwillig Entwicklungszweige im Produktionsbetrieb ein, entweder um zum Projekt beizutragen oder weil sie eine besonders neue Funktion benötigen. Ihre Rückmeldungen sind sehr wertvoll, um Fehler zu beheben und die Gesamtqualität und Stabilität der entstehenden Version einzuschätzen.

Die aus ausreichend stabilem Code erzeugten neuen Zweige bilden eine stabile Version und werden im Allgemeinen mehrere Jahre gepflegt. Ein sofortiger Wechsel auf einen neueren Zweig ist daher auch dann nicht nötig, wenn nicht der neueste verwendet wird. Nach der Veröffentlichung eines stabilen Zweigs darf er nur Fehlerkorrekturen erhalten. Sehr selten kommen kleinere Funktionserweiterungen hinzu, wenn sie den Nutzern die Arbeit erleichtern. Alle Korrekturen eines stabilen Zweigs stammen zwingend aus dem master-Zweig. Dadurch geht beim Upgrade keine Korrektur verloren. Patches zur Fehlerbehebung bitte deshalb gegen master und nicht gegen einen stabilen Zweig erstellen. Möglicherweise ist der Fehler dort bereits behoben. Dieses Verfahren sorgt zudem dafür, dass Regressionen in stabilen Zweigen äußerst selten sind. Es gibt daher keinen Grund, nicht auf die neueste Version des verwendeten Zweigs zu aktualisieren.

Zweige tragen zwei durch einen Punkt getrennte Zahlen, etwa “1.6”. Seit 1.9 konzentrieren sich Zweige mit ungerader zweiter Zahl vor allem auf sensible technische Änderungen und richten sich eher an erfahrene Nutzer, da sie wahrscheinlich mehr Fehler auslösen als die übrigen. Sie werden nur etwa ein Jahr gepflegt und dürfen nicht dort eingesetzt werden, wo im Notfall kein Rollback möglich ist. Eine vollständige Versionsnummer enthält eine oder zwei weitere Zahlen für den Korrekturstand. Beispielsweise ist 1.5.14 die 14. Korrekturversion im Zweig 1.5 nach der Veröffentlichung von 1.5.0. Sie enthält 126 Korrekturen einzelner Fehler, 24 Dokumentationsaktualisierungen und 75 weitere rückportierte Patches, von denen die meisten zur Behebung der genannten 126 Fehler benötigt wurden. Bestehende Funktionen dürfen in einem stabilen Zweig niemals geändert oder entfernt werden. So bleiben Upgrades innerhalb desselben Zweigs stets unbedenklich.

HAProxy ist aus verschiedenen Quellen mit unterschiedlichen Veröffentlichungsrhythmen verfügbar:

• Die offizielle Community-Website http://www.haproxy.org/ bietet den Quellcode der neuesten Entwicklungsversion, sämtlicher stabiler Versionen sowie nächtliche Snapshots jedes Zweigs. Der Veröffentlichungsrhythmus ist langsam: Zwischen stabilen Versionen oder Entwicklungssnapshots liegen mehrere Monate. Auch sehr alte Versionen werden dort noch unterstützt. Alles wird nur als Quellcode bereitgestellt und muss daher selbst gebaut beziehungsweise paketiert werden;

• GitHub unter https://github.com/haproxy/haproxy/ spiegelt ausschließlich den Entwicklungszweig und bindet Issue-Tracker, kontinuierliche Integration und Werkzeuge zur Messung der Codeabdeckung ein. Dieses Angebot richtet sich ausschließlich an Mitwirkende;

• Zahlreiche Betriebssysteme, etwa Linux-Distributionen und BSD-Ports, liefern langfristig gepflegte Versionen. Diese enthalten nicht immer alle Korrekturen der offiziellen Versionen, aber zumindest die kritischen. Für die meisten Nutzer, die keine anspruchsvollen Konfigurationen benötigen und Aktualisierungen einfach halten möchten, ist dies häufig eine gute Wahl;

• Kommerzielle Versionen von http://www.haproxy.com/ bieten professionell unterstützte Pakete für verschiedene Betriebssysteme oder Appliances. Sie basieren auf aktuellen stabilen Versionen und enthalten zusätzlich stark nachgefragte Funktionen, die aus der nächsten Version rückportiert wurden. Sie sind die beste Wahl für Nutzer, die neue Funktionen mit der Zuverlässigkeit eines stabilen Zweigs, sehr schnelle Fehlerbehebung oder einfach einen Supportvertrag für ein Open-Source-Produkt suchen;

Um festzustellen, ob die eingesetzte Version die neueste ihres Zweigs ist, wie folgt vorgehen:

• Prüfen, welche ausführbare HAProxy-Datei verwendet wird. Manche Systeme liefern HAProxy bereits mit, während die Administration eine eigene Version an anderer Stelle installiert. Daher in den Startskripten nachsehen, welche Datei tatsächlich aufgerufen wird;

• Die Herkunft der HAProxy-Version bestimmen. Meist genügt “haproxy -v”. Eine Entwicklungsversion sieht wie folgt aus; hinter der Zweignummer steht “dev”:

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

Eine stabile Version sieht wie folgt aus. Dasselbe gilt für unveränderte stabile

Versionen der Betriebssystemanbieter:

HAProxy version 1.5.14 2015/07/02

Ein nächtlicher Snapshot einer stabilen Version enthält dagegen eine hexadezimale
Zeichenfolge hinter der Versionsnummer und statt des Veröffentlichungsdatums

das Datum des Snapshots:

HAProxy version 1.5.14-e4766ba 2015/07/29

Jedes andere Format kann auf ein systemspezifisches Paket mit eigenen Patches hinweisen.
HAProxy-Enterprise-Versionen verwenden beispielsweise

folgendes Format (<branch>-<latest commit>-<revision>):

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

Frühere Versionen vor 2.4 gaben den Prozessnamen mit einem Bindestrich zwischen "HA" und
"Proxy" aus. Dies gilt auch für die oben gezeigten Beispiele, die nur zur Darstellung des
korrekten Formats angepasst wurden. In Skripten dieses Wort daher besser ignorieren oder
einen weniger strengen Abgleich verwenden. Neuere Versionen ergänzen zudem eine URL zur
Projektwebsite.

Ab Version 2.1 gibt es außerdem eine Zeile "Status". Sie nennt, ob die Version für den
Produktionsbetrieb geeignet ist und gegebenenfalls bis wann, sowie einen Link zur Liste
bekannter Fehler dieser Version.

• Bei systemspezifischen Paketen im Paket-Repository oder Aktualisierungssystem des Anbieters prüfen, ob das System noch unterstützt wird und der verwendete Zweig weiterhin Korrekturen erhält. Bei Community-Versionen von haproxy.org die Website besuchen, den Status des Zweigs prüfen und die neueste Version mit der installierten vergleichen. Ist die eigene Version älter, kann sie aktualisiert werden. Wird der Zweig nicht mehr gepflegt, ist ein Upgrade bereits deutlich überfällig. Dann muss ein Wechsel auf einen neueren Zweig erwogen werden; dabei die README sorgfältig lesen.

HAProxy muss entsprechend seiner Bezugsquelle aktualisiert werden. Üblicherweise erfolgt dies über das Paketaktualisierungsverfahren des Systemanbieters. Bei einer Installation aus dem Quellcode nach dem Entpacken die README im Quellverzeichnis lesen und den Anweisungen für das verwendete Betriebssystem folgen.

8 - Ergänzende Produkte und Alternativen

HAProxy lässt sich gut mit einigen der folgenden Produkte kombinieren. Deshalb werden sie hier erwähnt, auch wenn sie nicht direkt zu HAProxy gehören.

4.1. Apache HTTP Server

Apache ist der De-facto-Standard unter den HTTP-Servern. Das sehr umfangreiche, modulare Projekt unterstützt sowohl die Auslieferung von Dateien als auch dynamische Inhalte. Es kann als Frontend für Anwendungsserver dienen, Anfragen als Proxy weiterleiten und Antworten zwischenspeichern. In all diesen Fällen wird häufig ein vorgeschalteter Load-Balancer benötigt. Apache unterstützt verschiedene Betriebsarten mit unterschiedlichem Ressourcenbedarf. Manche Module verlangen weiterhin das aufwendigere Prefork-Modell und verhindern dadurch eine gute Skalierung bei vielen Verbindungen. HAProxy kann hier erheblich helfen, indem er die Verbindungszahl pro Server auf einen sicheren Wert begrenzt. Dadurch wird der Server deutlich schneller, und seine Ressourcen bleiben für die Anwendung verfügbar.

Apache kann die Clientadresse mit der Erweiterung “mod_rpaf” aus dem Header X-Forwarded-For auslesen. HAProxy setzt diesen Header automatisch, wenn “option forwardfor” konfiguriert ist. Außerdem kann HAProxy einen mit dem Internet verbundenen Apache gut schützen, da er vielen Arten von DoS-Angriffen besser standhält.

4.2. NGINX

NGINX ist der zweite De-facto-Standard unter den HTTP-Servern und deckt wie Apache viele Funktionen ab. Sein Modell ähnelt dem von HAProxy, sodass er problemlos Zehntausende gleichzeitige Verbindungen verarbeitet. Wird er als Gateway zu Anwendungen eingesetzt, etwa mit dem mitgelieferten PHP FPM, kann eine Begrenzung der Frontend-Verbindungen die PHP-Anwendung entlasten. HAProxy hilft dabei sowohl als gewöhnlicher Load-Balancer als auch bei der Regulierung des Datenverkehrs, um PHP durch weniger Überlastung zu beschleunigen. Da beide Produkte dank ihrer ereignisgesteuerten Architektur wenig CPU-Leistung benötigen, können sie oft problemlos auf demselben System installiert werden. NGINX implementiert das PROXY-Protokoll von HAProxy. So kann HAProxy die Verbindungsinformationen des Clients an NGINX weitergeben, damit die Anwendung alle relevanten Angaben erhält. Einige Benchmarks haben außerdem gezeigt, dass konsistentes Hashing in einem vor NGINX eingesetzten HAProxy bei der Auslieferung großer statischer Dateien vorteilhaft ist: Es verbessert die Cache-Trefferrate des Betriebssystems, die sich im Wesentlichen mit der Anzahl der Serverknoten vervielfacht.

4.3. Varnish

Varnish ist ein intelligenter Reverse-Proxy mit Cache, der sich am besten als Beschleuniger für Webanwendungen beschreiben lässt. Varnish implementiert kein SSL/TLS und konzentriert seine gesamte CPU-Leistung auf seine Kernaufgabe. Da auch Varnish das PROXY-Protokoll von HAProxy implementiert, lässt sich HAProxy einfach davor einsetzen, um SSL-Verarbeitung und Lastverteilung zu übernehmen und alle relevanten Clientinformationen weiterzugeben. Varnish kann komprimierte Objekte aus dem Cache dekomprimieren, wenn ein Server sie komprimiert geliefert hat, komprimiert sie aber nicht selbst. Unterstützen die Backend-Server keine Komprimierung, kann HAProxy die ausgehenden Daten komprimieren. Bei mehr als geringem Datenverkehr ist die Komprimierung auf dem Load-Balancer allerdings selten sinnvoll.

Bei großen Cache-Farmen mit mehreren Knoten kann HAProxy die Last durch konsistentes URL-Hashing gezielt auf die Cache-Knoten verteilen und doppelte Cache-Inhalte vermeiden. Die gesamte Cache-Kapazität entspricht dann der Summe aller Knoten. Zusätzlich kann das kurzzeitige Zwischenspeichern sehr kleiner, einfacher Objekte in HAProxy Netzwerk-Roundtrips einsparen und die CPU-Last auf HAProxy- und Varnish-Knoten senken. Dies ist nur möglich, wenn Varnish diese Objekte nicht weiter verarbeitet. Häufig wird dies als „Favicon-Cache“ bezeichnet; damit lässt sich unter Umständen ein erheblicher Anteil unnötiger nachgelagerter Anfragen vermeiden. Vor einem anderen Cache darf HAProxy jedoch nicht für längere Zeit, also mehr als wenige Sekunden, zwischenspeichern. Das würde die Fehlerbehebung erheblich erschweren, ohne nennenswerte zusätzliche Einsparungen zu bringen.

4.4. Alternativen

Linux Virtual Server, kurz LVS oder IPVS, ist der in den Linux-Kernel integrierte Load-Balancer für Schicht 4. Er arbeitet auf Paketebene und verarbeitet TCP und UDP. Meist ist er eher eine Ergänzung als eine Alternative, da er keinerlei Kenntnis von Schicht 7 hat.

Pound ist ein weiterer bekannter Load-Balancer. Er ist wesentlich einfacher und hat deutlich weniger Funktionen als HAProxy. Für viele sehr einfache Konfigurationen eignen sich jedoch beide. Sein Autor legt den Schwerpunkt seit jeher auf gut prüfbaren Code und möchte den Funktionsumfang klein halten. Die Architektur mit Threads skaliert bei hohen Verbindungszahlen weniger gut, dennoch ist Pound ein gutes Produkt.

Pen ist ein recht schlanker Load-Balancer. Er unterstützt SSL und hält Clientzuordnungen in einer Tabelle fester Größe mit den IP-Adressen der Clients. Ein paketorientierter Modus ermöglicht Direct Server Return und in gewissem Umfang UDP. Pen ist für geringe Last ausgelegt; die Zuordnungstabelle enthält nur 2048 Einträge.

NGINX kann in gewissem Umfang Last verteilen, auch wenn dies eindeutig nicht seine Hauptaufgabe ist. Serverausfälle werden anhand des Produktionsverkehrs erkannt, die Verfahren zur Lastverteilung sind eingeschränkter, und die Sitzungspersistenz ist sehr begrenzt. In einfachen Bereitstellungen, in denen NGINX bereits vorhanden ist, kann dies dennoch sinnvoll sein. Da NGINX gut mit HAProxy zusammenarbeitet, lässt sich HAProxy problemlos später ergänzen, wenn die Grenzen erreicht sind.

Auch Varnish verteilt Last auf seine Backend-Server und unterstützt echte Health Checks. Sitzungspersistenz implementiert es jedoch nicht. Wie bei NGINX kann dies für den Anfang ausreichen, solange keine Sitzungspersistenz benötigt wird. Da HAProxy und Varnish sehr gut zusammenarbeiten, lässt sich HAProxy auch hier später leicht ergänzen, um den Funktionsumfang zu erweitern.

9 - Dokumentation und Community

1. Verfügbare Dokumentation

Die vollständige HAProxy-Dokumentation besteht aus den folgenden Dokumenten. Die jeweils passende Dokumentation spart Zeit und liefert die genaueste Antwort auf die eigene Fragestellung. Bitte keine Fragen an die Mailingliste senden, deren Antworten bereits in diesen Dokumenten stehen.

• intro.txt (dieses Dokument): behandelt die Grundlagen der Lastverteilung, HAProxy als Produkt, seine Fähigkeiten und Grenzen, bekannte Fallstricke, Einschränkungen einzelner Betriebssysteme, Bezugsquellen, Weiterentwicklung, die Versorgung mit allen bekannten Fehlerkorrekturen, Aktualisierungen sowie Ergänzungen und Alternativen.

• management.txt : erklärt den Start von haproxy, die Verwaltung zur Laufzeit und auf mehreren Knoten sowie die Durchführung nahtloser Upgrades.

• configuration.txt : das Referenzhandbuch erläutert sämtliche Konfigurationsschlüsselwörter und ihre Optionen. Es dient als Nachschlagewerk für Konfigurationsänderungen.

• coding-style.txt: richtet sich an Entwickler, die Code zum Projekt beitragen möchten, und erläutert den einzuhaltenden Programmierstil. Er ist nicht besonders streng, und auch der vorhandene Code hält ihn nicht vollständig ein. Beiträge, die zu stark davon abweichen, werden jedoch abgelehnt.

• proxy-protocol.txt: die De-facto-Spezifikation des PROXY-Protokolls, das HAProxy und verschiedene Produkte von Drittanbietern implementieren.

• security.txt: beschreibt die Meldung von Sicherheitsproblemen und erläutert, was als Schwachstelle gilt und was nicht.

• README: beschreibt, wie HAProxy aus dem Quellcode gebaut wird

5. Kontakte

Entwickler und andere Mitglieder der Community sind in der Regel am besten über die Mailingliste unter haproxy@formilux.org zu erreichen. Die Liste und ihre Archive sind öffentlich; vertrauliche Informationen sollten daher nicht veröffentlicht werden. Dort sind etwa tausend Nutzer mit unterschiedlicher Erfahrung vertreten. Selbst sehr komplexe Fragen erhalten meist relativ schnell eine passende Antwort. Vorschläge sind ebenfalls willkommen. Wer Schwierigkeiten mit E-Mail hat, kann die Discourse-Plattform unter http://discourse.haproxy.org/ nutzen. Dort lesen allerdings weniger Personen mit, und die meisten Fragen werden von einem sehr kleinen Team bearbeitet. Bitte in jedem Fall geduldig und respektvoll mit denjenigen umgehen, die ihre Freizeit dafür einsetzen, anderen zu helfen.

Ein vermuteter, aber noch nicht sicher bestätigter Fehler wird am besten auf der Mailingliste gemeldet. Wer überzeugt ist, einen Fehler gefunden zu haben, die aktuelle Version seines Zweigs verwendet und bereits ein GitHub-Konto besitzt, kann direkt unter https://github.com/haproxy/haproxy/ ein Issue mit allen verfügbaren Einzelheiten anlegen. Auch dort sind die Informationen öffentlich; daher nichts veröffentlichen, was später bereut werden könnte. Da der Issue-Tracker die Diskussion als langen Verlauf darstellt, sehr umfangreiche Ausgaben von mehreren hundert Zeilen oder mehr bitte als Anhang beifügen, statt sie in den Text einzufügen.

Bei einem vermuteten Sicherheitsproblem ist die Datei doc/security.txt zu beachten. Sie erläutert, was bei HAProxy als Schwachstelle gilt und was nicht, und wie eine tatsächliche Schwachstelle vertraulich gemeldet wird. Die meisten Verdachtsfälle erweisen sich als gewöhnliche Fehler, die besser auf dem oben beschriebenen Weg gemeldet werden.

Vollständige lokale Handbuchsammlung

• Einsteigerhandbuch
• Konfigurationshandbuch
• Verwaltungshandbuch

Herkunft dieser Ausgabe

• Ausgabe: HAProxy 3.4.6-66, Dokumentationsstand des Wartungszweigs
• Neueste stabile Version: HAProxy 3.4.6, Tag v3.4.6
• Quell-Commit: 16acce1dac1d
• Gerenderte Upstream-Handbücher: docs.haproxy.org/3.4/
• Lokale Lizenzkopien: HAProxy-Lizenzhinweis und GPLv2

10 - 1. Kurzer Überblick über HTTP

Dieses Dokument beschreibt die Konfigurationssprache der oben angegebenen Version. Es enthält keine Hinweise, Beispiele oder Empfehlungen. Dafür stehen das Referenzhandbuch und das Architekturhandbuch zur Verfügung. Die nummerierten Kapitel sind in der flachen HAProxy-Seitenleiste zur direkten Navigation angeordnet.

Im HTTP-Modus analysiert und indiziert HAProxy sowohl Anfragen als auch Antworten vollständig. Dadurch lassen sich Abgleichkriterien für nahezu jeden Bestandteil ihres Inhalts festlegen.

Dafür ist es wichtig, den Aufbau von HTTP-Anfragen und -Antworten sowie ihre Zerlegung durch HAProxy zu verstehen. Damit wird es leichter, korrekte Regeln zu schreiben und Fehler in vorhandenen Konfigurationen zu finden.

HTTP ist durch eine Reihe von RFCs standardisiert, denen HAProxy möglichst genau folgt:

• RFC 9110: HTTP-Semantik (Bedeutung der Protokollelemente)
• RFC 9111: HTTP-Caching (Regeln für HTTP-Caches)
• RFC 9112: HTTP/1.1 (Darstellung, Interoperabilitätsregeln, Sicherheit)
• RFC 9113: HTTP/2 (Darstellung, Interoperabilitätsregeln, Sicherheit)
• RFC 9114: HTTP/3 (Darstellung, Interoperabilitätsregeln, Sicherheit)

Außerdem spezifizieren RFC 8999 bis 9002 die QUIC-Transportschicht, die das HTTP/3-Protokoll verwendet.

1.1. Das HTTP-Transaktionsmodell

HTTP arbeitet transaktionsorientiert: Jede Anfrage führt zu genau einer Antwort. Ursprünglich gab es in Protokollversion 1.0 nur eine Anfrage je Verbindung. Der Client baut eine TCP-Verbindung zum Server auf und sendet darüber eine Anfrage. Der Server antwortet, anschließend wird die Verbindung geschlossen. Eine weitere Anfrage erfordert dann eine neue Verbindung:

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

In diesem oft “HTTP close” genannten Modus gibt es ebenso viele Verbindungsaufbauten wie HTTP-Transaktionen. Da der Server die Verbindung nach der Antwort schließt, muss der Client die Inhaltslänge nicht kennen. Mit dem Schließen der Verbindung betrachtet er die Antwort als vollständig. Werden Antworten wegen Netzwerkfehlern abgeschnitten, kann der Client sie deshalb irrtümlich für vollständig halten. Früher wurden dadurch gelegentlich unvollständige Bilder auf dem Bildschirm angezeigt.

Der transaktionsorientierte Aufbau ermöglichte eine Erweiterung, bei der die Verbindung zwischen aufeinanderfolgenden Transaktionen offen bleibt. Dabei muss der Server jedoch für jede Antwort die Inhaltslänge angeben, damit der Client nicht endlos wartet. Dazu dient der besondere Header “Content-length”. Dieser “keep-alive” genannte Modus kam mit HTTP/1.1 hinzu; einige HTTP/1.0-Implementierungen unterstützen ihn ebenfalls. Zwischen Anfragen wiederverwendete Verbindungen heißen persistente Verbindungen:

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

Vorteile sind die geringere Latenz zwischen Transaktionen, der geringere Rechenaufwand auf dem Server und die Möglichkeit, abgeschnittene Antworten zu erkennen. Der Modus ist meist schneller als das Schließen nach jeder Antwort, aber nicht immer: Manche Clients begrenzen die Zahl gleichzeitiger Verbindungen stärker, wodurch eine schlechte Netzwerkverbindung weniger gut ausgeglichen wird. Zudem müssen manche Server Verbindungen lange offen halten, um auf eine mögliche weitere Anfrage zu warten. Viele Verbindungen können dann viel Speicher belegen. Zu frühes Schließen kann dagegen Anfragen unterbrechen, die genau in diesem Moment eintreffen.

In diesem Modus muss die Antwortgröße vorab bekannt sein. Bei dynamisch erzeugten oder komprimierten Inhalten ist das nicht immer möglich. Deshalb wurde der “chunked mode” eingeführt. Statt sofort die Gesamtgröße anzukündigen, meldet der Sender nur die Größe des nächsten bereits gepufferten Antwortblocks, des sogenannten Chunks. Mit einem Block der Größe null kann er die Übertragung jederzeit beenden. Der Header Content-Length wird in diesem Modus nicht verwendet.

Eine weitere Verbesserung ist Pipelining. Dabei bleibt Keep-Alive aktiv, der Client wartet jedoch nicht auf die erste Antwort, bevor er die zweite Anfrage sendet. Das ist beim Abruf vieler Bilder einer Seite nützlich:

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

Dies kann die Leistung erheblich verbessern, da die Netzwerklatenz zwischen aufeinanderfolgenden Anfragen entfällt. Viele HTTP-Implementierungen unterstützen Pipelining nicht korrekt, weil HTTP keine Möglichkeit bietet, eine Antwort der zugehörigen Anfrage zuzuordnen. Deshalb muss der Server genau in der Reihenfolge der eingegangenen Anfragen antworten. Nach mehreren Einführungsversuchen verschiedener Clients wurde Pipelining in der Praxis wegen seiner Unzuverlässigkeit auf manchen Servern vollständig aufgegeben. Server müssen es dennoch unterstützen.

Die nächste Verbesserung ist Multiplexing, wie es HTTP/2 und HTTP/3 verwenden. Mehrere Transaktionen, also Anfrage-Antwort-Paare, laufen parallel über eine einzige Verbindung und kommen unabhängig voneinander mit ihrer jeweiligen Geschwindigkeit voran. Multiplex-Protokolle führen dafür den Begriff Stream ein: eine dieser parallelen Kommunikationen über dieselbe Verbindung. Jeder Stream erhält normalerweise eine innerhalb der Verbindung eindeutige Kennung. Beide Endpunkte erkennen daran, wohin die Daten gehören. Clients starten häufig viele Streams gleichzeitig, bis zu 100 und manchmal mehr, und lassen den Server die Anfragen bearbeiten und je nach Verfügbarkeit der Antworten in beliebiger Reihenfolge beantworten. Multiplexing verringert vor allem die Anzahl der Hin- und Rückläufe deutlich und beschleunigt das Laden von Seiten über Netzwerke mit hoher Latenz. Bei bildreichen Websites ist bisweilen zu sehen, wie alle Bilder gleichzeitig geladen werden.

Diese Protokolle komprimieren außerdem Header-Felder, um weniger Bytes übertragen zu müssen. Das verbessert ihre Effizienz, macht sie ohne geeignete Werkzeuge jedoch praktisch weder von Hand bearbeitbar noch mit bloßem Auge lesbar, wie es bei HTTP/1 möglich war. Deshalb stellt die Fachliteratur einschließlich dieses Dokuments HTTP-Nachrichten weiterhin in HTTP/1-Syntax dar, auch für neuere Protokollversionen.

HTTP/2 hat konstruktionsbedingte Einschränkungen. Paketverluste betreffen beispielsweise alle Streams gleichzeitig. Benötigt ein Client viel Zeit zum Abruf eines Objekts, etwa weil er es auf die Festplatte schreiben muss, kann er den Abruf verlangsamen und währenddessen den Zugriff auf dahinter wartende Daten unmöglich machen. Dies heißt Head-of-Line-Blocking, kurz HoL-Blocking oder auch nur HoL.

HTTP/3 verwendet QUIC, das seinerseits auf UDP aufsetzt. QUIC beseitigt Head-of-Line-Blocking auf der Transportebene durch unabhängig behandelte Streams. Bei Paketverlusten beeinträchtigt ein betroffener Stream die anderen nicht; auf alle lässt sich parallel zugreifen. QUIC unterstützt auch die Migration von Verbindungen, die HAProxy derzeit jedoch nicht unterstützt.

Für persistente Verbindungen verwendet HAProxy standardmäßig Keep-Alive. Es verarbeitet jede Anfrage und Antwort und lässt die Verbindung auf beiden Seiten zwischen dem Ende einer Antwort und der nächsten Anfrage ruhen. Bei einer HTTP/2-Verbindung vom Client verarbeitet es alle Anfragen parallel und lässt die Verbindung bis zu weiteren Anfragen offen und inaktiv, wie bei einer HTTP-Verbindung mit Keep-Alive.

HAProxy unterstützt im Wesentlichen 3 Verbindungsmodi:

• keep alive: Alle Anfragen und Antworten werden verarbeitet. Die Verbindungen zum Client und zum Server bleiben für weitere Anfragen offen. Dies ist der Standard und passt zum modernen Web sowie zu HTTP/2 und HTTP/3.

• server close: Die Verbindung zum Server wird nach der Antwort geschlossen.

• close: Nach dem Ende der Antwort wird die Verbindung auf beiden Seiten aktiv geschlossen.

Außerdem kann die serverseitige Verbindung standardmäßig für jede Anfrage eines beliebigen Clients wiederverwendet werden, wie es die HTTP-Spezifikation verlangt. Benötigte Informationen zu einem bestimmten Client, etwa seine Quelladresse, müssen daher mit jeder Anfrage übertragen werden. Bei HTTP/2 zum Server ordnet HAProxy die Verbindung standardmäßig demselben Client zu, um Head-of-Line-Blocking zwischen Clients zu vermeiden.

1.2. Begriffe

Die Begriffe in HAProxy haben sich mit dem HTTP-Protokoll und dessen Verwendung weiterentwickelt. Anfangs unterschieden sich Verbindung, Sitzung, Stream und Transaktion kaum. Mit der Zeit wurden diese Begriffe genauer abgegrenzt, um den modernen HTTP-Versionen zu entsprechen. Einige ältere Bezeichnungen bleiben aus Kompatibilitätsgründen in der Konfiguration oder der Befehlszeilenschnittstelle sichtbar.

Für die aktuelle HAProxy-Version gelten folgende Definitionen:

• Verbindung: Ein einzelner bidirektionaler Kommunikationskanal zwischen einem entfernten Teilnehmer, also Client oder Server, und HAProxy auf der niedrigsten möglichen Ebene. Meist entspricht er einem TCP-Socket zwischen einem Paar aus IP-Adressen und Ports. Clientseitig sind Verbindungen die ersten Objekte, die beim Verbindungsaufbau zu HAProxy entstehen. Regeln auf Verbindungsebene werden zuerst angewendet.

• Sitzung: Ergänzt eine Verbindung um Kontextinformationen, etwa transportbezogene Daten wie TLS-Schlüssel oder Variablen. In HAProxy bezeichnete der Begriff lange durchgehende HTTP/1.0-Kommunikation zwischen zwei Endpunkten. Deshalb erscheint er noch in Namen mancher CLI-Befehle oder Statistiken, obwohl heute Streams gemeint sind. Hilfetexte und Beschreibungen versuchen, dies eindeutig zu machen. Auf Netzwerkebene ist der Begriff weiterhin gültig, etwa für TCP-Sitzungen im Betriebssystem oder durch eine Firewall, ebenso für Anwendungen außerhalb von HTTP, etwa eine telnet- oder SSH-Sitzung. Er darf nicht mit Anwendungssitzungen verwechselt werden, die einen vollständigen Benutzerkontext in einem Cookie speichern und demselben Server zugeleitet werden müssen.

• Stream: Entspricht genau einer durchgehenden bidirektionalen Kommunikation auf Anwendungsebene, auf die Analysen und Änderungen angewendet werden können. Bei HTTP enthält er eine einzelne Anfrage und die zugehörige Antwort. Er entsteht beim Eingang der Anfrage und endet mit der vollständigen Auslieferung der Antwort. In diesem Zusammenhang besteht eine 1:1-Beziehung zum Stream eines Multiplex-Protokolls. Bei TCP-Kommunikation gibt es einen Stream je Verbindung.

• Transaktion: Besteht nur aus einer Anfrage und der zugehörigen Antwort. Vor der Einführung von Streams wurde der Begriff zusammen mit Sitzungen verwendet; heute besteht eine 1:1-Beziehung zwischen Transaktion und Stream. Sichtbar ist er vor allem im Variablengültigkeitsbereich “txn”, der während der gesamten Transaktion und damit des Streams gilt.

• Anfrage: Bezeichnet den Datenverkehr vom Client zum Server. Der Begriff wird vorwiegend bei HTTP verwendet, um anzugeben, wo Operationen ausgeführt werden, bei TCP aber ebenso zur Angabe der Verarbeitungsrichtung. In Zählern dienen Anfragen oft als Einheit für Verkehr oder Aktivität. Sie führen nicht immer zu einer Antwort, etwa bei Fehlern. Da es jedoch keine unaufgeforderten Antworten ohne Anfragen gibt, bleiben Anfragen ein sinnvolles Maß für die Gesamtaktivität. Bei TCP gibt es ebenso viele Anfragen wie Verbindungen.

• Antwort: Bezeichnet den Datenverkehr vom Server zum Client oder von HAProxy zum Client, wenn HAProxy die Antwort selbst erzeugt, etwa bei einer HTTP-Weiterleitung.

• Dienst: Bezeichnet meist eine interne Verarbeitung in HAProxy, für die kein Server erforderlich ist, etwa die Statistikseite, der Cache oder Lua-Code für eine kleine Anwendung. Ein Dienst liest normalerweise eine Anfrage, führt Operationen aus und erzeugt eine Antwort.

1.3. HTTP-Anfrage

Als Beispiel dient folgende HTTP-Anfrage:

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

1.3.1. Die Anfragezeile

Zeile 1 ist die Anfragezeile. Sie besteht immer aus 3 Feldern:

• einer Methode: GET
• einer URI: /serv/login.php?lang=en&profile=2
• einer Versionsangabe: HTTP/1.1

Die Felder werden durch sogenannte LWS getrennt, linearen Leerraum nach dem Standard. Meist sind das Leerzeichen; möglich sind aber auch Tabulatoren oder Zeilenumbrüche beziehungsweise Wagenrückläufe, gefolgt von Leerzeichen oder Tabulatoren. Die Methode selbst darf keinen Doppelpunkt (’:’) enthalten und besteht ausschließlich aus Buchstaben. Wegen dieser vielfältigen Kombinationen ist es sinnvoll, die Zerlegung HAProxy zu überlassen, statt selbst einen komplexen oder ungenauen regulären Ausdruck zu schreiben.

Die URI kann verschiedene Formen haben:

• Eine relative URI:

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

Dies ist eine vollständige URL ohne Host-Teil. Diese Form empfangen
normalerweise Server, Reverse-Proxys und transparente Proxys.

• Eine absolute URI, auch URL genannt:

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

Sie besteht aus einem Schema (Protokollname gefolgt von '://'), einem
Hostnamen oder einer Adresse, optional einem Doppelpunkt (':') mit
Portnummer und einer relativen URI ab dem ersten Schrägstrich ('/')
nach der Adresse. Meist empfangen Proxys diese Form. Ein Server,
der HTTP/1.1 unterstützt, muss sie jedoch ebenfalls akzeptieren.

• Ein Stern (’*’): Diese Form ist nur zusammen mit OPTIONS zulässig und kann nicht weitergeleitet werden. Sie dient dazu, die Fähigkeiten des nächsten Netzknotens abzufragen.

• Eine Kombination aus Adresse und Port, etwa 192.168.0.12:80. Sie wird mit CONNECT verwendet, um TCP-Tunnel durch HTTP-Proxys aufzubauen, meist für HTTPS, gelegentlich auch für andere Protokolle.

Eine relative URI besteht aus zwei Teilen. Vor dem Fragezeichen steht der Pfad, normalerweise der relative Pfad zu statischen Objekten auf dem Server. Danach folgt die Abfragezeichenfolge. Sie wird hauptsächlich bei GET-Anfragen an dynamische Skripte verwendet und hängt stark von der eingesetzten Sprache, dem Framework oder der Anwendung ab.

HTTP/2 und HTTP/3 übertragen keine Versionsinformation mit der Anfrage. Daher wird die Version des zugrunde liegenden Protokolls angenommen, also “HTTP/2”. Außerdem senden diese Protokolle keine zusammenhängende Anfragezeile. Sie zerlegen sie in einzelne Pseudo-Header, deren Namen mit einem Doppelpunkt beginnen. HAProxy setzt daraus wieder eine entsprechende Anfragezeile zusammen. Deshalb können sich protokollierte Anfragezeilen zwischen HTTP/1.x und HTTP/2 oder HTTP/3 leicht unterscheiden.

1.3.2. Die Anfrage-Header

Die Header beginnen in der zweiten Zeile. Am Zeilenanfang steht ein Name, unmittelbar gefolgt von einem Doppelpunkt (’:’). Üblicherweise folgt danach LWS, vorgeschrieben ist das jedoch nicht. Anschließend stehen die Werte. Mehrere gleichnamige Header können in einer Zeile zusammengefasst und ihre Werte durch Kommas getrennt werden, sofern die Reihenfolge erhalten bleibt. Dies kommt häufig beim Feld “Cookie:” vor. Ein Header kann mehrere Zeilen umfassen, wenn die Folgezeilen mit LWS beginnen. Im Beispiel aus 1.3 enthalten die Zeilen 4 und 5 insgesamt 3 Werte für “Accept:”. Gemäß Spezifikation wird LWS am Anfang und Ende eines Headers ignoriert und gehört nicht zum Wert.

Entgegen einer verbreiteten Annahme wird bei Header-Namen nicht zwischen Groß- und Kleinschreibung unterschieden. Das gilt auch für Werte, die andere Header-Namen bezeichnen, etwa bei “Connection:”. HTTP/2 und HTTP/3 übertragen Header-Namen immer in Kleinbuchstaben, was im Debug-Modus zu sehen ist. Intern werden sämtliche Header-Namen in Kleinbuchstaben normalisiert, damit HTTP/1.x und HTTP/2 oder HTTP/3 dieselbe Darstellung verwenden. Auf der anderen Seite werden sie unverändert gesendet. Deshalb kommt eine mit Binnenmajuskeln geschriebene HTTP/1.x-Anfrage mit kleingeschriebenen Header-Namen an.

Die erste leere Zeile beendet die Header. Oft wird von einem doppelten Zeilenumbruch gesprochen. Das ist ungenau, auch wenn ein doppelter Zeilenumbruch eine gültige Form einer Leerzeile ist.

HAProxy berücksichtigt diese komplexen Kombinationen beim Indizieren, Prüfen und Zählen der Header-Werte. Über ihre mögliche Schreibweise muss man sich daher keine Gedanken machen. Eine Anwendung sollte aber nicht als fehlerhaft gelten, nur weil sie ungewöhnliche, jedoch gültige Konstrukte verwendet.

Wichtiger Hinweis:

Wie in RFC7231 vorgeschlagen, normalisiert HAProxy Header, indem es
Zeilenumbrüche innerhalb eines Headers durch LWS ersetzt und so
mehrzeilige Header zusammenführt. Das ist für eine korrekte Analyse
nötig und hilft weniger leistungsfähigen HTTP-Parsern, korrekt zu
arbeiten und sich nicht durch solche komplexen Konstrukte täuschen
zu lassen.

1.4. HTTP-Antwort

Eine HTTP-Antwort ähnelt einer HTTP-Anfrage stark. Beide heißen HTTP-Nachrichten. Als Beispiel dient folgende Antwort:

Zeilen-  Inhalt
nummer
   1     HTTP/1.1 200 OK
   2     Content-length: 350
   3     Content-Type: text/html

Als Sonderfall unterstützt HTTP sogenannte Informationsantworten mit Statuscodes 1xx. Sie enthalten keinen Teil der eigentlichen Antwort, sondern dienen als Signalisierung, etwa um einen Client zum weiteren Senden seiner Anfrage aufzufordern. Bei einer Antwort mit Status 100 stehen die angeforderten Informationen in der nächsten folgenden Antwort, deren Status nicht 100 ist. Auf eine Anfrage können somit mehrere Antworten folgen. Das funktioniert nur mit aktiviertem Keep-Alive; 1xx-Nachrichten wurden mit HTTP/1.1 eingeführt. HAProxy kann diese Nachrichten korrekt weiterleiten und überspringen und verarbeitet nur die nächste Antwort mit einem anderen Status als 100. Sofern nicht ausdrücklich anders angegeben, werden diese Nachrichten weder protokolliert noch verändert. Status 101 bedeutet, dass das Protokoll auf derselben Verbindung wechselt. HAProxy muss dann wie nach CONNECT in den Tunnelmodus wechseln. Der Header Upgrade enthält zusätzliche Informationen zum neuen Protokoll.

1.4.1. Die Antwortzeile

Zeile 1 ist die Antwortzeile. Sie besteht immer aus 3 Feldern:

• einer Versionsangabe: HTTP/1.1
• einem Statuscode: 200
• einer Begründung: OK

Der Statuscode hat immer 3 Stellen. Die erste Ziffer bezeichnet die allgemeine Statusklasse:

• 1xx = zu überspringende Informationsnachricht, etwa 100 oder 101
• 2xx = OK, Inhalt folgt, etwa 200 oder 206
• 3xx = OK, kein Inhalt folgt, etwa 302 oder 304
• 4xx = vom Client verursachter Fehler, etwa 401, 403 oder 404
• 5xx = vom Server verursachter Fehler, etwa 500, 502 oder 503

Statuscodes über 599 dürfen nicht übertragen werden. Manche Implementierungen verwenden sie jedoch in Protokollen, um interne Zustände zu melden. Die genaue Bedeutung der Codes beschreibt RFC9110. HTTP/2 und neuere Versionen haben keine Versionsangabe und übermitteln den Statuscode im Pseudo-Header “:status”.

Das Feld “reason” ist nur ein Hinweis und wird von Clients nicht ausgewertet. Es kann beliebigen Inhalt haben; üblich sind jedoch die etablierten Meldungen. Das Feld kann aus einem oder mehreren Wörtern bestehen, etwa “OK”, “Found” oder “Authentication Required”. Ab HTTP/2 existiert es nicht und wird nicht übertragen. Leitet HAProxy eine Antwort von HTTP/2 oder neuer an einen HTTP/1-Client weiter, erzeugt es ein solches übliches, zum Statuscode passendes Begründungsfeld.

HAProxy kann selbst folgende Statuscodes ausgeben:

Code  Anlass / Grund
 200  Zugriff auf die Statistikseite und Antworten auf Überwachungsanfragen
 301  Weiterleitung, abhängig vom konfigurierten Code
 302  Weiterleitung, abhängig vom konfigurierten Code
 303  Weiterleitung, abhängig vom konfigurierten Code
 307  Weiterleitung, abhängig vom konfigurierten Code
 308  Weiterleitung, abhängig vom konfigurierten Code
 400  Ungültige oder zu große Anfrage
 401  Die Aktion erfordert eine Authentifizierung, etwa beim Zugriff
      auf die Statistikseite.
 403  Eine Regel "http-request deny" verbietet die Anfrage.
 404  Die angeforderte Ressource wurde nicht gefunden.
 408  Die Zeitüberschreitung für Anfragen tritt ein, bevor die Anfrage
      vollständig ist.
 410  Die angeforderte Ressource ist nicht mehr verfügbar und wird
      auch künftig nicht mehr verfügbar sein.
 413  Eine HTTP/1.0-Anfrage mit GET/HEAD/DELETE enthält Nutzdaten;
      siehe auch "h1-accept-payload-with-any-method".
 500  HAProxy hat einen nicht behebbaren internen Fehler festgestellt,
      etwa eine fehlgeschlagene Speicherreservierung. Dies sollte
      niemals vorkommen.
 501  HAProxy kann eine Client-Anfrage wegen einer nicht unterstützten
      Funktion nicht erfüllen.
 502  Der Server liefert eine leere, ungültige oder unvollständige
      Antwort, oder eine Regel "http-response deny" blockiert sie.
 503  Kein Server konnte die Anfrage bearbeiten, oder eine
      Überwachungsanfrage erfüllt die Bedingung "monitor fail".
 504  Die Zeitüberschreitung für Antworten tritt ein, bevor der
      Server antwortet.

Die oben aufgeführten Fehlercodes 4xx und 5xx lassen sich anpassen; siehe “errorloc” in Abschnitt 4.2 . Andere Statuscodes können gezielt durch bestimmte Aktionen ausgegeben werden, etwa “deny”, “return” und “redirect” in Abschnitt 4.3 .

1.4.2. Die Antwort-Header

Antwort-Header funktionieren genauso wie Anfrage-Header. HAProxy verwendet daher dieselbe Analysefunktion für beide. Einzelheiten stehen in Abschnitt 1.3.2.

11 - 2. HAProxy konfigurieren

2.1. Format der Konfigurationsdatei

Die Konfiguration von HAProxy bezieht Parameter aus 3 wesentlichen Quellen:

• den Befehlszeilenargumenten, die immer Vorrang haben
• den Konfigurationsdateien, deren Format hier beschrieben wird
• der Umgebung des laufenden Prozesses, sofern bestimmte Umgebungsvariablen ausdrücklich referenziert werden

Die Konfigurationsdatei verwendet ein recht einfaches hierarchisches Format mit wenigen Grundregeln:

1. Eine Konfigurationsdatei ist eine geordnete Folge von Anweisungen.

2. Eine Anweisung ist eine einzelne nicht leere Zeile bis zum ersten
   ungeschützten "#" (Raute).

3. Eine Zeile besteht aus Tokens oder „Wörtern“, die durch ungeschützte
   Leerzeichen oder Tabulatoren getrennt sind.

4. Das erste Wort oder die erste Wortfolge einer Zeile ist eines der in
   diesem Dokument aufgeführten Schlüsselwörter oder Schlüsselwortfolgen.

5. Alle übrigen Wörter sind Argumente des ersten. Manche sind bekannte,
   hier aufgeführte Schlüsselwörter, andere Werte, Verweise auf andere
   Konfigurationsteile oder Ausdrücke.

6. Bestimmte Schlüsselwörter begrenzen einen Abschnitt, in dem nur ein
   Teil der Schlüsselwörter unterstützt wird.

7. Ein Abschnitt endet am Dateiende oder mit einem besonderen Schlüsselwort,
   das einen neuen Abschnitt beginnt.

Mehr ist zum Schreiben eines einfachen, aber zuverlässigen Konfigurationsgenerators nicht nötig. Um jede beliebige Konfiguration zuverlässig auszuwerten oder bestimmte Grenzfälle zu behandeln, reicht dies jedoch nicht aus.

Aus den obigen Regeln ergeben sich zunächst einige Folgerungen. Nach Regel 6 und 7 gelten die Schlüsselwörter zum Definieren eines neuen Abschnitts überall und können in keinem bestimmten Abschnitt eine andere Bedeutung haben. Diese Schlüsselwörter bestehen stets aus einem einzelnen Wort, nicht aus einer Wortfolge. Der nachfolgende Abschnitt wird gewöhnlich mit demselben Namen bezeichnet. So meint „globaler Abschnitt“ den Konfigurationsabschnitt nach dem Schlüsselwort “global”. Diese Bezeichnung wird in Fehlermeldungen häufig verwendet, um die zu bearbeitenden Stellen leichter auffindbar zu machen.

Mehrere Abschnittstypen erzeugen ein internes Objekt oder einen Konfigurationsbereich, der von anderen unterscheidbar sein muss. Dafür nehmen sie ein zusätzliches Wort entgegen, das den Namen dieses Abschnitts festlegt. Bei einigen ist der Abschnittsname zwingend erforderlich. So erzeugt “frontend foo” einen neuen Abschnitt des Typs “frontend” mit dem Namen “foo”. Ein Name gilt gewöhnlich nur für seinen Abschnittstyp; zwei Abschnitte unterschiedlichen Typs können denselben Namen tragen. Davon wird jedoch abgeraten, da es die Konfigurationsverwaltung erschwert.

Aus Regel 7 folgt unmittelbar, dass beim Einlesen mehrerer Dateien jede davon mit einem neuen Abschnitt beginnen muss und jedes Dateiende einen Abschnitt beendet. Eine Datei kann weder Unterabschnitte enthalten noch einen bestehenden Abschnitt beenden und einen neuen beginnen.

Regel 1 besagt, dass die Reihenfolge wichtig ist. Manche Schlüsselwörter definieren Direktiven, die mehrfach wiederholt werden können, um eine geordnete Folge von Regeln zu bilden. Beispielsweise können mit “tcp-request” Regeln für “accept” und “reject” anhand verschiedener Kriterien abwechselnd angewendet werden. Ein Werkzeug zur Bearbeitung von Konfigurationsdateien muss deshalb beim Ändern einer Datei stets die Reihenfolge innerhalb eines Abschnitts erhalten. Die Reihenfolge der Abschnitte ist gewöhnlich unerheblich. Eine Ausnahme bildet der globale Abschnitt: Er muss vor den anderen stehen, kann aber bei Bedarf wiederholt werden. Außerdem können bestimmten erzeugten Objekten wie Proxys automatisch Kennungen zugewiesen werden, die sich beim Umordnen der Abschnitte ändern. Sie erscheinen beispielsweise in der Statistik. In der folgenden Konfiguration erhält “foo” daher eine kleinere ID als “bar”. Werden die beiden Abschnitte vertauscht, kehrt sich dies um:

listen foo
    bind :80

listen bar
    bind :81

Ein weiterer wichtiger Punkt: Nach den Regeln 2 und 3 gehören Leerzeilen, Leerzeichen, Tabulatoren und Kommentare nach einem ungeschützten “#” nicht zur Konfiguration, da sie nur als Begrenzungen dienen. Die folgenden Konfigurationen sind daher exakt gleichwertig:

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

und:

global
    daemon

# this is the public web frontend
frontend foo
    mode http

Üblicherweise wird nur das Schlüsselwort, das einen neuen Abschnitt beginnt, linksbündig angeordnet. Alle anderen Schlüsselwörter werden durch einen Tabulator oder einige vorangestellte Leerzeichen eingerückt. So ist sofort erkennbar, dass sie zu demselben Abschnitt gehören, wie im zweiten Beispiel oben. Kommentare vor einem neuen Abschnitt helfen beim Erkennen des gesuchten Abschnitts. Eine Leerzeile am Abschnittsende erleichtert es ebenfalls, beim Bearbeiten dessen Ende zu finden.

Tabulatoren eignen sich gut zum Einrücken, lassen sich aber schlecht kopieren und einfügen. Werden stattdessen Leerzeichen verwendet, werden nur wenige (2 bis 4) empfohlen. So bleibt die Bearbeitung vor Ort auch mit einfachen Editoren ohne automatische Einrückung handhabbar.

Früher wurden Argumente häufig an festen Tabulatorpositionen ausgerichtet, da die meisten Schlüsselwörter höchstens zwei Argumente annahmen. Für moderne Versionen mit komplexen Ausdrücken eignet sich dies nicht mehr und wird nicht empfohlen.

2.2. Anführungszeichen und Maskierung

In modernen Konfigurationen benötigen manche Argumente Zeichen, die zuvor ausschließlich als Trennzeichen dienten. HAProxy unterstützt deshalb die Maskierung eines Zeichens mit einem vorangestellten Backslash (’\’), schwaches Quoting mit doppelten Anführungszeichen ("") um einen Textabschnitt und starkes Quoting mit einfachen Anführungszeichen (’’) um einen Textabschnitt.

Dies ähnelt dem Vorgehen in verschiedenen Programmiersprachen und besonders dem üblichen Verhalten der Bourne-Shell. Beim Zerlegen der Zeilen in Wörter berücksichtigt der Konfigurationsparser auch Anführungszeichen und Backslashes. So entscheidet er, ob ein Zeichen als Trennzeichen oder als wörtliches Zeichen innerhalb des aktuellen Wortes gilt. Anschließend werden das Maskierungszeichen und die Anführungszeichen entfernt; das verbleibende Wort wird unverändert etwa als Schlüsselwort oder Argument verwendet.

Wird innerhalb eines Wortes ein Backslash benötigt, muss er entweder mit sich selbst maskiert werden, also durch einen doppelten Backslash, oder in einfache Anführungszeichen gesetzt werden.

Außerhalb von Anführungszeichen wird ein Sonderzeichen durch einen vorangestellten Backslash (’\’) maskiert:

\    kennzeichnet ein Leerzeichen statt eines Trennzeichens
\#   kennzeichnet eine Raute statt des Beginns eines Kommentars
\\   fügt einen Backslash ein
\'   fügt ein einfaches Anführungszeichen statt eines starken Quoting-Zeichens ein
\"   fügt ein doppeltes Anführungszeichen statt eines schwachen Quoting-Zeichens ein

Zusätzlich lassen sich einige nicht druckbare Zeichen mit der üblichen C-Schreibweise einfügen:

\n   fügt einen Zeilenvorschub ein (LF, Zeichen \x0a oder dezimal ASCII 10)
\r   fügt einen Wagenrücklauf ein (CR, Zeichen \x0d oder dezimal ASCII 13)
\t   fügt einen Tabulator ein (Zeichen \x09 oder dezimal ASCII 9)
\xNN fügt das Zeichen mit dem hexadezimalen ASCII-Code NN ein (z. B. \x0a für LF).

Für schwaches Quoting wird das zu schützende Zeichen oder die Zeichenfolge in doppelte Anführungszeichen ("") gesetzt. Dadurch werden folgende Interpretationen verhindert:

     Leerzeichen oder Tabulator als Worttrenner
'    einfaches Anführungszeichen als Begrenzer für starkes Quoting

#    Raute als Kommentarbeginn

Schwaches Quoting ermöglicht die Auswertung von Umgebungsvariablen, denen ein Dollarzeichen (’$’) vorangestellt wird. Außerhalb von Anführungszeichen werden diese nicht ausgewertet. Wird innerhalb doppelter Anführungszeichen ein Dollarzeichen als solches benötigt, muss es mit einem Backslash maskiert werden.

Für starkes Quoting wird das zu schützende Zeichen oder die Zeichenfolge in einfache Anführungszeichen (’’) gesetzt. Darin wird nichts interpretiert; dies ist eine wirksame Methode, reguläre Ausdrücke zu schützen.

Die folgende Tabelle zeigt daraus abgeleitet, wie Sonderzeichen in verschiedenen Kontexten eingegeben werden können. Nicht druckbare Zeichen sind durch ihren Namen in spitzen Klammern ersetzt. Manche Zeichen lassen sich nur maskiert darstellen und besitzen innerhalb einfacher Anführungszeichen keine mögliche Darstellung; deshalb fehlen sie dort:

  Zeichen    |  Unquotiert   |  Schwach quotiert           |  Stark quotiert
  -----------+---------------+-----------------------------+-----------------
    <TAB>    |  \<TAB>, \x09 |  "<TAB>", "\<TAB>", "\x09"  |  '<TAB>'
  -----------+---------------+-----------------------------+-----------------
    <LF>     |  \n, \x0a     |  "\n", "\x0a"               |
  -----------+---------------+-----------------------------+-----------------
    <CR>     |  \r, \x0d     |  "\r", "\x0d"               |
  -----------+---------------+-----------------------------+-----------------
    <SPC>    |  \<SPC>, \x20 |  "<SPC>", "\<SPC>", "\x20"  |  '<SPC>'
  -----------+---------------+-----------------------------+-----------------
    "        |  \", \x22     |  "\"", "\x22"               |  '"'
  -----------+---------------+-----------------------------+-----------------
    #        |  \#, \x23     |  "#", "\#", "\x23"          |  '#'
  -----------+---------------+-----------------------------+-----------------
    $        |  $, \$, \x24  |  "\$", "\x24"               |  '$'
  -----------+---------------+-----------------------------+-----------------
    '        |  \', \x27     |  "'", "\'", "\x27"          |
  -----------+---------------+-----------------------------+-----------------
    \        |  \\, \x5c     |  "\\", "\x5c"               |  '\'
  -----------+---------------+-----------------------------+-----------------

Beispiel:

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

In einem besonderen Fall kann eine zweite Ebene von Anführungszeichen oder Maskierung nötig sein. Manche Schlüsselwörter nehmen Argumente in runden Klammern entgegen, teilweise durch Kommas getrennt. Meist sind dies Ganzzahlen oder vordefinierte Wörter. Bei beliebigen Zeichenketten kann jedoch eine weitere Maskierungsebene erforderlich sein, um Zeichen des Arguments von dessen Begrenzungszeichen zu unterscheiden. Ein häufiges Beispiel ist der Konverter “regsub”. Er nimmt einen regulären Ausdruck als Argument entgegen. Wird darin eine schließende runde Klammer benötigt, muss sie eigene Anführungszeichen erhalten.

Für Anführungszeichen verhält sich der Parser für Schlüsselwortargumente genauso wie der Parser auf oberster Ebene. Lediglich die Escape-Sequenzen \#, \$ und \xNN werden nicht verarbeitet. Weniger offensichtlich ist, dass die innen verwendeten Begrenzungszeichen zunächst maskiert oder in Anführungszeichen gesetzt werden müssen, damit sie nicht bereits auf der obersten Ebene aufgelöst werden.

Das folgende Beispiel verwendet den Konverter “regsub” mit 3 Argumenten: einem regulären Ausdruck, einer Ersetzungszeichenkette und einer Menge von Flags:

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

Hier waren keine besonderen Anführungszeichen nötig. Soll nun aber sowohl “foo” als auch “bar” durch “blah” ersetzt werden, wird der reguläre Ausdruck “(foo|bar)” benötigt. Folgendes ist nicht möglich:

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

Denn die Zeichenkette soll so aufgeteilt werden:

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

Tatsächlich wird jedoch eine Zeichenkette zwischen öffnender und schließender Klammer übergeben, gefolgt von ungültigem Resttext:

    http-request set-path %[path,regsub((foo|bar),blah,g)]
                                       |--------|--------|
                        arg1=(foo|bar _/        /
                    ungültiger Rest   _________/

Es scheint naheliegend, die schließende Klammer in Anführungszeichen zu setzen. Allein genügt dies aber nicht: Wie oben beschrieben, verarbeitet der Parser auf oberster Ebene die Anführungszeichen und löst sie vor der Verarbeitung dieses Wortes auf:

http-request set-path %[path,regsub("(foo|bar)",blah,g)]
------------ -------- ----------------------------------
   Wort1       Wort2    Wort3=%[path,regsub((foo|bar),blah,g)]

Für den Argumentparser auf der zweiten Ebene hat sich somit nichts geändert: Er sieht weiterhin einen abgeschnittenen regulären Ausdruck als einziges Argument und ungültigen Resttext am Ende. Werden die Anführungszeichen maskiert, gelangen sie unverändert auf die zweite Ebene:

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

Alternativ kann die gesamte Zeichenkette außen in einfache und innen in doppelte Anführungszeichen gesetzt werden, damit die doppelten Anführungszeichen nicht wieder entfernt werden:

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

Dabei ist zu beachten, dass Begrenzungszeichen innerhalb der übergeordneten Zeichenkette gewöhnliche Zeichen bleiben und keine Trennfunktion mehr haben. Insbesondere gehören Leerzeichen und Tabulatoren neben Kommas zur Zeichenkette. Das folgende Beispiel ist an mehreren Stellen falsch:

    http-request set-path '%[path, regsub("(foo|bar)", blah, g)]'
    ------------ --------  --------------------------------------
       Wort1       Wort2    Wort3=%[path, regsub("(foo|bar)", blah, g)]
                                        |--------|---------||-----|--|
                       Konverter=" regsub" _/        /         /   /
                                    arg1=(foo|bar) _/         /   /
                                     arg2=" blah" ___________/   /
                                        arg3=" g" ______________/

Allein die Leerzeichen um die Kommas führen dazu, dass diese Teil des Feldes selbst werden. Der Konverter " regsub" mit führendem Leerzeichen wird daher nicht gefunden und löst einen Fehler aus. Weniger offensichtlich ist, dass die Ersetzungszeichenkette " blah" ein Leerzeichen in die Ausgabe einfügt. Eine gute Faustregel lautet deshalb, niemals unnötige Leerzeichen in Ausdrücke einzufügen.

In regulären Ausdrücken kann das Dollarzeichen (’$’) auftreten oder ein Backslash (’\’) in der Ersetzungszeichenkette verwendet werden. Diese Zeichen werden innerhalb doppelter Anführungszeichen ebenfalls verarbeitet. Daher sind einfache Anführungszeichen oder eine doppelte Maskierung vorzuziehen. Beispiel:

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

Innerhalb einfacher Anführungszeichen sind Backslashes keine Maskierungszeichen. Das gesamte obige Wort ist bereits durch einfache Anführungszeichen vor ihrer Interpretation geschützt. Wäre dagegen der gesamte Ausdruck in doppelte Anführungszeichen gesetzt, würden das Dollarzeichen und die Backslashes bereits auf oberster Ebene aufgelöst und dadurch der Argumentinhalt auf der zweiten Ebene beschädigt.

Da einfache Anführungszeichen innerhalb von starkem Quoting nicht maskiert werden können, müssen sie bei Bedarf im Argument zweimal maskiert oder in Anführungszeichen gesetzt werden. Dafür gibt es mehrere Möglichkeiten:

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

Im Zweifelsfall zunächst ganz auf Anführungszeichen verzichten und nur Argumente mit Kommas oder schließenden runden Klammern in einfache oder doppelte Anführungszeichen setzen. Enthält die Zeichenkette ein Dollarzeichen oder einen Backslash, müssen diese Anführungszeichen gegebenenfalls mit einem Backslash maskiert werden. Dies ähnelt der doppelten Maskierung eines an “eval” übergebenen Befehls in einer Bourne-Shell. Für API-Autoren ist es vermutlich am besten, ausnahmslos jedes Argument unabhängig von seinem Inhalt mit maskierten Anführungszeichen zu umgeben. Für Anwender sind Konfigurationen wahrscheinlich besser lesbar, wenn der gesamte Ausdruck in einfachen und jedes Argument in doppelten Anführungszeichen steht.

2.3. Umgebungsvariablen

Die HAProxy-Konfiguration unterstützt Umgebungsvariablen. Sie werden ausschließlich innerhalb doppelter Anführungszeichen interpretiert und beim Einlesen der Konfiguration expandiert. Variablennamen müssen mit einem Dollarzeichen ("$") beginnen und können wie in der Bourne-Shell zusätzlich in geschweifte Klammern ("{}") eingeschlossen werden. Sie dürfen alphanumerische Zeichen und Unterstriche ("_") enthalten, sollten aber nicht mit einer Ziffer beginnen. Enthält eine Variable mehrere durch Leerzeichen getrennte Werte, lässt sie sich in einzelne Argumente expandieren: Dazu die Variable in geschweifte Klammern setzen und vor der schließenden Klammer das Suffix ‘[*]’ ergänzen. Ein Standardwert für nicht gesetzte Variablen kann nach einem Bindestrich ‘-’ hinter dem Variablennamen angegeben werden. Er ersetzt nur nicht vorhandene Variablen, keine leeren.

Beispiel:

bind "fd@${FD_APP1}"

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

user "$HAPROXY_USER"

Einige Variablen werden von HAProxy definiert und können in der Konfigurationsdatei verwendet werden. Sie sind in der folgenden Tabelle aufgeführt und in vier Kategorien eingeteilt:

• verwendbar: Die Variable ist in der Konfiguration zugänglich. Sie kann direkt aufgelöst oder in bedingten Blöcken und Prädikaten zum Aktivieren oder Deaktivieren von Konfigurationsfragmenten verwendet werden, wie in Abschnitt 2.4 „Bedingte Blöcke“ beschrieben.

• veränderbar: Die Variable kann in der Konfiguration mit “setenv”/“unsetenv” neu definiert oder entfernt werden.

• aufgelistet: Die Variable erscheint in der Ausgabe des CLI-Befehls “show env”, der in Abschnitt 9.3 „Unix-Socket-Befehle“ des Verwaltungshandbuchs beschrieben ist.

Daneben gibt es die Unterkategorien „Master“ und „Worker“, die in der folgenden Tabelle mit ‘M’ bzw. ‘W’ gekennzeichnet sind. Sie zeigen die Unterschiede zwischen den beiden Prozessen beim Start von HAProxy im Master-Worker-Modus.

• Master: Die Variable ist im Master-Prozess gesetzt und zugänglich. Sie erscheint daher in der Ausgabe von “show env” der Master-CLI und kann in bedingten Blöcken oder Direktiven spezielle Einstellungen für den Master aktivieren. Siehe die Beispiele in Abschnitt 2.4 „Bedingte Blöcke“.

• Worker: Die Variable ist im Worker-Prozess gesetzt und zugänglich. Sie erscheint in “show env” der Worker-CLI oder in “@1 show env” der Master-CLI und kann ebenfalls Bedingungen für Parameter des Worker-Prozesses bilden. Siehe die Beispiele in Abschnitt 2.4 „Bedingte Blöcke“.

Im eigenständigen Betrieb ohne die Option “-W” und ohne das Schlüsselwort “master-worker” verhält sich der Prozess wie ein Worker. Ausgenommen sind die Variablen “HAPROXY_MASTER_CLI” und “HAPROXY_MWORKER”, die dann nicht definiert sind.

Einige Variablen sind als weder verwendbar noch veränderbar gekennzeichnet:

• HAPROXY_CFGFILES
• HAPROXY_MWORKER
• HAPROXY_CLI
• HAPROXY_MASTER_CLI
• HAPROXY_LOCALPEER

Ihre Werte sind beim Einlesen der Konfiguration undefiniert und werden erst später während der Initialisierung gesetzt. Daher wird empfohlen, diese Variablen weder in bedingten Blöcken noch in den Schlüsselwörtern “setenv”/“resetenv”/“unsetenv” des globalen Abschnitts zu referenzieren.

Die folgende Tabelle fasst den Status der Variablen für die verschiedenen Betriebsarten zusammen:

  +---------------------------+---------+------------+-----------+
  |          Variable         | nutzbar |  änderbar  | angezeigt |
  |                           +---------+------------+-----------+
  |                           |  M | W  |   M  |  W  |  M  |  W  |
  +---------------------------+----+----+------+-----+-----+-----+
  | HAPROXY_STARTUP_VERSION   |  X | X  |      |     |  X  |  X  |
  | HAPROXY_BRANCH            |  X | X  |      |     |  X  |  X  |
  | HAPROXY_CFGFILES          |    |    |      |     |  X  |  X  |
  | HAPROXY_MWORKER           |    |    |      |     |  X  |  X  |
  | HAPROXY_CLI               |    |    |      |     |     |  X  |
  | HAPROXY_MASTER_CLI        |    |    |      |     |  X  |     |
  | HAPROXY_LOCALPEER         |    | X  |      |     |     |  X  |
  | HAPROXY_HTTP_LOG_FMT      |    | X  |      |  X  |     |     |
  | HAPROXY_HTTP_CLF_LOG_FMT  |    | X  |      |  X  |     |     |
  | HAPROXY_HTTPS_LOG_FMT     |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_LOG_FMT       |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_CLF_LOG_FMT   |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_FC_LOG_FMT |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_BC_LOG_FMT |    | X  |      |  X  |     |     |
  +---------------------------+----+----+------+-----+-----+-----+

Im Einzelnen handelt es sich um folgende Variablen:

• HAPROXY_LOCALPEER: beim Prozessstart definiert; enthält den Namen des lokalen Peers. Siehe “-L” im Verwaltungshandbuch.

• HAPROXY_CFGFILES: durch Semikolons getrennte Liste der von HAProxy geladenen Konfigurationsdateien. Kann bei der Angabe eines Verzeichnisses nützlich sein.

• HAPROXY_HTTP_LOG_FMT: enthält das HTTP-Standardprotokollformat aus Abschnitt 8.2.3 „HTTP-Protokollformat“. Damit lässt sich das Standardformat überschreiben, ohne die gesamte ursprüngliche Definition kopieren zu müssen.

• HAPROXY_HTTP_CLF_LOG_FMT: enthält das HTTP-CLF-Standardprotokollformat aus Abschnitt 8.2.3 „HTTP-Protokollformat“. Damit lässt sich das Standardformat überschreiben, ohne die gesamte ursprüngliche Definition kopieren zu müssen.

Beispiel:

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

• HAPROXY_HTTPS_LOG_FMT: wie HAPROXY_HTTP_LOG_FMT, jedoch für das HTTPS-Protokollformat aus Abschnitt 8.2.4 „HTTPS-Protokollformat“.

• HAPROXY_TCP_LOG_FMT: wie HAPROXY_HTTP_LOG_FMT, jedoch für das TCP-Protokollformat aus Abschnitt 8.2.2 „TCP-Protokollformat“.

• HAPROXY_TCP_CLF_LOG_FMT: wie HAPROXY_HTTP_CLF_LOG_FMT, jedoch für das TCP-CLF-Protokollformat aus Abschnitt 8.2.2 „TCP-Protokollformat“.

• HAPROXY_KEYLOG_FC_LOG_FMT: enthält das Keylog-Format für die clientseitige TLS-Verbindung des Frontends. Schlüsseleinträge werden durch Zeilenumbrüche getrennt; das Format ist daher möglicherweise nicht mit dem verwendeten syslog-Server kompatibel. “tune.ssl.keylog on” ist erforderlich.

• HAPROXY_KEYLOG_BC_LOG_FMT: wie HAPROXY_KEYLOG_FC_LOG_FMT, jedoch für die serverseitige TLS-Verbindung des Backends. Schlüsseleinträge werden durch Zeilenumbrüche getrennt; das Format ist daher möglicherweise nicht mit dem verwendeten syslog-Server kompatibel. “tune.ssl.keylog on” ist erforderlich.

• HAPROXY_MWORKER: Diese Variable wird im Master-Worker-Modus auf 1 gesetzt.

• HAPROXY_CLI: konfigurierte Listener-Adressen des Statistik-Sockets jedes Prozesses, durch Semikolons getrennt.

• HAPROXY_MASTER_CLI: im Master-Worker-Modus die durch Semikolons getrennten Listener-Adressen der Master-CLI.

• HAPROXY_STARTUP_VERSION: enthält die beim Start verwendete Version. Im Master-Worker-Modus ist dies die Version, mit der der Master gestartet wurde, auch nach Aktualisierung der ausführbaren Datei und anschließendem Neuladen.

• HAPROXY_BRANCH: enthält die Version des HAProxy-Zweigs, etwa “2.8”, jedoch nicht die vollständige Versionsnummer. Dies kann bei einer Migration nützlich sein, wenn Ressourcen wie Maps oder Zertifikate in einem Pfad mit der Nummer des Versionszweigs liegen.

Zusätzlich werden einige Pseudovariablen intern aufgelöst und lassen sich wie gewöhnliche Variablen verwenden. Pseudovariablen beginnen immer mit einem Punkt (’.’); nur in ihnen ist ein Punkt zulässig. Derzeit gibt es folgende Pseudovariablen:

• .FILE: Name der gerade eingelesenen Konfigurationsdatei.

• .LINE: Zeilennummer in der gerade eingelesenen Konfigurationsdatei, beginnend bei eins.

• .SECTION: Name des gerade eingelesenen Abschnitts oder dessen Typ, wenn der Abschnitt keinen Namen hat, etwa “global”. Vor dem ersten Abschnitt ist dies eine leere Zeichenkette.

Diese Variablen werden an der Stelle aufgelöst, an der sie eingelesen werden. Wird beispielsweise “.LINE” in einer “log-format”-Direktive eines defaults-Abschnitts verwendet, steht die Zeilennummer bereits vor dem Parsen und Kompilieren der “log-format”-Direktive fest. Nachfolgende Proxys verwenden daher dieselbe Zeilennummer.

So lassen sich in Variablen, Protokollen, Fehlerstatus, Health Checks und Header-Werten Informationen zum Auffinden einer Regel ausgeben. Zeilennummern können sogar zur Benennung von Konfigurationsobjekten wie Servern dienen.

2.4. Bedingte Blöcke

Manchmal ist es praktisch, beliebige Teile der Konfiguration abhängig von Bedingungen ein- oder auszuschalten. So lassen sich beispielsweise SSL oder Cipher sowie Listener einer Vorproduktionsumgebung ohne Änderung der Konfiguration aktivieren oder deaktivieren. Auch die Konfigurationssyntax kann während einer Migration zwei verschiedene HAProxy-Versionen unterstützen. HAProxy bietet dafür verschachtelbare Direktiven nach Art eines Präprozessors, die Textblöcke einbeziehen oder ignorieren. Diese Direktiven müssen in einer eigenen Zeile stehen und wirken auf die folgenden Zeilen. Zwei davon unterstützen einen Ausdruck; die anderen wechseln lediglich zu einem alternativen Block oder schließen die aktuelle Ebene ab. Bedingte Blöcke werden mit folgenden 4 Direktiven gebildet:

• .if <condition>
• .elif <condition>
• .else
• .endif

“.if” eröffnet eine neue verschachtelte Ebene, “.elif” und “.else” bleiben auf derselben Ebene, und “.endif” schließt eine Ebene. Jedes “.if” muss mit einem zugehörigen “.endif” abgeschlossen werden. “.elif” darf nur auf “.if” oder “.elif” folgen; beliebig viele “.elif” können aufeinanderfolgen. Je “.if” ist nur ein “.else” zulässig. Es muss immer nach dem “.if” oder dem letzten “.elif” eines Blocks stehen.

Kommentare können bei Bedarf nach einem ‘#’ in derselben Zeile stehen und werden ignoriert. Die Direktiven werden wie andere Konfigurationsdirektiven in Tokens zerlegt; daher können Bedingungen Umgebungsvariablen verwenden.

Bedingungen lassen sich auch beim Start mit dem Parameter -cc auswerten. Siehe „3. HAProxy starten“ im Verwaltungshandbuch.

Eine Bedingung ist entweder eine leere Zeichenkette, die falsch ergibt, oder ein Ausdruck aus einer beliebigen Kombination folgender Elemente:

• die Ganzzahl null (‘0’), die immer “false” ergibt
• eine Ganzzahl ungleich null, etwa ‘1’, die immer “true” ergibt
• ein Prädikat, optional gefolgt von Argumenten in runden Klammern
• eine Bedingung in einem Paar runder Klammern ‘(’ und ‘)’
• ein Ausrufezeichen (’!’) vor einem der obigen nicht leeren Elemente, das dessen Wert negiert
• mit logischem AND (’&&’) verknüpfte Ausdrücke, die von links nach rechts ausgewertet werden, bis einer falsch ergibt
• mit logischem OR (’||’) verknüpfte Ausdrücke, die von rechts nach links ausgewertet werden, bis einer wahr ergibt

Dabei werden derselbe Zeilen-Tokenizer und Argumentparser wie in der übrigen Konfigurationssprache verwendet. Wörter werden an Folgen eines oder mehrerer ungeschützter Leerzeichen oder Tabulatoren getrennt und vor der Auswertung mit jeweils einem Leerzeichen wieder zusammengesetzt. So muss nicht die gesamte Zeile in Anführungszeichen gesetzt werden. Allerdings gehören dadurch Leerzeichen um Kommas oder Klammern tatsächlich zum Wert, was nicht immer erwartet wird. Beispielsweise prüft der folgende Ausdruck:

.if defined( HAPROXY_MWORKER )

ob die Variable " HAPROXY_MWORKER " mit den Leerzeichen existiert. Dieser Ausdruck:

.if streq("$ENABLE_SSL",     1)

vergleicht dagegen die Umgebungsvariable “ENABLE_SSL” mit dem Wert " 1", der ein einzelnes führendes Leerzeichen enthält. Denn die Zeile wird zunächst wie folgt in Wörter zerlegt:

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

Anschließend wird das schwache Quoting verarbeitet und die Umgebungsvariable “$ENABLE_SSL” aufgelöst, beispielsweise mit ENABLE_SSL=0. Schließlich werden die Wörter mit jeweils einem Leerzeichen dazwischen zu einer einzigen Zeichenkette zusammengesetzt:

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

Erst danach wird diese als einzelner Ausdruck ausgewertet. Das zwischen Komma und “1” eingefügte Leerzeichen gehört weiterhin zum Argumentwert, sodass das Argument " 1" lautet:

   .if streq(0, 1)
  |---|-----|-|--|
    \    \    \  \_ Argument2: " 1"
     \    \    \___ Argument1: "0"
      \    \_______ Funktion: "streq"
       \___________ Direktive: ".if"

Selbst wenn ENABLE_SSL den Wert “1” hätte, würde dieser also nicht mit " 1" übereinstimmen, da sich die Zeichenketten um ein Leerzeichen unterscheiden.

Hinweis: Wie in Abschnitt „2.2. Anführungszeichen und Maskierung“ erläutert, ist es eine gute Faustregel, niemals unnötige Leerzeichen in Ausdrücke einzufügen.

Wie in anderen Sprachen hat AND Vorrang vor OR. Daher wird “A && B || C && D” als “(A && B) || (C && D)” ausgewertet.

Derzeit werden folgende Prädikate unterstützt:

• awslc_api_atleast(<ver>): ergibt wahr, wenn die aktuelle awslc-API-Nummer mindestens so neu wie <ver> ist, andernfalls falsch. Beispiel: awslc_api_atleast(35)

• awslc_api_before(<ver>): ergibt wahr, wenn die aktuelle awslc-API-Nummer strikt älter als <ver> ist, andernfalls falsch. Beispiel: awslc_api_before(26)

• defined(<name>) : ergibt wahr, wenn die Umgebungsvariable <name> existiert, unabhängig von ihrem Inhalt

• feature(<name>) : ergibt wahr, wenn die Funktion <name> in der Funktionsliste von “haproxy -vv” als vorhanden aufgeführt ist, also <name> nach einem ‘+’ erscheint

• openssl_version_atleast(<ver>): ergibt wahr, wenn die aktuelle openssl-Version mindestens so neu wie <ver> ist, andernfalls falsch. Bibliotheken wie LibreSSL, AWS-LC und WolfSSL geben ebenfalls eine Pseudo-OpenSSL-Version an. Beispiel:

ssllib_name_startswith(OpenSSL) && openssl_version_atleast(1.1.1)

• openssl_version_before(<ver>): ergibt wahr, wenn die aktuelle openssl-Version strikt älter als <ver> ist, andernfalls falsch. Bibliotheken wie LibreSSL, AWS-LC und WolfSSL geben ebenfalls eine Pseudo-OpenSSL-Version an. Beispiel: openssl_version_before(3.5.0)

• ssllib_name_startswith(<name>) : ergibt wahr, wenn der Name der mit HAProxy eingebundenen SSL-Bibliothek mit <name> beginnt. Beispiel: ssllib_name_startswith(wolfSSL)

• streq(<str1>,<str2>) : ergibt nur dann wahr, wenn beide Zeichenketten gleich sind

• strneq(<str1>,<str2>): ergibt nur dann wahr, wenn sich beide Zeichenketten unterscheiden

• strstr(<str1>,<str2>): ergibt nur dann wahr, wenn die zweite Zeichenkette in der ersten vorkommt.

• version_atleast(<ver>): ergibt wahr, wenn die aktuelle haproxy-Version mindestens so neu wie <ver> ist, andernfalls falsch. Die Versionssyntax entspricht der Ausgabe von “haproxy -v”; fehlende Bestandteile werden als null angenommen.

• version_before(<ver>): ergibt wahr, wenn die aktuelle haproxy-Version strikt älter als <ver> ist, andernfalls falsch. Die Versionssyntax entspricht der Ausgabe von “haproxy -v”; fehlende Bestandteile werden als null angenommen.

• enabled(<opt>) : ergibt wahr, wenn die Option <opt> zur Laufzeit aktiviert ist. Nur ein Teil der Optionen wird unterstützt:

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

Beispiel:

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

global
  master-worker

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

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

global
  master-worker

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

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

global
  setenv WITH_SSL yes
  unsetenv SSL_ONLY

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

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

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

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

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

Vier weitere Direktiven dienen der Ausgabe von Statusmeldungen:

• .diag “message” : gibt diese Meldung nur im Diagnosemodus (-dD) aus
• .notice “message” : gibt diese Meldung auf der Stufe NOTICE aus
• .warning “message”: gibt diese Meldung auf der Stufe WARNING aus
• .alert “message” : gibt diese Meldung auf der Stufe ALERT aus

Meldungen auf der Stufe WARNING können den Prozessstart verhindern, wenn “zero-warning” aktiviert ist. Meldungen auf der Stufe ALERT führen immer zu einem schwerwiegenden Fehler. Damit lassen sich ungeeignete Bedingungen erkennen und Hinweise für den Anwender ausgeben.

Beispiel:

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

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

2.5. Zeitformat

Manche Parameter enthalten Zeitwerte, etwa Zeitüberschreitungen. Sofern nicht ausdrücklich anders angegeben, werden sie gewöhnlich in Millisekunden ausgedrückt. Durch Anhängen einer Einheit an den Zahlenwert können aber auch andere Einheiten verwendet werden. Dies ist zu beachten, da es nicht bei jedem Schlüsselwort wiederholt wird. Unterstützt werden:

• us: Mikrosekunden. 1 Mikrosekunde = 1/1000000 Sekunde
• ms: Millisekunden. 1 Millisekunde = 1/1000 Sekunde. Dies ist der Standard.
• s : Sekunden. 1s = 1000ms
• m : Minuten. 1m = 60s = 60000ms
• h : Stunden. 1h = 60m = 3600s = 3600000ms
• d : Tage. 1d = 24h = 1440m = 86400s = 86400000ms

2.6. Größenformat

Manche Parameter enthalten Größenwerte, etwa Bandbreitengrenzen. Sofern nicht ausdrücklich anders angegeben, werden sie gewöhnlich in Bytes ausgedrückt. Durch Anhängen einer Einheit an den Zahlenwert können aber auch andere Einheiten verwendet werden. Dies ist zu beachten, da es nicht bei jedem Schlüsselwort wiederholt wird. Die folgenden Einheiten werden unabhängig von der Groß-/Kleinschreibung unterstützt:

• k: Kilobytes. 1 Kilobyte = 1024 Bytes
• m: Megabytes. 1 Megabyte = 1048576 Bytes
• g: Gigabytes. 1 Gigabyte = 1073741824 Bytes

Zeit- und Größenformate erfordern Ganzzahlen; Nachkommastellen sind nicht zulässig.

2.7. Namensformat für Maps und ACLs

Für Maps und ACLs können Musterlisten verwendet werden. Eine Musterliste wird durch ihren Namen identifiziert und kann an verschiedenen Stellen der Konfiguration zum Einsatz kommen. Je nach Namensformat gibt es drei Kategorien:

• Musterlisten aus regulären Dateien: Dies ist der Standardfall. Der absolute oder relative Dateiname dient als Name. Die Datei muss existieren, andernfalls tritt ein Fehler auf; sie darf jedoch leer sein. Das Präfix “file@” kann angegeben werden, gehört aber nicht zum Namen der Liste. Ein Dateiname verweist mit und ohne dieses Präfix auf dieselbe Musterliste.

• Musterlisten aus optionalen Dateien: Vor dem Dateinamen muss das Präfix “opt@” stehen. Die Datei muss nicht existieren. Ist sie vorhanden, wird ihr Inhalt geladen; fehlt sie, wird kein Fehler gemeldet. Das Präfix gehört nicht zum Namen der Liste. Bei gleichem Dateinamen verweisen optionale und reguläre Dateien daher auf dieselbe Musterliste.

• Musterlisten aus virtuellen Dateien: Der Name ist lediglich eine Kennung und verweist auf keine Datei. Das Präfix “virt@” muss verwendet werden und gehört zum Namen. Diese Listen lassen sich daher nicht mit den anderen Arten vermischen.

Virtuelle Dateien eignen sich für vollständig dynamisch verwaltete Muster, die beim Start und Neuladen noch nicht vorhanden sind. Optionale Dateien können unter denselben Bedingungen verwendet werden. Muster lassen sich jedoch in die Datei schreiben, etwa mit einem externen Skript auf Basis des CLI-Befehls “show map”. Dadurch können sie beim Neuladen erhalten bleiben.

Hinweis: Auch wenn solche Namen unwahrscheinlich sind, können damit keine regulären Dateien geladen werden, deren Name mit “file@”, “opt@” oder “virt@” beginnt. Dazu muss ausdrücklich “./” vor den Dateinamen gesetzt werden, beispielsweise “file@./virt@map”.

2.8. Variablen

In der HAProxy-Konfiguration lassen sich Variablen in Sample-Abruffunktionen, Konvertern, log-format-Zeichenketten und TCP/HTTP-Aktionen verwenden. Prozessweite Variablen sind während der gesamten Prozesslebensdauer global zugänglich; andere haben eine kürzere Lebensdauer. Wie in Shell-Skripten ist eine Variable ein symbolischer Name für einen Speicherbereich. Ihre Größe ist unbegrenzt, und der Speicher wird dynamisch reserviert. Deshalb müssen Variablen besonders bei intensiver Nutzung mit Vorsicht eingesetzt werden. Über die globalen Parameter “tune.vars” lässt sich jedoch der maximale Speicherverbrauch der Variablen begrenzen.

Variablen müssen im Format “<scope>.<name>” bezeichnet werden. <scope> ist ein einzelnes Wort für die Lebensdauer der Variablen. Der Teil <name> darf innerhalb eines Geltungsbereichs nur ‘a-z’, ‘A-Z’, ‘0-9’ und ‘_’ enthalten. Er ist dort eindeutig. Derselbe Name kann jedoch in verschiedenen Geltungsbereichen vorkommen und bezeichnet dann unterschiedliche Variablen. Unterstützt werden folgende Geltungsbereiche:

• proc : Variablen, die während der gesamten Prozesslebensdauer bekannt und global zugänglich sind. “proc”-Variablen lassen sich über die CLI mit “get var” und “set var” bearbeiten. In Abschnitten des Typs “global” können sie außerdem mit “set-var” und “set-var-fmt” gesetzt werden.

• sess : Variablen, die während der gesamten Sitzungslebensdauer bekannt sind. “sess”-Variablen gehören ausschließlich zu einer Sitzung, sind außerhalb davon unsichtbar und werden nicht mit anderen Sitzungen geteilt.

• txn : Variablen, die während der gesamten Transaktionslebensdauer bekannt sind. “txn”-Variablen gehören ausschließlich zu einem Stream, sind außerhalb davon unsichtbar und werden nicht mit anderen Streams geteilt.

• req : Variablen, die während der Anfrageverarbeitung eines bestimmten Streams bekannt sind. “req”-Variablen sind vom Erzeugen des Streams bis zum ersten Verbindungsversuch zum Server sichtbar. Sie gehören ausschließlich zu einem Stream, sind außerhalb davon unsichtbar und werden nicht mit anderen Streams geteilt. Zwischen “req”- und “res”-Variablen gibt es keinerlei Überschneidung.

• res : Variablen, die während der Antwortverarbeitung eines bestimmten Streams bekannt sind. “res”-Variablen sind vom ersten Verbindungsversuch zum Server bis zur Zerstörung des Streams sichtbar. Sie gehören ausschließlich zu einem Stream, sind außerhalb davon unsichtbar und werden nicht mit anderen Streams geteilt. Zwischen “req”- und “res”-Variablen gibt es keinerlei Überschneidung.

• check: Variablen, die während eines Health Checks bekannt sind. “check”-Variablen gehören ausschließlich zu einem Health Check, sind außerhalb davon unsichtbar und werden nicht mit anderen Health Checks geteilt. Sie können mit speziellen “tcp-check”- oder “http-check”-Direktiven gesetzt werden.

Je nach Kontext können zusätzliche Geltungsbereiche verwendet werden, die auf den Elternstream des aktuellen Streams verweisen:

• psess: wie “sess”, verwendet jedoch die Sitzung des Elternstreams, sofern vorhanden.

• ptxn : wie “txn”, verwendet jedoch die Transaktion des Elternstreams, sofern vorhanden.

• preq : wie “req”, verwendet jedoch den Elternstream, sofern vorhanden. “preq”-Variablen sind nur während der Anfrageverarbeitung des Elternstreams zugänglich.

• pres : wie “res”, verwendet jedoch den Elternstream, sofern vorhanden. “pres”-Variablen sind nur während der Antwortverarbeitung des Elternstreams zugänglich.

Auf den Elternstream verweisende Geltungsbereiche sind nutzbar, sobald dieser definiert ist. Meist gibt es keinen Elternstream; andernfalls wird dies ausdrücklich angegeben. Derzeit können nur Werte von Variablen aus einem Geltungsbereich des Elternstreams gelesen werden. Solche Variablen lassen sich weder setzen noch entfernen. Ein Kindstream übernimmt gewöhnlich zu einem bestimmten Zeitpunkt eine Verarbeitung für den Elternstream und hält diesen an, bis der Vorgang abgeschlossen ist. Der Elternstream kann daher beispielsweise mitten in der Anfrage- oder Antwortverarbeitung pausieren. Bestimmte Geltungsbereiche sind dann vom Kindstream aus nicht verfügbar. Untersucht etwa ein Kindstream eine Anfrage, findet er keine Variablen im Geltungsbereich “pres”: Der Elternstream verarbeitet gerade keine Antwort und hat deshalb keine Variablen im Bereich “res”.

Der Inhalt einer Variablen ist das Ergebnis eines Sample-Abrufausdrucks und übernimmt dessen Ausgabetyp. Dieser muss zur Verwendung der Variablen passen. Enthält eine Variable beispielsweise eine Zeichenkette und wird im Konverter “add()” verwendet, muss sie für einen erfolgreichen Aufruf in eine gültige Ganzzahl umwandelbar sein. Das ist besonders beim Vergleich von Variablen mit statischen Werten wichtig: Es muss die passende Abgleichmethode verwendet werden.

2.9. Adressformate

Mehrere Direktiven wie “bind”, “server”, “nameserver” und “log” benötigen eine Adresse.

Dies kann ein Hostname, eine IPv4- oder IPv6-Adresse oder ‘’ sein. ‘’ entspricht der speziellen Adresse “0.0.0.0” und kann bei “bind” oder “dgram-bind” verwendet werden, um auf allen IPv4-Adressen des Systems zu lauschen. Die IPv6-Entsprechung ist ‘::’.

Je nach Direktive folgt auf die IP-Adresse ein Port oder Portbereich. Bei ‘bind’ ist dies zwingend erforderlich, bei ‘server’ optional.

Die Adresse kann auch mit einem Schrägstrich ‘/’ beginnen. Dann gehört sie zur Familie “unix”, und ‘/’ mit den folgenden Zeichen muss den Pfad angeben.

Ob standardmäßig der Socket-Typ beziehungsweise die Transportmethode “datagram” oder “stream” verwendet wird, hängt von der Direktive mit der Adresse ab. ‘bind’ und ‘server’ verwenden standardmäßig “stream”, während ’log’, ’nameserver’ und ‘dgram-bind’ “datagram” verwenden.

Optional kann ein Präfix die Adressfamilie und/oder den Socket-Typ sowie die Transportmethode erzwingen.

2.9.1. Präfixe für Adressfamilien

‘abns@<name>’: Der folgende <name> bezeichnet einen abstrakten Namensraum (nur unter Linux).

‘abnsz@<name>’: Der folgende <name> bezeichnet einen nullterminierten abstrakten Namensraum (nur unter Linux).

‘fd@<n>’: Die folgende Adresse ist ein vom Elternprozess geerbter Dateideskriptor <n>. Er muss gebunden sein, kann aber bereits lauschen oder noch nicht.

‘ip@<address>[:port1[-port2]]’: Die folgende <address> gilt je nach Syntax als IPv4- oder IPv6-Adresse. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘ipv4@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv4-Adresse. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘ipv6@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv6-Adresse. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘sockpair@<n>’: Die folgende Adresse ist der Dateideskriptor eines verbundenen Unix-Sockets oder eines Socket-Paars. Beim Verbindungsaufbau erzeugt der Initiator ein Paar verbundener Sockets und übergibt einen davon über den FD an die Gegenstelle. Der Listener wartet auf den FD über den Unix-Socket und verwendet ihn wie den FD eines accept(). Mit Vorsicht verwenden.

           Fehler: Dieses Protokoll ist unter macOS bekanntermaßen
           unzuverlässig, da die sendmsg(2)-Implementierung von macOS
           fehlerhaft ist. Die Verbindung wird möglicherweise nicht korrekt angenommen.

‘unix@<path>’: Die folgende Zeichenkette gilt als UNIX-Socket <path>. Das Präfix eignet sich zur Angabe eines UNIX-Socket-Pfads, der nicht mit ‘/’ beginnt.

2.9.2. Präfixe für Socket-Typen

Den obigen Präfixen für Adressfamilien kann ein weiteres Präfix vorangestellt werden, um Socket-Typ und Transportmethode zu erzwingen. Der Standard hängt von der Direktive mit der Adresse ab, kann aber in manchen Fällen überschrieben werden. So verwendet “log” standardmäßig syslog über UDP, lässt sich aber auf syslog über TCP zwingen.

Diese Präfixe wurden für interne Zwecke entworfen. Anwender sollten stattdessen die Aliase aus dem folgenden Abschnitt „2.9.3. Protokollpräfixe“ verwenden. Gelegentlich sind sie dennoch praktisch, etwa bei geerbten Sockets, die über ihre Dateideskriptornummer bekannt sind. In diesem Fall ist die Adressfamilie “fd”, und der Socket-Typ muss angegeben werden.

Wer eines dieser Präfixe benötigt, weil sich das gewünschte Verhalten nicht mit Protokollpräfixen konfigurieren lässt, sollte dies den Betreuern melden.

‘stream+<family>@<address>’ erzwingt “stream” als Socket-Typ und Transportmethode.

‘dgram+<family>@<address>’ erzwingt “datagram” als Socket-Typ und Transportmethode.

‘quic+<family>@<address>’ erzwingt den Socket-Typ “datagram” und die Transportmethode “stream”.

2.9.3. Protokollpräfixe

‘quic4@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv4-Adresse; der Socket-Typ wird jedoch auf “datagram” und die Transportmethode auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein UDP-Port oder -Portbereich angegeben werden. Dies entspricht “quic+ipv4@”.

‘quic6@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv6-Adresse; der Socket-Typ wird jedoch auf “datagram” und die Transportmethode auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein UDP-Port oder -Portbereich angegeben werden. Dies entspricht “quic+ipv6@”.

’tcp@<address>[:port1[-port2]]’: Die folgende <address> gilt je nach Syntax als IPv4- oder IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘stream+ip@’.

’tcp4@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv4-Adresse; Socket-Typ und Transportmethode werden jedoch auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘stream+ipv4@’.

’tcp6@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘stream+ipv6@’.

‘mptcp@<address>[:port1[-port2]]’: Die folgende <address> gilt je nach Syntax als IPv4- oder IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch mit dem MPTCP-Protokoll auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘mptcp4@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv4-Adresse; Socket-Typ und Transportmethode werden jedoch mit dem MPTCP-Protokoll auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘mptcp6@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch mit dem MPTCP-Protokoll auf “stream” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden.

‘udp@<address>[:port1[-port2]]’: Die folgende <address> gilt je nach Syntax als IPv4- oder IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch auf “datagram” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘dgram+ip@’.

‘udp4@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv4-Adresse; Socket-Typ und Transportmethode werden jedoch auf “datagram” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘dgram+ipv4@’.

‘udp6@<address>[:port1[-port2]]’: Die folgende <address> gilt immer als IPv6-Adresse; Socket-Typ und Transportmethode werden jedoch auf “datagram” festgelegt. Je nach verwendender Direktive kann oder muss ein Port oder Portbereich angegeben werden. Dies ist ein Alias für ‘dgram+ipv6@’.

‘uxdg@<path>’: Die folgende Zeichenkette gilt als Unix-Socket <path>; die Transportmethode wird jedoch auf “datagram” festgelegt. Dies ist ein Alias für ‘dgram+unix@’.

‘uxst@<path>’: Die folgende Zeichenkette gilt als Unix-Socket <path>; die Transportmethode wird jedoch auf “stream” festgelegt. Dies ist ein Alias für ‘stream+unix@’.

In künftigen Versionen könnten weitere Präfixe für Protokolle wie QUIC verwendet werden, das einen Stream-Transport auf Sockets des Typs “datagram” bereitstellt.

2.10. Beispiele

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

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

    frontend http-in
        bind *:80
        default_backend servers

    backend servers
        server server1 127.0.0.1:8000 maxconn 32


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

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

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

Ist haproxy über $PATH erreichbar, lassen sich diese Konfigurationen in einer Shell wie folgt prüfen:

$ sudo haproxy -f configuration.conf -c

12 - 3. Globaler Abschnitt

Parameter im Abschnitt “global” gelten für den gesamten Prozess und sind häufig vom Betriebssystem (OS) abhängig. Sie werden in der Regel einmalig festgelegt und müssen nach korrekter Konfiguration nicht mehr geändert werden. Für einige gibt es entsprechende Befehlszeilenoptionen.

Im Abschnitt “global” werden die folgenden Schlüsselwörter unterstützt:

• Prozessverwaltung und Sicherheit

  • 51degrees-allow-unmatched
  • 51degrees-cache-size
  • 51degrees-data-file
  • 51degrees-difference
  • 51degrees-drift
  • 51degrees-property-name-list
  • 51degrees-property-separator
  • 51degrees-use-performance-graph
  • 51degrees-use-predictive-graph
  • ca-base
  • chroot
  • cluster-secret
  • cpu-affinity
  • cpu-map
  • cpu-policy
  • cpu-set
  • crt-base
  • daemon
  • default-path
  • description
  • deviceatlas-json-file
  • deviceatlas-log-level
  • deviceatlas-properties-cookie
  • deviceatlas-separator
  • dns-accept-family
  • expose-deprecated-directives
  • expose-experimental-directives
  • external-check
  • fd-hard-limit
  • gid
  • grace
  • group
  • h1-accept-payload-with-any-method
  • h1-case-adjust
  • h1-case-adjust-file
  • h1-do-not-close-on-insecure-transfer-encoding
  • h2-workaround-bogus-websocket-clients
  • hard-stop-after
  • harden.reject-privileged-ports.tcp
  • harden.reject-privileged-ports.quic
  • insecure-fork-wanted
  • insecure-setuid-wanted
  • issuers-chain-path
  • jwt.allow_none_alg
  • jwt.decrypt_alg_list
  • jwt.decrypt_enc_list
  • key-base
  • limited-quic
  • localpeer
  • log
  • log-send-hostname
  • log-tag
  • lua-load
  • lua-load-per-thread
  • lua-prepend-path
  • max-threads-per-group
  • mworker-max-reloads
  • nbthread
  • node
  • numa-cpu-mapping
  • ocsp-update.disable
  • ocsp-update.maxdelay
  • ocsp-update.mindelay
  • ocsp-update.httpproxy
  • ocsp-update.mode
  • pidfile
  • pp2-never-send-local
  • presetenv
  • prealloc-fd
  • resetenv
  • set-dumpable
  • set-var
  • setenv
  • ssl-default-bind-ciphers
  • ssl-default-bind-ciphersuites
  • ssl-default-bind-client-sigalgs
  • ssl-default-bind-curves
  • ssl-default-bind-options
  • ssl-default-bind-sigalgs
  • ssl-default-server-ciphers
  • ssl-default-server-ciphersuites
  • ssl-default-server-client-sigalgs
  • ssl-default-server-curves
  • ssl-default-server-options
  • ssl-default-server-sigalgs
  • ssl-dh-param-file
  • ssl-propquery
  • ssl-provider
  • ssl-provider-path
  • ssl-security-level
  • ssl-server-verify
  • ssl-skip-self-issued-ca
  • stats
  • stats-file
  • strict-limits
  • uid
  • ulimit-n
  • unix-bind
  • unsetenv
  • user
  • wurfl-cache-size
  • wurfl-data-file
  • wurfl-information-list
  • wurfl-information-list-separator

• Leistungsoptimierung

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

• Fehlerbehebung

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

• HTTPClient

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

3.1. Prozessverwaltung und Sicherheit

51degrees-data-file <file path>

51degrees-data-file <file path>

Der Pfad der 51Degrees-Datendatei für die Geräteerkennung. Die Datei sollte entpackt und für HAProxy mit den erforderlichen Berechtigungen zugänglich sein.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES kompiliert wurde.

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

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

Eine Liste von 51Degrees-Eigenschaftsnamen, die aus dem Datensatz geladen werden sollen. Eine vollständige Liste ist auf der 51Degrees-Website verfügbar: https://51degrees.com/resources/property-dictionary

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES kompiliert wurde.

51degrees-property-separator <char>

51degrees-property-separator <char>

Ein Zeichen, das an jeden Eigenschaftswert in einem Antwortheader angehängt wird, der 51Degrees-Ergebnisse enthält. Wenn nicht gesetzt, wird als Standardwert ‘,’ verwendet.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES kompiliert wurde.

51degrees-cache-size <number>

51degrees-cache-size <number>

Legt die Größe des 51Degrees-Konverter-Caches auf <number> Einträge fest. Dies ist ein LRU-Cache, der vorherige Geräteerkennungen und deren Ergebnisse speichert. Standardmäßig ist dieser Cache deaktiviert.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES kompiliert wurde.

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

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

Aktiviert (‘on’) oder deaktiviert (‘off’) die Verwendung des Leistungsgraphen im Erkennungsprozess. Der Standardwert hängt von der 51Degrees-Bibliothek ab.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES und 51DEGREES_VER=4 kompiliert wurde.

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

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

Aktiviert (‘on’) oder deaktiviert (‘off’) die Verwendung des Vorhersagegraphen im Erkennungsprozess. Der Standardwert hängt von der 51Degrees-Bibliothek ab.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES und 51DEGREES_VER=4 kompiliert wurde.

51degrees-drift <number>

51degrees-drift <number>

Legt den zulässigen Driftwert für eine Erkennung fest.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES und 51DEGREES_VER=4 kompiliert wurde.

51degrees-difference <number>

51degrees-difference <number>

Legt den zulässigen Differenzwert für eine Erkennung fest.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES und 51DEGREES_VER=4 kompiliert wurde.

51degrees-allow-unmatched { on | off }

51degrees-allow-unmatched { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Verwendung von nicht übereinstimmenden Knoten im Erkennungsprozess. Der Standardwert hängt von der 51Degrees-Bibliothek ab.

Bitte beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_51DEGREES und 51DEGREES_VER=4 kompiliert wurde.

acme.scheduler { auto | off }

acme.scheduler { auto | off }

Aktiviert oder deaktiviert den ACME-Scheduler.

Der ACME-Scheduler startet beim Start von HAProxy und durchläuft die Zertifikate. Er startet eine ACME-Erneuerungsaufgabe, wenn der notAfter-Wert gegenüber curtime + (notAfter - notBefore) / 12 bereits verstrichen ist; ist notBefore nicht definiert, gilt ein Zeitraum von 7 Tagen. Anschließend schläft der Scheduler und wacht nach 12 Stunden wieder auf.

Der Standardwert ist “auto”.

Siehe auch: acme

ca-base <dir>

ca-base <dir>

Weist ein Standardverzeichnis zum Abrufen von SSL-CA-Zertifikaten und CRLs zu, wenn mit den Anweisungen “ca-file”, “ca-verify-file” oder “crl-file” ein relativer Pfad verwendet wird. Absolute Pfade, die in “ca-file”, “ca-verify-file” und “crl-file” angegeben sind, haben Vorrang und ignorieren “ca-base”.

chroot { <jail dir> | auto }

chroot { <jail dir> | auto }

Wechselt in das Verzeichnis <jail dir> und führt dort chroot() aus, bevor Privilegien abgegeben werden. Dies erhöht die Sicherheit bei Ausnutzung einer unbekannten Schwachstelle, da ein Angriff auf das System dadurch sehr erschwert wird. Es ist wichtig sicherzustellen, dass <jail dir> leer und für niemanden beschreibbar ist. Wird der Prozess mit Superuser-Rechten gestartet, wird chroot() direkt ausgeführt. Unter Linux versucht haproxy bei einem Start ohne Privilegien, dies innerhalb eines mit unshare(CLONE_NEWUSER) neu erzeugten Benutzernamensraums auszuführen. Ist dieser Mechanismus nicht verfügbar, schlägt chroot() mit der üblichen Fehlermeldung fehl.

Als Sonderfall kann <jail dir> auf “auto” gesetzt werden. Dann erzeugt haproxy ein anonymes temporäres Verzeichnis, entfernt dessen Verzeichniseintrag und führt darin chroot() aus. Das resultierende Jail hat keinen Namen im Dateisystem, ist leer und schreibgeschützt. Ein eigenes Jail-Verzeichnis muss daher nicht vorbereitet werden.

Wenn mit Superuser-Berechtigungen gestartet wird, wird eine Warnung ausgegeben, wenn kein chroot verwendet wird, um Benutzer dazu zu ermutigen, stets dieses Verfahren zu nutzen. Falls aus irgendeinem Grund ein zwingender Grund besteht, chroot nicht zu verwenden (z. B. Zugriff auf einen Server über einen Unix-Socket mit unpassendem Pfad), bleibt es möglich, die Warnung zu unterdrücken, indem explizit “chroot /” hinzugefügt wird. Dies hat den Vorteil, dass es in der Konfiguration sichtbar ist.

close-spread-time <time>

close-spread-time <time>

Definiert ein Zeitfenster, über das beim geordneten Herunterfahren das Schließen ungenutzter und aktiver Verbindungen verteilt wird. Nach Empfang von SIGUSR1 und Ablauf einer gegebenenfalls vorhandenen Schonfrist werden ohne diese Option alle ungenutzten Verbindungen auf einmal geschlossen. Aktive HTTP- oder HTTP2-Verbindungen werden nach Empfang der nächsten Anfrage beendet, entweder mit einer zusätzlichen Zeile “Connection: close” in der HTTP-Antwort oder einem GOAWAY-Frame bei HTTP2. Ist die Option gesetzt, wird das Schließen über die angegebene Zeit <time> verteilt. Bei close-spread-time “infinite” wird das aktive Schließen von Verbindungen während des geordneten Herunterfahrens deaktiviert. Der Header “Connection: close” wird HTTP-Antworten nicht mehr hinzugefügt (ebenso wenig GOAWAY bei HTTP2). Ungenutzte Verbindungen werden erst bei Erreichen ihrer Zeitüberschreitung geschlossen, entsprechend den verschiedenen konfigurierten Zeitüberschreitungen.

Argumente:

<time>  ist ein Zeitfenster (standardmäßig in Millisekunden), über das
        das Schließen von Verbindungen beim geordneten Beenden verteilt
        wird, oder "infinite", wenn das aktive Schließen von Verbindungen
        deaktiviert werden soll.

Es wird empfohlen, diesen Wert niedriger als den Wert in der “hard-stop-after”-Option einzustellen, falls diese verwendet wird, damit alle Verbindungen die Möglichkeit haben, vor dem Prozessende ordnungsgemäß zu schließen.

Siehe auch: grace, hard-stop-after, idle-close-on-response

cluster-secret <secret>

cluster-secret <secret>

Definiert eine ASCII-Zeichenkette als Geheimnis, das zwischen mehreren Knoten desselben Clusters geteilt wird. Es kann für verschiedene Zwecke verwendet werden. Es wird mindestens verwendet, um zustandslose Reset-Tokens für alle von diesem Prozess instanziierten QUIC-Verbindungen abzuleiten. Ebenso dient es zur Ableitung von Geheimnissen zum Verschlüsseln von Retry-Tokens.

Wenn dieser Parameter nicht gesetzt ist, wird beim Prozessstart ein zufälliger Wert gewählt. Dies ermöglicht die Nutzung von Funktionen, die darauf basieren, wenn auch mit gewissen Einschränkungen.

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

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

Auf einigen Betriebssystemen ist es möglich, eine Thread-Gruppe oder einen Thread einer bestimmten CPU-Menge zuzuordnen. Das bedeutet, dass die zugewiesenen Threads niemals auf anderen CPUs ausgeführt werden. Die Anweisung “cpu-map” legt CPU-Mengen für einzelne Threads oder Thread-Gruppen fest. Das erste Argument ist ein Thread-Gruppenbereich, optional gefolgt von einem Thread-Menge. Diese Bereiche haben folgendes Format:

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

<number> muss je nach Wortbreite des Rechners zwischen 1 und 32 oder 64 liegen. Gruppen-IDs oberhalb von ’thread-groups’ und Thread-IDs oberhalb der Wortbreite des Rechners werden ignoriert. Alle Thread-Nummern sind relativ zu ihrer jeweiligen Gruppe. Ein Bereich kann mit zwei durch einen Bindestrich (’-’) getrennten Nummern angegeben werden. Wie bei der bind-Direktive “thread” wählt “all” alle Threads, “odd” nur ungerade und “even” nur gerade Nummern aus. Das zweite und alle weiteren Argumente sind CPU-Mengen. Jede CPU-Menge ist entweder eine einzelne Nummer, beginnend bei 0 für die erste CPU, oder ein Bereich aus zwei durch einen Bindestrich (’-’) getrennten Nummern. CPU-Nummern und Bereiche können durch Kommas getrennt oder als weitere Argumente in derselben Zeile mehrfach angegeben werden. Außerhalb von Linux und BSD kann der maximale CPU-Index auf 31 oder 63 begrenzt sein. Mehrere “cpu-map”-Direktiven sind zulässig; jede ersetzt jedoch frühere “cpu-map”-Angaben, soweit sie sich überschneiden.

Bereiche können teilweise definiert werden: Die obere Grenze darf fehlen. Dann wird sie durch den entsprechenden Höchstwert ersetzt, je nach Wortbreite des Rechners 32 oder 64.

Vor die Thread-Menge kann das Präfix “auto:” gesetzt werden. HAProxy bindet die Threads dann automatisch an CPUs, indem es die Thread- und CPU-Mengen schrittweise durchläuft. Dafür müssen beide Mengen gleich groß sein. Unabhängig von der Deklarationsreihenfolge der CPU-Mengen erfolgt die Bindung von der niedrigsten zur höchsten Grenze. Mit “auto:” werden nicht gleichzeitig ein Gruppenbereich und ein Thread-Bereich unterstützt. Nur einer darf ein Bereich sein; der andere muss eine feste Nummer sein.

Gruppenbereiche werden aus historischen Gründen unterstützt. Heute bezeichnet eine einzelne Nummer eine Thread-Gruppe und muss 1 sein, wenn keine Thread-Gruppen verwendet werden. Ohne Thread-Gruppen muss einem Thread-Bereich oder einer Thread-Nummer “1/” vorangestellt werden. Schließlich ist “1” genau gleichbedeutend mit “1/all” und bezeichnet alle Threads der Gruppe.

Beispiele:

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

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

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

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

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

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

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

cpu-affinity <affinity>

cpu-affinity <affinity>

Legt fest, wie Threads an CPUs gebunden werden sollen. Derzeit werden folgende Werte akzeptiert:

• per-core: Jeder Thread wird an alle Hardware-Threads eines Kerns gebunden.
• per-group: Jeder Thread wird an alle Hardware-Threads der Gruppe gebunden. Dies ist der Standard, sofern nicht “threads-per-core 1” in “cpu-policy” verwendet wird. “per-group” akzeptiert ein optionales Argument zur CPU-Zuweisung. Ist eine CPU-Liste größer als die maximal zulässige Anzahl von CPUs pro Gruppe und muss auf mehrere Gruppen aufgeteilt werden, bestimmt eine zusätzliche Option, wie die Gruppen an diese CPUs gebunden werden:
  • auto: Jede Thread-Gruppe erhält nur einen gleich großen Anteil zusammenhängender CPU-Kerne, die ausschließlich ihr zugeordnet sind und nicht mit anderen Gruppen geteilt werden. Dies ist der Standard, da es im Allgemeinen günstiger ist.
  • loose: Jede Gruppe darf weiterhin jede CPU der Liste verwenden. Das führt im Allgemeinen zu mehr Konkurrenz um Ressourcen, kann aber gelegentlich helfen, mit störender Zusatzlast auf denselben CPUs besser umzugehen.
• auto: Verwendet “per-group”, sofern nicht “threads-per-core 1” in “cpu-policy” gesetzt ist; dann wird “per-core” verwendet. Dies ist der Standard.
• per-thread: Bindet einen Thread an genau einen Hardware-Thread. Bei “threads-per-core 1” in “cpu-policy” wird jeder Thread an einen Hardware-Thread eines anderen Kerns gebunden.
• per-ccx: Jeder Thread wird an alle Hardware-Threads eines CCX gebunden.

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

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

Wählt die zu verwendende Richtlinie für die CPU-Zuweisung.

Auf Systemen mit mehreren CPUs gibt es viele Gründe, nicht alle verfügbaren CPU-Kerne zu verwenden oder sie auf verschiedene Thread-Gruppen aufzuteilen: Leistung, Latenz, Kosten oder die systemweite Ressourcenverwaltung. Mit “cpu-set” können bereits einige Kerne ausgeschlossen werden. Anschließend muss aber entschieden werden, wie die übrigen auf Threads und Thread-Gruppen verteilt werden.

Diese Zuordnung erfolgt normalerweise mit “cpu-map”, kann auf heterogenen Systemen jedoch besonders schwer zu pflegen sein.

Die Direktive “cpu-policy” wählt stattdessen eine von wenigen Zuweisungsrichtlinien aus, wenn “cpu-map” nicht verwendet wird. Derzeit werden die folgenden Richtlinien unterstützt; “performance” ist der Standard:

• none Es erfolgt keine besondere nachgelagerte Auswahl. Alle aktivierten CPUs sind nutzbar. Ist die Thread-Anzahl nicht gesetzt, entspricht sie der Anzahl verfügbarer CPUs, jedoch pro Thread-Gruppe höchstens 32 auf 32-Bit-Systemen oder 64 auf 64-Bit-Systemen. Ist die Anzahl der Thread-Gruppen nicht gesetzt, wird sie auf 1 gesetzt.

• efficiency Wie “group-by-ccx” unten, allerdings werden CPU-Cluster ausgeschlossen, deren Kerne mehr als 25% leistungsfähiger sind als die des nächstleistungsschwächeren Typs. Dies sind typischerweise “big”- oder “performance”-Kerne. Werden mehrere CPU-Kerntypen erkannt, wird also nur der effiziente Typ verwendet. Bei mäßiger Last kann dies sinnvoll sein, wenn die leistungsstärksten Kerne für die Anwendung oder eine Sicherheitskomponente verfügbar bleiben sollen. Einige moderne CPUs haben viele solcher effizienten Kerne, die zusammen bei geringerem Energieverbrauch eine angemessene Leistung liefern können.

• first-usable-node Wenn die CPUs beim Start nicht bereits eingeschränkt wurden (etwa mit “taskset”) und “nbthread” nicht gesetzt ist, wird der erste NUMA-Knoten mit aktivierten CPUs verwendet. Die Anzahl seiner CPUs wird zur Thread-Anzahl. Für alle wird eine einzige Thread-Gruppe aktiviert, innerhalb der systemabhängigen Grenze von 32 oder 64.

• group-by-2-ccx Wie “group-by-ccx” unten, erstellt aber für je zwei CCX eine Gruppe. Bei CPUs mit vielen CCX aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen CCX die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-2-clusters Wie “group-by-cluster”, erstellt aber für je zwei Cluster eine Gruppe. Bei CPUs mit vielen Clustern aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen Clustern die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-3-ccx Wie “group-by-ccx” unten, erstellt aber für je drei CCX eine Gruppe. Bei CPUs mit vielen CCX aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen CCX die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-3-clusters Wie “group-by-cluster”, erstellt aber für je drei Cluster eine Gruppe. Bei CPUs mit vielen Clustern aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen Clustern die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-4-ccx Wie “group-by-ccx” unten, erstellt aber für je vier CCX eine Gruppe. Bei CPUs mit vielen CCX aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen CCX die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-4-clusters Wie “group-by-cluster”, erstellt aber für je vier Cluster eine Gruppe. Bei CPUs mit vielen Clustern aus jeweils wenigen Kernen kann dies sinnvoll sein, um viele Gruppen zu vermeiden oder die Verteilung etwas zu glätten, wenn nicht alle Kerne verwendet werden. Beachten Sie, dass langsame Kommunikation zwischen Clustern die Leistung dabei sehr stark beeinträchtigen kann. Im Allgemeinen wird davon abgeraten.

• group-by-ccx Wenn weder “nbthread” noch “nbtgroups” gesetzt ist, wird für jeden CPU Core Complex (“CCX”) mit verfügbaren CPUs eine Thread-Gruppe erzeugt, mit ebenso vielen Threads wie CPUs. Ein CCX fasst CPUs mit ähnlich schnellem Zugriff auf den Last Level Cache (“LLC”) zusammen, typischerweise den L3-Cache. Auf den meisten modernen Rechnern ist es für die Leistung entscheidend, CPUs aus entfernten CCX nicht in derselben Thread-Gruppe zu mischen. Alle Threads einer Gruppe werden an alle CPUs des CCX gebunden. So bleibt die Kommunikation innerhalb der Gruppe lokal im CCX, ohne eine zu enge Bindung zu erzwingen. Die Grenzen für Threads pro Gruppe und für die Anzahl der Thread-Gruppen werden eingehalten. Dies wird für Systeme mit mehreren Sockeln und NUMA-Systeme sowie für CPUs mit hohen Latenzen zwischen CCX empfohlen.

• group-by-cluster Wenn weder “nbthread” noch “nbtgroups” gesetzt ist, wird für jeden CPU-Cluster mit verfügbaren CPUs eine Thread-Gruppe erzeugt, mit ebenso vielen Threads wie CPUs. Alle Threads einer Gruppe werden an alle CPUs des Clusters gebunden. So bleibt die Kommunikation innerhalb der Gruppe lokal im Cluster, ohne eine zu enge Bindung zu erzwingen. Die Grenzen für Threads pro Gruppe und für die Anzahl der Thread-Gruppen werden eingehalten. Dies wird für Systeme mit mehreren Sockeln und NUMA-Systeme sowie für CPUs mit hohen Latenzen zwischen CCX empfohlen. Auf den meisten Servern sind Cluster und CCX identisch. Auf heterogenen Rechnern (“performance” gegenüber “efficiency” oder “big” gegenüber “little”) besteht ein Cluster dagegen meist nur aus einem Teil eines CCX mit sehr ähnlichen CPUs (gleicher Typ, maximal +/-5% Frequenzunterschied). Der Unterschied zeigt sich auf modernen Laptops und Desktop-Rechnern, auf denen Entwickler und Administratoren Konfigurationen prüfen.

• performance Wie “group-by-ccx” oben, allerdings werden CPU-Cluster ausgeschlossen, deren Kerne weniger als 80% der Leistung des nächstleistungsstärkeren Typs erreichen. Das sind typischerweise “little”- oder “efficient”-Kerne. Ihr Hinzufügen bringt im Allgemeinen wenig und kann leicht nachteilig sein (z. B. bei TLS-Handshakes). Häufig ist es deutlich wirksamer, solche Kerne für andere Aufgaben wie die Netzwerkverarbeitung freizuhalten. Auf Entwicklungssystemen können sie auch Hilfsprogramme wie Lastgeneratoren und Überwachungswerkzeuge ausführen. Dies ist die Standardrichtlinie.

• resource Wie “group-by-cluster” oben, allerdings wird nur der kleinste und effizienteste CPU-Cluster verwendet; alle anderen werden ignoriert. Damit lässt sich der Ressourcenverbrauch auf das kleinste Maß begrenzen, das noch angemessene Leistung liefert. Beispielsweise kann so der Energieverbrauch weiter gesenkt oder bei einer Sidecar-Konfiguration auf gemieteten Systemen die Zahl benötigter Kerne minimiert werden, um das System leichter verkleinern zu können. Ist nur ein Cluster vorhanden, wird dieser weiterhin vollständig verwendet.

Optional kann das Schlüsselwort “threads-per-core” hinzugefügt werden. Es akzeptiert “1” und “auto”. Bei 1 wird pro Kern nur ein Thread erzeugt, unabhängig von der Anzahl der Hardware-Threads des Kerns. Bei auto wird pro Hardware-Thread ein Thread erzeugt. Ist keine Affinität angegeben und wird threads-per-core 1 verwendet, ist die Affinität standardmäßig per-core.

Siehe auch: “cpu-map”, “cpu-set”, “nbthread”

cpu-set <directive>...

cpu-set <directive>...

Erlaubt eine symbolische Beschreibung der CPU-Mengen, auf denen ausgeführt werden soll. Die Direktive unterstützt folgende Schlüsselwörter: - reset hebt frühere Einschränkungen auf, die beispielsweise von einem Dienstmanager oder einem “taskset”-Befehl geerbt wurden. - drop-cpu <set> bindet nicht an CPUs dieser Menge - only-cpu <set> bindet nicht an CPUs außerhalb dieser Menge - drop-node <set> bindet nicht an CPUs dieses NUMA-Knotens - only-node <set> bindet nicht an CPUs außerhalb dieses NUMA-Knotens - drop-cluster <set> bindet nicht an CPUs mit dieser Hardware-Cluster-Nummer - only-cluster <set> bindet nicht an CPUs mit anderen Hardware-Cluster-Nummern - drop-core <set> bindet nicht an CPUs mit dieser Hardware-Kernnummer - only-core <set> bindet nicht an CPUs mit anderen Hardware-Kernnummern - drop-thread <set> bindet nicht an CPUs mit dieser Hardware-Thread-Nummer - only-thread <set> bindet nicht an CPUs mit anderen Hardware-Thread-Nummern. Siehe auch: “cpu-policy”

crt-base <dir>

crt-base <dir>

Legt ein Standardverzeichnis zum Laden von SSL-Zertifikaten fest, wenn “crtfile” oder “crt” einen relativen Pfad verwendet. Angegebene absolute Pfade haben Vorrang und ignorieren “crt-base”.

daemon

daemon

Lässt den Prozess per fork in den Hintergrund wechseln. Dies ist die empfohlene Betriebsart und entspricht dem Befehlszeilenargument “-D”. Mit “-db” in der Befehlszeile kann sie deaktiviert werden. Im systemd-Modus wird diese Option ignoriert.

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

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

Standardmäßig lädt HAProxy Dateien mit relativen Pfaden aus dem Verzeichnis, in dem der Prozess gestartet wurde. Manchmal sollen alle relativen Pfade stattdessen von einem anderen Verzeichnis ausgehen, als wäre der Prozess dort gestartet worden. Dafür ist diese Direktive vorgesehen. Technisch führt sie während der Verarbeitung jeder Konfigurationsdatei vorübergehend chdir() zum angegebenen Verzeichnis aus und kehrt nach jeder Datei in das ursprüngliche Verzeichnis zurück. Ihr Argument legt die Richtlinie zum Laden von Dateien fest, deren Pfad nicht mit einem Schrägstrich (’/’) beginnt: - “current” lädt alle relativen Dateien aus dem Startverzeichnis des Prozesses; dies ist der Standard.

- "config" lädt alle relativen Dateien aus dem Verzeichnis der
  Konfigurationsdatei. Enthält deren Pfad einen Schrägstrich ('/'), wird
  der längste Teil bis zum letzten Schrägstrich als Zielverzeichnis
  verwendet, andernfalls das aktuelle Verzeichnis. Damit lassen sich
  Maps, Fehlerdateien, Zertifikate und Lua-Skripte als verschiebbare
  Pakete bündeln. Werden mehrere Konfigurationsdateien geladen, wird
  das Verzeichnis für jede Datei aktualisiert.

- "parent" lädt alle relativen Dateien aus dem übergeordneten Verzeichnis
  des Verzeichnisses der Konfigurationsdatei. Enthält deren Pfad einen
  Schrägstrich ('/'), wird ".." an den längsten Teil bis zum letzten
  Schrägstrich angehängt und als Zielverzeichnis verwendet; andernfalls
  ist das Verzeichnis "..". So lassen sich Maps, Fehlerdateien,
  Zertifikate und Lua-Skripte als verschiebbare Pakete bündeln, deren
  Bestandteile in verschiedenen Unterverzeichnissen liegen
  (z. B. "config/", "certs/", "maps/", ...).

- "origin" lädt alle relativen Dateien aus dem angegebenen (erforderlichen)
  Pfad. Dies kann die Verwaltung verschiedener HAProxy-Instanzen
  erleichtern, die parallel auf einem System laufen. Jede Instanz
  verwendet dabei ein anderes Präfix, während die übrigen Abschnitte
  leicht verschiebbar bleiben.

Jede Direktive “default-path” ersetzt sofort jede frühere und kann einen Wechsel in ein anderes Verzeichnis bewirken. Auch wenn dies stets das gewünschte Verhalten ergeben sollte, ist die Verwendung mehrerer default-path-Direktiven keine gute Praxis. Werden dennoch mehrere verwendet, sollte die Richtlinie in allen Konfigurationsdateien einheitlich bleiben.

Warnung: Einige Konfigurationselemente wie Maps oder Zertifikate werden eindeutig über ihren konfigurierten Pfad identifiziert. Bei einer verschiebbaren Verzeichnisstruktur können mehrere davon denselben eindeutigen Namen erhalten. Das erschwert Aktualisierungen zur Laufzeit, insbesondere wenn mehrere Konfigurationsdateien aus verschiedenen Verzeichnissen geladen werden. Vor der Verwendung relativer Pfade ist ein strikt kollisionsfreies Schema für Dateinamen unbedingt erforderlich. Ein robuster Ansatz wäre, allen Dateinamen den jeweiligen Standortnamen voranzustellen oder dies auf Verzeichnisebene zu tun.

description <text>

description <text>

Fügt einen Text hinzu, der die Instanz beschreibt.

Bestimmte Zeichen (beispielsweise #) müssen maskiert werden. Da der Text in eine HTML-Seite eingefügt wird, sollten Sie die Zeichen “<” und “>” vermeiden.

deviceatlas-json-file <path>

deviceatlas-json-file <path>

Legt den Pfad der DeviceAtlas-JSON-Datendatei fest, die über die API geladen wird. Der Pfad muss auf eine gültige JSON-Datendatei verweisen, auf die der HAProxy-Prozess zugreifen kann.

deviceatlas-log-level <value>

deviceatlas-log-level <value>

Legt den Informationsumfang fest, den die API zurückgibt. Diese Direktive ist optional; ohne Angabe gilt der Standardwert 0.

deviceatlas-properties-cookie <name>

deviceatlas-properties-cookie <name>

Legt den Namen des Client-Cookies für die Erkennung fest, wenn bei der Anfrage die clientseitige DeviceAtlas-Komponente verwendet wurde. Diese Direktive ist optional; ohne Angabe gilt der Standardwert DAPROPS.

deviceatlas-separator <char>

deviceatlas-separator <char>

Legt das Trennzeichen für die Ergebnisse der API-Eigenschaften fest. Diese Direktive ist optional; ohne Angabe gilt der Standardwert |.

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

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

Standardmäßig akzeptieren DNS-Resolver sowohl IPv4- als auch IPv6-Adressen. Dies lässt sich mit “resolve-prefer” in server-Zeilen und dem Adressfamilienargument der Aktion “do-resolve” beeinflussen. Es ist jedoch nur eine Präferenz: Ist ausschließlich die andere Familie vorhanden, bleibt ihre Verwendung möglich. In Umgebungen ohne nutzbares Dual-Stack kann ein unerreichbarer, nur auf IPv6 verweisender DNS-Eintrag erhebliche Probleme verursachen. Er ersetzt einen früheren IPv4-Eintrag, der bis zur nächsten Anfrage möglicherweise weiter funktioniert hätte. Die globale Option “dns-accept-family” kann die Verwendung nur einer oder beider Adressfamilien erzwingen. Ihr Argument ist eine durch Kommas getrennte Liste folgender Wörter: - “ipv4”: IPv4-Adressen abfragen und akzeptieren (“A”-Einträge) - “ipv6”: IPv6-Adressen abfragen und akzeptieren (“AAAA”-Einträge) - “auto”: IPv4 verwenden; IPv6 zusätzlich verwenden, wenn das System dafür ein Standardgateway besitzt. Das Ergebnis der letzten Prüfung wird 30 Sekunden lang zwischengespeichert.

Wird nur eine Familie verwendet, werden für die andere weder Anfragen an Resolver gesendet noch Antworten berücksichtigt. Seit 3.3 ist “auto” der Standardwert. Damit werden tatsächlich erst dann beide Familien aktiviert, wenn die Routbarkeit von IPv6 feststeht; andernfalls bleibt es bei IPv4. Siehe auch: “resolve-prefer”, “do-resolve”

expose-deprecated-directives

expose-deprecated-directives

Diese Anweisung muss vor einigen als veraltet gekennzeichneten Direktiven stehen, damit Warnungen unterdrückt werden und die Konfigurationsdatei nicht abgewiesen wird. Betroffen sind nicht alle veralteten Direktiven, sondern nur solche ohne alternative Lösung.

expose-experimental-directives

expose-experimental-directives

Diese Anweisung muss vor als experimentell gekennzeichneten Direktiven stehen, sonst wird die Konfigurationsdatei abgewiesen. Die von dieser Option erfassten Funktionen arbeiten nicht garantiert zuverlässig und können während des Wartungszyklus funktionsunfähig werden. Während der Arbeit an der nächsten Version pflegen die Entwickler sie nach bestem Bemühen und unternehmen angemessene Anstrengungen, ihre Funktionsfähigkeit zu erhalten, geben aber keine Garantie. Deshalb ist für diese Funktionen keine Unterstützung über das Erscheinen der nächsten LTS-Version hinaus zu erwarten. Von Benutzern, die experimentelle Funktionen erproben möchten, wird erwartet, dass sie zeitnah aktualisieren, um deren Verbesserungen zu erhalten. Ob diese Direktive noch benötigt wird, lässt sich leicht erkennen: Ist sie aktiviert, ohne von einer solchen Funktion verwendet zu werden, weist eine Warnung darauf hin, sie zu deaktivieren. Bleibt die Warnung aus, wird sie also noch benötigt.

external-check [preserve-env]

external-check [preserve-env]

Erlaubt einen externen Agenten für Health Checks. Als Sicherheitsmaßnahme ist dies standardmäßig deaktiviert. Selbst bei Aktivierung können Prüfungen weiterhin fehlschlagen, wenn nicht auch “insecure-fork-wanted” aktiviert ist. Verwendet das gestartete Programm eine ausführbare Datei mit setuid (was es wirklich nicht tun sollte), muss möglicherweise auch “insecure-setuid-wanted” im globalen Abschnitt gesetzt werden. Standardmäßig starten Prüfungen mit einer bereinigten Umgebung, die nur Variablen aus dem Befehl “external-check” im Backend-Abschnitt enthält. Manchmal soll die Umgebung dennoch erhalten bleiben, etwa wenn komplexe Skripte daraus zusätzliche Pfade oder Informationen beziehen. Dafür kann das Schlüsselwort “preserve-env” angehängt werden. Dann wird jedoch dringend davon abgeraten, setuid-Programme auszuführen oder Prüfungen unter einem privilegierten Benutzer laufen zu lassen, da das Prüfprogramm sonst möglichen Angriffen ausgesetzt ist. Weitere Einzelheiten finden Sie bei “option external-check”, “insecure-fork-wanted” und “insecure-setuid-wanted”.

fd-hard-limit <number>

fd-hard-limit <number>

Setzt unabhängig von Systemgrenzen eine Obergrenze für die Anzahl der vom Prozess verwendeten Dateideskriptoren. Mit “ulimit-n” und “maxconn” kann ein Wert erzwungen werden. Sind beide nicht gesetzt, gilt die harte Grenze von RLIMIT_NOFILE, wie sie “ulimit -n -H” ausgibt. Einige moderne Betriebssysteme erlauben hier jedoch extrem große Werte (in der Größenordnung von 1 Milliarde), die im normalen Betrieb viel zu viel RAM verbrauchen würden. Mit fd-hard-limit kann eine gegebenenfalls niedrigere Obergrenze durchgesetzt werden. Systemgrenzen unterhalb von <number> werden also immer eingehalten; bei höheren Systemgrenzen gilt der angegebene Wert. Standardmäßig ist fd-hard-limit auf 1048576 gesetzt. Dieser Standard kann beim Kompilieren über DEFAULT_MAXFD geändert werden. Der Wert kann als maximale Systemgrenze (des Kernels) dienen, wenn die harte RLIMIT_NOFILE-Grenze extrem groß ist. fd-hard-limit im globalen Abschnitt kann den beim Bauen über DEFAULT_MAXFD vorgegebenen Wert vorübergehend überschreiben. Im folgenden Beispiel ist keine andere Einstellung gesetzt; maxconn passt sich automatisch dem kleineren Wert aus “fd-hard-limit” und der RLIMIT_NOFILE-Grenze an:

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

Siehe auch: ulimit-n, maxconn

gid <number>

gid <number>

Ändert die Gruppen-ID des Prozesses auf <number>. Es wird empfohlen, diese Gruppen-ID HAProxy oder einer kleinen Gruppe ähnlicher Daemons vorzubehalten. HAProxy muss unter einem Benutzer dieser Gruppe oder mit Superuser-Rechten gestartet werden. Hat der startende Benutzer zusätzliche Gruppen, kann HAProxy diese nur ablegen, wenn es mit Superuser-Rechten gestartet wurde. Siehe auch “group” und “uid”.

grace <time>

grace <time>

Definiert eine Verzögerung zwischen SIGUSR1 und dem tatsächlichen geordneten Herunterfahren.

Argumente:

<time>  ist eine zusätzliche Wartezeit (standardmäßig in Millisekunden)
        nach dem Empfang des Signals SIGUSR1, die vor dem Fortsetzen
        des geordneten Beendens abgewartet wird.

Dies dient der Kompatibilität mit älteren Umgebungen, in denen der haproxy-Prozess gestoppt werden muss, externe Komponenten den Status aber noch vor dem Freigeben der Listener erkennen müssen. Dabei wird die interne Variable “stopping” (ausgegeben von der Sample-Abruffunktion “stopping”) auf true gesetzt, während die Listener weiterhin ungestört Verbindungen annehmen. Erst nach Ablauf der Verzögerung beginnt das normale geordnete Herunterfahren. Dies darf nicht für Prozesse verwendet werden, die neu geladen werden: Der alte Prozess wird seine Bindungen sonst nicht freigeben; der neue kann möglicherweise nicht starten, oder es können andere Probleme entstehen.

Beispiel:

global
  grace 10s

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

Ein flexiblerer und dauerhafterer Ansatz wäre, dass ein Orchestrierungssystem über die CLI eine globale Variable setzt, diese für Antworten auf externe Prüfungen verwendet und erst nach einer Verzögerung SIGUSR1 sendet.

Beispiel:

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

Siehe auch: hard-stop-after, monitor

group <group name>

group <group name>

Ähnlich wie “gid”, verwendet aber die GID des Gruppennamens <group name> aus /etc/group. Siehe auch “gid” und “user”.

h1-accept-payload-with-any-method

h1-accept-payload-with-any-method

Weist HTTP/1.0-Anfragen mit GET/HEAD/DELETE und einer Nutzlast nicht mit der HTTP-Antwort 413 Payload Too Large zurück.

Während HTTP/1.1 dies ausdrücklich erlaubt, ist HTTP/1.0 hier nicht eindeutig. Einige ältere Server erwarten keine Nutzlast und prüfen niemals die Länge des Inhalts (über Content-Length- oder Transfer-Encoding-Header). Manche Zwischenstationen verarbeiten die Nutzlast von HTTP/1.0-GET/HEAD/DELETE-Anfragen daher korrekt, andere ignorieren sie vollständig. Das kann Sicherheitsprobleme verursachen, da Request-Smuggling-Angriffe möglich sind. Standardmäßig weist HAProxy HTTP/1.0-GET/HEAD/DELETE-Anfragen mit Nutzlast deshalb zurück.

Bei einigen alten Clients kann dies jedoch Probleme verursachen. In diesem Fall kann diese globale Option gesetzt werden.

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

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

Nach der HTTP/1.1-Spezifikation (RFC9112#6.1) stellt das gleichzeitige Vorhandensein von Transfer-Encoding und Content-Length in derselben Nachricht ein erhebliches Risiko für Content-Smuggling-Angriffe dar, wenn sich irgendwo in der vor- oder nachgelagerten Kette ein HTTP/1.0-Agent befindet. Ein Agent muss die Verbindung in diesem Fall nach der Antwort unbedingt schließen, um jede Ausnutzung zu verhindern. Das kann bei sehr alten Clients jedoch die Leistung beeinträchtigen, insbesondere wenn sie für jede Anfrage eine TLS-Verbindung neu aushandeln müssen. Diese Option weist HAProxy an, die Regel nicht durchzusetzen, sondern die Nachricht lediglich zu bereinigen und die Verbindung nach der Antwort offen zu halten. Dies darf nur erfolgen, wenn absolut sicher ist, dass keine HTTP/1.0-Agenten in der Kette vorhanden sind und alle Implementierungen vor HAProxy die HTTP/1.1-Regeln zu diesen Header-Feldern vollständig einhalten. In jedem Fall ignoriert und entfernt HAProxy weiterhin den überflüssigen Content-Length-Header, um die nächste Station nicht zu verwirren.

Wird diese Option wegen eines alten fehlerhaften Clients oder Servers aktiviert, ist Folgendes wichtig: Unabhängig davon, ob die Option nötig ist, riskiert ein Agent, der diese Regel verletzt, dass ältere Agenten seine Nachrichten abschneiden. Diese würden Content-Length berücksichtigen und Transfer-Encoding ignorieren, obwohl die summierte Größe der codierten Chunk-Längenangaben nicht darin enthalten ist. Die obige Regel dient also nicht nur der Sicherheit, sondern auch dazu, Agenten auszusondern, die wegen Inkompatibilitäten mit älteren Agenten Kommunikationsprobleme haben können.

h1-case-adjust <from> <to>

h1-case-adjust <from> <to>

Definiert die Anpassung der Groß- und Kleinschreibung für den Header-Namen <from>, sofern aktiviert. Vor dem Senden an HTTP/1-Clients oder -Server wird er in <to> geändert. <from> muss kleingeschrieben sein; <from> und <to> dürfen sich nur in der Groß- und Kleinschreibung unterscheiden. Für mehrere Header-Namen kann die Direktive wiederholt werden. Doppelte Einträge sind nicht zulässig. Müssen viele Header-Namen angepasst werden, ist “h1-case-adjust-file” möglicherweise praktischer. Beachten Sie, dass ohne “option h1-case-adjust-bogus-client” oder “option h1-case-adjust-bogus-server” in einem Proxy keine Umwandlung erfolgt.

Es gibt keine standardisierte Groß- und Kleinschreibung für Header-Namen, da sie gemäß RFC7230 unabhängig davon verglichen werden. Anwendungen müssen sie daher ohne Unterscheidung der Groß- und Kleinschreibung verarbeiten. Einige fehlerhafte Anwendungen verletzen jedoch die Standards und verlassen sich auf die von Browsern meist verwendete Schreibweise. Bei HTTP/2 wird dies kritisch, da alle Header-Namen kleingeschrieben übertragen werden müssen. HAProxy folgt derselben Konvention: Unabhängig von der HTTP-Version werden alle Header-Namen kleingeschrieben an Clients und Server gesendet.

Anwendungen, die Anfragen oder Antworten nicht korrekt verarbeiten, benötigen solche Umgehungslösungen möglicherweise vorübergehend, um die an sie gesendeten Header-Namen bis zur Fehlerbehebung anzupassen. Beachten Sie, dass eine Anwendung, die dies benötigt, für Content-Smuggling-Angriffe anfällig sein könnte und unbedingt korrigiert werden muss.

Beispiel:

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

Siehe “h1-case-adjust-file”, “option h1-case-adjust-bogus-client” und “option h1-case-adjust-bogus-server”.

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

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

Definiert eine Datei mit Schlüssel-Wert-Paaren, um die Groß- und Kleinschreibung bestimmter Header-Namen vor dem Senden an HTTP/1-Clients oder -Server anzupassen. Die Datei <hdrs-file> muss pro Zeile 2 Header-Namen enthalten. Der erste muss kleingeschrieben sein; beide dürfen sich nur in der Groß- und Kleinschreibung unterscheiden. Zeilen mit ‘#’ am Anfang und Leerzeilen werden ignoriert. Führende und abschließende Tabulatoren und Leerzeichen werden entfernt. Doppelte Einträge sind nicht zulässig. Ohne “option h1-case-adjust-bogus-client” oder “option h1-case-adjust-bogus-server” in einem Proxy erfolgt keine Umwandlung.

Wird diese Direktive wiederholt, wird nur die letzte verarbeitet. Sie ist eine Alternative zu “h1-case-adjust”, wenn viele Header-Namen angepasst werden müssen. Bitte lesen Sie die Hinweise zu den damit verbundenen Risiken.

Siehe “h1-case-adjust”, “option h1-case-adjust-bogus-client” und “option h1-case-adjust-bogus-server”.

h2-workaround-bogus-websocket-clients

h2-workaround-bogus-websocket-clients

Deaktiviert die Bekanntgabe der Unterstützung für h2-Websockets an Clients. Dies kann Probleme mit Clients umgehen, die Schwierigkeiten mit der Implementierung des noch relativ neuen RFC8441 haben, etwa Firefox 88. Damit Clients für den Websocket-Tunnel automatisch auf http/1.1 zurückfallen können, geben Sie h2-Unterstützung in der bind-Zeile mit “alpn” ohne explizites Schlüsselwort “proto” an. Wurde diese Anweisung zuvor aktiviert, lässt sie sich mit dem vorangestellten Schlüsselwort “no” deaktivieren.

hard-stop-after <time>

hard-stop-after <time>

Definiert die maximal zulässige Zeit für ein sauberes, geordnetes Herunterfahren.

Argumente:

<time>  ist die maximale Zeit (standardmäßig in Millisekunden), die die
        Instanz nach einer über das Signal SIGUSR1 empfangenen Aufforderung
        zum geordneten Beenden noch weiterläuft.

Damit lässt sich sicherstellen, dass die Instanz auch dann beendet wird, wenn während eines Soft-Stops Verbindungen offen bleiben (beispielsweise bei langen Zeitüberschreitungen für einen Proxy im TCP-Modus). Dies gilt sowohl im TCP- als auch im HTTP-Modus.

Beispiel:

global
  hard-stop-after 30s

Siehe auch: grace

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

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

Schaltet für jedes Protokoll einen Schutz ein oder aus, der die Kommunikation mit Clients verbietet, die privilegierte Ports als Quellport verwenden. Dieser Portbereich ist in RFC 6335 definiert. Standardmäßig ist der Schutz für das QUIC-Protokoll aktiv, da dieses Verhalten verdächtig ist und für Spoofing- oder DNS/NTP-Amplifikationsangriffe genutzt werden kann.

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

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

Ersetzt, verkleinert oder erweitert die Liste der Statuscodes, die für die Beendigungscodes und den Zähler “http_err_cnt” in Stick-Tabellen einen Fehler kennzeichnen. Der Standardbereich für Fehler reicht von 400 bis 499. In bestimmten Situationen ziehen es jedoch einige Benutzer vor, bestimmte Codes auszuschließen, insbesondere beim Erfassen von Clientfehlern (z. B. 404 auf Systemen mit dynamisch erzeugten Inhalten). Siehe auch “http-fail-codes” und “http_err_cnt”.

Ein Bereich ohne vorangestelltes ‘+’ oder ‘-’ ersetzt den vorhandenen Bereich durch den neuen. Ein Bereich mit vorangestelltem ‘+’ erweitert den vorhandenen Bereich um den angegebenen Bereich; dieser darf sich mit dem vorhandenen Bereich überschneiden, muss es aber nicht. Ein Bereich mit vorangestelltem ‘-’ entfernt den angegebenen Bereich aus dem vorhandenen. Ein Bereich besteht aus einer Zahl von 100 bis 599, auf die optional “-” und eine weitere Zahl folgen, die mindestens so groß wie die erste ist und die Obergrenze des Bereichs angibt. Mehrere Bereiche für dieselbe Operation zum Hinzufügen, Entfernen oder Ersetzen können durch Kommas getrennt werden.

Beispiel:

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

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

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

Ersetzt, verkleinert oder erweitert die Liste der Statuscodes, die für die Beendigungscodes und den Zähler “http_fail_cnt” in Stick-Tabellen einen Fehlschlag kennzeichnen. Der Standardbereich für Fehlschläge reicht von 500 bis 599, mit Ausnahme von 501 und 505, die durch Clients ausgelöst werden können. Diese Codes zeigen normalerweise an, dass der Server die Anfrage nicht verarbeiten konnte. Einige Benutzer ziehen es vor, bestimmte Codes in Situationen auszuschließen, in denen diese bekanntermaßen nicht relevant sind, beispielsweise 500 in bestimmten SOAP-Umgebungen, wo dieser Code keinen Serverfehler ausdrückt. Die Syntax ist genau dieselbe wie bei http-err-codes oben. Siehe auch “http-err-codes” und “http_fail_cnt”.

insecure-fork-wanted

insecure-fork-wanted

Standardmäßig versucht HAProxy mit allen verfügbaren Mitteln zu verhindern, dass nach dem Start weitere Threads oder Prozesse erzeugt werden. Dies ist besonders wichtig bei Lua-Dateien unklarer Herkunft und beim Experimentieren mit Entwicklungsversionen, die noch Fehler enthalten können, deren Ausnutzbarkeit unklar ist. Generell ist es eine sinnvolle Vorsichtsmaßnahme, sicherzustellen, dass Datenverkehr keine unerwarteten Hintergrundaktivitäten auslösen kann. Allerdings verhindert dies die Ausführung externer Prüfungen und kann bestimmte, sehr spezielle Lua-Skripte beeinträchtigen, die ausdrücklich auf die Möglichkeit zum Forken angewiesen sind. Diese Option dient dazu, den Schutz zu deaktivieren. Beachten Sie, dass dies keine gute Idee ist: Eine Schwachstelle in einer Bibliothek oder in HAProxy selbst lässt sich bei deaktiviertem Schutz leichter ausnutzen. Außerdem ist das Forken aus Lua oder an anderer Stelle unzuverlässig, da der durch Fork erzeugte Prozess zufällig eine von einem anderen Thread gesetzte Sperre übernehmen kann und dann einen Vorgang niemals abschließen kann. Daher wird dringend empfohlen, diese Option niemals zu verwenden und jede Arbeitslast, die einen solchen Fork benötigt, zu überdenken und auf eine sicherere Lösung umzustellen (beispielsweise Agenten anstelle externer Prüfungen). Diese Option unterstützt das Präfix “no”, um sie zu deaktivieren. Sie kann auch mit “-dI” in der haproxy-Befehlszeile aktiviert werden.

insecure-setuid-wanted

insecure-setuid-wanted

HAProxy muss zur Laufzeit keine ausführbaren Programme aufrufen (außer bei externen Prüfungen, von denen dringend abgeraten wird) und soll sich sogar in einer leeren chroot-Umgebung isolieren. Daher gibt es grundsätzlich keinen triftigen Grund, den Aufruf eines ausführbaren setuid-Programms zu erlauben, ohne dass sich der Benutzer der Risiken vollständig bewusst ist. Wenn HAProxy externe Prüfungen aufrufen und/oder chroot deaktivieren muss, könnte das Ausnutzen einer Schwachstelle in einer Bibliothek oder in HAProxy selbst zur Ausführung eines externen Programms führen. Unter Linux lässt sich der Prozess so einschränken, dass ein auf einem solchen Programm gesetztes setuid-Bit ignoriert wird. Dies verringert das Risiko einer Rechteausweitung in dieser Situation erheblich. HAProxy tut dies standardmäßig. Falls dies bei einer externen Prüfung Probleme verursacht (beispielsweise wenn sie den Befehl “ping” benötigt), kann dieser Schutz durch explizites Hinzufügen dieser Direktive im globalen Abschnitt deaktiviert werden. Ist die Direktive aktiviert, lässt sie sich durch Voranstellen des Schlüsselworts “no” wieder deaktivieren.

issuers-chain-path <dir>

issuers-chain-path <dir>

Legt ein Verzeichnis fest, aus dem Zertifikatsketten zur Vervollständigung der Ausstellerkette geladen werden. Alle Dateien müssen im PEM-Format vorliegen. Wenn bei Zertifikaten, die mit “crt” oder “crt-list” geladen werden, die Zertifikatskette (auch als Zwischenzertifikat bekannt) nicht in der PEM-Datei enthalten ist, vervollständigt HAProxy die Kette, sofern der Aussteller des Zertifikats dem ersten Zertifikat der mit “issuers-chain-path” geladenen Kette entspricht. Eine “crt”-Datei mit PrivateKey+Certificate+IntermediateCA2+IntermediateCA1 könnte durch PrivateKey+Certificate ersetzt werden. HAProxy vervollständigt die Kette, wenn im Verzeichnis “issuers-chain-path” eine Datei mit IntermediateCA2+IntermediateCA1 vorhanden ist. Alle anderen Zertifikate mit demselben Aussteller teilen sich die Kette im Speicher.

Die OCSP-Funktionen können die vervollständigte Kette verwenden, wenn keine .issuer-Datei verwendet wurde oder keine Kette in der PEM-Datei enthalten war.

jwt.allow_none_alg

jwt.allow_none_alg

Erlaubt JWT-Token mit dem Algorithmus “none” im Konverter ‘jwt_verify’. Wenn diese Option gesetzt ist, gelten diese Token immer als gültig. Standardmäßig werden unsignierte Token abgelehnt, da sie als unsicher gelten (siehe RFC8725 Abschnitt 3.1 ).

jwt.decrypt_alg_list <list>

jwt.decrypt_alg_list <list>

Legt die Liste der in den Konvertern jwt_decrypt_XXX erlaubten Algorithmen fest. JWT-Tokens mit einem nicht unterstützten oder deaktivierten Algorithmus werden niemals entschlüsselt. Die angegebenen Algorithmen müssen dasselbe Format wie in Abschnitt 4.1 von RFC7518 haben und durch Doppelpunkte getrennt werden. Mit dem besonderen Namen “ALL” können alle unterstützten Algorithmen aktiviert werden (eine vollständige Liste finden Sie beim Konverter “jwt_decrypt_jwk”); einem Algorithmusnamen kann ein ‘!’ hinzugefügt werden, um ihn ausdrücklich zu deaktivieren. Beachten Sie, dass diese Option alle Algorithmen deaktiviert, die nicht ausdrücklich in der angegebenen Liste aufgeführt sind, sofern nicht “ALL” angegeben wird.

Beispiele:

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

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

jwt.decrypt_enc_list <list>

jwt.decrypt_enc_list <list>

Legt die Liste der in den Konvertern jwt_decrypt_XXX erlaubten Verschlüsselungsalgorithmen fest. JWT-Tokens mit einem nicht unterstützten oder deaktivierten Verschlüsselungsalgorithmus werden niemals entschlüsselt. Die angegebenen Algorithmen müssen dasselbe Format wie in Abschnitt 5.1 von RFC7518 haben und durch Doppelpunkte getrennt werden. Mit dem besonderen Namen “ALL” können alle unterstützten Algorithmen aktiviert werden (eine vollständige Liste finden Sie beim Konverter “jwt_decrypt_jwk”); einem Algorithmusnamen kann ein ‘!’ hinzugefügt werden, um ihn ausdrücklich zu deaktivieren. Beachten Sie, dass diese Option alle Algorithmen deaktiviert, die nicht ausdrücklich in der angegebenen Liste aufgeführt sind, sofern nicht “ALL” angegeben wird.

Beispiele:

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

key-base <dir>

key-base <dir>

Legt ein Standardverzeichnis fest, aus dem private SSL-Schlüssel geladen werden, wenn bei “key”-Direktiven ein relativer Pfad verwendet wird. Angegebene absolute Pfade haben Vorrang und ignorieren “key-base”. Diese Option funktioniert nur mit einer load-Zeile in einem crt-store.

limited-quic

limited-quic

Diese Einstellung muss verwendet werden, um QUIC-Listener-Bindungen ausdrücklich zu aktivieren, wenn haproxy mit einer OpenSSL-Version ohne QUIC-Unterstützung kompiliert wurde. Sie aktiviert eine interne Kompatibilitätsschicht von haproxy, die beim Kompilieren mit USE_QUIC_OPENSSL_COMPAT=1 ausgewählt worden sein muss. Diese Kompatibilitätsschicht unterstützt die meisten erforderlichen TLS-Operationen, allerdings ohne QUIC 0-RTT.

Diese Funktion richtet sich hauptsächlich an OpenSSL vor Version 3.5.2, wo die QUIC-API noch nicht oder nur teilweise implementiert war. Die Kompatibilitätsschicht lässt sich auch für Version 3.5.2 und höher aktivieren, was aber vermutlich unnötig ist.

Wenn limited-quic gesetzt ist, die Kompatibilitätsschicht beim Kompilieren aber nicht ausgewählt wurde, wird die Option ohne Meldung ignoriert, und die QUIC-TLS-Operationen verwenden die TLS-Bibliothek.

localpeer <name>

localpeer <name>

Legt den Peer-Namen der lokalen Instanz fest. Die Option wird ignoriert, wenn das Befehlszeilenargument “-L” angegeben wurde oder wenn sie nach “peers”-Abschnittsdefinitionen verwendet wird. In diesen Fällen wird beim Einlesen der Konfiguration eine Warnung ausgegeben.

Diese Option setzt außerdem die Umgebungsvariable HAPROXY_LOCALPEER. Siehe auch “-L” im Verwaltungshandbuch und den Abschnitt “peers” weiter unten.

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

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

Fügt einen globalen Syslog-Server hinzu. Es können mehrere globale Server definiert werden. Sie erhalten Protokollmeldungen zu Starts und Beendigungen sowie alle Protokollmeldungen von Proxys, die mit “log global” konfiguriert sind. Weitere Einzelheiten finden Sie bei der Option “log” für Proxys.

log-send-hostname [<string>]

log-send-hostname [<string>]

Legt das Hostnamenfeld im Syslog-Header fest. Wenn der optionale Parameter “string” gesetzt ist, erhält das Feld den Inhalt dieser Zeichenfolge; andernfalls wird der Hostname des Systems verwendet. Dies wird meist verwendet, wenn Protokollmeldungen nicht über einen zwischengeschalteten Syslog-Server weitergeleitet werden oder wenn lediglich der in den Protokollen ausgegebene Hostname angepasst werden soll.

log-tag <string>

log-tag <string>

Setzt das Tag-Feld im Syslog-Header auf diese Zeichenfolge. Standardmäßig wird der Programmname verwendet, mit dem das Programm über die Befehlszeile gestartet wurde; dieser ist üblicherweise “haproxy”. Manchmal kann es sinnvoll sein, damit mehrere auf demselben Host laufende Prozesse zu unterscheiden. Siehe auch die pro Proxy einstellbare Direktive “log-tag”.

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

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

Diese globale Direktive lädt eine Lua-Datei und führt sie im gemeinsamen Kontext aus, der für alle Threads sichtbar ist. Jede in diesem Kontext gesetzte Variable ist für jeden Thread sichtbar. Dies ist die einfachste und empfohlene Methode, Lua-Programme zu laden, skaliert bei vielen Lua-Aufrufen jedoch nicht gut, da jeweils nur ein Thread mit dem globalen Zustand arbeiten kann. Ein so geladenes Programm sieht in der Variablen “core.thread” immer den Wert 0. Diese Direktive kann mehrfach verwendet werden.

Die Argumente sind in der Lua-Datei über den folgenden Code im Dateirumpf verfügbar. Denken Sie daran, dass Lua-Arrays mit dem Index 1 beginnen. Eine in einer Datei deklarierte “local”-Variable ist in der gesamten Datei verfügbar, in anderen Dateien jedoch nicht.

 local args = table.pack(...)

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

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

Diese globale Direktive lädt eine Lua-Datei in jeden gestarteten Thread und führt sie dort aus. Globale Variablen sind nur innerhalb des jeweiligen Threads sichtbar, sodass jeder Thread einen anderen Wert sehen kann. Daher wird dringend empfohlen, in so geladenen Programmen keine globalen Variablen zu verwenden. Für jeden Thread wird eine unabhängige Kopie geladen und initialisiert; alles erfolgt nacheinander und in der numerischen Reihenfolge der Threads von 1 bis nbthread. Falls bestimmte Operationen nur einmal ausgeführt werden müssen, sollte das Programm anhand der Variablen “core.thread” prüfen, welcher Thread gerade initialisiert wird. So geladene Programme laufen gleichzeitig auf allen Threads und sind sehr gut skalierbar. Dies ist die empfohlene Methode zum Laden einfacher Funktionen, die Sample-Fetches, Konverter, Aktionen oder Dienste registrieren, sobald feststeht, dass das Programm nicht von globalen Variablen abhängt. Der Einfachheit halber steht die Direktive auch dann zur Verfügung, wenn nur ein Thread verwendet wird oder Threads deaktiviert sind (in diesem Fall entspricht sie lua-load). Diese Direktive kann mehrfach verwendet werden.

Zur Verwendung von Argumenten siehe lua-load.

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

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

Stellt die angegebene Zeichenfolge, gefolgt von einem Semikolon, der Lua-Variablen package.<type> voran. <type> muss entweder “path” oder “cpath” sein. Wenn <type> nicht angegeben wird, ist der Standardwert “path”.

Die Pfade von Lua sind durch Semikolons getrennte Listen von Mustern, die bestimmen, wie die Funktion require nach der Quelldatei einer Bibliothek sucht. Fragezeichen (?) innerhalb eines Musters werden durch den Modulnamen ersetzt. Der Pfad wird von links nach rechts ausgewertet. Somit werden später vorangestellte Pfade früher geprüft.

Beispielsweise bei Angabe des folgenden Pfads:

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

Beim Aufruf von require "example" versucht Lua zunächst, das Skript /usr/share/haproxy-lua/example.lua zu laden. Falls es nicht vorhanden ist, wird /usr/share/haproxy-lua/example/init.lua versucht. Falls auch dieses nicht vorhanden ist, werden die Standardpfade geprüft.

Einzelheiten finden Sie in der Lua-Dokumentation unter https://www.lua.org/pil/8.1.html .

master-worker (deprecated)

master-worker (deprecated)

Master-Worker-Modus. Er entspricht dem Befehlszeilenargument “-W”.

Dieses Schlüsselwort ist veraltet. Starten Sie den Master-Worker-Modus stattdessen mit “-W” oder “-Ws”.

Dieser Modus startet einen “master”, der nach dem Einlesen der Konfiguration mittels Fork einen “worker” zur Verarbeitung des Datenverkehrs erzeugt. Der Master dient als Prozessmanager, der die “workers” überwacht.

In diesem Modus können Sie HAProxy direkt neu laden, indem Sie dem Master das Signal SIGUSR2 senden. Beim Neuladen wird der Master aufgefordert, die Konfiguration erneut einzulesen und mittels Fork einen neuen Worker zu erzeugen. Der bisherige Worker bleibt bis zum Ende seiner Aufgaben erhalten.

Der Master-Worker-Modus ist sowohl mit dem Vordergrund- als auch mit dem Daemon-Modus kompatibel.

Wenn ein Worker mit einem Fehlercode beendet wird, etwa wegen eines Segmentierungsfehlers, werden standardmäßig alle Worker beendet, und der Master wird ebenfalls beendet. Es bietet sich an, dieses Verhalten mit Restart=on-failure in einer systemd-Unit-Datei zu kombinieren, um den gesamten Prozess neu zu starten. Falls Sie dieses Verhalten nicht wünschen, müssen Sie das Schlüsselwort “no-exit-on-failure” verwenden.

Siehe auch “-W” im Verwaltungshandbuch.

master-worker no-exit-on-failure

master-worker no-exit-on-failure

Wenn im Master-Worker-Modus ein Worker mit einem Fehlercode beendet wird, etwa wegen eines Segmentierungsfehlers, werden standardmäßig alle Worker beendet, und der Master wird ebenfalls beendet. Es bietet sich an, dieses Verhalten mit Restart=on-failure in einer systemd-Unit-Datei zu kombinieren, um den gesamten Prozess neu zu starten.

Dieses Schlüsselwort ermöglicht es, die übrigen Prozesse nach dem Absturz eines Workers weiterlaufen zu lassen, anstatt alle zu beenden. Es muss mit Vorsicht verwendet werden, da es ausschließlich zur Fehlerdiagnose vorgesehen ist und den Master-Prozess in einen abnormen Zustand versetzen könnte.

max-threads-per-group <number>

max-threads-per-group <number>

Legt die maximale Anzahl von Threads in einer Thread-Gruppe fest. Sofern die Anzahl der Thread-Gruppen nicht mit der Direktive “thread-groups” festgelegt ist, erstellt haproxy so viele Thread-Gruppen wie nötig, um die angeforderte Thread-Anzahl zu erreichen. Der Mindestwert ist 1, der Höchstwert 64 (auf 64-Bit-Systemen beziehungsweise 32 auf 32-Bit-Systemen). Niedrigere Werte verringern die Konkurrenz bei atomaren Operationen auf gemeinsam genutzten Zuständen, können jedoch die Anzahl der Sockets erhöhen, die zum Erstellen aller Listener und zum Vorhalten ungenutzter Backend-Verbindungen benötigt werden. Höhere Werte verringern diesen Aufwand, verursachen bei Konkurrenz jedoch eine höhere CPU-Auslastung und niedrigere Verbindungsraten. Der Standardwert ist 16. In Tests auf verschiedenen Systemen erwies sich dies als der beste Kompromiss, darunter x86_64-Prozessoren mehrerer Hersteller und große Arm64-Systeme, sowohl auf physischer Hardware als auch unter Hypervisoren.

mworker-max-reloads <number>

mworker-max-reloads <number>

Im Master-Worker-Modus begrenzt diese Option, wie viele Neuladungen ein Worker überleben kann. Wenn der Worker nach einer Neuladung nicht beendet wurde und die Anzahl seiner Neuladungen diesen Wert überschreitet, erhält er ein SIGTERM-Signal. Diese Option hilft, die Anzahl der Worker unter Kontrolle zu halten. Siehe auch “show proc” im Verwaltungshandbuch.

Standardmäßig ist dieser Wert auf 50 gesetzt.

nbthread <number>

nbthread <number>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für Threads einkompiliert wurde. Sie lässt HAProxy mit <number> Threads laufen. “nbthread” funktioniert auch, wenn HAProxy im Vordergrund gestartet wird. Auf einigen Plattformen mit Unterstützung für CPU-Affinität wird der Standardwert von “nbthread” automatisch auf die Anzahl der CPUs gesetzt, an die der Prozess beim Start gebunden ist. Dadurch lässt sich die Thread-Anzahl vom aufrufenden Prozess aus mit Befehlen wie “taskset” oder “cpuset” einfach anpassen. Andernfalls ist der Standardwert 1. Der Standardwert wird in der Ausgabe von “haproxy -vv” angezeigt. Beachten Sie, dass sowohl hier gesetzte als auch automatisch ermittelte Werte der durch “thread-hard-limit” festgelegten Grenze unterliegen (sofern diese gesetzt ist).

numa-cpu-mapping

numa-cpu-mapping

Auf einer NUMA-fähigen Plattform ermöglicht dies der Direktive “cpu-policy”, die Topologie zu untersuchen und die beste Auswahl an CPUs sowie die dazugehörige Thread-Anzahl zu ermitteln. Falls die angewendete Bindung auf einer bestimmten Architektur jedoch nicht optimal ist, kann sie mit der Anweisung ’no numa-cpu-mapping’ deaktiviert werden. Diese automatische Bindung wird auch dann nicht angewendet, wenn eine ’nbthread’-Anweisung in der Konfiguration vorhanden ist, wenn die Prozessaffinität bereits festgelegt wurde, beispielsweise über die Direktive ‘cpu-map’ oder das Dienstprogramm taskset, oder wenn cpu-policy auf einen anderen Wert gesetzt ist. Siehe auch “cpu-map”, “cpu-policy”, “cpu-set”.

ocsp-update.disable [ on | off ]

ocsp-update.disable [ on | off ]

Deaktiviert ocsp-update in HAProxy vollständig. Sämtliche ocsp-update-Konfiguration wird ignoriert. Der Standardwert ist “off”. Weitere Informationen zum automatischen Aktualisierungsmechanismus finden Sie bei der Option “ocsp-update”.

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

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

Ermöglicht die Verwendung eines HTTP-Proxys für die OCSP-Aktualisierungen. Dies funktioniert nur mit HTTP; HTTPS wird nicht unterstützt. Mit dieser Option kann der OCSP-Aktualisierer eine absolute URI in der Anfrage an den Proxy senden.

ocsp-update.maxdelay <number>

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

Legt das maximale Intervall zwischen zwei automatischen Aktualisierungen derselben OCSP-Antwort fest. Die Zeit wird in Sekunden angegeben und beträgt standardmäßig 3600 (1 Stunde). Der Wert muss höher als “ocsp-update.mindelay” sein. Weitere Informationen zum automatischen Aktualisierungsmechanismus finden Sie bei der Option “ocsp-update”.

ocsp-update.mindelay <number>

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

Legt das minimale Intervall zwischen zwei automatischen Aktualisierungen derselben OCSP-Antwort fest. Die Zeit wird in Sekunden angegeben und beträgt standardmäßig 300 (5 Minuten). Dies ist besonders bei OCSP-Antworten ohne ausdrücklichen Ablaufzeitpunkt nützlich. Der Wert muss niedriger als “ocsp-update.maxdelay” sein. Weitere Informationen zum automatischen Aktualisierungsmechanismus finden Sie bei der Option “ocsp-update”.

ocsp-update.mode [ on | off ]

ocsp-update.mode [ on | off ]

Legt den standardmäßigen ocsp-update-Modus für alle in der Konfiguration verwendeten Zertifikate fest. Diese globale Option kann durch die crt-list-Option “ocsp-update” überschrieben werden. Standardmäßig ist sie auf “off” gesetzt. Weitere Informationen zum automatischen Aktualisierungsmechanismus finden Sie bei der Option “ocsp-update”.

pidfile <pidfile>

pidfile <pidfile>

Schreibt im Daemon-Modus die PIDs aller Daemons in die Datei <pidfile> beziehungsweise im Master-Worker-Modus die PID des Master-Prozesses in die Datei <pidfile>. Diese Option entspricht dem Befehlszeilenargument “-p”. Die Datei muss für den Benutzer zugänglich sein, der den Prozess startet. Siehe auch “daemon” und “master-worker”.

pp2-never-send-local

pp2-never-send-local

Bis einschließlich Version 2.1 enthielt HAProxy einen Fehler in der Implementierung des PROXY-Protokolls v2, durch den bei Zustandsprüfungen ein PROXY-Befehl anstelle eines LOCAL-Befehls gesendet wurde. Dies ist zwar geringfügig, führt aber in den Protokollen einiger Server zu Verwirrung. Leider wurde der Fehler erst sehr spät entdeckt. Dabei zeigte sich, dass einige Server, deren PROXY-Protokollimplementierung möglicherweise nur mit HAProxy getestet wurde, den LOCAL-Befehl nicht korrekt verarbeiten und dauerhaft im Zustand “down” verbleiben, wenn HAProxy sie prüft. In diesem Fall kann diese globale Option aktiviert werden, um zum alten (fehlerhaften) Verhalten zurückzukehren, bis die Hersteller der betroffenen Komponenten kontaktiert und die Komponenten korrigiert wurden. Diese Option ist standardmäßig deaktiviert und wirkt auf alle Server mit der Anweisung “send-proxy-v2”.

presetenv <name> <value>

presetenv <name> <value>

Setzt die Umgebungsvariable <name> auf den Wert <value>. Wenn die Variable bereits existiert, wird sie NICHT überschrieben. Die Änderungen werden sofort wirksam, sodass bereits die nächste Zeile in der Konfigurationsdatei den neuen Wert sieht. Siehe auch “setenv”, “resetenv” und “unsetenv”.

prealloc-fd

prealloc-fd

Öffnet einmalig den höchsten Dateideskriptor und bewirkt damit eine Vorabzuweisung der Datenstrukturen des Kernels. Dies verhindert kurze Pausen, wenn nbthread>1 gilt und HAProxy einen Dateideskriptor öffnet, für den der Kernel seine Datenstrukturen erweitern muss.

resetenv [<name> ...]

resetenv [<name> ...]

Entfernt alle Umgebungsvariablen außer den als Argument angegebenen. Dies ermöglicht eine bereinigte, kontrollierte Umgebung, bevor mit setenv oder unsetenv neue Werte gesetzt werden. Beachten Sie, dass einige interne Funktionen Umgebungsvariablen verwenden können, etwa Funktionen zur Zeitverarbeitung, aber auch OpenSSL oder sogar externe Prüfungen. Dies darf nur mit äußerster Vorsicht und nach vollständiger Validierung verwendet werden. Die Änderungen werden sofort wirksam, sodass bereits die nächste Zeile in der Konfigurationsdatei die neue Umgebung sieht. Siehe auch “setenv”, “presetenv” und “unsetenv”.

server-state-base <directory>

server-state-base <directory>

Legt das Verzeichnispräfix fest, das allen Namen von Serverzustandsdateien vorangestellt wird, die nicht mit ‘/’ beginnen. Siehe auch “server-state-file”, “load-server-state-from-file” und “server-state-file-name”.

server-state-file <file>

server-state-file <file>

Gibt den Pfad zur Datei mit den Serverzuständen an. Beginnt der Pfad mit einem Schrägstrich (’/’), gilt er als absolut; andernfalls wird er relativ zu dem mit “server-state-base” festgelegten Verzeichnis (falls gesetzt) oder zum aktuellen Verzeichnis interpretiert. Vor dem Neuladen von HAProxy können die aktuellen Serverzustände mit dem Statistikbefehl “show servers state” gespeichert werden. Die Ausgabe dieses Befehls muss in die durch <file> bezeichnete Datei geschrieben werden. Beim Start liest, lädt und übernimmt HAProxy vor der Verarbeitung von Datenverkehr den Zustand jedes Servers, der sowohl in der Datei als auch in der aktuellen laufenden Konfiguration vorhanden ist. Siehe auch “server-state-base” und “show servers state”, “load-server-state-from-file” und “server-state-file-name”

set-dumpable [ on | off | libs ]

set-dumpable [ on | off | libs ]

Mit dieser Option lässt sich das Verhalten bei der Erstellung eines Speicherabbilds nach einem Prozessabsturz festlegen. Verfügbare Optionen sind:

• on aktiviert die Erstellung von Speicherabbildern auf Prozessebene, falls sie zuvor deaktiviert war.

• off deaktiviert eine zuvor aktivierte Erstellung von Speicherabbildern.

• libs aktiviert die Erstellung von Speicherabbildern mit einer eingebetteten Kopie der für die Fehlerdiagnose benötigten Programmdateien und Bibliotheken. Entwickler können dies anfordern. In diesem Fall versucht haproxy, die Bibliotheken, von denen es abhängt, in den Speicher zu laden und dort sorgfältig aufzubewahren. Falls der Prozess abstürzt, werden sie in das Speicherabbild aufgenommen, sodass sie nicht mehr aus dem Dateisystem beschafft werden müssen und keine Gefahr besteht, dass sie nicht zum Speicherabbild passen. Dafür werden einige bis einige zehn Megabyte zusätzlicher RAM benötigt, weshalb dies auf kleinen Systemen besser nicht verwendet werden sollte.

Diese Option sollte standardmäßig deaktiviert bleiben und nur auf Anforderung eines Entwicklers aktiviert werden. Standardmäßig ist sie deaktiviert. Ohne Argument ist der Standardwert “on”. Wenn sie aktiviert wurde, kann sie dennoch durch Voranstellen des Schlüsselworts “no” oder durch Setzen auf “off” ausdrücklich deaktiviert werden. Sie hat keine Auswirkungen auf Leistung oder Stabilität, versucht aber mit allen verfügbaren Mitteln, Speicherabbilder wieder zu aktivieren, die möglicherweise durch Dateigrößenlimits (ulimit -f), Größenlimits für Speicherabbilder (ulimit -c) oder die Fähigkeit eines Prozesses zur Erstellung von Speicherabbildern nach Änderung seiner UID/GID (etwa /proc/sys/fs/suid_dumpable unter Linux) deaktiviert wurden. Speicherabbilder können weiterhin durch die Berechtigungen des aktuellen Verzeichnisses (prüfen Sie, aus welchem Verzeichnis die Datei gestartet wird), die Berechtigungen des chroot-Verzeichnisses (möglicherweise muss die chroot-Direktive vorübergehend deaktiviert oder das Verzeichnis an einen eigenen beschreibbaren Ort verlegt werden) oder andere systemspezifische Einschränkungen begrenzt sein. Einige Linux-Varianten sind beispielsweise dafür bekannt, die standardmäßige core-Datei durch den Pfad zu einem Programm zu ersetzen, das nicht einmal auf dem System installiert ist (prüfen Sie /proc/sys/kernel/core_pattern). Häufig lässt sich das Problem einfach durch Eintragen von “core”, “core.%p” oder “/var/log/core/core.%p” beheben. Wenn Sie diese Option aktivieren und auf das erneute Auftreten eines seltenen Problems warten, ist es oft sinnvoll, zunächst ein solches Speicherabbild zu erzeugen, beispielsweise durch Senden von “kill -11” an den “haproxy”-Prozess, und zu prüfen, ob dieser beim Beenden ein Speicherabbild am erwarteten Ort hinterlässt.

set-var <var-name> <expr>

set-var <var-name> <expr>

Setzt die prozessweite Variable ‘<var-name>’ auf das Ergebnis der Auswertung des Sample-Ausdrucks <expr>. Die Variable ‘<var-name>’ darf nur eine prozessweite Variable sein (mit dem Präfix ‘proc.’). Dies funktioniert genau wie die Aktion ‘set-var’ in TCP- oder HTTP-Regeln, mit dem Unterschied, dass der Ausdruck beim Einlesen der Konfiguration ausgewertet und die Variable sofort gesetzt wird. Im Ausdruck sind nur Sample-Fetch-Funktionen und Konverter erlaubt, die interne Daten verwenden, typischerweise ‘int(value)’ oder ‘str(value)’. Auch bereits angelegte Variablen können referenziert werden. Diese Variablen können anschließend aus den regulären Regelsätzen gelesen und geändert werden.

Beispiel:

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

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

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

Setzt die prozessweite Variable ‘<var-name>’ auf die Zeichenfolge, die sich aus der Auswertung des Protokollformats <fmt> ergibt. Die Variable ‘<var-name>’ darf nur eine prozessweite Variable sein (mit dem Präfix ‘proc.’). Dies funktioniert genau wie die Aktion ‘set-var-fmt’ in TCP- oder HTTP-Regeln, mit dem Unterschied, dass der Ausdruck beim Einlesen der Konfiguration ausgewertet und die Variable sofort gesetzt wird. Im Ausdruck sind nur Sample-Fetch-Funktionen und Konverter erlaubt, die interne Daten verwenden, typischerweise ‘int(value)’ oder ‘str(value)’. Auch bereits angelegte Variablen können referenziert werden. Diese Variablen können anschließend aus den regulären Regelsätzen gelesen und geändert werden. Einzelheiten zur Syntax benutzerdefinierter Protokollformate finden Sie in Abschnitt 8.2.6 .

Beispiel:

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

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

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

Legt eine Liste von Capabilities fest, die erhalten bleiben müssen, wenn der Prozess entweder als Benutzer ohne Root-Rechte (uid > 0) gestartet und ausgeführt wird oder zunächst mit uid 0 (root) startet und anschließend zu einem Benutzer ohne Root-Rechte wechselt. Standardmäßig gehen beim Wechsel der uid alle Berechtigungen verloren. Einige davon werden jedoch oft benötigt, etwa um sich beim transparenten Proxying von einer fremden Adresse aus mit einem Server zu verbinden oder einen Port unterhalb von 1024 zu binden, beispielsweise bei Verwendung von “tune.quic.fe.sock-per-conn default-on”. Dies führt zu Konfigurationen, die vollständig unter uid 0 laufen. Das Setzen von Capabilities ist im Allgemeinen eine sicherere Alternative, da nur die benötigten Capabilities erhalten bleiben. Die Funktion ist OS-spezifisch und nur unter Linux aktiviert, wenn beim Kompilieren USE_LINUX_CAP=1 gesetzt wurde. Die Liste der unterstützten Capabilities hängt ebenfalls vom OS ab und wird in der Fehlermeldung aufgeführt, die bei Angabe eines ungültigen oder leeren Capability-Namens erscheint. Mehrere Capabilities können durch Kommas getrennt angegeben werden. Zu den häufig verwendeten gehören “cap_net_raw”, das die transparente Bindung an eine fremde Adresse erlaubt, und “cap_net_bind_service”, das die Bindung an einen privilegierten Port erlaubt und von QUIC verwendet werden kann. Wenn der Prozess unter demselben Benutzer ohne Root-Rechte gestartet und ausgeführt wird, sollten die benötigten Capabilities zusätzlich zu diesem Schlüsselwort mit setcap auf der haproxy-Programmdatei gesetzt werden. Weitere Einzelheiten zum Setzen von Capabilities auf der haproxy-Programmdatei finden Sie in Kapitel 13.1 zur Unterstützung von Linux-Capabilities im Verwaltungshandbuch.

Beispiel:

global
    setcap cap_net_bind_service,cap_net_admin

setenv <name> <value>

setenv <name> <value>

Setzt die Umgebungsvariable <name> auf den Wert <value>. Wenn die Variable bereits existiert, wird sie überschrieben. Die Änderungen werden sofort wirksam, sodass bereits die nächste Zeile in der Konfigurationsdatei den neuen Wert sieht. Siehe auch “presetenv”, “resetenv” und “unsetenv”.

shm-stats-file <name>

shm-stats-file <name>

Wenn diese Direktive gesetzt ist, aktiviert sie die Verwendung gemeinsamen Speichers zum Speichern von Statistikzählern. <name> wird als Argument an shm_open() übergeben, um den gemeinsamen Speicher an einem eindeutigen Ort zu öffnen. Die Direktive ist daher nur auf Systemen verfügbar, die shm_open() unterstützen. Wenn SHM für Statistiken verwendet wird, werden alle gemeinsam nutzbaren Zähler für Frontends, Backends, Listener und Server im SHM gespeichert, sofern für diese Objekte eine GUID gesetzt ist. Beim Neuladen von haproxy versucht der neue Prozess, den SHM nach Objekten zu durchsuchen, die sich anhand ihrer GUID und ihres Typs den in der Konfiguration definierten Objekten zuordnen lassen. Damit sollen die Werte einiger Zähler beim Neuladen erhalten bleiben. Wird haproxy hingegen ordnungsgemäß beendet, werden die SHM-Objekte freigegeben, wodurch die Zähler tatsächlich zurückgesetzt werden. Die Datei kann auch vor dem Start eines neuen Prozesses manuell entfernt werden, um ein Zurücksetzen zu erzwingen.

Siehe auch “guid”, “guid-prefix” und “shm-stats-file-max-objects”

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

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

Diese Einstellung legt fest, wie viele Objekte der für gemeinsame Zähler verwendete gemeinsame Speicher pro Thread-Gruppe maximal aufnehmen kann. Sie steht in direktem Zusammenhang mit der maximalen Speichergröße des shm und dient dazu, den shm vorab auf eine bestimmte Größe abzubilden, damit zur Laufzeit keine erneute Speicherabbildung nötig ist. Der Standardwert ist 2k. Dies sollte für die meisten Konfigurationen ausreichen, ohne einen unangemessenen Speicherverbrauch zu riskieren, lässt sich bei Bedarf aber einfach ändern. haproxy meldet beim Start, wenn der Wert zu niedrig ist, um alle Objekte zu registrieren, die im gemeinsamen Speicher abgelegt werden sollen. Diese Einstellung ist nur relevant, wenn “shm-stats-file” definiert wurde.

Siehe auch “thread-groups”

ssl-default-bind-ciphers <ciphers>

ssl-default-bind-ciphers <ciphers>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “bind”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Verschlüsselungsalgorithmen (“cipher suite”) beschreibt, die beim SSL/TLS-Handshake bis einschließlich TLSv1.2 ausgehandelt werden. Das Format der Zeichenfolge ist in “man 1 ciphers” der OpenSSL-Handbuchseiten definiert. Hintergrundinformationen und Empfehlungen finden Sie beispielsweise unter (https://wiki.mozilla.org/Security/Server_Side_TLS ) und (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Zur Konfiguration von TLSv1.3-Verschlüsselungsalgorithmen siehe das Schlüsselwort “ssl-default-bind-ciphersuites”. Weitere Informationen finden Sie beim Schlüsselwort “bind”.

ssl-default-bind-ciphersuites <ciphersuites>

ssl-default-bind-ciphersuites <ciphersuites>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde und HAProxy mit OpenSSL 1.1.1 oder höher erstellt wurde. Sie legt für alle “bind”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Verschlüsselungsalgorithmen (“cipher suite”) beschreibt, die beim TLSv1.3-Handshake ausgehandelt werden. Das Format der Zeichenfolge ist in “man 1 ciphers” der OpenSSL-Handbuchseiten im Abschnitt “ciphersuites” definiert. Zur Konfiguration von Verschlüsselungsalgorithmen für TLSv1.2 und frühere Versionen siehe das Schlüsselwort “ssl-default-bind-ciphers”. Diese Einstellung akzeptiert möglicherweise auch TLSv1.2-Cipher-Suites. Dieses Verhalten ist jedoch nicht dokumentiert und wird nicht empfohlen, da es inkonsistent oder fehlerhaft sein könnte. Die standardmäßigen TLSv1.3-Cipher-Suites von OpenSSL sind: “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256”

TLSv1.3 unterstützt nur 5 Cipher-Suites:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_CCM_SHA256
• TLS_AES_128_CCM_8_SHA256

Weitere Informationen finden Sie beim Schlüsselwort “bind”.

Beispiel:

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

ssl-default-bind-client-sigalgs <sigalgs>

ssl-default-bind-client-sigalgs <sigalgs>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “bind”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Signaturalgorithmen für die Client-Authentifizierung beschreibt. Das Format ist eine durch Doppelpunkte getrennte Liste von Signaturalgorithmen. Jeder Signaturalgorithmus kann in einer von zwei Formen angegeben werden: als Name eines TLS1.3-Signaturschemas (“rsa_pss_rsae_sha256”) oder als Kombination aus Public-Key-Algorithmus + Digest (“ECDSA+SHA256”). Eine Liste kann beide Formen enthalten. Weitere Informationen zum Format finden Sie unter SSL_CTX_set1_client_sigalgs(3). Eine Liste der Signaturalgorithmen ist außerdem in RFC8446, Abschnitt 4.2.3 , sowie in der OpenSSL-Datei ssl/t1_lib.c verfügbar. Diese Einstellung gilt nicht für TLSv1.1 und frühere Protokollversionen, da die Signaturalgorithmen in diesen Versionen nicht gesondert ausgehandelt werden. Es wird nicht empfohlen, diese Einstellung zu ändern, sofern keine Kompatibilität mit einer Middlebox erforderlich ist.

ssl-default-bind-curves <curves>

ssl-default-bind-curves <curves>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt die standardmäßige Zeichenfolge fest, die die Liste der Algorithmen für elliptische Kurven (“curve suite”) beschreibt, die beim SSL/TLS-Handshake mit ECDHE ausgehandelt werden. Das Format ist eine durch Doppelpunkte getrennte Liste von Kurvennamen. Weitere Informationen finden Sie beim Schlüsselwort “bind”.

ssl-default-bind-options [<option>]...

ssl-default-bind-options [<option>]...

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt standardmäßige ssl-options fest, die für alle “bind”-Zeilen erzwungen werden. Die verfügbaren Optionen finden Sie beim Schlüsselwort “bind”.

Beispiel:

global
   ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets

ssl-default-bind-sigalgs <sigalgs>

ssl-default-bind-sigalgs <sigalgs>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “bind”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Signaturalgorithmen beschreibt, die beim TLSv1.2- und TLSv1.3-Handshake ausgehandelt werden. Das Format ist eine durch Doppelpunkte getrennte Liste von Signaturalgorithmen. Jeder Signaturalgorithmus kann in einer von zwei Formen angegeben werden: als Name eines TLS1.3-Signaturschemas (“rsa_pss_rsae_sha256”) oder als Kombination aus Public-Key-Algorithmus + Digest (“ECDSA+SHA256”). Eine Liste kann beide Formen enthalten. Weitere Informationen zum Format finden Sie unter SSL_CTX_set1_sigalgs(3). Eine Liste der Signaturalgorithmen ist außerdem in RFC8446, Abschnitt 4.2.3 , sowie in der OpenSSL-Datei ssl/t1_lib.c verfügbar. Diese Einstellung gilt nicht für TLSv1.1 und frühere Protokollversionen, da die Signaturalgorithmen in diesen Versionen nicht gesondert ausgehandelt werden. Es wird nicht empfohlen, diese Einstellung zu ändern, sofern keine Kompatibilität mit einer Middlebox erforderlich ist.

ssl-default-server-ciphers <ciphers>

ssl-default-server-ciphers <ciphers>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “server”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Verschlüsselungsalgorithmen beschreibt, die beim SSL/TLS-Handshake bis einschließlich TLSv1.2 mit dem Server ausgehandelt werden. Das Format der Zeichenfolge ist in “man 1 ciphers” der OpenSSL-Handbuchseiten definiert. Hintergrundinformationen und Empfehlungen finden Sie beispielsweise unter (https://wiki.mozilla.org/Security/Server_Side_TLS ) und (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Zur Konfiguration von TLSv1.3-Verschlüsselungsalgorithmen siehe das Schlüsselwort “ssl-default-server-ciphersuites”. Weitere Informationen finden Sie beim Schlüsselwort “server”.

ssl-default-server-ciphersuites <ciphersuites>

ssl-default-server-ciphersuites <ciphersuites>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde und HAProxy mit OpenSSL 1.1.1 oder höher erstellt wurde. Sie legt für alle “server”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Verschlüsselungsalgorithmen beschreibt, die beim TLSv1.3-Handshake mit dem Server ausgehandelt werden. Das Format der Zeichenfolge ist in “man 1 ciphers” der OpenSSL-Handbuchseiten im Abschnitt “ciphersuites” definiert. Zur Konfiguration von Verschlüsselungsalgorithmen für TLSv1.2 und frühere Versionen siehe das Schlüsselwort “ssl-default-server-ciphers”. Weitere Informationen finden Sie beim Schlüsselwort “server”.

ssl-default-server-client-sigalgs <sigalgs>

ssl-default-server-client-sigalgs <sigalgs>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “server”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Signaturalgorithmen für die Client-Authentifizierung beschreibt. Das Format ist eine durch Doppelpunkte getrennte Liste von Signaturalgorithmen. Jeder Signaturalgorithmus kann in einer von zwei Formen angegeben werden: als Name eines TLS1.3-Signaturschemas (“rsa_pss_rsae_sha256”) oder als Kombination aus Public-Key-Algorithmus + Digest (“ECDSA+SHA256”). Eine Liste kann beide Formen enthalten. Weitere Informationen zum Format finden Sie unter SSL_CTX_set1_client_sigalgs(3). Eine Liste der Signaturalgorithmen ist außerdem in RFC8446, Abschnitt 4.2.3 , sowie in der OpenSSL-Datei ssl/t1_lib.c verfügbar. Diese Einstellung gilt nicht für TLSv1.1 und frühere Protokollversionen, da die Signaturalgorithmen in diesen Versionen nicht gesondert ausgehandelt werden. Es wird nicht empfohlen, diese Einstellung zu ändern, sofern keine Kompatibilität mit einer Middlebox erforderlich ist.

ssl-default-server-curves <curves>

ssl-default-server-curves <curves>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt die standardmäßige Zeichenfolge fest, die die Liste der Algorithmen für elliptische Kurven (“curve suite”) beschreibt, die beim SSL/TLS-Handshake mit ECDHE ausgehandelt werden. Das Format ist eine durch Doppelpunkte getrennte Liste von Kurvennamen. Weitere Informationen finden Sie beim Schlüsselwort “server”.

ssl-default-server-options [<option>]...

ssl-default-server-options [<option>]...

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt standardmäßige ssl-options fest, die für alle “server”-Zeilen erzwungen werden. Die verfügbaren Optionen finden Sie beim Schlüsselwort “server”.

ssl-default-server-sigalgs <sigalgs>

ssl-default-server-sigalgs <sigalgs>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “server”-Zeilen ohne eigene ausdrückliche Definition die standardmäßige Zeichenfolge fest, die die Liste der Signaturalgorithmen beschreibt, die beim TLSv1.2- und TLSv1.3-Handshake ausgehandelt werden. Das Format ist eine durch Doppelpunkte getrennte Liste von Signaturalgorithmen. Jeder Signaturalgorithmus kann in einer von zwei Formen angegeben werden: als Name eines TLS1.3-Signaturschemas (“rsa_pss_rsae_sha256”) oder als Kombination aus Public-Key-Algorithmus + Digest (“ECDSA+SHA256”). Eine Liste kann beide Formen enthalten. Weitere Informationen zum Format finden Sie unter SSL_CTX_set1_sigalgs(3). Eine Liste der Signaturalgorithmen ist außerdem in RFC8446, Abschnitt 4.2.3 , sowie in der OpenSSL-Datei ssl/t1_lib.c verfügbar. Diese Einstellung gilt nicht für TLSv1.1 und frühere Protokollversionen, da die Signaturalgorithmen in diesen Versionen nicht gesondert ausgehandelt werden. Es wird nicht empfohlen, diese Einstellung zu ändern, sofern keine Kompatibilität mit einer Middlebox erforderlich ist.

ssl-dh-param-file <file>

ssl-dh-param-file <file>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie legt für alle “bind”-Zeilen ohne eigene ausdrückliche Definition die standardmäßigen DH-Parameter fest, die beim SSL/TLS-Handshake mit ephemerem Diffie-Hellman-Schlüsselaustausch (DHE) verwendet werden. Benutzerdefinierte DH-Parameter in einer bind-Zertifikatsdatei haben, sofern vorhanden, Vorrang. Wenn weder mit ssl-dh-param-file noch direkt in der Zertifikatsdatei benutzerdefinierte DH-Parameter angegeben sind, werden keine DHE-Verschlüsselungsverfahren verwendet, es sei denn, tune.ssl.default-dh-param ist gesetzt. Im letzteren Fall werden vordefinierte DH-Parameter der angegebenen Größe verwendet. Benutzerdefinierte Parameter gelten als sicherer, daher wird ihre Verwendung empfohlen. Sie können mit dem OpenSSL-Befehl “openssl dhparam <size>” erzeugt werden. Dabei sollte die Größe mindestens 2048 betragen, da DH-Parameter mit 1024 Bit nicht mehr als sicher gelten sollten.

ssl-passphrase-cmd <cmd> <args> ...

ssl-passphrase-cmd <cmd> <args> ...

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde. Sie ermöglicht die Definition einer vollständigen Befehlszeile, die aufgerufen wird, wenn während der Initialisierung ein verschlüsseltes Zertifikat geladen wird. Der Befehl kann ein Skript oder ein anderes Programm sein. Er erhält als ersten Parameter den Pfad des verschlüsselten privaten Schlüssels und anschließend die benutzerdefinierten “args”-Parameter. Er sollte die Passphrase zum Entschlüsseln des privaten Schlüssels auf der Standardausgabe ausgeben. Für jeden während der Initialisierung neu geladenen verschlüsselten privaten Schlüssel versucht HAProxy zunächst alle bereits bekannten Passphrasen zur Entschlüsselung und ruft den Passphrasenbefehl erst dann erneut auf, wenn keine davon funktioniert.

ssl-propquery <query>

ssl-propquery <query>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde und die OpenSSL-Version mindestens 3.0 ist. Sie ermöglicht die Definition einer standardmäßigen Eigenschaftszeichenfolge, die beim Abrufen von Algorithmen aus Providern verwendet wird. Sie verhält sich wie die openssl-Option propquery und verwendet dieselbe Syntax (beschrieben unter https://www.openssl.org/docs/man3.0/man7/property.html ). Wenn beispielsweise zwei Provider geladen sind, foo und der Standardprovider, ermöglicht die propquery “?provider=foo”, standardmäßig die vom Provider foo bereitgestellten Algorithmusimplementierungen auszuwählen und auf die des Standardproviders zurückzugreifen, wenn sie nicht gefunden wurden.

ssl-provider <name>

ssl-provider <name>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde und die OpenSSL-Version mindestens 3.0 ist. Sie ermöglicht das Laden eines Providers während der Initialisierung. Bei erfolgreichem Laden kann HAProxy die vom geladenen Provider bereitgestellten Funktionen verwenden. In einer Konfigurationsdatei können mehrere ‘ssl-provider’-Optionen angegeben werden. Die Provider werden in der Reihenfolge ihres Auftretens geladen.

Beachten Sie, dass das explizite Laden eines Providers verhindert, dass OpenSSL den Provider ‘default’ automatisch lädt. OpenSSL erlaubt es auch, die zu ladenden Provider direkt in seiner Konfigurationsdatei (beispielsweise openssl.cnf) festzulegen. Daher ist diese Option ‘ssl-provider’ zum Laden von Providern nicht erforderlich. Mit dem CLI-Befehl “show ssl providers” können alle erfolgreich geladenen Provider angezeigt werden.

Der Standardsuchpfad für OpenSSL-Provider ist in der Ausgabe des Befehls “openssl version -a” zu finden. Befindet sich der Provider in einem anderen Verzeichnis, können Sie die Umgebungsvariable OPENSSL_MODULES auf das Verzeichnis setzen, in dem der Provider liegt.

Siehe auch “ssl-propquery” und “ssl-provider-path”.

ssl-provider-path <path>

ssl-provider-path <path>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für OpenSSL einkompiliert wurde und die OpenSSL-Version mindestens 3.0 ist. Sie ermöglicht die Angabe des Suchpfads, den OpenSSL bei der Suche nach Providern verwenden soll. Sie verhält sich wie die Umgebungsvariable OPENSSL_MODULES. Sie gilt für alle folgenden ‘ssl-provider’-Optionen, bis ein neuer ‘ssl-provider-path’ definiert wird. Siehe auch “ssl-provider”.

ssl-load-extra-del-ext

ssl-load-extra-del-ext

Diese Einstellung konfiguriert, wie HAProxy nach zusätzlichen SSL-Dateien sucht. Standardmäßig fügt HAProxy dem Dateinamen eine neue Erweiterung hinzu (beispielsweise wird für “foobar.crt” die Datei “foobar.crt.key” geladen). Wenn diese Option aktiviert ist, entfernt HAProxy die Erweiterung, bevor es die neue hinzufügt (beispielsweise wird für “foobar.crt” die Datei “foobar.key” geladen).

Die crt-Datei muss die Erweiterung “.crt” haben, damit diese Option funktioniert.

Diese Option ist nicht mit Bundle-Erweiterungen (.ecdsa, .rsa. .dsa) kompatibel und versucht nicht, diese zu entfernen.

Diese Option ist standardmäßig deaktiviert. Siehe auch “ssl-load-extra-files”.

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

Diese Einstellung verändert, wie HAProxy beim Laden von SSL-Zertifikaten nach nicht ausdrücklich angegebenen Dateien sucht. Die Option gilt sowohl für Zertifikate von “bind”-Zeilen als auch für solche von “server”-Zeilen. Einige der zusätzlichen Dateien haben bei Zertifikaten von “server”-Zeilen jedoch keine funktionalen Auswirkungen.

Standardmäßig erkennt HAProxy automatisch zahlreiche Dateien, die nicht in der Konfiguration angegeben sind. Wenn Sie die Startzeit optimieren möchten, können Sie dieses Verhalten deaktivieren.

“none”: Lädt nur die in der Konfiguration angegebenen Dateien. Wenn eine Datei nicht existiert, wird nicht versucht, ein Zertifikatsbundle zu laden. Bei einem Verzeichnis wird nicht versucht, Zertifikate mit demselben Basisnamen zu einem Bundle zusammenzufassen.

“all”: Dies ist das Standardverhalten. Es wird versucht, alles zu laden: Zertifikatsbundles, sctl, ocsp, issuer, key.

“bundle”: Wenn eine in der Konfiguration angegebene Datei nicht existiert, versucht HAProxy, ein “Zertifikatsbundle” zu laden. Zertifikatsbundles werden nur auf der Frontend-Seite verwaltet und funktionieren nicht für Backend-Zertifikate.

Seit HAProxy 2.3 werden die Bundles nicht mehr in denselben OpenSSL-Zertifikatsspeicher geladen. Stattdessen wird jedes Zertifikat in einen eigenen Speicher geladen, was der Angabe mehrerer “crt” entspricht. Dafür ist OpenSSL 1.1.1 erforderlich. Bundles dienen somit nur noch der Abwärtskompatibilität und sind für eine hybride RSA/ECC-bind-Konfiguration nicht mehr erforderlich.

Damit HAProxy diese PEM-Dateien als “Zertifikatsbundle” erkennt, müssen sie wie folgt benannt werden: Alle zu einem Bundle zusammenzufassenden PEM-Dateien müssen denselben Basisnamen und ein Suffix haben, das den Schlüsseltyp angibt. Derzeit werden drei Suffixe unterstützt: rsa, dsa und ecdsa. Wenn beispielsweise www.example.com zwei PEM-Dateien hat, eine RSA-Datei und eine ECDSA-Datei, müssen sie “example.pem.rsa” und “example.pem.ecdsa” heißen. Der erste Teil des Dateinamens ist beliebig; nur das Suffix ist entscheidend. Um dieses Bundle in HAProxy zu laden, geben Sie nur den Basisnamen an:

Beispiel: bind :8443 ssl crt example.pem

Beachten Sie, dass das Suffix nicht an HAProxy übergeben wird. Dadurch wird HAProxy angewiesen, nach einem Zertifikatsbundle zu suchen.

HAProxy lädt alle PEM-Dateien des Bundles so, als wären sie einzeln mit mehreren “crt” konfiguriert worden.

Das Laden von Bundles hat keine Auswirkungen mehr auf das Laden von Verzeichnissen, da die Dateien einzeln geladen werden.

In der CLI werden Bundles als separate Dateien behandelt. Für ihren Commit ist die Bundle-Erweiterung erforderlich.

OCSP-Dateien (.ocsp), Ausstellerdateien (.issuer), Certificate Transparency (.sctl) sowie private Schlüssel (.key) werden beim Bündeln mehrerer Zertifikate unterstützt.

“sctl”: Versucht, für jedes Schlüsselwort crt die Datei “<basename>.sctl” zu laden. Wenn sie für ein Backend-Zertifikat bereitgestellt wird, wird sie zwar geladen, hat aber keine funktionalen Auswirkungen.

“ocsp”: Versucht, für jedes Schlüsselwort crt die Datei “<basename>.ocsp” zu laden. Wenn sie für ein Backend-Zertifikat bereitgestellt wird, wird sie zwar geladen, hat aber keine funktionalen Auswirkungen.

“issuer”: Versucht, die Datei “<basename>.issuer” zu laden, wenn der Aussteller der OCSP-Datei nicht in der PEM-Datei enthalten ist. Wenn sie für ein Backend-Zertifikat bereitgestellt wird, wird sie zwar geladen, hat aber keine funktionalen Auswirkungen.

“key”: Wenn die PEM-Datei keinen privaten Schlüssel enthält, wird versucht, eine Datei “<basename>.key” mit einem privaten Schlüssel zu laden.

Das Standardverhalten ist “all”.

Beispiel:

ssl-load-extra-files bundle sctl
ssl-load-extra-files sctl ocsp issuer
ssl-load-extra-files none

Siehe auch: “crt”, Abschnitt 5.1 zu bind-Optionen und Abschnitt 5.2 zu Serveroptionen.

ssl-security-level <number>

ssl-security-level <number>

Diese Direktive ermöglicht die Auswahl der OpenSSL-Sicherheitsstufe, wie unter https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html beschrieben. Die Sicherheitsstufe wird auf alle SSL-Kontexte in HAProxy angewendet. Es werden nur Werte zwischen 0 und 5 unterstützt.

Der Standardwert hängt von Ihrer OpenSSL-Version, der Distribution und davon ab, wie die Bibliothek kompiliert wurde.

Diese Direktive erfordert mindestens OpenSSL 1.1.1.

ssl-server-verify [none|required]

ssl-server-verify [none|required]

Legt das Standardverhalten für die SSL-Verifizierung auf der Serverseite fest. Bei ’none’ werden Serverzertifikate nicht geprüft. Der Standardwert ist ‘required’, sofern das Verhalten nicht mit der Befehlszeilenoption ‘-dV’ erzwungen wird.

ssl-skip-self-issued-ca

ssl-skip-self-issued-ca

Eine selbstausgestellte CA, auch x509-Root-CA genannt, bildet den Vertrauensanker für die Kettenvalidierung. Sie als Server zu senden ist nutzlos; der Client muss sie bereits besitzen. In einer Standardkonfiguration darf eine solche CA nicht in der PEM-Datei enthalten sein. Mit dieser Option können Sie sie in der PEM-Datei behalten, ohne sie an den Client zu senden. Ein Anwendungsfall ist die Bereitstellung des Ausstellers für ocsp ohne eine ‘.issuer’-Datei, wobei er über ‘issuers-chain-path’ gemeinsam genutzt werden kann. Dies betrifft alle Zertifikate ohne Zwischenzertifikate. Für BoringSSL ist diese Option nutzlos; .issuer wird ignoriert, da die ocsp-Funktionen dies nicht benötigen. Erfordert mindestens OpenSSL 1.0.2.

stats calculate-max-counters [on|off]

stats calculate-max-counters [on|off]

Aktiviert oder deaktiviert die Berechnung der Maximalwertzähler für die Statistik. Wenn Sie diese nicht benötigen, kann ihre Deaktivierung die Leistung etwas erhöhen. Der Standardwert ist on.

stats maxconn <connections>

stats maxconn <connections>

Standardmäßig ist der Statistik-Socket auf 10 gleichzeitige Verbindungen begrenzt. Dieser Wert kann mit “stats maxconn” geändert werden.

stats socket [<address:port>|<path>] [param*]

stats socket [<address:port>|<path>] [param*]

Bindet einen UNIX-Socket an <path> oder eine TCPv4/v6-Adresse an <address:port>. Verbindungen zu diesem Socket liefern verschiedene Statistikausgaben und ermöglichen sogar die Ausführung einiger Befehle, um bestimmte Laufzeiteinstellungen zu ändern. Weitere Einzelheiten finden Sie in Abschnitt 9.3 “Unix-Socket-Befehle” des Verwaltungshandbuchs.

Alle von “bind”-Zeilen unterstützten Parameter werden unterstützt, beispielsweise um den Zugriff auf bestimmte Benutzer zu beschränken oder deren Zugriffsrechte einzuschränken. Weitere Informationen finden Sie in Abschnitt 5.1 .

stats timeout <timeout, in milliseconds>

stats timeout <timeout, in milliseconds>

Die standardmäßige Zeitüberschreitung des Statistik-Sockets beträgt 10 Sekunden. Dieser Wert kann mit “stats timeout” geändert werden. Der Wert muss in Millisekunden angegeben werden oder mit einer Zeiteinheit aus { us, ms, s, m, h, d } versehen sein.

stats-file <path>

stats-file <path>

Pfad zu einer erzeugten haproxy-Statistikdatei. Beim Start lädt haproxy die Werte in seine internen Zähler. Mit dem CLI-Befehl “dump stats-file” wird eine solche Statistikdatei erzeugt. Weitere Einzelheiten finden Sie im Verwaltungshandbuch.

stress-level <level>

stress-level <level>

Aktiviert alternativen Code, um die haproxy-Programmdatei gezielt zu belasten. Die Stufe ist eine ganze Zahl von 0 bis 9. Der Standardwert 0 deaktiviert jede belastende Ausführung. Die Stufen von 1 bis 9 erhöhen den Belastungsdruck auf die haproxy-Programmdatei. Beachten Sie, dass jede positive Stufe die Leistung erheblich beeinträchtigen kann. Daher sollte dies ausschließlich zur Fehlerdiagnose und auf Anforderung eines Entwicklers aktiviert werden.

strict-limits

strict-limits

Lässt den Prozessstart fehlschlagen, wenn ein setrlimit-Aufruf fehlschlägt. HAProxy versucht, auf Grundlage seiner Berechnungen das bestmögliche setrlimit zu setzen. Schlägt dies fehl, wird eine Warnung ausgegeben. Diese Option stellt sicher, dass HAProxy ausdrücklich fehlschlägt, wenn das Setzen dieser Limits scheitert. Sie ist standardmäßig aktiviert. Durch Voranstellen des Schlüsselworts “no” kann sie dennoch ausdrücklich deaktiviert werden.

thread-group <group> [<thread-range>...]

thread-group <group> [<thread-range>...]

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für Threads einkompiliert wurde. Sie führt die Threads auf, aus denen die Thread-Gruppe <group> bestehen soll. Thread- und Gruppennummern beginnen bei 1. Thread-Bereiche werden entweder durch einzelne Thread-Nummern oder durch eine Unter- und Obergrenze angegeben, die durch einen Bindestrich ‘-’ getrennt sind (z. B. “1-16”). Nicht zugewiesene Threads werden automatisch nicht zugewiesenen Thread-Gruppen zugeordnet. Mit dieser Direktive definierte Thread-Gruppen erhalten niemals mehr Threads als angegeben. Wird dieselbe Gruppe mehrfach definiert, überschreibt die neue Definition die vorherigen. Siehe auch “nbthread” und “thread-groups”.

thread-groups <number>

thread-groups <number>

Diese Einstellung ist nur verfügbar, wenn die Unterstützung für Threads einkompiliert wurde. Sie teilt die Threads von HAProxy in <number> unabhängige Gruppen auf. Derzeit ist der Standardwert 1. Mit Thread-Gruppen lässt sich die gemeinsame Nutzung von Ressourcen zwischen Threads verringern, um Konkurrenz zu begrenzen; dies erfordert allerdings etwas zusätzlichen Konfigurationsaufwand. Es ist auch die einzige Möglichkeit, mehr als 64 Threads zu verwenden, da pro Gruppe bis zu 64 Threads konfiguriert werden können. Die maximale Anzahl von Gruppen wird beim Kompilieren festgelegt und beträgt standardmäßig 16. Siehe auch “nbthread”.

thread-hard-limit <number>

thread-hard-limit <number>

Diese Einstellung erzwingt eine Obergrenze für die Anzahl der Threads, unabhängig davon, ob diese ermittelt oder konfiguriert wurde. Dies ist besonders auf Betriebssystemen mit automatischer Ermittlung der Thread-Anzahl nützlich, wenn in allgemeinen und portablen Konfigurationen weniger Threads als CPUs gewünscht sind. Während “nbthread” eine feste Thread-Anzahl erzwingt, die bei Überschreiten der verfügbaren CPUs zu einer Warnung und schlechter Leistung führt, begrenzt thread-hard-limit nur den Höchstwert. Es beschränkt die Thread-Anzahl automatisch auf diesen Wert, erhöht aber niedrigere Werte nicht. Wird “nbthread” auf einen höheren Wert festgelegt, hat thread-hard-limit Vorrang, und eine Warnung wird ausgegeben, damit die Unstimmigkeit in der Konfiguration behoben werden kann. Standardmäßig gibt es keine Begrenzung. Siehe auch “nbthread”.

uid <number>

uid <number>

Ändert die Benutzer-ID des Prozesses auf <number>. Es wird empfohlen, diese Benutzer-ID ausschließlich für HAProxy oder eine kleine Gruppe ähnlicher Daemons zu verwenden. HAProxy muss mit Superuser-Rechten gestartet werden, um zu einer anderen Benutzer-ID wechseln zu können. Siehe auch “gid” und “user”.

ulimit-n <number>

ulimit-n <number>

Setzt die maximale Anzahl von Dateideskriptoren pro Prozess auf <number>. Standardmäßig wird sie automatisch berechnet, weshalb empfohlen wird, diese Option nicht zu verwenden. Wenn lediglich die Anzahl der Dateideskriptoren begrenzt werden soll, verwenden Sie besser “fd-hard-limit”.

Beachten Sie, dass dynamische Server bei dieser automatischen Ressourcenberechnung nicht berücksichtigt werden. Bei einer großen Anzahl solcher Server kann es erforderlich sein, den Wert manuell anzugeben.

Siehe auch: fd-hard-limit, maxconn

unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] [ group <group> ] [ gid <gid> ]

Legt gemeinsame Einstellungen für UNIX-Listener-Sockets fest, die in “bind”-Anweisungen deklariert werden. Dies dient hauptsächlich dazu, die Deklaration dieser UNIX-Sockets zu vereinfachen und das Fehlerrisiko zu verringern, da diese Einstellungen meist erforderlich, aber zugleich prozessspezifisch sind. Mit <prefix> lässt sich erzwingen, dass alle Socket-Pfade relativ zu diesem Verzeichnis angegeben werden. Dies kann für den Zugriff auf die chroot-Umgebung einer anderen Komponente erforderlich sein. Beachten Sie, dass diese Pfade aufgelöst werden, bevor HAProxy selbst chroot ausführt; sie sind daher absolut. <mode>, <user>, <uid>, <group> und <gid> haben dieselbe Bedeutung wie die gleichnamigen Parameter der “bind”-Anweisung. Wenn beide angegeben sind, hat die “bind”-Anweisung Vorrang. Die “unix-bind”-Einstellungen können somit als prozessweite Standardwerte betrachtet werden.

unsetenv [<name> ...]

unsetenv [<name> ...]

Entfernt die als Argumente angegebenen Umgebungsvariablen. Dies kann nützlich sein, um vertrauliche Informationen zu verbergen, die bei bestimmten Vorgängen gelegentlich aus der Umgebung des Benutzers übernommen werden. Nicht vorhandene Variablen werden ohne Meldung ignoriert, sodass nach dem Vorgang sicher keine dieser Variablen mehr vorhanden ist. Die Änderungen werden sofort wirksam, sodass bereits die nächste Zeile in der Konfigurationsdatei diese Variablen nicht mehr sieht. Siehe auch “setenv”, “presetenv” und “resetenv”.

user <user name>

user <user name>

Ähnlich wie “uid”, verwendet jedoch die UID des Benutzernamens <user name> aus /etc/passwd. Siehe auch “uid” und “group”.

node <name>

node <name>

Wie bei DNS-Namen sind nur Buchstaben, Ziffern, Bindestriche und Unterstriche erlaubt.

Diese Anweisung ist in HA-Konfigurationen nützlich, in denen mindestens zwei Prozesse oder Server dieselbe IP-Adresse nutzen. Durch unterschiedliche Knotennamen auf allen Knoten lässt sich sofort erkennen, welcher Server den Datenverkehr verarbeitet.

wurfl-cache-size <size>

wurfl-cache-size <size>

Legt die Größe des WURFL-User-Agent-Caches fest. Für schnellere Abfragen werden bereits verarbeitete User-Agents in einem LRU-Cache vorgehalten:

• “0” : Es wird kein Cache verwendet.
• <size> : Größe des lru-Caches in Elementen.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_WURFL=1 kompiliert wurde.

wurfl-data-file <file path>

wurfl-data-file <file path>

Der Pfad der WURFL-Datendatei zur Bereitstellung von Geräteerkennungsdiensten. Die Datei sollte mit den entsprechenden Berechtigungen für HAProxy zugänglich sein.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_WURFL=1 kompiliert wurde.

wurfl-information-list [<capability>]*

wurfl-information-list [<capability>]*

Eine durch Leerzeichen getrennte Liste von WURFL-Capabilities, virtuellen Capabilities und Eigenschaftsnamen, die in eingefügten Headern verwendet werden sollen. Eine vollständige Liste der Namen von Capabilities und virtuellen Capabilities ist auf der Website von Scientiamobile verfügbar:

https://www.scientiamobile.com/wurflCapability

Gültige WURFL-Eigenschaften sind:

• wurfl_id Enthält die Geräte-ID des gefundenen Geräts.

• wurfl_root_id Enthält die Root-Geräte-ID des gefundenen Geräts.

• wurfl_isdevroot Gibt an, ob das gefundene Gerät ein Root-Gerät ist. Mögliche Werte sind “TRUE” oder “FALSE”.

• wurfl_useragent Der ursprüngliche User-Agent dieser konkreten Webanfrage.

• wurfl_api_version Enthält eine Zeichenfolge, die die aktuell verwendete Libwurfl-API-Version darstellt.

• wurfl_info Eine Zeichenfolge mit Informationen zur eingelesenen wurfl.xml und ihrem vollständigen Pfad.

• wurfl_last_load_time Enthält den UNIX-Zeitstempel des letzten erfolgreichen Ladens von WURFL.

• wurfl_normalized_useragent Der normalisierte User-Agent.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_WURFL=1 kompiliert wurde.

wurfl-information-list-separator <char>

wurfl-information-list-separator <char>

Ein Zeichen, das Werte in einem Antwort-Header mit WURFL-Ergebnissen trennt. Falls es nicht gesetzt ist, wird standardmäßig ein Komma (’,’) verwendet.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_WURFL=1 kompiliert wurde.

wurfl-patch-file [<file path>]

wurfl-patch-file [<file path>]

Eine Liste von Pfaden zu WURFL-Patchdateien. Beachten Sie, dass Patches beim Start und somit vor chroot geladen werden.

Beachten Sie, dass diese Option nur verfügbar ist, wenn HAProxy mit USE_WURFL=1 kompiliert wurde.

3.2. Leistungsoptimierung

busy-polling

busy-polling

In manchen Situationen, insbesondere bei niedrigen Latenzanforderungen auf Prozessoren mit variabler Taktfrequenz oder beim Betrieb in virtuellen Maschinen, geht der Prozessor jedes Mal in den Ruhezustand oder wird für längere Zeit einer anderen VM zugeteilt, wenn der Prozess mit dem Poller auf I/O wartet. Dies verursacht übermäßig hohe Latenzen. Diese Option verhindert, dass der Prozessor in den Ruhezustand wechselt, indem sie für die Poller stets eine Zeitüberschreitung von null verwendet. Dies verringert die Latenz erheblich (beobachtet wurden 30 bis 100 Mikrosekunden), birgt jedoch das Risiko einer Überhitzung des Prozessors. Die Option kann auch mit Threads verwendet werden. In diesem Fall können falsch gebundene Threads stark miteinander konkurrieren, was zu schlechterer Leistung und hohen Werten in den Feldern für entzogene CPU-Zeit in der Ausgabe von “show info” führt; daran lassen sich die falsch konfigurierten Threads erkennen. Bei Verwendung dieser Option darf der Prozess nicht auf demselben Prozessor wie die Netzwerk-Interrupts laufen. Außerdem sollte die Option möglichst nicht auf mehreren CPU-Threads verwendet werden, die sich denselben Kern teilen. Sie ist standardmäßig deaktiviert. Wenn sie aktiviert wurde, kann sie dennoch durch Voranstellen des Schlüsselworts “no” ausdrücklich deaktiviert werden. Die Poller “select” und “poll” ignorieren sie.

Bei einem nahtlosen Neuladen wird diese Option für alte Prozesse automatisch deaktiviert. Dadurch wird übermäßige CPU-Konkurrenz vermieden, wenn mehrere Prozesse noch eine Zeit lang auf das Ende ihrer bestehenden Verbindungen warten.

max-spread-checks <delay in milliseconds>

max-spread-checks <delay in milliseconds>

Standardmäßig versucht HAProxy, den Beginn der Zustandsprüfungen über das kleinste Prüfintervall aller Server einer Serverfarm zu verteilen. Damit soll eine geballte Belastung der auf demselben Server laufenden Dienste vermieden werden. Bei großen Prüfintervallen (10 Sekunden oder mehr) dauert es jedoch einige Zeit, bis die letzten Server der Serverfarm erstmals geprüft werden, was problematisch sein kann. Dieser Parameter erzwingt eine Obergrenze für die Verzögerung zwischen der ersten und der letzten Prüfung, auch wenn die Prüfintervalle der Server größer sind. Kürzere Prüfintervalle der Server werden jedoch weiterhin eingehalten.

maxcompcpuusage <number>

maxcompcpuusage <number>

Legt die maximale CPU-Auslastung fest, die HAProxy erreichen darf, bevor die Komprimierung für neue Anfragen eingestellt oder die Komprimierungsstufe laufender Anfragen verringert wird. Dies funktioniert wie ‘maxcomprate’, misst jedoch die CPU-Auslastung anstelle der Bandbreite eingehender Daten. Der Wert wird als Prozentsatz der von HAProxy genutzten CPU angegeben. Der Wert 100 deaktiviert die Begrenzung. Der Standardwert ist 100. Ein niedrigerer Wert verhindert, dass die Komprimierungsarbeit den gesamten Prozess verlangsamt und hohe Latenzen verursacht.

maxcomprate <number>

maxcomprate <number>

Setzt die maximale Eingaberate für die Komprimierung pro Prozess auf <number> Kilobyte pro Sekunde. Wird das Maximum erreicht, wird die Komprimierungsstufe jedes Streams während seiner Verarbeitung verringert. Ist das Maximum bereits zu Beginn eines Streams erreicht, wird dieser überhaupt nicht komprimiert. Ist das Maximum nicht erreicht, wird die Komprimierungsstufe bis auf tune.comp.maxlevel erhöht. Der Wert null bedeutet, dass es keine Begrenzung gibt; dies ist der Standardwert.

maxconn <number>

maxconn <number>

Setzt die maximale Anzahl gleichzeitiger Verbindungen pro Prozess auf <number>. Dies entspricht dem Befehlszeilenargument “-n”. Der über “-n” angegebene Wert hat Vorrang vor dem im globalen Abschnitt gesetzten maxconn-Wert. Der Haproxy-Prozess kann auch mit der Kompilierungsvariablen SYSTEM_MAXCONN erstellt werden, die dann als systemweiter Höchstwert für maxconn dient. Auch diese Grenze kann zur Laufzeit mit dem Befehlszeilenargument “-n” überschritten werden, falls SYSTEM_MAXCONN gesetzt ist. Proxys nehmen keine weiteren Verbindungen an, sobald maxconn erreicht ist. Das weiche Dateideskriptorlimit des Prozesses (abrufbar mit dem Befehl “ulimit -n”) wird anhand des angegebenen maxconn-Werts automatisch angepasst. Siehe auch “ulimit-n”. Hinweis: Der Poller “select” kann auf einigen Plattformen nicht zuverlässig mehr als 1024 Dateideskriptoren verwenden. Wenn Ihre Plattform nur select unterstützt und beim Start “select FAILED” meldet, müssen Sie maxconn so weit verringern, bis es funktioniert (im Allgemeinen auf etwas unter 500). Wenn maxconn nicht gesetzt ist, wird der Wert anhand der aktuellen Dateideskriptorlimits automatisch berechnet, die der Befehl “ulimit -nH” meldet (verwendet wird der größere der harten und weichen Werte). Anschließend wird der automatische Wert gegebenenfalls durch “fd-hard-limit” und durch ein mit der Befehlszeilenoption “-m” erzwungenes Speicherlimit verringert. Der automatische Wert hängt außerdem von der Puffergröße, dem für die Komprimierung zugewiesenen Speicher, der SSL-Cachegröße sowie der Verwendung von SSL und dem zugehörigen maxsslconn ab (das ebenfalls automatisch bestimmt werden kann).

Siehe auch: fd-hard-limit, ulimit-n

maxconnrate <number>

maxconnrate <number>

Setzt die maximale Anzahl von Verbindungen pro Sekunde und Prozess auf <number>. Proxys nehmen keine weiteren Verbindungen an, sobald diese Grenze erreicht ist. Damit lässt sich die Gesamtkapazität unabhängig von der Kapazität jedes einzelnen Frontends begrenzen. Beachten Sie, dass dies nur als Schutzmaßnahme für den Dienst eingesetzt werden kann: Bei Erreichen der Grenze ist eine faire Aufteilung zwischen den Frontends nicht unbedingt gewährleistet. Daher ist es sinnvoll, jedes Frontend zusätzlich auf einen Wert nahe seinem erwarteten Anteil zu begrenzen. Auch eine Verringerung von tune.maxaccept kann die Verteilung gerechter machen.

maxpipes <number>

maxpipes <number>

Setzt die maximale Anzahl von Pipes pro Prozess auf <number>. Derzeit werden Pipes nur für kernelbasiertes TCP-Splicing verwendet. Da eine Pipe zwei Dateideskriptoren enthält, wird der Wert von “ulimit-n” entsprechend erhöht. Der Standardwert ist maxconn/4, was selbst für die meisten hohen Belastungen mehr als ausreichend erscheint. Der Splice-Code weist Pipes dynamisch zu, gibt sie wieder frei und kann auf normales Kopieren zurückfallen. Ein zu niedriger Wert kann daher lediglich die Leistung beeinträchtigen.

maxsessrate <number>

maxsessrate <number>

Setzt die maximale Anzahl von Sitzungen pro Sekunde und Prozess auf <number>. Proxys nehmen keine weiteren Verbindungen an, sobald diese Grenze erreicht ist. Damit lässt sich die Gesamtkapazität unabhängig von der Kapazität jedes einzelnen Frontends begrenzen. Beachten Sie, dass dies nur als Schutzmaßnahme für den Dienst eingesetzt werden kann: Bei Erreichen der Grenze ist eine faire Aufteilung zwischen den Frontends nicht unbedingt gewährleistet. Daher ist es sinnvoll, jedes Frontend zusätzlich auf einen Wert nahe seinem erwarteten Anteil zu begrenzen. Auch eine Verringerung von tune.maxaccept kann die Verteilung gerechter machen.

maxsslconn <number>

maxsslconn <number>

Setzt die maximale Anzahl gleichzeitiger SSL-Verbindungen pro Prozess auf <number>. Standardmäßig gibt es keine SSL-spezifische Begrenzung; die globale Einstellung maxconn gilt somit für alle Verbindungen. Diese Begrenzung verhindert, dass openssl zu viel Speicher verwendet und abstürzt, wenn malloc NULL zurückgibt (da dieser Fall leider nicht zuverlässig geprüft wird). Beachten Sie, dass die Grenze sowohl für eingehende als auch für ausgehende Verbindungen gilt. Eine Verbindung, die entschlüsselt und anschließend wieder verschlüsselt wird, zählt daher als 2 SSL-Verbindungen. Wenn dieser Wert nicht gesetzt ist, aber ein Speicherlimit erzwungen wird, wird er automatisch anhand des Speicherlimits, von maxconn, der Puffergröße, des für die Komprimierung zugewiesenen Speichers, der SSL-Cachegröße und der Verwendung von SSL in Frontends, Backends oder beiden berechnet. Wenn bei vorhandenem Speicherlimit weder maxconn noch maxsslconn angegeben sind, passt HAProxy diese Werte automatisch so an, dass 100% der Verbindungen gefahrlos über SSL erfolgen können. Dabei werden die Seiten berücksichtigt, auf denen SSL aktiviert ist (Frontend, Backend oder beide).

maxsslrate <number>

maxsslrate <number>

Setzt die maximale Anzahl von SSL-Sitzungen pro Sekunde und Prozess auf <number>. SSL-Listener nehmen keine weiteren Verbindungen an, sobald diese Grenze erreicht ist. Damit lässt sich die gesamte SSL-CPU-Auslastung unabhängig von der Kapazität jedes einzelnen Frontends begrenzen. Beachten Sie, dass dies nur als Schutzmaßnahme für den Dienst eingesetzt werden kann: Bei Erreichen der Grenze ist eine faire Aufteilung zwischen den Frontends nicht unbedingt gewährleistet. Daher ist es sinnvoll, jedes Frontend zusätzlich auf einen Wert nahe seinem erwarteten Anteil zu begrenzen. Beachten Sie außerdem, dass Sitzungen vor dem Eintritt in den SSL-Stack gezählt werden, nicht danach. Dies schützt den Stack auch vor fehlerhaften Handshakes. Auch eine Verringerung von tune.maxaccept kann die Verteilung gerechter machen.

maxzlibmem <number>

maxzlibmem <number>

Legt die maximale Menge an RAM in Megabyte fest, die zlib pro Prozess verwenden darf. Sobald diese Menge erreicht ist, werden neue Streams nicht komprimiert, solange kein RAM verfügbar ist. Bei 0 gibt es keine Begrenzung. Der Standardwert ist 0. Der Wert kann in Byte über den UNIX-Socket mit “show info” in der Zeile “MaxZlibMemUsage” abgefragt werden; der von zlib verwendete Speicher wird unter “ZlibMemUsage” ebenfalls in Byte angezeigt.

no-memory-trimming

no-memory-trimming

Deaktiviert das Freigeben ungenutzten Speichers (“malloc_trim”) zu den wenigen Zeitpunkten, an denen versucht wird, große Speichermengen zurückzugewinnen (bei Speichermangel oder beim Neuladen). Dabei wird der Speicherzuweiser des Systems gezwungen, alle ungenutzten Bereiche zu durchsuchen und freizugeben. Dies gilt im Allgemeinen als sinnvolle Maßnahme, um einem neuen Prozess mehr Speicher zu überlassen, den der alte voraussichtlich kaum noch nutzen wird. Auf einigen Systemen mit Zehntausenden bis Hunderttausenden gleichzeitigen Verbindungen kann jedoch starke Speicherfragmentierung auftreten, wodurch die Freigabe extrem lange dauert. Währenddessen fließt kein Datenverkehr mehr durch den Prozess, neue Verbindungen werden nicht mehr angenommen, einige Zustandsprüfungen können sogar fehlschlagen, und der Watchdog kann den nicht reagierenden Prozess beenden, wodurch ein riesiges Speicherabbild entsteht. Falls dies auftritt, wird empfohlen, mit dieser Option die Speicherbereinigung zu deaktivieren und nicht länger zu versuchen, dem neuen Prozess Speicher zu überlassen. Fortschrittliche Speicherzuweiser sind von diesem Problem normalerweise nicht betroffen.

noepoll

noepoll

Deaktiviert die Verwendung des Ereignisabfragesystems “epoll” unter Linux. Dies entspricht dem Befehlszeilenargument “-de”. Als nächstes Abfragesystem wird im Allgemeinen “poll” verwendet. Siehe auch “nopoll”.

noevports

noevports

Deaktiviert die Verwendung des Ereignisabfragesystems event ports auf SunOS-Systemen, die von Solaris 10 oder höher abgeleitet sind. Dies entspricht dem Befehlszeilenargument “-dv”. Als nächstes Abfragesystem wird im Allgemeinen “poll” verwendet. Siehe auch “nopoll”.

nogetaddrinfo

nogetaddrinfo

Deaktiviert die Verwendung von getaddrinfo(3) zur Namensauflösung. Dies entspricht dem Befehlszeilenargument “-dG”. Stattdessen wird das veraltete gethostbyname(3) verwendet.

nokqueue

nokqueue

Deaktiviert die Verwendung des Ereignisabfragesystems “kqueue” unter BSD. Dies entspricht dem Befehlszeilenargument “-dk”. Als nächstes Abfragesystem wird im Allgemeinen “poll” verwendet. Siehe auch “nopoll”.

noktls

noktls

Deaktiviert die Verwendung von ktls. Dies entspricht dem Befehlszeilenargument “-dT”.

nopoll

nopoll

Deaktiviert die Verwendung des Ereignisabfragesystems “poll”. Dies entspricht dem Befehlszeilenargument “-dp”. Als nächstes Abfragesystem wird “select” verwendet. Es sollte niemals erforderlich sein, “poll” zu deaktivieren, da es auf allen von HAProxy unterstützten Plattformen verfügbar ist. Siehe auch “nokqueue”, “noepoll” und “noevports”.

noreuseport

noreuseport

Deaktiviert die Verwendung von SO_REUSEPORT; siehe socket(7). Dies entspricht dem Befehlszeilenargument “-dR”.

nosplice

nosplice

Deaktiviert kernelbasiertes TCP-Splicing zwischen Sockets unter Linux. Dies entspricht dem Befehlszeilenargument “-dS”. Daten werden dann mit herkömmlichen und portableren recv/send-Aufrufen kopiert. Kernelbasiertes TCP-Splicing ist auf einige sehr neue Varianten des Kernels 2.6 beschränkt. Die meisten Versionen zwischen 2.6.25 und 2.6.28 sind fehlerhaft und leiten beschädigte Daten weiter; sie dürfen daher nicht verwendet werden. Diese Option erleichtert es, Kernel-Splicing im Zweifelsfall global zu deaktivieren. Siehe auch “option splice-auto”, “option splice-request” und “option splice-response”.

profiling.memory { on | off }

profiling.memory { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Speicherprofilierung pro Funktion. Dabei werden Nutzungsstatistiken der malloc/calloc/realloc/free-Aufrufe im gesamten Prozess einschließlich der Bibliotheken erfasst und über den CLI-Befehl “show profiling” ausgegeben. Dies ist vor allem für Fälle gedacht, in denen eine ungewöhnliche Speichernutzung beobachtet wird, die sich nicht durch die Pools erklären lässt, und weitere Informationen benötigt werden. Die Leistungseinbuße liegt typischerweise bei etwa 1%, auf Rechnern mit vielen Threads möglicherweise etwas höher; daher eignet sich dies normalerweise für den Produktionseinsatz. Dasselbe lässt sich zur Laufzeit mit dem CLI-Befehl “set profiling memory” erreichen; siehe das Verwaltungshandbuch.

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

Aktiviert (‘on’) oder deaktiviert (‘off’) die CPU-Profilierung pro Task. Bei ‘auto’ wird die Profilierung auf einem Thread automatisch aktiviert, sobald dessen durchschnittliche Latenz im Aktivitätsfeld “avg_loop_us” 1000 Mikrosekunden oder mehr erreicht. Sie wird automatisch deaktiviert, wenn die Latenz wieder unter 990 Mikrosekunden fällt (dieser Wert ist ein Mittelwert über die letzten 1024 Schleifendurchläufe, verändert sich also nicht schnell und glättet kurze Spitzen deutlich). Die Profilierung kann sich auf überlasteten Systemen, in Containern oder virtuellen Maschinen auch gelegentlich von selbst aktivieren, ebenso wenn das System auslagert (was auf einem Load-Balancer unter keinen Umständen geschehen darf).

Bei aktivierter Task-Profilierung kann HAProxy zusätzlich erfassen, wie lange jeder Task eine Sperre hält oder auf eine Sperre wartet, sowie die Wartezeit auf eine erfolgreiche Speicherzuweisung bei einem Cache-Miss im Pool. Dies kann helfen, bestimmte Latenzursachen zu verstehen. Dazu können zusätzlich die Schlüsselwörter “lock” (Erfassung von Sperrzeiten aktivieren), “no-lock” (deaktivieren), “memory” (Erfassung der Speicherzuweisungszeiten aktivieren) oder “no-memory” (deaktivieren) angegeben werden. Standardmäßig sind diese nicht aktiviert, da sie auf stark ausgelasteten Systemen einen nicht unerheblichen CPU-Aufwand verursachen können (3-10%). Beachten Sie, dass dieser Zusatzaufwand nur entsteht, wenn die Profilierung tatsächlich läuft. Im Modus “auto” tritt er somit nur auf, wenn HAProxy die Profilierung aktiviert.

Die CPU-Profilierung pro Task kann sehr hilfreich sein, um festzustellen, wofür Zeit aufgewendet wird und welche Anfragen welche Auswirkungen auf andere Anfragen haben. Ihre Aktivierung beeinträchtigt die Gesamtleistung typischerweise um weniger als 1%. Daher wird empfohlen, den Standardwert ‘auto’ beizubehalten, sodass sie nur arbeitet, wenn ein Problem erkannt wird. Diese Funktion erfordert ein System, das den Systemaufruf clock_gettime(2) mit den Uhrenkennungen CLOCK_MONOTONIC und CLOCK_THREAD_CPUTIME_ID unterstützt; andernfalls beträgt die gemeldete Zeit null. Diese Option kann zur Laufzeit mit “set profiling” in der CLI geändert werden.

spread-checks <0..50, in percent>

spread-checks <0..50, in percent>

Manchmal ist es sinnvoll, Agenten- und Zustandsprüfungen nicht in exakt gleichmäßigen Abständen an Server zu senden, beispielsweise wenn sich viele logische Server auf demselben physischen Server befinden. Mit diesem Parameter kann dem Prüfintervall eine zufällige Abweichung zwischen 0 und +/- 50% hinzugefügt werden. Werte zwischen 2 und 5 scheinen gute Ergebnisse zu liefern. Der Standardwert bleibt 0.

ssl-engine <name> [algo <comma-separated list of algorithms>]

ssl-engine <name> [algo <comma-separated list of algorithms>]

Setzt die OpenSSL-Engine auf <name>. Eine Liste gültiger Werte für <name> erhalten Sie mit dem Befehl “openssl engine”. Diese Anweisung kann mehrfach verwendet werden; dadurch werden mehrere Kryptografie-Engines aktiviert. Die Angabe einer nicht unterstützten Engine verhindert den Start von HAProxy. Beachten Sie, dass viele Engines eine niedrigere HTTPS-Leistung liefern als reine Software auf modernen Prozessoren. Der optionale Befehl “algo” legt mit der OPENSSL-Funktion ENGINE_set_default_string() die Standardalgorithmen fest, die eine ENGINE bereitstellt. Der Wert “ALL” verwendet die Engine für sämtliche kryptografischen Operationen. Wird keine algo-Liste angegeben, wird “ALL” verwendet. Es kann eine durch Kommas getrennte Liste verschiedener Algorithmen angegeben werden, darunter RSA, DSA, DH, EC, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. Dies ist dasselbe Format wie in der openssl-Konfigurationsdatei: https://www.openssl.org/docs/man1.0.2/apps/config.html

Mit HAProxy Version 2.6 wurde die Engine-Unterstützung im Standard-Build deaktiviert. Diese Option ist nur verfügbar, wenn HAProxy mit entsprechender Unterstützung erstellt wurde. Falls ssl-engine benötigt wird, kann HAProxy mit dem Flag USE_ENGINE=1 neu kompiliert werden.

ssl-mode-async

ssl-mode-async

Fügt dem SSL-Kontext den Modus SSL_MODE_ASYNC hinzu. Dies ermöglicht asynchrone TLS-I/O-Operationen, wenn SSL-Engines mit entsprechender Unterstützung verwendet werden. Die aktuelle Implementierung unterstützt maximal 32 Engines. Die Openssl-ASYNC-API unterstützt keine verschiebbaren Lese-/Schreibpuffer und ist nicht mit der Pufferverwaltung von HAProxy vereinbar. Daher ist der asynchrone Modus für Lese-/Schreiboperationen deaktiviert (er ist nur während des anfänglichen Handshakes und bei Handshakes zur Neuverhandlung aktiviert).

tune.applet.zero-copy-forwarding { on | off }

tune.applet.zero-copy-forwarding { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die kopierfreie Datenweiterleitung für Applets. Sie ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding.

tune.buffers.limit <number>

tune.buffers.limit <number>

Legt eine harte Obergrenze für die Anzahl der Puffer fest, die pro Prozess zugewiesen werden dürfen. Der Standardwert ist null und bedeutet unbegrenzt. Die Grenze wird automatisch so angepasst, dass die für Notfälle reservierten Puffer berücksichtigt werden; der Benutzer muss daher keine komplizierten Berechnungen durchführen. Das Erzwingen dieses Werts kann besonders nützlich sein, um den Speicherverbrauch eines Prozesses zu begrenzen und zugleich ein vernünftiges Verhalten beizubehalten. Wird diese Grenze erreicht, wartet ein Task, der einen Puffer anfordert, zunächst auf die Freigabe eines anderen Puffers. Solange die Grenzen sinnvoll gewählt sind, ist die Wartezeit meist sehr kurz und nicht wahrnehmbar. Einige historische Einschränkungen haben diesen Mechanismus jedoch über mehrere Versionen hinweg geschwächt. Es ist bekannt, dass manche Tasks bei anhaltendem Mangel in bestimmten Situationen bis zum Ablauf ihrer Zeitüberschreitung blockieren können. Daher ist es sicherer, diese Einstellung nur zu verwenden, wenn sie unbedingt erforderlich ist.

tune.buffers.reserve <number>

tune.buffers.reserve <number>

Legt die Anzahl der Puffer pro Thread fest, die vorab zugewiesen und ausschließlich für Situationen mit Speichermangel reserviert werden, in denen Speicherzuweisungen fehlschlagen. Der Mindestwert ist 0, der Standardwert 4. Es gibt keinen Grund für Benutzer, diesen Wert zu ändern, sofern nicht ein Entwickler des Kernteams dies aus einem sehr speziellen Grund empfiehlt.

tune.bufsize <size>

tune.bufsize <size>

Setzt die Puffergröße auf diesen Wert (in Byte). Niedrigere Werte ermöglichen mehr gleichzeitige Streams bei derselben RAM-Menge, höhere Werte ermöglichen den Betrieb einiger Anwendungen mit sehr großen Cookies. Der Standardwert ist 16384 und kann beim Kompilieren geändert werden. Es wird dringend empfohlen, den Standardwert beizubehalten: Sehr niedrige Werte führen dazu, dass einige Dienste wie die Statistikfunktion nicht mehr funktionieren, während höhere Werte den Speicherverbrauch erhöhen und möglicherweise den gesamten verfügbaren Systemspeicher aufbrauchen. Zumindest der globale Parameter maxconn sollte um denselben Faktor verringert werden, um den dieser Wert erhöht wird. Außerdem erfordert HTTP/2 einen Wert von mindestens 16384. Der Wert muss außerdem unter 256 MB (268435456 Byte) liegen. Ist der Headerblock einer HTTP-Anfrage größer als (tune.bufsize - tune.maxrewrite), gibt HAProxy den Fehler HTTP 400 (Bad Request) zurück. Ist entsprechend der Headerblock einer HTTP-Antwort größer als dieser Wert, gibt HAProxy HTTP 502 (Bad Gateway) zurück. Beachten Sie, dass der mit diesem Parameter gesetzte Wert auf 32-Bit-Rechnern automatisch auf das nächste Vielfache von 8 und auf 64-Bit-Rechnern auf das nächste Vielfache von 16 aufgerundet wird. Siehe auch: tune.bufsize.large, tune.bufsize.small.

tune.bufsize.large <size>

tune.bufsize.large <size>

Legt die Größe großer Puffer in Byte fest. Standardmäßig ist die Unterstützung großer Puffer nicht aktiviert; sie muss ausdrücklich durch Setzen dieses Werts aktiviert werden.

Diese Puffer sind für bestimmte Situationen vorgesehen, in denen mehr Daten gepuffert werden müssen, ohne die Größe regulärer Puffer zu ändern. Große Puffer werden nicht implizit verwendet. Siehe auch: tune.bufsize.

Beachten Sie, dass bei konfigurierten großen Puffern beim Start für jeden Thread drei spezielle große Puffer zur internen Verwendung zugewiesen werden.

tune.bufsize.small <size>

tune.bufsize.small <size>

Legt die Größe kleiner Puffer in Byte fest. Der Standardwert ist 1024.

Diese Puffer sind für bestimmte Situationen vorgesehen, in denen der Speicherverbrauch begrenzt ist, die Zuweisung eines vollständigen Puffers jedoch unnötig erscheint. Falls ein kleiner Puffer nicht ausreicht, wird automatisch eine erneute Zuweisung durchgeführt, um auf einen Puffer der Standardgröße zu wechseln.

Derzeit verwendet nur das HTTP/3-Protokoll kleine Puffer automatisch, um die Antwort-Header zu senden. Ansonsten kann ihre Unterstützung für bestimmte Proxys über die Option “use-small-buffers” aktiviert werden. Siehe auch: tune.bufsize.

Siehe auch: option use-small-buffers

tune.cli.max-payload-size <size>

tune.cli.max-payload-size <size>

Legt die maximal zulässige Größe der Nutzdaten fest, die einem Befehl in der CLI übergeben werden.

In der CLI ist eine Befehlszeile durch die Puffergröße begrenzt. Alle Befehle und ihre Argumente müssen daher zur Verarbeitung in einen Puffer passen. Ausgenommen sind die Nutzdaten, die dem letzten Befehl der Befehlszeile übergeben werden können. Für diese Nutzdaten kann bei Bedarf ein eigener Speicherbereich zugewiesen werden. Ihre Größe wird durch diesen Parameter begrenzt. Der Standardwert ist 128KB.

Obwohl dieser Wert für die meisten Anwendungen ausreichen sollte, muss ein neuer Wert bei einer Änderung sorgfältig gewählt werden. Ein sehr hoher Wert kann die Leistung von HAProxy beeinträchtigen. Je nach Befehl kann die Verarbeitung sehr großer Nutzdaten lange dauern und möglicherweise den Watchdog auslösen.

Einzelheiten zur CLI finden Sie im Verwaltungshandbuch.

tune.comp.maxlevel <number>

tune.comp.maxlevel <number>

Legt die maximale Komprimierungsstufe fest. Die Komprimierungsstufe beeinflusst die CPU-Auslastung während der Komprimierung. Dieser Wert beeinflusst die CPU-Auslastung während der Komprimierung. Jeder Stream mit Komprimierung initialisiert den Komprimierungsalgorithmus mit diesem Wert. Der Standardwert ist 1.

tune.defaults.purge

tune.defaults.purge

Zur Unterstützung dynamischer Backends bleiben nun alle benannten defaults-Abschnitte nach dem Einlesen im Speicher. Dies ist erforderlich, da ein zur Laufzeit hinzugefügtes Backend seine Konfiguration auf einem benannten defaults-Abschnitt aufbauen muss.

Bei vielen defaults-Instanzen kann dies erheblichen Speicher beanspruchen. Wenn die Funktion für dynamische Backends nicht benötigt wird, kann in diesem Fall mit dieser Option das Löschen der defaults-Abschnitte nach dem Einlesen erzwungen werden. Referenzierte defaults-Abschnitte müssen jedoch weiterhin erhalten bleiben, wenn sie Einstellungen enthalten, die von den referenzierenden Proxys nicht kopiert werden können. Dies ist beispielsweise der Fall, wenn der defaults-Abschnitt TCP/HTTP-Regeln oder einen tcpcheck-Regelsatz definiert.

tune.disable-fast-forward

tune.disable-fast-forward

Deaktiviert die schnelle Datenweiterleitung. Dieser Mechanismus optimiert die Weiterleitung, indem Daten direkt von einer Seite zur anderen übertragen werden, ohne den Stream aufzuwecken. Mit dieser Direktive kann die Optimierung deaktiviert werden. Beachten Sie, dass dadurch auch jegliches kernelbasierte TCP-Splicing sowie die kopierfreie Weiterleitung deaktiviert werden. Dieser Befehl ist nicht für den regulären Einsatz vorgesehen und wird im Allgemeinen nur von Entwicklern bei komplexen Fehlerdiagnosen empfohlen.

tune.disable-zero-copy-forwarding

tune.disable-zero-copy-forwarding

Deaktiviert die kopierfreie Datenweiterleitung global. Dieser Mechanismus optimiert die schnelle Datenweiterleitung, indem er die Verwendung des Kanalpuffers vermeidet. Mit dieser Direktive kann die Optimierung deaktiviert werden. Beachten Sie, dass dadurch auch jegliches kernelbasierte TCP-Splicing deaktiviert wird.

Siehe auch: tune.pt.zero-copy-forwarding, tune.applet.zero-copy-forwarding, tune.h1.zero-copy-fwd-recv, tune.h1.zero-copy-fwd-send, tune.h2.zero-copy-fwd-send, tune.quic.zero-copy-fwd-send

tune.epoll.mask-events <event[,...]>

tune.epoll.mask-events <event[,...]>

Im Laufe der Entwicklung von HAProxy traten einige komplexe Probleme auf, die durch Fehler im epoll-Mechanismus des Linux-Kernels verursacht wurden. Diese Probleme sind üblicherweise sehr selten und außerhalb der Umgebung des Meldenden nicht reproduzierbar. Sie lassen sich mitunter nur umgehen, indem epoll deaktiviert und stattdessen poll verwendet wird, was für Hochleistungsumgebungen nicht zufriedenstellend ist. Die Probleme betreffen jeweils nur sehr spezielle und seltene Ereignistypen. Eine Möglichkeit, diese zu maskieren, kann daher eine akzeptablere Umgehungslösung bieten. Diese Option erlaubt es, einige ungewöhnliche Ereignisse ohne Meldung zu ignorieren und durch ein Eingabeereignis zu ersetzen, das ein nicht näher bestimmtes eingehendes Ereignis meldet. Dadurch werden an bestimmten Stellen die schnellen Fehlerverarbeitungspfade vermieden und nur die üblichen Verarbeitungspfade verwendet. Dies sollte niemals verwendet werden, sofern nicht ein Experte zur Diagnose oder Umgehung eines Kernel-Fehlers dazu auffordert.

Die Option erwartet ein einziges Argument: eine durch Kommas getrennte Liste von Wörtern, die jeweils ein zu maskierendes Ereignis bezeichnen. Derzeit werden folgende Ereignisse unterstützt: - “err”: maskiert das Ereignis EPOLLERR - “hup”: maskiert EPOLLHUP-Ereignisse - “rdhup”: maskiert EPOLLRDHUP-Ereignisse

Beispiel:

# mask all non-traffic epoll events:
tune.epoll.mask-events err,hup,rdhup

tune.events.max-events-at-once <number>

tune.events.max-events-at-once <number>

Legt die Anzahl von Ereignissen fest, die ein asynchroner Task-Handler (aus der event_hdl-API) auf einmal verarbeiten darf. <number> sollte zwischen 1 und 10000 liegen. Ein hoher Wert kann durch die ununterbrochene, umfangreiche Arbeit des Tasks zu Konkurrenz zwischen Threads führen. Ein niedriger Wert kann dagegen dazu führen, dass der Task ständig neu eingeplant wird, weil er pro Durchlauf nicht genügend Ereignisse verarbeiten kann und mit dem Ereigniserzeuger nicht Schritt hält. Der Standardwert kann beim Kompilieren festgelegt werden; andernfalls beträgt er 100.

tune.fail-alloc

tune.fail-alloc

Wenn mit DEBUG_FAIL_ALLOC kompiliert oder mit “-dMfail” gestartet wurde, gibt dies die prozentuale Wahrscheinlichkeit an, mit der ein Zuweisungsversuch fehlschlägt. Der Wert muss zwischen 0 (keine Fehlschläge) und 100 (keine Erfolge) liegen. Dies ist zur Fehlerdiagnose nützlich und stellt sicher, dass Fehler bei der Speicherzuweisung angemessen behandelt werden. Ohne Einstellung beträgt der Anteil 0. Die Befehlszeilenoption “-dMfail” setzt ihn jedoch automatisch auf eine Fehlerquote von 1%, sodass zum Testen keine Konfigurationsänderung erforderlich ist.

tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]

tune.fd.edge-triggered { on | off }  [ EXPERIMENTAL ]

Aktiviert (‘on’) oder deaktiviert (‘off’) den flankengesteuerten Abfragemodus für FDs, die ihn unterstützen. Derzeit wird dies nur mit epoll unterstützt. Es kann die Anzahl der epoll_ctl()-Aufrufe deutlich verringern und in bestimmten Szenarien die Leistung leicht verbessern. Die Funktion ist noch experimentell, kann bei verbleibenden Fehlern zum Stillstand von Verbindungen führen und ist standardmäßig deaktiviert.

tune.glitches.kill.cpu-usage <number>

tune.glitches.kill.cpu-usage <number>

Legt die minimale CPU-Auslastung zwischen 0 und 100 fest, ab der Verbindungen mit zu vielen Unregelmäßigkeiten beendet werden. Dies gilt für Verbindungen, die ihre glitches-threshold-Grenze erreicht haben. In Umgebungen, in denen sehr lange bestehende Verbindungen häufig fehlerhaftes Verhalten zeigen, ohne die Leistung zu beeinträchtigen, kann es sinnvoll sein, sie trotz dieses Verhaltens beizubehalten, solange sie keinen Schaden verursachen, und sie erst bei zunehmender CPU-Auslastung zu beenden. Dieser Parameter legt fest, dass eine Verbindung, die ihre Unregelmäßigkeitsschwelle erreicht, aktiv beendet wird, wenn die CPU-Auslastung mindestens diesen Wert erreicht, niemals jedoch darunter. Beachten Sie, dass die CPU-Auslastung pro Thread gemessen wird, sodass auch eine einzelne fehlerhaft arbeitende Verbindung beendet werden kann. Der Standardwert ist null; eine Verbindung wird dann beim Erreichen ihrer glitches-threshold-Grenze automatisch beendet. Als Faustregel kann der Wert auf das Doppelte der üblichen CPU-Auslastung oder auf die übliche CPU-Auslastung zuzüglich der Hälfte des ungenutzten Anteils gesetzt werden (wenn die CPU üblicherweise 60% erreicht, kann hier beispielsweise 80 sinnvoll sein). Dieser Parameter hat ohne tune.h2.fe.glitches-threshold, tune.quic.fe.sec.glitches-threshold oder tune.h1.fe.glitches-threshold keine Wirkung. Siehe auch die globalen Parameter “tune.h2.fe.glitches-threshold”, “tune.h1.fe.glitches-threshold” und “tune.quic.fe.sec.glitches-threshold”.

tune.h1.be.glitches-threshold <number>

tune.h1.be.glitches-threshold <number>

Legt die Schwelle für die Anzahl von Unregelmäßigkeiten auf einer HTTP/1-Backend-Verbindung fest, nach deren Überschreiten die Verbindung automatisch beendet wird. Dadurch lassen sich fehlerhaft arbeitende Verbindungen automatisch beenden, ohne dafür explizite Regeln schreiben zu müssen. Der Standardwert ist null: Es wird keine Schwelle gesetzt, sodass kein Ereignis zum Schließen einer Verbindung führt. Typische Ereignisse sind fehlerhaft formatierte Header, die dennoch durch “accept-unsafe-violations-in-http-response” akzeptiert wurden. Ein von null verschiedener Wert sollte vermutlich im Hunderter- oder Tausenderbereich liegen, um wirksam zu sein, ohne Server mit geringfügigen Fehlern zu beeinträchtigen. Mit “tune.glitches.kill.cpu-usage” können Verbindungen auch erst dann beendet werden, wenn die CPU-Auslastung einen bestimmten Wert überschreitet. Beachten Sie, dass bei 75% der konfigurierten Schwelle ein geordnetes Schließen versucht wird, indem auf den Verbindungsmodus zum Schließen umgeschaltet und gegebenenfalls “Connection: close” angekündigt wird. Dadurch wird eine leicht fehlerhafte Verbindung nach einiger Zeit nicht mehr verwendet, ohne laufende Übertragungen zu gefährden.

Siehe auch: tune.h1.fe.glitches-threshold, bc_glitches und tune.glitches.kill.cpu-usage

tune.h1.fe.glitches-threshold <number>

tune.h1.fe.glitches-threshold <number>

Legt die Schwelle für die Anzahl von Unregelmäßigkeiten auf einer HTTP/1-Frontend-Verbindung fest, nach deren Überschreiten die Verbindung automatisch beendet wird. Dadurch lassen sich fehlerhaft arbeitende Verbindungen automatisch beenden, ohne dafür explizite Regeln schreiben zu müssen. Der Standardwert ist null: Es wird keine Schwelle gesetzt, sodass kein Ereignis zum Schließen einer Verbindung führt. Typische Ereignisse sind fehlerhaft formatierte Header, die dennoch durch “accept-unsafe-violations-in-http-request” akzeptiert wurden. Ein von null verschiedener Wert sollte vermutlich im Hunderter- oder Tausenderbereich liegen, um wirksam zu sein, ohne Clients mit geringfügigen Fehlern zu beeinträchtigen. Mit “tune.glitches.kill.cpu-usage” können Verbindungen auch erst dann beendet werden, wenn die CPU-Auslastung einen bestimmten Wert überschreitet. Beachten Sie, dass bei 75% der konfigurierten Schwelle ein geordnetes Schließen versucht wird, indem auf den Verbindungsmodus zum Schließen umgeschaltet und gegebenenfalls “Connection: close” angekündigt wird. Dadurch kann ein Client mit geringfügigen Protokollabweichungen eine neue Verbindung aufbauen und unbeeinträchtigt weiterarbeiten, ohne jemals ein hartes Schließen auszulösen und damit laufende Übertragungen zu gefährden.

Siehe auch: tune.h1.be.glitches-threshold, fc_glitches und tune.glitches.kill.cpu-usage

tune.h1.zero-copy-fwd-recv { on | off }

tune.h1.zero-copy-fwd-recv { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) den kopierfreien Datenempfang für den H1-Multiplexer. Er ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-send

tune.h1.zero-copy-fwd-send { on | off }

tune.h1.zero-copy-fwd-send { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) das kopierfreie Senden von Daten für den H1-Multiplexer. Es ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-recv

tune.h2.be.glitches-threshold <number>

tune.h2.be.glitches-threshold <number>

Legt die Schwelle für die Anzahl von Unregelmäßigkeiten auf einer Backend-Verbindung fest, bei deren Erreichen die Verbindung automatisch beendet wird. Dadurch lassen sich fehlerhaft arbeitende Verbindungen automatisch beenden, ohne dafür explizite Regeln schreiben zu müssen. Der Standardwert ist null: Es wird keine Schwelle gesetzt, sodass kein Ereignis zum Schließen einer Verbindung führt. Beachten Sie, dass manche H2-Server auf lange bestehenden Verbindungen gelegentlich einige Unregelmäßigkeiten verursachen können. Ein von null verschiedener Wert sollte daher vermutlich im Hunderter- oder Tausenderbereich liegen, um wirksam zu sein, ohne Server mit geringfügigen Fehlern zu beeinträchtigen. Mit “tune.glitches.kill.cpu-usage” können Verbindungen auch erst dann beendet werden, wenn die CPU-Auslastung einen bestimmten Wert überschreitet. Beachten Sie, dass bei 75% der konfigurierten Schwelle ein geordnetes Schließen versucht wird, indem ein GOAWAY für einen zukünftigen Stream angekündigt wird. Dadurch wird eine leicht fehlerhafte Verbindung nach einiger Zeit nicht mehr verwendet, ohne laufende Übertragungen zu gefährden.

Siehe auch: tune.h2.fe.glitches-threshold, bc_glitches und tune.glitches.kill.cpu-usage

tune.h2.be.initial-window-size <number>

tune.h2.be.initial-window-size <number>

Legt die anfängliche HTTP/2-Fenstergröße für ausgehende Verbindungen fest, also die Anzahl von Bytes, die der Server als Antwort senden kann, bevor er auf eine Bestätigung von HAProxy warten muss. Diese Einstellung betrifft nur Nutzdaten, keine Header. Ohne Einstellung gilt der gemeinsame Standardwert von tune.h2.initial-window-size. Eine leichte Erhöhung kann sinnvoll sein, um schnellere Downloads zu ermöglichen oder die CPU-Auslastung der Server zu verringern, geht jedoch zulasten einer fairen Verteilung zwischen den Clients. Besser ist die Verwendung von tune.h2.be.rxbuf, das keine solche Ungleichverteilung verursacht. Die Einstellung hat keinen Einfluss auf den Ressourcenverbrauch.

Siehe auch: tune.h2.initial-window-size.

tune.h2.be.max-concurrent-streams <number>

tune.h2.be.max-concurrent-streams <number>

Legt die maximale Anzahl gleichzeitiger HTTP/2-Streams pro ausgehender Verbindung fest (also die Anzahl ausstehender Anfragen auf einer einzelnen Verbindung zu einem Server). Ohne Einstellung gilt der Standardwert von tune.h2.max-concurrent-streams. Ein kleinerer Wert als der Standardwert 100 kann die Reaktionsfähigkeit einer Website verbessern, erfordert jedoch mehr bestehende Verbindungen zu den Servern. Wenn “http-reuse” auf “always” gesetzt ist, wird empfohlen, diesen Wert zu verringern, damit nicht zu viele verschiedene Clients dieselbe Verbindung nutzen. Ist ein Client langsamer als andere, führt ein als “Head-of-Line-Blocking” bekannter Mechanismus häufig zu einem Kaskadeneffekt auf die Downloadgeschwindigkeit aller Clients, die sich die Verbindung teilen (halten Sie tune.h2.be.initial-window-size in diesem Fall niedrig). Es wird dringend empfohlen, diesen Wert nicht zu erhöhen; für manche Anwendungen können niedrige Werte optimal sein (typischerweise 1..5).

tune.h2.be.max-frames-at-once <number>

tune.h2.be.max-frames-at-once <number>

Legt die maximale Anzahl eingehender HTTP/2-Frames fest, die auf einer Backend-Verbindung auf einmal verarbeitet werden. Bei sehr großen Puffern kann ein niedriger Wert (einige zehn bis einige hundert) sinnvoll sein, um geringe Latenz und eine gerechtere Verteilung zwischen mehreren Verbindungen zu gewährleisten. Der Standardwert ist null, das heißt, es wird keine Begrenzung erzwungen.

tune.h2.be.rxbuf <size>

tune.h2.be.rxbuf <size>

Legt die Größe des HTTP/2-Empfangspuffers für ausgehende Verbindungen in Byte fest. Die Größe wird auf das nächste Vielfache von tune.bufsize aufgerundet und von allen Streams gemeinsam genutzt, die Daten hochladen (sowohl HEADERS- als auch DATA-Frames). Jeder Stream erhält in jedem Fall einen Puffer. Außerdem werden 7/8 der ungenutzten Puffer unter den Streams aufgeteilt, die Nutzdaten herunterladen. Dadurch lässt sich die Upload-Leistung deutlich verbessern und Head-of-Line-Blocking (HoL) auf Backend-Verbindungen vermeiden, die bei “always” für http-reuse von mehreren Clients gemeinsam genutzt werden. Das pro Stream angekündigte Fenster wird automatisch an den verfügbaren Platz angepasst, sodass es in der Praxis nicht nötig sein sollte, tune.h2.be.initial-window-size zu ändern. Wird weniger als die für alle Streams erforderliche Größe gesetzt, wird dieses Minimum verwendet. Der Standardwert beträgt etwa 1600k (100 Streams mit jeweils 16kB großen Puffern).

Siehe auch: tune.h2.be.initial-window-size, tune.h2.fe.rxbuf, http-reuse.

tune.h2.fe.glitches-threshold <number>

tune.h2.fe.glitches-threshold <number>

Legt die Schwelle für die Anzahl von Unregelmäßigkeiten auf einer Frontend-Verbindung fest, bei deren Erreichen die Verbindung automatisch beendet wird. Dadurch lassen sich fehlerhaft arbeitende Verbindungen automatisch beenden, ohne dafür explizite Regeln schreiben zu müssen. Der Standardwert ist null: Es wird keine Schwelle gesetzt, sodass kein Ereignis zum Schließen einer Verbindung führt. Beachten Sie, dass manche H2-Clients auf lange bestehenden Verbindungen gelegentlich einige Unregelmäßigkeiten verursachen können. Ein von null verschiedener Wert sollte daher vermutlich im Hunderter- oder Tausenderbereich liegen, um wirksam zu sein, ohne Clients mit geringfügigen Fehlern zu beeinträchtigen. Mit “tune.glitches.kill.cpu-usage” können Verbindungen auch erst dann beendet werden, wenn die CPU-Auslastung einen bestimmten Wert überschreitet. Beachten Sie, dass bei 75% der konfigurierten Schwelle ein geordnetes Schließen versucht wird, indem ein GOAWAY für einen zukünftigen Stream angekündigt wird. Dadurch kann ein Client mit geringfügigen Protokollabweichungen eine neue Verbindung aufbauen und unbeeinträchtigt weiterarbeiten, ohne jemals ein hartes Schließen auszulösen und damit laufende Übertragungen zu gefährden.

Siehe auch: tune.h2.be.glitches-threshold, fc_glitches und tune.glitches.kill.cpu-usage

tune.h2.fe.initial-window-size <number>

tune.h2.fe.initial-window-size <number>

Legt die anfängliche HTTP/2-Fenstergröße für eingehende Verbindungen fest, also die Anzahl von Bytes, die der Client hochladen kann, bevor er auf eine Bestätigung von HAProxy warten muss. Diese Einstellung betrifft nur Nutzdaten (also den Body von POST-Anfragen), keine Header. Ohne Einstellung gilt der gemeinsame Standardwert von tune.h2.initial-window-size. Eine Erhöhung kann sinnvoll sein, um schnellere Uploads zu ermöglichen. Der Standardwert entspricht tune.bufsize (16384) und ermöglicht pro Stream eine Bandbreite von mindestens 1.25 Mbps bei 100 ms Ping-Zeit sowie 125 Mbps bei 1 ms Ping-Zeit. Die Einstellung hat keinen Einfluss auf den Ressourcenverbrauch. Zu hohe Werte können dazu führen, dass Clients eine schlechtere Reaktionsfähigkeit erleben, wenn Seiten parallel zu großen Uploads abgerufen werden. Besser ist die Verwendung von tune.h2.fe.rxbuf, das keine Ungleichverteilung verursacht.

Siehe auch: tune.h2.initial-window-size.

tune.h2.fe.max-concurrent-streams <number> [args...]

tune.h2.fe.max-concurrent-streams <number> [args...]

Legt die maximale Anzahl gleichzeitiger HTTP/2-Streams pro eingehender Verbindung fest (also die Anzahl ausstehender Anfragen auf einer einzelnen Verbindung von einem Client). Ohne Einstellung gilt der Standardwert von tune.h2.max-concurrent-streams. Ein höherer Wert als der Standardwert 100 kann die Ladezeit komplexer Websites mit vielen kleinen Objekten über Netzwerke mit hoher Latenz gelegentlich etwas verbessern. Er kann aber auch den Speicherverbrauch erhöhen, da ein Client mehr Ressourcen auf einmal zuweisen kann. Der Standardwert 100 ist im Allgemeinen gut geeignet; es wird empfohlen, ihn nicht zu ändern. Eine höhere Parallelität beeinflusst außerdem die Verarbeitungslast und Latenz bei einer großen Anzahl von Verbindungen, die jeweils viele Streams verwenden, und kann Denial-of-Service-Angriffe erleichtern. Der Befehl unterstützt nach der Zahl folgende optionale Argumente:

• rq-load { <number> | auto | ignore }:

Mit dem optionalen Argument "rq-load" kann die angekündigte Anzahl
gleichzeitiger Streams dynamisch an die Auslastung der Ausführungswarteschlange
des ausführenden Threads angepasst werden: Solange die Auslastung des
Threads unter dem angegebenen Schwellenwert bleibt, wird das konfigurierte
Stream-Limit angekündigt. Steigt die Thread-Auslastung über das konfigurierte
Limit, wird das angekündigte Stream-Limit proportional zum Quadrat des
Überschreitungsverhältnisses verringert. Zielauslastungen zwischen 50 und
100 bewirken bei hoher Last in der Regel eine sehr gute Drosselung.
Alternativ zu einer expliziten Zahl akzeptiert das Schlüsselwort "ignore"
als Standardwert: Dabei wird die Auslastung der Ausführungswarteschlange
des Threads bei der Drosselung des angekündigten Stream-Limits nicht
berücksichtigt. Mit "auto" wird das Limit auf den Wert von
"tune.runqueue-depth" gesetzt, was in der Regel ohne weitere Anpassungen
der Konfiguration gute Ergebnisse liefert.

• min <number>:

Dies legt bei Verwendung von rq-load die mindestens angekündigte Anzahl
gleichzeitiger Streams fest, selbst wenn dadurch die konfigurierte
Zielauslastung überschritten wird. So bleibt eine Website auch bei sehr
hoher Last gut reaktionsfähig. Mindest- und Standardwert ist 1; Werte zwischen
5 und 15 können jedoch die Benutzererfahrung verbessern.

Beispiel:

tune.h2.fe.max-concurrent-streams 100 rq-load auto min 15

tune.h2.fe.max-frames-at-once <number>

tune.h2.fe.max-frames-at-once <number>

Legt die maximale Anzahl eingehender HTTP/2-Frames fest, die auf einer Frontend-Verbindung auf einmal verarbeitet werden. Bei sehr großen Puffern kann ein niedriger Wert (einige zehn bis einige hundert) sinnvoll sein, um geringe Latenz und eine gerechtere Verteilung zwischen mehreren Verbindungen zu gewährleisten. Der Standardwert ist null, das heißt, es wird keine Begrenzung erzwungen.

tune.h2.fe.max-rst-at-once <number>

tune.h2.fe.max-rst-at-once <number>

Legt die maximale Anzahl eingehender HTTP/2-RST_STREAM-Frames fest, die auf einer Frontend-Verbindung auf einmal verarbeitet werden. Sobald die angegebene Anzahl von RST_STREAM-Frames empfangen wurde, wird der Verbindungshandler in eine Warteschlange mit niedriger Priorität gestellt und nach allen anderen Tasks verarbeitet. Ein sehr niedriger Wert (1 oder einige wenige) kann sinnvoll sein, um die Auswirkungen von RST_STREAM-Fluten deutlich zu verringern. RST_STREAM tritt auch auf, wenn ein Benutzer auf die Stopp-Schaltfläche seines Browsers klickt. Die wenigen zusätzlichen Millisekunden durch das erneute Einreihen sind jedoch im Allgemeinen nicht wahrnehmbar, verringern aber gewöhnlich die durch solche Fluten verursachte Last erheblich. Der Standardwert ist null, das heißt, es wird keine Begrenzung erzwungen.

tune.h2.fe.max-total-streams <number>

tune.h2.fe.max-total-streams <number>

Legt die maximale Gesamtanzahl von HTTP/2-Streams fest, die pro eingehender Verbindung verarbeitet werden. Sobald diese Grenze erreicht ist, sendet HAProxy einen GOAWAY-Frame zum geordneten Schließen. Dieser informiert den Client darüber, dass die Verbindung geschlossen wird, sobald alle ausstehenden Streams geschlossen wurden. In der Praxis schließen Clients die Verbindung nach Empfang dieser Meldung meist so schnell wie möglich und bauen für weitere Anfragen eine neue auf. Dies ist in Situationen nützlich und erwünscht, in denen Clients sehr lange verbunden bleiben und ein Ungleichgewicht innerhalb einer Serverfarm verursachen. In manchen hochdynamischen Umgebungen werden beispielsweise zusätzliche Load-Balancer während des Betriebs instanziiert, um auf zunehmende Last zu reagieren. Wenn die Last wieder abnimmt, sollen sie beendet werden, ohne bestehende Verbindungen abzubrechen. Eine hier gesetzte Grenze beschränkt die Lebensdauer der Verbindungen und sorgt für ihre häufige Erneuerung. Einige neue Verbindungen können dabei zu anderen Knoten aufgebaut werden, sodass bestehende Ressourcen schnell freigegeben werden.

Beachten Sie den impliziten Zusammenhang zwischen dieser Grenze und “tune.h2.fe.max-concurrent-streams” oben. HAProxy akzeptiert stets die Verarbeitung möglicherweise ausstehender Streams, die sich noch auf dem Weg zwischen Client und Frontend befinden. Daher wird die angekündigte Grenze automatisch um den für max-concurrent-streams konfigurierten Wert erhöht. Dieser erhöhte Wert dient als harte Grenze; überschreitet ein nicht protokollkonformer Client sie, wird die Verbindung geschlossen. Beim Zählen der Anfragen pro Verbindung anhand der Protokolle kann daher je nach Geschwindigkeit, mit der der Client Streams erzeugt, jeder Wert zwischen max-total-streams und (max-total-streams + max-concurrent-streams) auftreten.

Der Standardwert ist null und erzwingt keine zusätzliche Grenze über die vom Protokoll vorgegebene hinaus (2^30 ~= 1.07 Milliarden). Werte um 1000 können bereits eine häufige Erneuerung der Verbindungen bewirken, ohne bei den meisten Clients eine wahrnehmbare Latenz zu verursachen. Ein zu niedriger Wert kann durch häufige TLS-Neuverbindungen die CPU-Auslastung erhöhen und zusätzlich die Ladezeit von Seiten verlängern. Beachten Sie, dass einige Lasttestwerkzeuge keine Neuverbindungen unterstützen und mit dieser Einstellung Fehler melden können. Daher kann es erforderlich sein, sie bei Leistungsmessungen zu deaktivieren. Siehe auch “tune.h2.fe.max-concurrent-streams”.

tune.h2.fe.rxbuf <size>

tune.h2.fe.rxbuf <size>

Legt die Größe des HTTP/2-Empfangspuffers für eingehende Verbindungen in Byte fest. Die Größe wird auf das nächste Vielfache von tune.bufsize aufgerundet und von allen Streams gemeinsam genutzt, die Daten hochladen (sowohl HEADERS- als auch DATA-Frames). Jeder Stream erhält in jedem Fall einen Puffer. Außerdem werden 7/8 der ungenutzten Puffer unter den Streams aufgeteilt, die Nutzdaten hochladen, wodurch sich die Upload-Leistung deutlich verbessern lässt. Das pro Stream angekündigte Fenster wird automatisch an den verfügbaren Platz angepasst, sodass es in der Praxis nicht nötig sein sollte, tune.h2.fe.initial-window-size zu ändern. Wird weniger als die für alle Streams erforderliche Größe gesetzt, wird dieses Minimum verwendet. Der Standardwert 1600k (100 Streams mit jeweils 16kB großen Puffern) ermöglicht einem Client mit einer RTT von 100ms ungefähr 130 Mbps Uploadgeschwindigkeit.

Siehe auch: tune.h2.fe.initial-window-size und tune.h2.be.rxbuf.

tune.h2.header-table-size <number>

tune.h2.header-table-size <number>

Legt die Größe der dynamischen HTTP/2-Headertabelle fest. Der Standardwert beträgt 4096 Byte; der Wert darf nicht größer als 65536 Byte sein. Ein höherer Wert kann es bestimmten Clients je nach ihren Fähigkeiten ermöglichen, kompaktere Anfragen zu senden. Diese Speichermenge wird für jede HTTP/2-Verbindung benötigt. Es wird empfohlen, den Wert nicht zu ändern.

tune.h2.initial-window-size <number>

tune.h2.initial-window-size <number>

Legt den Standardwert für die anfängliche HTTP/2-Fenstergröße sowohl eingehender als auch ausgehender Verbindungen fest. Dieser Wert gilt für eingehende Verbindungen, wenn tune.h2.fe.initial-window-size nicht gesetzt ist, und für ausgehende Verbindungen, wenn tune.h2.be.initial-window-size nicht gesetzt ist. Er dient sowohl als Anfangswert als auch als Mindestwert pro Stream. Der Standardwert beträgt 16384 (tune.bufsize). Für Uploads ermöglicht dies pro Stream ungefähr mindestens 1.25 Mbps Bandbreite über ein Netzwerk mit 100 ms Ping-Zeit beziehungsweise 125 Mbps über ein lokales Netzwerk mit 1 ms. Wenn innerhalb der durch tune.h2.be.rxbuf und tune.h2.fe.rxbuf festgelegten Grenzen weniger als die maximale Anzahl von Empfangspuffern verwendet wird, werden ungenutzte Puffer unter den empfangenden Streams aufgeteilt. Daher gibt es normalerweise keinen Grund, diese Standardeinstellung zu ändern. Da eine Änderung des Standardwerts sowohl die Uploadgeschwindigkeit erhöht als auch die Downloadkapazität ungerechter zwischen den Clients verteilt, wird empfohlen, stattdessen die seitenspezifischen Einstellungen tune.h2.fe.initial-window-size und tune.h2.be.initial-window-size zu verwenden.

tune.h2.log-errors { none | connection | stream }

tune.h2.log-errors { none | connection | stream }

Legt fest, welche Fehler im H2-Demultiplexer einen Protokolleintrag erzeugen. Der Standardwert ist “stream”: Jeder beim Dekodieren im Demultiplexer auftretende Fehler führt zu einem Protokolleintrag. Der Wert “connection” bedeutet, dass nur Fehler protokolliert werden, die die Verbindung ungültig machen. “none” bedeutet schließlich, dass kein Dekodierfehler protokolliert wird. Es wird empfohlen, mindestens “connection” einzustellen, um Protokollabweichungen zu erkennen, auch wenn in schwierigen Phasen vorübergehend auf “none” umgeschaltet werden muss.

tune.h2.max-concurrent-streams <number>

tune.h2.max-concurrent-streams <number>

Legt den Standardwert für die maximale Anzahl gleichzeitiger HTTP/2-Streams pro Verbindung fest (also die Anzahl ausstehender Anfragen auf einer einzelnen Verbindung). Dieser Wert gilt für eingehende Verbindungen, wenn tune.h2.fe.max-concurrent-streams nicht gesetzt ist, und für ausgehende Verbindungen, wenn tune.h2.be.max-concurrent-streams nicht gesetzt ist. Der Standardwert ist 100. Die Auswirkungen unterscheiden sich je nach Seite; Einzelheiten finden Sie daher bei den beiden oben genannten Einstellungen. Es wird empfohlen, diese Einstellung nicht zu verwenden und stattdessen zu den seitenspezifischen Einstellungen zu wechseln. Der Wert null deaktiviert die Begrenzung, sodass ein einzelner Client so viele Streams erzeugen kann, wie HAProxy zuweisen kann. Es wird dringend empfohlen, diesen Wert nicht zu ändern.

tune.h2.max-frame-size <number>

tune.h2.max-frame-size <number>

Legt die maximale HTTP/2-Framegröße fest, die HAProxy seinen Peers als akzeptierte Empfangsgröße ankündigt. Der Standardwert ist der größere Wert aus 16384 und der Puffergröße (tune.bufsize). HAProxy kündigt in keinem Fall Unterstützung für Frames an, die größer als seine Puffer sind. Diese Einstellung dient hauptsächlich dazu, bei großen Puffern die maximale Framegröße begrenzen zu können. Zu große Frames können die Leistung beeinträchtigen oder bei einigen Peers fehlerhaftes Verhalten auslösen. Es wird dringend empfohlen, diesen Wert nicht zu ändern.

tune.h2.zero-copy-fwd-send { on | off }

tune.h2.zero-copy-fwd-send { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) das kopierfreie Senden von Daten für den H2-Multiplexer. Es ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding

tune.http.cookielen <number>

tune.http.cookielen <number>

Legt die maximale Länge erfasster Cookies fest. Dies ist der höchste Wert, den “capture cookie xxx len yyy” annehmen darf; jeder höhere Wert wird automatisch auf diesen gekürzt. Der Wert sollte keinesfalls zu hoch gesetzt werden, da bei jeder Cookie-Erfassung unabhängig vom konfigurierten Wert stets diese Größe zugewiesen wird (alle verwenden denselben Pool). Dieser Wert gilt jeweils für Anfrage und Antwort, sodass pro Verbindung das Doppelte dieses Werts an Speicher zugewiesen wird. Ohne Angabe ist die Grenze auf 63 Zeichen gesetzt. Es wird empfohlen, diesen Wert nicht zu ändern.

tune.http.logurilen <number>

tune.http.logurilen <number>

Legt die maximale Länge der Anfrage-URI in Protokollen fest. Dadurch lässt sich verhindern, dass lange Anfrage-URIs mit wertvollen Abfragezeichenfolgen in Protokollzeilen abgeschnitten werden. Dies hängt nicht mit Syslog-Grenzen zusammen. Wenn Sie diese Grenze erhöhen, können Sie auch den Parameter ’log … len yyy’ erhöhen. Ihr Syslog-Daemon benötigt möglicherweise ebenfalls spezielle Konfigurationsdirektiven. Der Standardwert ist 1024.

tune.http.maxhdr <number>

tune.http.maxhdr <number>

Legt die maximale Anzahl von Headern fest, die in empfangenen HTTP-Nachrichten erlaubt ist. Enthält eine Nachricht mehr Header als dieser Wert (einschließlich der ersten Zeile), wird sie bei einer Anfrage mit dem Statuscode “400 Bad Request” beziehungsweise bei einer Antwort mit “502 Bad Gateway” abgelehnt. Der Standardwert ist 101 und reicht für alle Anwendungsfälle aus, da der weit verbreitete Apache-Server dieselbe Grenze verwendet. Es kann sinnvoll sein, die Grenze vorübergehend zu erhöhen, damit eine fehlerhafte Anwendung bis zu ihrer Korrektur funktioniert. Der zulässige Bereich ist 1..32767. Beachten Sie, dass jeder zusätzliche Header pro Stream 32 Bit Speicher benötigt; setzen Sie die Grenze daher nicht zu hoch.

HTTP/1.1 ist ein Textprotokoll, weshalb beim Senden einer Nachricht keine besondere Begrenzung gilt. Die Begrenzung beim Einlesen der Nachricht genügt. HTTP/2 und HTTP/3 sind Binärprotokolle und erfordern einen Kodierungsschritt. Auch beim Kodieren der Header wird eine Grenze gesetzt, um die Beschränkungen dieser Protokolle einzuhalten. Diese Grenze ist ausreichend hoch, wird aber absichtlich nicht dokumentiert. Aus demselben Grund gilt dieselbe Grenze auch bei den ersten Schritten der Dekodierung.

tune.idle-pool.shared { full | on | off }

tune.idle-pool.shared { full | on | off }

Steuert die gemeinsame Nutzung von Pools ungenutzter Verbindungen zu demselben Server durch mehrere Threads. Sie kann für alle Threads derselben Thread-Gruppe aktiviert werden (‘on’), für alle Threads aktiviert werden (‘full’) oder deaktiviert werden (‘off’). Standardmäßig werden die Pools innerhalb derselben Thread-Gruppe gemeinsam genutzt (‘on’), um die Anzahl dauerhafter Verbindungen zu einem Server zu minimieren und die Wiederverwendungsrate zu optimieren. Die gemeinsame Nutzung mit Threads anderer Thread-Gruppen kann die Leistung beeinträchtigen und ist standardmäßig nicht aktiviert. Sie kann aber sinnvoll sein, wenn eine möglichst hohe Verbindungswiederverwendung Priorität hat. Zur Fehlerdiagnose oder bei Verdacht auf einen Fehler in HAProxy bei der Wiederverwendung von Verbindungen kann es hilfreich sein, die gemeinsame Nutzung dieser Pools durch mehrere Threads ausdrücklich zu deaktivieren und die Option auf “off” zu setzen. Es wird dringend davon abgeraten, diese Option zu deaktivieren, ohne für alle Server, die zur Erzielung hoher Leistung auf Verbindungswiederverwendung angewiesen sind, einen konservativen Wert für “pool-low-conn” zu setzen. Andernfalls können Verbindungen mit zunehmender Thread-Anzahl sehr häufig geschlossen werden.

tune.idletimer <timeout>

tune.idletimer <timeout>

Legt die Zeitspanne fest, nach der HAProxy davon ausgeht, dass ein leerer Puffer wahrscheinlich zu einem inaktiven Stream gehört. Dies dient dazu, einige Paketgrößen optimal anzupassen, wenn abwechselnd große und kleine Datenmengen weitergeleitet werden. Der Parameter beeinflusst die Entscheidung, splice() zu verwenden oder große Puffer über SSL zu senden. Der Wert wird in Millisekunden zwischen 0 und 65535 angegeben. Der Wert null bedeutet, dass HAProxy nicht versucht, inaktive Streams zu erkennen. Der Standardwert ist 1000 und scheint Pausen von Endbenutzern korrekt zu erkennen (beispielsweise das Lesen einer Seite vor einem Klick). Es sollte keinen Grund geben, diesen Wert zu ändern. Siehe tune.ssl.maxrecord weiter unten.

tune.listener.default-shards { by-process | by-thread | by-group }

tune.listener.default-shards { by-process | by-thread | by-group }

Normalerweise erzeugt jede “bind”-Zeile einen einzigen Shard, also einen Socket, an dem alle Threads des Prozesses lauschen. Bei vielen Threads ist dies nicht sehr effizient und kann im Kernel erheblichen Aufwand beim Aktualisieren des Abfragestatus oder beim Verteilen von Ereignissen auf die verschiedenen Threads verursachen. Moderne Betriebssysteme unterstützen die Verteilung eingehender Verbindungen: Mehrere Sockets dürfen an dieselbe Adresse und denselben Port gebunden werden, und alle eingehenden Verbindungen werden gleichmäßig auf diese Sockets verteilt. Jeder Thread sieht dadurch nur die Verbindungen, die in dem Socket warten, an den er gebunden ist. Dies verringert den Aufwand im Kernel erheblich und verbessert die Leistung bei der Verarbeitung eingehender Verbindungen. In HAProxy wird dies üblicherweise über “shards” in “bind”-Zeilen aktiviert. Der Standardwert ist 1, sodass jeder Listener im Prozess nur einmal vorhanden ist. Auf Systemen mit vielen Prozessoren kann es bequemer sein, den Standardwert auf “by-thread” zu setzen, um stets einen Listener-Socket pro Thread zu erzeugen, oder auf “by-group”, um stets einen Listener-Socket pro Thread-Gruppe zu erzeugen. Achten Sie bei “by-thread” auf den Dateideskriptorverbrauch, da jeder Listener so viele Sockets benötigt, wie Threads vorhanden sind. Einige Betriebssysteme (z. B. FreeBSD) erlauben außerdem höchstens 256 Sockets an derselben Adresse. “by-group” entspricht bei Standardkonfigurationen mit einer einzigen Thread-Gruppe weiterhin “by-process”. Auf Systemen ohne Unterstützung dieses Mechanismus wird auf die gemeinsame Nutzung desselben Sockets zurückgefallen. Der Standardwert ist “by-group”, mit Rückfall auf “by-process” für Systeme oder Socket-Familien, die keine Mehrfachbindungen unterstützen.

tune.listener.multi-queue { on | fair | off }

tune.listener.multi-queue { on | fair | off }

Aktiviert (‘on’ / ‘fair’) oder deaktiviert (‘off’) die Annahme von Verbindungen über mehrere Warteschlangen am Listener. Dabei wird eingehender Datenverkehr auf alle Threads verteilt, auf denen eine “bind”-Zeile laufen darf, anstatt ihn vollständig selbst zu übernehmen. Dies sorgt für eine gleichmäßigere Verteilung des Datenverkehrs und skaliert deutlich besser, insbesondere wenn Threads aufgrund externer Aktivitäten ungleich ausgelastet sein können (beispielsweise wenn Netzwerk-Interrupts mit einem Thread konkurrieren). Der Standardmodus “on” optimiert die Thread-Auswahl, indem innerhalb einer Stichprobe der Thread mit den wenigsten Verbindungen gewählt wird. Dies ist bei langlebigen Verbindungen häufig die beste Wahl, da so alle Threads beschäftigt bleiben. Der zweite Modus “fair” durchläuft dagegen alle Threads unabhängig von ihrer momentanen Auslastung. Er kann für kurzlebige Verbindungen besser geeignet sein oder auf Rechnern mit sehr vielen Threads, auf denen die Wahrscheinlichkeit gering ist, im ersten Modus den am wenigsten ausgelasteten Thread zu finden. Schließlich lässt sich der Umverteilungsmechanismus mit “off” ausdrücklich deaktivieren, etwa zur Fehlerdiagnose oder bei kurzlebigen Verbindungen, wenn das Betriebssystem bereits eine ausreichend gute Verteilung bereitstellt. Der Standardwert ist “on”.

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

Gibt haproxy ausdrücklich vor, wie seine Sample-Objekte bei der Übergabe an Lua behandelt werden sollen. Wenn beispielsweise native Konverter, Sample-Fetches oder Variablen aus einem Lua-Skript verwendet werden, konvertiert haproxy den internen smp-Typ in den entsprechenden Lua-Typ. Aufgrund der historischen Implementierung gibt es Unklarheiten beim Umgang mit booleschen Werten: Bei der Konvertierung Lua -> haproxy smp bleiben boolesche Werte korrekt erhalten, bei haproxy smp -> Lua wurden sie dagegen irrtümlich in Ganzzahlen umgewandelt. Ein Sample-Fetch oder Konverter mit booleschem Rückgabewert gab bei Verwendung aus Lua daher die Ganzzahl 0 oder 1 zurück. In Lua sind boolesche Werte und Ganzzahlen jedoch nicht austauschbar. Um Mehrdeutigkeiten zu vermeiden, muss “tune.lua.bool-sample-conversion” deshalb ausdrücklich auf “normal” (Aufgabe des historischen Verhaltens zugunsten besserer Konsistenz) oder “pre-3.1-bug” (Erzwingen des historischen Verhaltens, damit die Logik bestehender Skripte nicht fehlerhaft arbeitet) gesetzt werden. Wenn die Option nicht ausdrücklich gesetzt ist und ein Lua-Skript aus der Konfiguration geladen wird, gibt haproxy eine Warnung aus und verwendet implizit “pre-3.1-bug”, um das historische Verhalten beizubehalten. Es wird empfohlen, diese Option auf “normal” zu setzen, nachdem sichergestellt wurde, dass die verwendeten Lua-Skripte boolesche haproxy-Samples korrekt als boolesche Werte behandeln.

Diese Einstellung muss vor jeder “lua-load”- oder “lua-load-per-thread”-Direktive gesetzt werden, damit sie berücksichtigt wird; andernfalls wird sie ignoriert.

tune.lua.burst-timeout <timeout>

tune.lua.burst-timeout <timeout>

Das Ausführungszeitlimit “burst” gilt für jeden Lua-Handler. Wenn der Handler vor Erreichen des Limits weder fertig wird noch die Ausführung abgibt, wird er abgebrochen. Dies verhindert Thread-Konkurrenz, eine zu lange Unterbrechung der Datenverkehrsverarbeitung und letztlich einen Prozessabsturz durch den Watchdog. Anders als andere Lua-Zeitlimits, die die Laufzeit über mehrere durch Yield unterbrochene Ausführungsphasen aufsummieren, stellt burst-timeout sicher, dass die Zeit in einem einzelnen Lua-Ausführungsfenster das konfigurierte Limit nicht überschreitet.

Yield bedeutet hier, dass die Lua-Ausführung tatsächlich unterbrochen wird, entweder durch einen expliziten Aufruf einer entsprechenden Funktion wie core.(m)sleep() oder core.yield() oder durch eine automatische erzwungene Unterbrechung (siehe tune.lua.forced-yield). Sie wird später fortgesetzt, wenn der zugehörige Task erneut zur Ausführung eingeplant wird. Nicht alle Lua-Handler können ihre Ausführung abgeben: Es muss zwischen unterbrechbaren und nicht unterbrechbaren Handlern unterschieden werden.

Bei unterbrechbaren Handlern (Tasks, Aktionen usw.) kann das Erreichen des Zeitlimits bedeuten, dass “tune.lua.forced-yield” für das System zu hoch ist. Ein niedrigerer Wert könnte die Situation verbessern. Es kann aber auch sinnvoll sein zu prüfen, ob manuelle Yield-Aufrufe an wichtigen Stellen der Lua-Funktion helfen. Ebenso kann es darauf hinweisen, dass der Handler zu viel Zeit in einer bestimmten, nicht unterbrechbaren Lua-Bibliotheksfunktion verbringt.

Bei nicht unterbrechbaren Handlern (Lua-Konvertern, Sample-Fetches) kann es schlicht bedeuten, dass der Handler zu viele Berechnungen durchführt. Dies könnte auf einen ungeeigneten Entwurf zurückgehen, denn solche Handler blockieren häufig den Ablauf der Anfrageausführung und sollen schnell beendet werden, damit die Anfrageverarbeitung fortfahren kann. Ein üblicher Lösungsansatz ist, die Lua-Funktion stärker auf Geschwindigkeit zu optimieren, da eine Verringerung von “tune.lua.forced-yield” hier nicht hilft.

Dieses Zeitlimit zählt nur die reine Lua-Laufzeit. Führt Lua ein core.sleep aus, wird die Schlafzeit nicht berücksichtigt. Das Standardzeitlimit beträgt 1000ms.

Hinweis: Wenn der Handler einen Lua-GC-Zyklus auslöst (entweder explizit oder nach einiger Zeit automatisch durch Lua), wird dessen Dauer ebenfalls angerechnet.

Die Dauer des GC-Zyklus lässt sich nicht gesondert bestimmen. Daher kann dies auf ausgelasteten Systemen zu Fehlalarmen führen, wenn der GC kaum mit der Arbeit nachkommt und den größten Teil der verfügbaren Ausführungszeit verbraucht. In diesem Fall kommen folgende Lösungsansätze infrage:

- prüfen, ob sich das Skript zur Verringerung des Lua-Speicherverbrauchs optimieren lässt
- Lua-GC-Parameter feinabstimmen und/oder manuelle GC-Zyklen anfordern
  (siehe: https://www.lua.org/manual/5.4/manual.html#pdf-collectgarbage)
- tune.lua.burst-timeout erhöhen

Der Wert 0 deaktiviert diesen Schutz vollständig.

tune.lua.forced-yield <number>

tune.lua.forced-yield <number>

Diese Direktive zwingt die Lua-Engine, nach jeweils <number> ausgeführten Anweisungen die Ausführung abzugeben. Dadurch lässt sich ein langes Skript unterbrechen, sodass der HAProxy-Scheduler andere Tasks verarbeiten kann, etwa Verbindungen annehmen oder Datenverkehr weiterleiten. Der Standardwert beträgt 10000 Anweisungen für mit “lua-load-per-thread” geladene Skripte und MAX(500, 10000 / nbthread) Anweisungen für mit “lua-load” geladene Skripte. Dieser Wert erwies sich als optimal für die Leistung und vermeidet zugleich Konkurrenz zwischen mehreren Threads um die globale Lua-Sperre.

Wenn HAProxy häufig Lua-Code ausführt, aber eine höhere Reaktionsfähigkeit benötigt wird, kann dieser Wert verringert werden. Ist der Lua-Code recht lang und sein Ergebnis für die Datenverarbeitung unbedingt erforderlich, kann <number> erhöht werden. Der Wert sollte jedoch sorgfältig gewählt werden, da er bei mehreren Threads die Konkurrenz erhöhen kann.

tune.lua.log.loggers { on | off }

tune.lua.log.loggers { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Protokollierung der Ausgabe von LUA-Skripten über die für den aktuellen Proxy geltenden Logger, sofern vorhanden.

Der Standardwert ist ‘on’.

tune.lua.log.stderr { on | auto | off }

tune.lua.log.stderr { on | auto | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Protokollierung der Ausgabe von LUA-Skripten über stderr. Bei ‘auto’ ist die Protokollierung über stderr unter folgenden Bedingungen aktiviert, wenn mindestens eine davon zutrifft:

- tune.lua.log.loggers ist auf 'off' gesetzt
- das Skript läuft außerhalb eines Proxy-Kontexts, und es gibt keinen globalen Logger
- das Skript läuft in einem Proxy-Kontext ohne zugeordneten Logger

Beachten Sie, dass diese Protokollierung, sofern aktiviert, zusätzlich zur über tune.lua.log.loggers konfigurierten Protokollierung erfolgt.

Der Standardwert ist ‘auto’.

tune.lua.maxmem <number>

tune.lua.maxmem <number>

Legt die maximale Menge an RAM in Megabyte fest, die Lua pro Prozess verwenden darf. Der Standardwert ist null und bedeutet unbegrenzt. Es ist wichtig, eine Grenze zu setzen, damit ein Skriptfehler nicht den gesamten verfügbaren Systemspeicher aufbraucht.

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

Wählt aus, welche Lua-Standardbibliotheken beim Initialisieren des Lua-Zustands geladen werden. Das Argument ist eine durch Kommas getrennte Liste von Bibliotheksnamen aus folgender Menge: table, io, os, string, math, utf8, package, debug. Anstelle einer Liste können die besonderen Werte “all” und “none” verwendet werden. “none” lässt sich nicht mit Bibliotheksnamen kombinieren. Der Standardwert ist “all”.

Die Bibliotheken base und coroutine werden unabhängig von dieser Einstellung immer geladen: base stellt grundlegende Lua-Funktionen bereit, auf die HAProxy angewiesen ist, und coroutine ist erforderlich, weil HAProxy coroutine.create() durch eine eigene sichere Implementierung ersetzt.

Beachten Sie, dass fork() und die Erzeugung neuer Threads in HAProxy unabhängig von dieser Einstellung bereits standardmäßig blockiert sind. Sie können nur über die globale Direktive “insecure-fork-wanted” wieder aktiviert werden. Die Beschränkung der geladenen Bibliotheken verringert die für Lua-Skripte zugängliche Angriffsfläche weiter. Insbesondere gilt: - Das Weglassen von “os” verhindert os.execute() und os.exit() - Das Weglassen von “io” verhindert io.open() und io.popen() - Das Weglassen von “package” verhindert das Laden nativer C-Module über require() - Das Weglassen von “debug” verhindert die Untersuchung interner HAProxy-Strukturen über debug.getupvalue(), debug.getmetatable() oder debug.sethook()

Beispiele:

tune.lua.openlibs none                    # only base + coroutine
tune.lua.openlibs string,math,table,utf8  # safe subset, no I/O or OS
tune.lua.openlibs all                     # default, load everything

Diese Einstellung muss vor jeder “lua-load”-, “lua-load-per-thread”- oder “lua-prepend-path”-Direktive gesetzt werden; andernfalls wird ein Fehler beim Einlesen der Konfiguration ausgegeben.

tune.lua.service-timeout <timeout>

tune.lua.service-timeout <timeout>

Dies ist das Ausführungszeitlimit für Lua-Dienste. Es hilft, Endlosschleifen oder übermäßig lange Lua-Ausführungen zu verhindern. Dieses Zeitlimit zählt nur die reine Lua-Laufzeit. Führt Lua einen Schlafvorgang aus, wird dessen Dauer nicht berücksichtigt. Das Standardzeitlimit beträgt 4s.

tune.lua.session-timeout <timeout>

tune.lua.session-timeout <timeout>

Dies ist das Ausführungszeitlimit für Lua-Sitzungen. Es hilft, Endlosschleifen oder übermäßig lange Lua-Ausführungen zu verhindern. Dieses Zeitlimit zählt nur die reine Lua-Laufzeit. Führt Lua einen Schlafvorgang aus, wird dessen Dauer nicht berücksichtigt. Das Standardzeitlimit beträgt 4s.

tune.lua.task-timeout <timeout>

tune.lua.task-timeout <timeout>

Dient demselben Zweck wie “tune.lua.session-timeout”, gilt jedoch speziell für Tasks. Standardmäßig ist dieses Zeitlimit nicht gesetzt, da ein Task während der gesamten Lebensdauer von HAProxy aktiv bleiben kann, beispielsweise ein Task zur Prüfung von Servern.

tune.max-checks-per-thread <number>

tune.max-checks-per-thread <number>

Legt die Anzahl aktiver Prüfungen pro Thread fest, ab deren Überschreiten ein Thread aktiv nach einem weniger ausgelasteten Thread für die Zustandsprüfung sucht oder sie in eine Warteschlange stellt, bis die Anzahl der auf ihm laufenden aktiven Prüfungen sinkt. Der Standardwert ist null, das heißt, es wird keine solche Grenze gesetzt. Dies kann in Umgebungen mit sehr vielen aufwendigen Prüfungen und vielen Threads erforderlich sein, wenn die Last ungleich verteilt erscheint und Zustandsprüfungen beim Start zufällig ihr Zeitlimit überschreiten. Dies tritt typischerweise mit OpenSSL 3.0 auf, das bei Zustandsprüfungen etwa 20-mal mehr CPU beansprucht als ältere Versionen. Die Einstellung versucht, die Arbeit für Zustandsprüfungen gleichmäßiger auf alle Threads zu verteilen. Die weitaus meisten Konfigurationen benötigen keine Änderung dieses Parameters. Beachten Sie, dass zu niedrige Werte die Zustandsprüfung erheblich verlangsamen können, wenn die Prüfungen lange dauern.

tune.maxaccept <number>

tune.maxaccept <number>

Legt fest, wie viele Verbindungen ein Prozess maximal unmittelbar nacheinander annehmen darf, bevor er sich anderer Arbeit zuwendet. Im Einzelprozessmodus lieferten höhere Werte bei hohen Verbindungsraten früher bessere Leistung; mit mehreren Warteschlangen gilt dies jedoch nicht mehr. Der Wert gilt für jeden Listener einzeln, wobei die Anzahl der Prozesse berücksichtigt wird, an die der Listener gebunden ist. Der Standardwert ist 4, womit die besten Ergebnisse erzielt wurden. Wurde ein deutlich höherer Wert aus einer sehr alten Konfiguration übernommen, kann es sich lohnen, ihn zu entfernen, da dies sowohl die Leistung verbessert als auch die Antwortzeit verringert. Im Mehrprozessmodus wird der Wert durch das Doppelte der Anzahl von Prozessen geteilt, an die der Listener gebunden ist. Der Wert -1 deaktiviert die Begrenzung vollständig. Normalerweise sollte es nicht nötig sein, diesen Wert anzupassen.

tune.maxpollevents <number>

tune.maxpollevents <number>

Legt die maximale Anzahl von Ereignissen fest, die bei einem Aufruf des Abfragesystems auf einmal verarbeitet werden können. Der Standardwert wird an das Betriebssystem angepasst. Es wurde beobachtet, dass Werte unter 200 die Latenz tendenziell leicht verringern, jedoch zulasten der Netzwerkbandbreite. Werte über 200 erhöhen dagegen tendenziell die Latenz zugunsten etwas höherer Bandbreite. Der konfigurierte Wert muss kleiner oder gleich 1000000 sein.

tune.maxrewrite <number>

tune.maxrewrite <number>

Setzt den reservierten Pufferbereich auf diese Größe in Byte. Der reservierte Bereich wird zum Umschreiben oder Hinzufügen von Headern verwendet. Die ersten Lesevorgänge auf Sockets füllen niemals mehr als bufsize-maxrewrite. Historisch war der Standardwert die Hälfte von bufsize, was jedoch wenig sinnvoll ist, da selten sehr viele Header hinzugefügt werden müssen. Ein zu hoher Wert verhindert die Verarbeitung großer Anfragen oder Antworten. Ein zu niedriger Wert verhindert das Hinzufügen neuer Header zu bereits großen Anfragen oder zu POST-Anfragen. Im Allgemeinen ist ein Wert von etwa 1024 sinnvoll. Ist er größer als die Hälfte von bufsize, wird er automatisch auf diese Hälfte angepasst. Daher müssen Sie sich bei einer Änderung von bufsize nicht darum kümmern.

tune.max-rules-at-once <number>

tune.max-rules-at-once <number>

Legt die maximale Anzahl von Regeln fest, die Funktionen zur Regelsatzauswertung auf einmal auswerten dürfen, sofern diese Funktionen ihre Ausführung abgeben können. Konfigurationen mit vielen “tcp-request content”- oder “http-request”-Regeln sind beispielsweise nicht ungewöhnlich. Viele Regeln zusammen mit CPU-intensiven Aktionen (etwa Aktionen auf Inhalten) können Konkurrenz zwischen Threads verursachen, da ohne Unterbrechung alle Regeln eines Regelsatzes innerhalb desselben Abfrageschleifendurchlaufs ausgewertet werden. Diese Option stellt sicher, dass bei inhaltsbezogenen Regelsätzen (die wegen der Inhaltsprüfung bereits Yield unterstützen) höchstens <number> Regeln innerhalb desselben Abfrageschleifendurchlaufs ausgeführt werden. Dazu zwingt sie die auswertende Funktion, die Ausführung abzugeben und die Auswertung erst im nächsten Abfrageschleifendurchlauf fortzusetzen.

Betroffen sind folgende Regelsätze:

• “tcp-request content”
• “tcp-response content”
• “http-request”
• “http-response”

Der Standardwert ist 50.

tune.memory.hot-size <number>

tune.memory.hot-size <number>

Legt die Speichermenge pro Thread fest, die im lokalen Cache sofort verfügbar gehalten wird und niemals von anderen Threads zurückgewonnen werden kann. Der Zugriff auf diesen Speicher ist sehr schnell und benötigt keine Sperren. Eine ausreichende Menge ist entscheidend für gute Leistung bei extremer Konkurrenz zwischen Threads. Der Wert wird in Byte angegeben. Der Standardwert wird beim Kompilieren über CONFIG_HAP_POOL_CACHE_SIZE festgelegt und beträgt standardmäßig 524288 (512 kB). Ein höherer Wert kann die Leistung in bestimmten Szenarien verbessern, insbesondere wenn Leistungsprofile eine starke Belastung der Speicherzuweisung zeigen. Erfahrungsgemäß liegt ein guter Wert zwischen der einfachen und der doppelten Größe des L2-Caches pro CPU-Kern. Zu hohe Werte beeinträchtigen die Leistung durch ineffiziente Nutzung der L3-Caches der CPUs und verbrauchen mehr Speicher. Es wird empfohlen, den Wert nicht zu ändern oder nur in kleinen Schritten vorzugehen. Um die CPU-Caches pro Thread vollständig zu deaktivieren, könnte ein sehr kleiner Wert funktionieren; besser ist jedoch “-dMno-cache” in der Befehlszeile.

tune.notsent-lowat.client <size>

tune.notsent-lowat.client <size>
tune.notsent-lowat.server <size>

Passt die Pufferung des Kernels pro Socket so an, dass die Sendeseite eines Sockets als voll gemeldet wird, sobald die gepufferte Datenmenge diesem Wert zuzüglich der gemessenen Fenstergröße entspricht. Dabei sollen nur die unbedingt benötigten Bytes in den Socket-Puffern verbleiben, ergänzt um eine kleine Reserve für die Daten, die bis zum nächsten Sendeversuch von haproxy übertragen werden. Ein niedriger Wert (typischerweise etwa tune.bufsize) kann den Speicherverbrauch der Systempuffer erheblich verringern und die Latenz auf Anwendungsebene reduzieren, die durch das Leeren gepufferter Daten entsteht. Auf unterstützenden Systemen ist diese Einstellung im Allgemeinen wirksamer und genauer als tune.sndbuf.client und tune.sndbuf.client. Sie gilt pro Verbindung (je nach Einstellung für Verbindungen von einem Client oder zu einem Server) und wird nur für TCP-Verbindungen verwendet. Der Standardwert ist null und bedeutet unbegrenzt. Dies ist nur unter Linux verfügbar.

tune.pattern.cache-size <number>

tune.pattern.cache-size <number>

Setzt die Größe des Caches für Mustersuchen auf <number> Einträge. Dieser LRU-Cache speichert frühere Suchen und deren Ergebnisse. Er wird von ACLs und Maps für langsame Mustersuchen verwendet, insbesondere mit den Vergleichsmethoden “sub”, “reg”, “dir”, “dom”, “end”, “bin” sowie für Zeichenfolgenvergleiche ohne Beachtung der Groß-/Kleinschreibung. Er arbeitet auf Musterausdrücken und kann daher das Ergebnis einer Suche über alle in einer Konfigurationszeile angegebenen Muster speichern (einschließlich aller aus Dateien geladenen Muster). Einträge, die über HTTP-Aktionen oder die CLI aktualisiert werden, werden automatisch ungültig gemacht. Die Standardgröße beträgt 10000 Einträge. Dadurch bleibt der Speicherbedarf bei etwa 5 MB pro Prozess/Thread auf 32-Bit-Systemen und 8 MB pro Prozess/Thread auf 64-Bit-Systemen, da die Caches thread- beziehungsweise prozesslokal sind. Das Kollisionsrisiko in diesem Cache ist sehr gering und liegt in der Größenordnung der Cachegröße geteilt durch 2^64. Bei 10000 Anfragen pro Sekunde und der Standardgröße von 10000 Einträgen besteht typischerweise eine Wahrscheinlichkeit von 1%, dass ein Brute-Force-Angriff nach 60 Jahren eine einzige Kollision erzeugt, beziehungsweise von 0.1% nach 6 Jahren. Dies gilt als deutlich geringer als das Risiko einer Speicherbeschädigung durch alternde Komponenten. Falls dies nicht akzeptabel ist, kann der Cache durch Setzen dieses Parameters auf 0 deaktiviert werden.

tune.peers.max-updates-at-once <number>

tune.peers.max-updates-at-once <number>

Legt die maximale Anzahl von Stick-Tabellen-Aktualisierungen fest, die haproxy beim Senden von Nachrichten auf einmal zu verarbeiten versucht. Das Abrufen der Daten für diese Aktualisierungen erfordert Sperroperationen, die ohne Begrenzung auf Rechnern mit vielen Threads CPU-intensiv sein können. Sie können außerdem während der anfänglichen gebündelten Übertragung zwischen einem älteren und einem neueren Prozess die Latenz des Datenverkehrs erhöhen. Umgekehrt können niedrige Werte ebenfalls höheren CPU-Aufwand und eine längere Gesamtdauer verursachen. Der Standardwert ist 200; es wird empfohlen, ihn nicht zu ändern.

tune.pipesize <size>

tune.pipesize <size>

Setzt die Größe der Kernel-Pipe-Puffer auf diesen Wert (in Byte). Standardmäßig verwenden Pipes die Standardgröße des Systems. Bei TCP-Splicing kann eine größere Pipe jedoch manchmal die Leistung verbessern, insbesondere wenn vermutet wird, dass die Pipes nicht vollständig gefüllt werden und viele splice()-Aufrufe erfolgen. Dies beeinflusst den Speicherbedarf des Kernels; der Wert darf daher nur geändert werden, wenn die Auswirkungen verstanden werden.

tune.pool-high-fd-ratio <number>

tune.pool-high-fd-ratio <number>

Legt den maximalen Anteil der von HAProxy global verwendeten Dateideskriptoren an der maximal nutzbaren Anzahl in Prozent fest, ab dem ungenutzte Verbindungen beendet werden, wenn keine Verbindung wiederverwendet werden kann und eine neue erstellt werden muss. Der Standardwert ist 25. Ein Viertel der Dateideskriptoren bedeutet, dass ungefähr die Hälfte der maximalen Anzahl von Frontend-Verbindungen eine ungenutzte Verbindung zum Backend vorhalten kann. Darüber hinauszugehen ist im allgemeinen Fall bei angestrebter Verbindungswiederverwendung vermutlich wenig sinnvoll.

tune.pool-low-fd-ratio <number>

tune.pool-low-fd-ratio <number>

Legt den maximalen Anteil der von HAProxy global verwendeten Dateideskriptoren an der maximal nutzbaren Anzahl in Prozent fest, ab dem keine weiteren Verbindungen zur Wiederverwendung in den Pool ungenutzter Verbindungen aufgenommen werden. Der Standardwert ist 20.

tune.pt.zero-copy-forwarding { on | off }

tune.pt.zero-copy-forwarding { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die kopierfreie Datenweiterleitung für den Pass-through-Multiplexer. Für ihre Verwendung muss auch Kernel-Splicing konfiguriert sein. Sie ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding, option splice-auto, option splice-request und option splice-response

tune.quic.be.cc.cubic-min-losses <number>

tune.quic.be.cc.cubic-min-losses <number>
tune.quic.fe.cc.cubic-min-losses <number>

Legt fest, wie viele verlorene Pakete erforderlich sind, damit der Cubic-Algorithmus zur Überlastungssteuerung tatsächlich ein Verlustereignis annimmt. Normalerweise gilt jedes Verlustereignis als Folge einer Überlastung und reicht aus, damit Cubic mit einem kleineren Fenster neu beginnt. Experimente zeigen jedoch zahlreiche Verlustursachen, die nichts mit Überlastung zu tun haben und als nicht überlastungsbedingte Verluste einzuordnen sind. Eine Anpassung des Fensters hat darauf keine Wirkung, außer die Kommunikation zu verlangsamen. Häufige Ursachen sind schwache Funksignale, Zustellung in falscher Reihenfolge, zufällige Verzögerungen durch hohe CPU-Auslastung auf einem Client oder ungenaue Systemzeitgeber. Diese Einstellung macht Cubic etwas toleranter gegenüber solchen Verlusten, indem sie die minimale Anzahl aufsummierter Verluste zwischen zwei ACKs ändert, die als Verlustereignis gilt. Der Standardwert ist 1. In Experimenten wurden teils deutliche Verbesserungen beobachtet, allerdings stets zusammen mit mehr durch erneute Übertragungen verschwendeter Bandbreite und einem erhöhten Risiko, bereits überlastete Verbindungen vollständig auszulasten. Der Wert 2 kann für kurze Zeit zum Vergleich einiger Messwerte verwendet werden. Überschreiten Sie niemals 2, ohne dass ein Experte die Situation zuvor analysiert hat. Standard- und Mindestwert sind 1. Verwenden Sie immer 1.

tune.quic.cc.cubic.min-losses <number> (deprecated)

tune.quic.cc.cubic.min-losses <number> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.cc.hystart { on | off }

tune.quic.be.cc.hystart { on | off }
tune.quic.fe.cc.hystart { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) den Algorithmus HyStart++ (RFC 9406) für QUIC-Verbindungen. Er ersetzt die Slow-Start-Phase von Überlastungssteuerungsalgorithmen, die hohe Paketverluste verursachen kann. Standardmäßig ist er deaktiviert.

tune.quic.cc-hystart { on | off } (deprecated)

tune.quic.cc-hystart { on | off } (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.cc.max-frame-loss <number>

tune.quic.be.cc.max-frame-loss <number>
tune.quic.fe.cc.max-frame-loss <number>

Legt fest, wie oft ein einzelner QUIC-Frame maximal als verloren markiert werden darf. Wird die Grenze überschritten, gilt die Verbindung als fehlerhaft und wird sofort geschlossen.

Der Standardwert ist 10.

tune.quic.max-frame-loss <number> (deprecated)

tune.quic.max-frame-loss <number> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.cc.max-win-size <size>

tune.quic.be.cc.max-win-size <size>
tune.quic.fe.cc.max-win-size <size>

Legt die standardmäßige maximale Fenstergröße für die Überlastungssteuerung einer einzelnen QUIC-Verbindung auf der Frontend- oder Backend-Seite fest. Der Wert muss als ganze Zahl mit optionalem Suffix ‘k’, ’m’ oder ‘g’ angegeben werden. Er muss zwischen 10k und 4g liegen.

Der QUIC-Multiplexer verwendet außerdem die aktuelle Größe des Überlastungsfensters, um zu entscheiden, ob beim Senden von Daten neue Stream-Puffer zugewiesen werden können. Die maximale Größe des Überlastungsfensters begrenzt somit auch diese Zuweisung.

Der Standardwert ist 480k.

Siehe auch die bind- und Serveroptionen “quic-cc-algo”.

tune.quic.frontend.default-max-window-size <size> (deprecated)

tune.quic.frontend.default-max-window-size <size> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.cc.reorder-ratio <0..100, in percent>

tune.quic.be.cc.reorder-ratio <0..100, in percent>
tune.quic.fe.cc.reorder-ratio <0..100, in percent>

Der Faktor, der auf die berechnete Schwelle für die Umordnung von Paketen angewendet wird. Ein zu kleiner Wert kann dazu führen, dass viele Pakete als verloren erkannt werden.

Der Standardwert ist 50.

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.max-idle-timeout <timeout>

tune.quic.be.max-idle-timeout <timeout>
tune.quic.fe.max-idle-timeout <timeout>

Legt den QUIC-Transportparameter max_idle_timeout auf der Frontend- oder Backend-Seite fest. Der Wert folgt dem HAProxy-Zeitformat und wird in Millisekunden angegeben. Er bestimmt die Zeitspanne, nach der eine Verbindung ohne Meldung geschlossen wird, wenn sie während der effektiven Zeitspanne inaktiv geblieben ist. Beide Endpunkte verwenden denselben ausgehandelten Wert: - den kleineren der beiden Parameter, wenn beide ungleich null sind, - den größeren, wenn nur einer ungleich null ist, - sind beide Parameter null, ist die Funktion deaktiviert.

Der Standardwert ist 30s.

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.sec.glitches-threshold <number>

tune.quic.be.sec.glitches-threshold <number>
tune.quic.fe.sec.glitches-threshold <number>

Legt die Schwelle für die Anzahl von Unregelmäßigkeiten pro Verbindung auf der Frontend- oder Backend-Seite fest, bei deren Erreichen die Verbindung automatisch beendet wird. Dadurch lassen sich fehlerhaft arbeitende Verbindungen automatisch beenden, ohne dafür explizite Regeln schreiben zu müssen. Der Standardwert ist null: Es wird keine Schwelle gesetzt, sodass kein Ereignis zum Schließen einer Verbindung führt. Beachten Sie, dass manche QUIC-Clients auf lange bestehenden Verbindungen gelegentlich einige Unregelmäßigkeiten verursachen können. Ein von null verschiedener Wert sollte daher vermutlich im Hunderter- oder Tausenderbereich liegen, um wirksam zu sein, ohne Clients mit geringfügigen Fehlern zu beeinträchtigen. Mit “tune.glitches.kill.cpu-usage” können Verbindungen auch erst dann beendet werden, wenn die CPU-Auslastung einen bestimmten Wert überschreitet.

Siehe auch: fc_glitches, tune.glitches.kill.cpu-usage

tune.quic.frontend.glitches-threshold <number> (deprecated)

tune.quic.frontend.glitches-threshold <number> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.fe.sec.retry-threshold <number>

tune.quic.fe.sec.retry-threshold <number>

Aktiviert die Retry-Funktion für alle konfigurierten QUIC-Listener dynamisch, sobald diese Anzahl halb offener Verbindungen erreicht ist. Eine halb offene Verbindung ist eine Verbindung, deren Handshake weder erfolgreich abgeschlossen noch fehlgeschlagen ist. Diese Einstellung erfordert ein gesetztes Cluster-Geheimnis, um zu funktionieren. Andernfalls wird sie ohne Meldung ignoriert (siehe “cluster-secret”). Sie wird ebenfalls ohne Meldung ignoriert, wenn die Verwendung von QUIC Retry erzwungen wurde (siehe “quic-force-retry”).

Der Standardwert ist 100.

Weitere Informationen zu QUIC Retry finden Sie unter https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 .

tune.quic.retry-threshold <number> (deprecated)

tune.quic.retry-threshold <number> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.fe.sock-per-conn { default-on | force-off }

tune.quic.fe.sock-per-conn { default-on | force-off }

Legt global fest, welche Sockets QUIC-Frontend-Verbindungen für Empfangs- und Sendeoperationen verwenden. Verbindungen können den Listener-Socket gemeinsam nutzen oder jeweils einen eigenen Socket anlegen.

Der Standardwert ist “default-on”. Dabei wird jeder QUIC-Verbindung ein eigener Socket zugewiesen. Dies ist die bevorzugte Option für bestmögliche Leistung bei hohem QUIC-Datenverkehr. Es ist auch die einzige Möglichkeit, einen ordnungsgemäßen Soft-Stop ohne Datenverlust für QUIC-Verbindungen sicherzustellen und vorübergehende Fehler bei sendto()-Operationen effizient zu behandeln. Dies setzt jedoch einige erweiterte Funktionen des UDP-Netzwerkstacks voraus. Wird Ihre Plattform als nicht kompatibel eingestuft, wechselt haproxy beim Start automatisch in den Modus “force-off”. Beachten Sie, dass QUIC-Listener an privilegierten Ports möglicherweise unter uid 0 laufen müssen oder OS-spezifische Anpassungen wie System-Capabilities erfordern, damit die Ziel-uid solche Ports binden darf. Siehe auch die globale Direktive “setcap”.

Der Wert “force-off” bedeutet, dass QUIC-Übertragungen über den gemeinsam genutzten Listener-Socket erfolgen. Bei geringem Datenverkehr kann dies ein guter Kompromiss sein, da der FD-Verbrauch sinkt. Die Leistung ist aufgrund höherer CPU-Auslastung jedoch nicht optimal, wenn viele Threads die Listener gemeinsam nutzen oder sehr viele QUIC-Verbindungen gleichzeitig verwendet werden können.

Diese Einstellung wirkt zusammen mit den jeweiligen bind-Optionen “quic-socket”. Wenn global “default-on” eingestellt ist, wird dieser Modus für jeden Listener aktiviert, außer für solche mit “quic-socket listener”. Wird dagegen global “force-off” verwendet, gilt dies für jede Listener-Instanz unabhängig von ihrer individuellen Konfiguration.

tune.quic.socket-owner { connection | listener } (deprecated)

tune.quic.socket-owner { connection | listener } (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Die neuere Option heißt “tune.quic.fe.sock-per-conn”. Dabei entspricht der bisherige Wert “connection” dem neuen Wert “default-on” und “listener” dem Wert “force-off”.

tune.quic.be.stream.data-ratio <0..100, in percent>

tune.quic.be.stream.data-ratio <0..100, in percent>
tune.quic.fe.stream.data-ratio <0..100, in percent>

Mit dieser Einstellung lässt sich die harte Obergrenze für die Anzahl der auf jedem Stream gleichzeitig unterwegs befindlichen Datenbytes festlegen. Sie wird als Prozentsatz der QUIC-Verbindungseinstellung stream rxbuf angegeben, wobei das Ergebnis auf bufsize aufgerundet wird.

Der Standardwert ist 90. Dies passt zum häufigsten Webszenario, in dem nur ein oder wenige Streams für Uploads verwendet werden, während die übrigen ausschließlich Downloads dienen. Bleibt die Verbindungsgrenze stream rxbuf auf einem angemessenen Niveau, stellt dies sicher, dass nur ein Teil der geöffneten Streams seine maximale Kapazität zuweisen kann.

Wenn eine Anwendung viele Upload-Streams parallel nutzt und diese ungleich bedient werden, kann eine Verringerung dieses Anteils sinnvoll sein, um die Verteilung gerechter zu machen und die Bandbreite pro Stream zu reduzieren.

Siehe auch: “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”

tune.quic.frontend.stream-data-ratio <0..100, in percent> (deprecated)

tune.quic.frontend.stream-data-ratio  <0..100, in percent> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.stream.max-concurrent <number>

tune.quic.be.stream.max-concurrent <number>
tune.quic.fe.stream.max-concurrent <number>

Auf der Frontend-Seite wird dieser Wert für den angekündigten Transportparameter initial_max_streams_bidi verwendet. Er wird als maximale Anzahl bidirektionaler Streams erzwungen, die der entfernte Peer während der Lebensdauer der Verbindung gleichzeitig öffnen darf. Dadurch wird die Anzahl gleichzeitiger HTTP/3-Clientanfragen begrenzt.

Der Standardwert ist 100. Beachten Sie, dass eine Verringerung die Empfangspufferkapazität der Streams einschränken und dadurch den Uploaddurchsatz verschlechtern kann. Dies lässt sich durch Erhöhen der QUIC-Verbindungseinstellung stream rxbuf ausgleichen.

Auf der Backend-Seite erzwingt haproxy den Wert lokal, um die Anzahl gleichzeitiger Anfragen zu begrenzen, die über eine einzelne Verbindung gemultiplext werden. Die Flusskontrolle des Peers kann sie weiter einschränken. Es kann erforderlich sein, den Standardwert 100 zu verringern, um die Reaktionsfähigkeit einer Website zu verbessern, allerdings zulasten einer höheren Anzahl offener Backend-Verbindungen. Ähnlich wie auf der Frontend-Seite beeinflusst diese Einstellung direkt die Rx-Pufferkapazität, begrenzt hier jedoch die HTTP-Downloadkapazität. Die QUIC-Einstellung stream rxbuf kann erhöht werden, wenn überwiegend HTTP-Antworten verarbeitet werden, die größer als “tune.bufsize” sind.

Siehe auch: “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.fe.stream.max-total <number>

tune.quic.fe.stream.max-total <number>

Legt die maximale Anzahl von Anfragen fest, die eine einzelne QUIC-Verbindung verarbeiten kann. Sobald diese Gesamtzahl erreicht ist, wird die Verbindung geordnet beendet. Bei HTTP/3 geschieht dies durch einen GOAWAY-Frame. Endgültig geschlossen wird die Verbindung, wenn alle verbleibenden Übertragungen abgeschlossen sind.

Diese Einstellung wird über den QUIC-Flusskontrollmechanismus als harte Grenze für die Verbindung angewendet. Verletzt ein Peer sie, wird die Verbindung sofort geschlossen.

Mit dieser Einstellung können Clients dazu gezwungen werden, von Zeit zu Zeit neue Verbindungen zu öffnen, um weitere Anfragen zu senden, und Verbindungen nicht übermäßig lange aufrechtzuerhalten. Niedrige Werte erhöhen jedoch die Latenz auf Clientseite sowie den CPU-Verbrauch auf beiden Seiten durch TLS-Handshakes.

Der Standardwert ist 0. Damit gilt keine besondere Grenze außer der durch die Kodierung des QUIC-Protokolls vorgegebenen (2^60, mehr als eine Milliarde Milliarden).

tune.quic.frontend.max-streams-bidi <number> (deprecated)

tune.quic.frontend.max-streams-bidi <number> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.stream.rxbuf <size>

tune.quic.be.stream.rxbuf <size>
tune.quic.fe.stream.rxbuf <size>

Diese Einstellung ist die harte Obergrenze für die Anzahl der auf einer QUIC-Frontend-Verbindung gleichzeitig unterwegs befindlichen Datenbytes. Sie wird als Wert für den Transportparameter initial_max_data verwendet. Abhängig von der Latenz beeinflusst sie direkt die Uploadbandbreite des Peers sowie den Speicherverbrauch pro Verbindung in haproxy.

Standardmäßig ist der Wert auf 0 gesetzt. Das bedeutet, dass er automatisch als Produkt aus max-concurrent und bufsize berechnet werden muss. Er kann beispielsweise erhöht werden, wenn eine Backend-Anwendung auf umfangreiche Uploads über Netzwerke mit hoher Latenz angewiesen ist.

Siehe auch: “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.frontend.max-data-size <size> (deprecated)

tune.quic.frontend.max-data-size <size> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.tx.pacing { on | off }

tune.quic.be.tx.pacing { on | off }
tune.quic.fe.tx.pacing { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Unterstützung für Pacing beim Senden über QUIC. Standardmäßig ist sie aktiv. Pacing soll die Datenausgabe gleichmäßiger verteilen, um Netzwerkverluste zu verringern. In den meisten Szenarien verbessert es den Netzwerkdurchsatz deutlich, indem erneute Übertragungen vermieden werden. Auf Netzwerken mit sehr hoher Bandbreite und niedriger Latenz kann eine Deaktivierung jedoch sinnvoll sein, um unerwünschte Verzögerungen zu vermeiden und den CPU-Verbrauch zu verringern.

Siehe auch die bind- und Serveroptionen “quic-cc-algo”.

tune.quic.disable-tx-pacing (deprecated)

tune.quic.disable-tx-pacing (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.be.tx.udp-gso { on | off }

tune.quic.be.tx.udp-gso { on | off }
tune.quic.fe.tx.udp-gso { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Unterstützung für UDP GSO beim Senden über QUIC. Standardmäßig ist sie aktiv. Diese Kernel-Funktion ermöglicht das Senden mehrerer Datagramme mit einem einzigen Systemaufruf, was bei großen Übertragungen effizienter ist. Bei Verdacht auf ein Sendeproblem kann es sinnvoll sein, sie auf Empfehlung der Entwickler zu deaktivieren.

tune.quic.disable-udp-gso (deprecated)

tune.quic.disable-udp-gso (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.listen { on | off }

tune.quic.listen { on | off }

Deaktiviert das QUIC-Transportprotokoll auf der Frontend-Seite. Alle QUIC-Listener werden weiterhin erstellt, lauschen jedoch nicht auf eingehende Datagramme. Somit verarbeitet haproxy auf der Frontend-Seite keinen QUIC-Datenverkehr.

Der Standardwert ist “on”. Bei Verdacht auf ein Problem mit QUIC-Datenverkehr lassen sich die QUIC-Listener mit dieser Option einfach ein- oder ausschalten, ohne jede einzelne Konfigurationszeile ändern zu müssen.

Siehe auch den Sample-Fetch “quic_enabled”.

tune.quic.mem.tx-max <size>

tune.quic.mem.tx-max <size>

Legt die maximale Speichermenge fest, die der QUIC-Stack auf der Transportschicht zum Senden verwenden darf. Dies begrenzt sowohl die gleichzeitig unterwegs befindlichen Bytes als auch die Ausgabepuffer des Multiplexers. Beachten Sie, dass diese Grenze zur Vermeidung von Konkurrenz zwischen Threads nicht strikt erzwungen wird und daher gelegentlich überschritten werden kann. Außerdem kann jede Verbindung stets ein Fenster von mindestens 2 Datagrammen verwenden. Daher sollte gleichzeitig ein passender maxconn-Wert gesetzt werden.

tune.quic.frontend.max-tx-mem <size> (deprecated)

tune.quic.frontend.max-tx-mem <size> (deprecated)

Dieses Schlüsselwort ist seit 3.3 veraltet und wird in 3.5 entfernt. Dies ist Teil der Vereinheitlichung der QUIC-Konfiguration. Bei Verwendung gilt diese Einstellung nur für Frontend-Verbindungen.

tune.quic.zero-copy-fwd-send { on | off }

tune.quic.zero-copy-fwd-send { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) das kopierfreie Senden von Daten für den QUIC-Multiplexer. Es ist standardmäßig aktiviert.

Siehe auch: tune.disable-zero-copy-forwarding

tune.renice.runtime <number>

tune.renice.runtime <number>

Diese Konfigurationsoption nimmt einen Wert zwischen -20 und 19 an. Sie setzt eine Scheduling-Priorität, wie in man 2 setpriority beschrieben. Die Priorität wird nach dem Einlesen der Konfiguration angewendet, also nur vom Worker oder vom eigenständig laufenden Prozess. Üblicherweise wird damit eine höhere Priorität als für einen Prozess festgelegt, der gerade die Konfiguration einliest (tune.renice.startup).

Siehe auch: tune.renice.startup

tune.renice.startup <number>

tune.renice.startup <number>

Diese Konfigurationsoption nimmt einen Wert zwischen -20 und 19 an. Sie setzt eine Scheduling-Priorität, wie in man 2 setpriority beschrieben. Die Priorität wird vor der übrigen Konfiguration angewendet, was nützlich sein kann, wenn die Priorität beim Einlesen der Konfiguration verringert werden soll. Dies betrifft den eigenständig laufenden Prozess oder den Worker vor dem Einlesen der Konfiguration. Sobald die Konfiguration eingelesen ist, wird die vorherige Priorität wiederhergestellt, sofern tune.renice.runtime nicht verwendet wird.

Siehe auch: tune.renice.runtime

tune.rcvbuf.backend <size>

tune.rcvbuf.backend  <size>
tune.rcvbuf.frontend <size>

Setzt die Größe des Kernel-Empfangspuffers für nicht verbundene Sockets auf diesen Wert. Dies kann für QUIC im Listener-Modus und für log-forward im Frontend verwendet werden. Die Standardpuffer des Systems sind mitunter für Sockets mit viel gebündeltem Datenverkehr zu klein, was Verluste und gegebenenfalls erneute Übertragungen (bei QUIC) verursachen und den Verbindungsaufbau unter hoher Last verlangsamen kann. Der Wert wird in Byte angegeben und auf jeden Socket angewendet. Im Listener-Modus werden Sockets von allen Verbindungen gemeinsam genutzt; die Gesamtzahl der Sockets hängt vom “shards”-Wert der “bind”-Zeile ab. Es gibt keinen allgemeingültigen guten Wert. Ein geeigneter Wert entspricht der erwarteten Größe pro Verbindung multipliziert mit der erwarteten Anzahl von Verbindungen. Der Kernel kann große Werte begrenzen. Siehe auch “tune.rcvbuf.client” und “tune.rcvbuf.server” für die entsprechenden Einstellungen verbundener Sockets sowie “tune.sndbuf.backend” und “tune.sndbuf.frontend” für die Sendeseite.

tune.rcvbuf.client <size>

tune.rcvbuf.client <size>
tune.rcvbuf.server <size>

Erzwingt die angegebene Größe in Byte für den Kernel-Empfangspuffer von Sockets auf der Client- oder Serverseite. Dieser Wert gilt für alle TCP/HTTP-Frontends und -Backends. Er sollte normalerweise niemals gesetzt werden. Die Standardgröße (0) lässt den Kernel den Wert anhand der verfügbaren Speichermenge automatisch anpassen. Manchmal können jedoch sehr niedrige Werte (z. B. 4096) helfen, Kernel-Speicher zu sparen, indem die Pufferung übermäßig großer empfangener Datenmengen verhindert wird. Niedrigere Werte erhöhen allerdings die CPU-Auslastung erheblich.

tune.recv_enough <size>

tune.recv_enough <size>

HAProxy verwendet einige Hinweise, um zu erkennen, ob ein kurzer Lesevorgang das Ende der Socket-Puffer anzeigt. Einer davon ist, dass ein Lesevorgang mehr als <recv_enough> Bytes zurückgibt. Der Standardwert ist 10136 (7 Segmente mit jeweils 1448). Mit dieser Einstellung lässt sich der Standardwert ändern, um Arbeitslasten mit vielen kurzen Nachrichten wie telnet- oder SSH-Sitzungen besser zu verarbeiten.

tune.ring.queues <number>

tune.ring.queues <number>

Legt die Anzahl der Schreibwarteschlangen vor Ringpuffern fest. Dies kann den CPU-Verbrauch von Traces bei der Fehlerdiagnose beeinflussen; sowohl zu niedrige als auch zu hohe Werte können erhebliche Auswirkungen haben. Ein geeigneter Wert wurde von den Entwicklern experimentell bestimmt. Daher sollte es keinen Grund geben, ihn zu ändern, sofern dies nicht zur Behebung bestimmter Probleme angefordert wird. Eine solche Einstellung sollte bei Versionsupgrades nicht dauerhaft in der Konfiguration verbleiben, da sich ihr optimaler Wert im Laufe der Zeit ändern kann.

tune.runqueue-depth <number>

tune.runqueue-depth <number>

Legt die maximale Anzahl von Tasks fest, die bei der Task-Ausführung auf einmal verarbeitet werden können. Der Standardwert hängt von der Thread-Anzahl ab, liegt aber zwischen 35 und 280, womit tendenziell die höchsten Anfrageraten und niedrigsten Latenzen erzielt werden. Eine Erhöhung kann die Latenz bei I/O-Operationen erhöhen; ein zu niedriger Wert kann zusätzlichen Aufwand verursachen. Bei höherer Thread-Anzahl sind niedrigere Werte vorteilhaft. Beim Experimentieren mit deutlich höheren Werten kann es sinnvoll sein, zusätzlich tune.sched.low-latency und gegebenenfalls tune.fd.edge-triggered zu aktivieren, um die maximale Latenz möglichst gering zu halten.

tune.sched.low-latency { on | off }

tune.sched.low-latency { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) den Task-Scheduler für niedrige Latenz. Standardmäßig verarbeitet HAProxy Tasks aus mehreren Klassen jeweils klassenweise, da dies am effizientesten ist. Bei hohen Werten von tune.runqueue-depth kann dies jedoch messbare Auswirkungen auf die Anfrage- oder Verbindungslatenz haben. Ist diese Einstellung aktiviert, werden vorhandene Tasks aus Klassen mit niedrigerer Priorität immer vor den anderen ausgeführt. Dadurch lässt sich die maximale Latenz neuer Anfragen oder Verbindungen inmitten sehr hohen Datenverkehrs verringern, allerdings zulasten einer stärkeren Beeinträchtigung dieses umfangreichen Datenverkehrs. Für den regulären Einsatz sollte diese Option besser deaktiviert bleiben. Der Standardwert ist off.

tune.sndbuf.backend <size>

tune.sndbuf.backend  <size>
tune.sndbuf.frontend <size>

Setzt die Größe des Kernel-Sendepuffers für nicht verbundene Sockets auf diesen Wert. Dies kann für die Protokollierung über UNIX-Sockets und UDP auf der Backend-Seite sowie für QUIC im Listener-Modus auf der Frontend-Seite verwendet werden. Die Standardpuffer des Systems sind mitunter für Sockets, die von vielen Verbindungen oder Protokollsendern gemeinsam genutzt werden, zu klein. Dies verursacht Verluste und möglicherweise erneute Übertragungen und verlangsamt den Aufbau neuer Verbindungen bei hohem Datenverkehr. Der Wert wird in Byte angegeben und auf jeden Socket angewendet. Im Listener-Modus werden Sockets von allen Verbindungen gemeinsam genutzt; die Gesamtzahl der Sockets hängt vom “shards”-Wert der “bind”-Zeile ab. Es gibt keinen allgemeingültigen guten Wert. Ein geeigneter Wert entspricht der erwarteten Größe pro Verbindung multipliziert mit der erwarteten Anzahl von Verbindungen. Der Kernel kann große Werte begrenzen. Siehe auch “tune.sndbuf.client” und “tune.sndbuf.server” für die entsprechenden Einstellungen verbundener Sockets sowie “tune.rcvbuf.backend” und “tune.rcvbuf.frontend” für die Empfangsseite.

tune.sndbuf.client <size>

tune.sndbuf.client <size>
tune.sndbuf.server <size>

Erzwingt die angegebene Größe in Byte für den Kernel-Sendepuffer von Sockets auf der Client- oder Serverseite. Dieser Wert gilt für alle TCP/HTTP-Frontends und -Backends. Er sollte normalerweise niemals gesetzt werden. Die Standardgröße (0) lässt den Kernel den Wert anhand der verfügbaren Speichermenge automatisch anpassen. Manchmal können jedoch sehr niedrige Werte (z. B. 4096) helfen, Kernel-Speicher zu sparen, indem die Pufferung übermäßig großer empfangener Datenmengen verhindert wird. Niedrigere Werte erhöhen allerdings die CPU-Auslastung erheblich. Ein weiterer Anwendungsfall ist das Verhindern von Schreibzeitüberschreitungen bei extrem langsamen Clients, wenn der Kernel wartet, bis ein großer Teil des Puffers gelesen wurde, bevor er HAProxy erneut benachrichtigt. Siehe auch tune.notsent-lowat.client und tune.notsent-lowat.server für wirksamere Einstellungen, die unter Linux eine feinere Steuerung von Speicherverbrauch und Reaktionsfähigkeit ohne Leistungseinbußen ermöglichen.

tune.ssl.cachesize <number>

tune.ssl.cachesize <number>

Legt die Größe des globalen SSL-Sitzungscaches in Blöcken fest. Ein Block ist groß genug, um eine kodierte Sitzung ohne Peer-Zertifikat aufzunehmen. Eine kodierte Sitzung mit Peer-Zertifikat wird abhängig von dessen Größe in mehreren Blöcken gespeichert. Ein Block benötigt ungefähr 200 Byte Speicher (basierend auf der Berechnung sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE, die für die Funktion shctx_init verwendet wird). Der Standardwert kann beim Kompilieren festgelegt werden; andernfalls beträgt er 20000. Ist der Cache voll, werden die am längsten ungenutzten Einträge entfernt und neu vergeben. Höhere Werte verringern die Häufigkeit solcher Bereinigungen und damit die Anzahl CPU-intensiver SSL-Handshakes, indem die Sitzungen aller Benutzer möglichst lange erhalten bleiben. Alle Einträge werden beim Start vorab zugewiesen. Der Wert 0 deaktiviert den SSL-Sitzungscache.

tune.ssl.capture-buffer-size <number>

tune.ssl.capture-buffer-size <number>
tune.ssl.capture-cipherlist-size <number> (deprecated)

Legt die maximale Größe des Puffers zur Erfassung der Verschlüsselungsalgorithmenliste, Erweiterungsliste, Liste elliptischer Kurven und Punktformate elliptischer Kurven aus dem ClientHello fest. Bei 0 (dem Standardwert) ist die Erfassung deaktiviert; andernfalls wird für jede SSL/TLS-Verbindung ein Puffer zugewiesen.

tune.ssl.certificate-compression { auto | off }

tune.ssl.certificate-compression { auto | off }

Diese Einstellung konfiguriert die Unterstützung für Zertifikatskomprimierung, eine Erweiterung (RFC 8879) für TLS 1.3.

Bei “auto” wird der Standardwert der TLS-Bibliothek verwendet.

Bei “off” wird versucht, die Unterstützung für diese Funktion ausdrücklich zu deaktivieren. HAProxy versucht dann weder, komprimierte Zertifikate zu senden, noch akzeptiert es solche Zertifikate.

Konfiguriert sowohl die Backend- als auch die Frontend-Seite.

Dieses Schlüsselwort wird von OpenSSL >= 3.2.0 unterstützt.

Der Standardwert ist auto.

tune.ssl.default-dh-param <number>

tune.ssl.default-dh-param <number>

Legt die maximale Größe der Diffie-Hellman-Parameter fest, die beim DHE-Schlüsselaustausch zur Erzeugung des ephemeren beziehungsweise temporären Diffie-Hellman-Schlüssels verwendet werden. Für die endgültige Größe wird versucht, die Größe des RSA- oder DSA-Schlüssels des Servers zu übernehmen (z. B. einen temporären DH-Schlüssel mit 2048 Bit für einen RSA-Schlüssel mit 2048 Bit), ohne jedoch diesen Höchstwert zu überschreiten. Es sind nur Werte ab 1024 erlaubt. Höhere Werte erhöhen die CPU-Last; Werte über 1024 Bit werden von Java 7 und älteren Clients nicht unterstützt. Dieser Wert wird nicht verwendet, wenn statische Diffie-Hellman-Parameter entweder direkt in der Zertifikatsdatei oder über ssl-dh-param-file bereitgestellt werden. Sind weder default-dh-param noch ssl-dh-param-file definiert und enthält die PEM-Datei des Servers für ein bestimmtes Frontend keine eigenen DH-Parameter, stehen DHE-Verschlüsselungsverfahren für dieses Frontend nicht zur Verfügung.

tune.ssl.force-private-cache

tune.ssl.force-private-cache

Diese Option deaktiviert die gemeinsame Nutzung des SSL-Sitzungscaches zwischen allen Prozessen. Sie sollte normalerweise nicht verwendet werden, da sie viele Neuverhandlungen erzwingt, wenn Clients zufällig bei unterschiedlichen Prozessen landen. Auf einigen Betriebssystemen, auf denen keine der Synchronisierungsmethoden für den SSL-Cache verwendet werden kann, ist sie jedoch möglicherweise erforderlich. In diesem Fall kann eine zusätzliche Ebene mit hashbasierter Lastverteilung vor der SSL-Ebene die Auswirkungen der fehlenden gemeinsamen Sitzungsnutzung begrenzen.

tune.ssl.hard-maxrecord <number>

tune.ssl.hard-maxrecord <number>

Legt die maximale Anzahl von Bytes fest, die zu einem Zeitpunkt an SSL_write() übergeben werden. Der Standardwert 0 bedeutet, dass es keine Begrenzung gibt. Im Gegensatz zu tune.ssl.maxrecord wird diese Einstellung nicht dynamisch angepasst. Kleinere Records können den Durchsatz verringern, sind aber bei ressourcenarmen Clients möglicherweise erforderlich.

tune.ssl.keylog { on | off }

tune.ssl.keylog { on | off }

Diese Option aktiviert die Protokollierung der TLS-Schlüssel. Sie sollte mit Vorsicht verwendet werden, da sie pro SSL-Sitzung mehr Speicher verbraucht und die Leistung beeinträchtigen könnte. Standardmäßig ist sie deaktiviert.

Diese Sample-Fetches sollten verwendet werden, um die SSLKEYLOGFILE zu erzeugen, die zum Entschlüsseln des Datenverkehrs mit wireshark erforderlich ist.

https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html

SSLKEYLOG besteht aus einer Reihe von Zeilen mit folgendem Format:

<Label> <space> <ClientRandom> <space> <Secret>

ClientRandom wird vom Sample-Fetch %[ssl_fc_client_random,hex] bereitgestellt. Das Geheimnis und das Label finden Sie in der folgenden Tabelle. Sie müssen eine SSLKEYLOGFILE mit allen Labels dieser Tabelle erzeugen.

Die folgenden Sample-Fetches liefern hexadezimale Zeichenfolgen und müssen nicht konvertiert werden.

  SSLKEYLOGFILE-Bezeichnung       |  Sample-Abrufe für die geheimen Werte
  --------------------------------|-----------------------------------------
  CLIENT_EARLY_TRAFFIC_SECRET     |  %[ssl_xx_client_early_traffic_secret]
  CLIENT_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_client_handshake_traffic_secret]
  SERVER_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_server_handshake_traffic_secret]
  CLIENT_TRAFFIC_SECRET_0         |  %[ssl_xx_client_traffic_secret_0]
  SERVER_TRAFFIC_SECRET_0         |  %[ssl_xx_server_traffic_secret_0]
  EXPORTER_SECRET                 |  %[ssl_xx_exporter_secret]
  EARLY_EXPORTER_SECRET           |  %[ssl_xx_early_exporter_secret]

Diese Fetches stehen für die Frontend- (fc) und Backend-Seite (bc) zur Verfügung. Ersetzen Sie “xx” durch “fc” oder “bc”, um die gewünschte Seite zu verwenden.

Dies ist nur mit OpenSSL 1.1.1 verfügbar und für TLS1.3-Sitzungen nützlich.

Wenn Sie den Inhalt einer SSLKEYLOGFILE für TLS < 1.3 erzeugen möchten, benötigen Sie nur diese Zeile:

“CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]”

Ein vollständiges Schlüsselprotokoll lässt sich mit einem log-format wie folgt erzeugen, auch wenn dies für Syslog nicht ideal ist:

log-format "CLIENT_EARLY_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_early_traffic_secret]\n
            CLIENT_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_handshake_traffic_secret]\n
            SERVER_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_server_handshake_traffic_secret]\n
            CLIENT_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_client_traffic_secret_0]\n
            SERVER_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_server_traffic_secret_0]\n
            EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_exporter_secret]\n
            EARLY_EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_early_exporter_secret]"

HAProxy stellt die obigen Formate auch als vordefinierte Umgebungsvariablen bereit, die direkt in einer “log-format”-Direktive verwendet werden können:

$HAPROXY_KEYLOG_FC_LOG_FMT   Verbindungsschlüssel für das Frontend (zum Client)
$HAPROXY_KEYLOG_BC_LOG_FMT   Verbindungsschlüssel für das Backend (zum Server)

tune.ssl.keyupdate-rate-limit <limit>

tune.ssl.keyupdate-rate-limit <limit>

Begrenzt die Anzahl von KeyUpdate-Nachrichten, die pro Sekunde akzeptiert werden, auf <limit>, bevor dies als Flut betrachtet und die Verbindung beendet wird. Die Verarbeitung von KeyUpdate ist CPU-intensiv, und es gibt kaum einen Grund, viele solcher Nachrichten zu empfangen. Der Wert “0” deaktiviert die Ratenbegrenzung. Der Standardwert ist 100.

tune.ssl.lifetime <timeout>

tune.ssl.lifetime <timeout>

Legt fest, wie lange eine zwischengespeicherte SSL-Sitzung gültig bleiben darf. Die Zeit wird in Sekunden angegeben und beträgt standardmäßig 300 (5 Minuten). Dies garantiert nicht, dass Sitzungen so lange erhalten bleiben: Ist der Cache voll, werden die am längsten ungenutzten Sitzungen unabhängig von ihrer konfigurierten Lebensdauer entfernt. Der eigentliche Zweck dieser Einstellung besteht darin, eine zu lange Verwendung von Sitzungen zu verhindern.

tune.ssl.maxrecord <number>

tune.ssl.maxrecord <number>

Legt die maximale Anzahl von Bytes fest, die zu Beginn der Datenübertragung an SSL_write() übergeben werden. Der Standardwert 0 bedeutet, dass es keine Begrenzung gibt. Bei SSL/TLS kann der Client Daten erst entschlüsseln, nachdem er einen vollständigen Record empfangen hat. Bei großen Records müssen Clients daher möglicherweise bis zu 16kB herunterladen, bevor sie mit der Verarbeitung beginnen können. Eine Begrenzung kann die Seitenladezeiten in Browsern verbessern, die über Netzwerke mit hoher Latenz oder niedriger Bandbreite verbunden sind. Es wird empfohlen, optimale Werte zu finden, die in 1 oder 2 TCP-Segmente passen (im Allgemeinen 1448 Byte über Ethernet mit aktivierten TCP-Zeitstempeln beziehungsweise 1460 bei deaktivierten Zeitstempeln). Dabei muss der zusätzliche Aufwand durch SSL/TLS berücksichtigt werden. Typische Werte von 1419 und 2859 lieferten in Tests gute Ergebnisse. Verwenden Sie “strace -e trace=write”, um den besten Wert zu ermitteln. HAProxy wechselt automatisch zu dieser Einstellung, sobald ein inaktiver Stream erkannt wurde (siehe tune.idletimer oben). Siehe auch tune.ssl.hard-maxrecord.

tune.ssl.ssl-ctx-cache-size <number>

tune.ssl.ssl-ctx-cache-size <number>

Setzt die Größe des Caches für erzeugte Zertifikate auf <number> Einträge. Dies ist ein LRU-Cache. Da die dynamische Erzeugung eines SSL-Zertifikats aufwendig ist, werden die Zertifikate zwischengespeichert. Die Standardgröße beträgt 1000 Einträge.

tune.streams-elasticity <number>

tune.streams-elasticity <number>

Definiert einen Zielprozentsatz für Streams pro Frontend-Verbindung im Verhältnis zur maximalen Anzahl gleichzeitiger Verbindungen (maxconn), wenn alle Verbindungen aufgebaut sind. Diese Kennzahl gilt für gemultiplexte Protokolle wie HTTP/2 oder QUIC, bei denen jede Verbindung mehrere Streams empfangen kann. Mindestens einer ist immer garantiert; der Prozentsatz muss daher mindestens 100% betragen. Während des Verbindungsaufbaus kündigt HAProxy dynamisch zusätzliche Streams bis zur konfigurierten Grenze an und hält dabei das Zielverhältnis ein. Beim Aufbau erhält jede Frontend-Verbindung mindestens einen Stream. Zusätzliche Streams werden anhand des Zielprozentsatzes und der konfigurierten Stream-Grenzen zugeteilt. Dies ermöglicht eine effiziente Stream-Zuweisung bei wechselnder Last: mehr Streams bei niedriger und weniger bei hoher Last.

Hochdynamische Websites mit vielen Objekten pro Seite profitieren von hohen Verhältnissen, die viele Streams pro Verbindung ermöglichen. Websites, die im Durchschnitt weniger Streams verwenden (WebSocket, Anwendungscode), können niedrigere Verhältnisse nahe 120 oder 150 bevorzugen (20 bis 50% mehr Streams als Verbindungen), um bei anhaltender Last übermäßige Stream-Anzahlen zu verhindern.

Der Standardwert ist 0 und bedeutet, dass auf dieser Ebene keine Begrenzung erzwungen wird. Es gelten nur die H2- und QUIC-Konfigurationen (bei der Standardeinstellung von 100 Streams pro Verbindung entspricht dies 10000%). Für kleine Installationen mit maxconn um tausend bleibt dies die empfohlene Einstellung. Mittelgroße Installationen mit einigen tausend bis einigen zehntausend Verbindungen setzen das Verhältnis typischerweise zwischen 1000 und 5000 und erlauben damit bei Volllast 10 bis 50 Streams pro Verbindung. Große Installationen mit Hunderttausenden bis Millionen Verbindungen können niedrigere Werte (120 bis 200) verwenden, um bei Volllast im Durchschnitt 1.2 bis 2 Streams pro Verbindung zu unterstützen.

Im Gegensatz zu HTTP/2 kann QUIC die Anzahl gleichzeitiger Streams während der Lebensdauer einer Verbindung dynamisch anpassen. Die QUIC-Flusskontrolle ist jedoch strenger als die von HTTP/2. Daher sollten bei ihrer Verwendung ausreichend hohe Werte angegeben werden, um zusätzliche Latenz auf der Verbindung zu vermeiden. Für QUIC-Listener mit aktiviertem 0-RTT gibt es eine weitere Einschränkung: Der dem Peer anfänglich angekündigte Wert ignoriert die Stream-Elastizität und richtet sich ausschließlich nach “tune.quic.fe.stream.max-concurrent”. Nach dieser ersten Ankündigung bleibt das Prinzip der Stream-Elastizität während der Lebensdauer der Verbindung jedoch wirksam.

Die Überwachung der Gesamtzahl aktiver Streams in Backends einschließlich der Warteschlangen liefert einen praktischen Anhaltspunkt für eine dauerhaft tragbare Ziellast und hilft, übermäßige Kapazitätsbereitstellung zu vermeiden.

tune.stick-counters <number>

tune.stick-counters <number>

Legt die Anzahl von Stick-Zählern fest, die eine Verbindung oder Anfrage gleichzeitig über “track-sc*"-Aktionen in “tcp-request”- oder “http-request”-Regeln verfolgen darf. Der Standardwert wird beim Kompilieren durch das Makro MAX_SESS_STK_CTR festgelegt und beträgt standardmäßig 3. Mit dieser Einstellung lässt sich der Wert ändern und der beim Kompilieren angegebene Wert ignorieren; er darf jedoch nicht größer als 100 sein. Eine Erhöhung kann beim Übertragen komplexer Konfigurationen auf haproxy erforderlich sein, verursacht jedoch Kosten: Jeder Eintrag benötigt 16 Byte pro Verbindung und 16 Byte pro Anfrage. Dieser Speicher muss für alle Anfragen zugewiesen und mit Nullen gefüllt werden, selbst wenn er nicht verwendet wird. Der Wert 10 erhöht daher den Speicherverbrauch pro Anfrage um 320 Byte und bewirkt, dass dieser Speicher für jede Anfrage gelöscht wird, was messbare CPU-Auswirkungen hat. Werden dagegen keine “track-sc”-Regeln verwendet, kann der Wert verringert werden (0 ist zulässig und deaktiviert Stick-Zähler vollständig).

tune.takeover-other-tg-connections <value>

tune.takeover-other-tg-connections <value>

Standardmäßig wird nicht versucht, ungenutzte Verbindungen aus anderen Thread-Gruppen zu verwenden. Dieses Verhalten lässt sich jedoch ändern. Gültige Werte für <value> sind: “none”, der Standardwert, bei dem kein Versuch unternommen wird, ungenutzte Verbindungen aus anderen Thread-Gruppen zu verwenden; “restricted”, bei dem nur dann eine ungenutzte Verbindung von einem anderen Thread angefordert wird, wenn Protokolle verwendet werden, die keine neuen Verbindungen aufbauen können, etwa Reverse HTTP, oder wenn strict-maxconn verwendet wird; und “full”, bei dem immer auch in anderen Thread-Gruppen nach ungenutzten Verbindungen gesucht wird. Beachten Sie, dass Verbindungen aus anderen Thread-Gruppen Leistungseinbußen verursachen können und daher nur verwendet werden sollten, wenn dies wirklich erforderlich ist. Dieses Verhalten wird inzwischen durch tune.idle-pool.shared gesteuert. Dieses Schlüsselwort dient nur noch der Kompatibilität mit älteren Konfigurationen und wird künftig als veraltet eingestuft.

tune.vars.global-max-size <size>

tune.vars.global-max-size <size>
tune.vars.proc-max-size <size>
tune.vars.reqres-max-size <size>
tune.vars.sess-max-size <size>
tune.vars.txn-max-size <size>

Diese fünf Einstellungen steuern die maximale Speichermenge, die das Variablensystem verwenden darf. “global” begrenzt den insgesamt für alle Gültigkeitsbereiche verfügbaren Speicher. “proc” begrenzt den Speicher für den Prozessbereich, “sess” für den Sitzungsbereich, “txn” für den Transaktionsbereich und “reqres” für die Verarbeitung jeder einzelnen Anfrage oder Antwort. Die Speicherabrechnung ist hierarchisch: Grenzen auf einer übergeordneten Ebene schließen die untergeordneten Ebenen ein. “proc” umfasst “sess”, “sess” umfasst “txn” und “txn” umfasst “reqres”.

Wenn beispielsweise “tune.vars.sess-max-size” auf 100 begrenzt ist, können auch “tune.vars.txn-max-size” und “tune.vars.reqres-max-size” den Wert 100 nicht überschreiten. Wird eine Variable “txn.var” angelegt, die 100 Bytes enthält, ist der gesamte verfügbare Platz verbraucht. Beachten Sie, dass eine Überschreitung der Grenzen zur Laufzeit keine Fehlermeldung auslöst, Werte aber abgeschnitten oder beschädigt werden können. Planen Sie deshalb den Platzbedarf für die Speicherung aller Variablen genau.

tune.zlib.memlevel <number>

tune.zlib.memlevel <number>

Legt den Parameter memLevel bei der Initialisierung von zlib für jeden Stream fest. Er bestimmt, wie viel Speicher für den internen Kompressionszustand reserviert werden soll. Der Wert 1 verwendet am wenigsten Speicher, ist jedoch langsam und verschlechtert das Kompressionsverhältnis. Der Wert 9 verwendet für optimale Geschwindigkeit am meisten Speicher. Zulässig sind Werte zwischen 1 und 9. Der Standardwert ist 8.

tune.zlib.windowsize <number>

tune.zlib.windowsize <number>

Legt die Fenstergröße (die Größe des Verlaufspuffers) als Parameter der zlib-Initialisierung für jeden Stream fest. Größere Werte verbessern die Kompression auf Kosten eines höheren Speicherverbrauchs. Zulässig sind Werte zwischen 8 und 15. Der Standardwert ist 15.

3.3. Fehlerbehebung

anonkey <key>

anonkey <key>

Legt den globalen Anonymisierungsschlüssel auf <key> fest. Dieser muss eine 32-Bit-Zahl zwischen 0 und 4294967295 sein. CLI-Befehle verwenden diesen Schlüssel standardmäßig, wenn der anonymisierte Modus aktiviert ist. Der Schlüssel kann auch zur Laufzeit mit dem CLI-Befehl “set anon global-key” gesetzt werden. Siehe auch das Kommandozeilenargument “-dC” im Verwaltungshandbuch.

debug.counters { on | off }

debug.counters { on | off }

Aktiviert (‘on’) oder deaktiviert (‘off’) die Aktualisierung der Ereigniszähler im Code. Diese Zähler werden vom CLI-Befehl “debug counters” unter dem Typ “CNT” ausgegeben. Sie stehen nur zur Verfügung, wenn der Code mit DEBUG_COUNTERS auf einem Wert von mindestens 1 kompiliert wurde. Bei dem Wert 1 werden die Zähler standardmäßig nicht aktualisiert (“debug.counters off”), bei dem Wert 2 werden sie standardmäßig aktualisiert (“debug.counters on”). Normalerweise besteht kein Anlass, diese Einstellung zu ändern, sofern nicht ein Entwickler darum bittet oder der Verdacht besteht, dass sie ungewöhnlich viel CPU-Zeit beansprucht. Im letzteren Fall ist ein Bericht an die Entwickler mit einem Auszug der Zähler erforderlich. Der Zustand lässt sich auch zur Laufzeit mit dem CLI-Befehl “debug counters” ändern. Weitere Informationen finden Sie im Verwaltungshandbuch.

force-cfg-parser-pause <timeout>

force-cfg-parser-pause <timeout>

Dieser Befehl hält den Konfigurationsparser für <timeout> Millisekunden an. Das ist bei der Entwicklung oder beim Testen von Zeitüberschreitungen in Init-Skripten hilfreich, insbesondere zur Simulation eines sehr langen Neuladens. Dafür muss expose-experimental-directives gesetzt sein.

<timeout> gibt die Wartezeit standardmäßig in Millisekunden an. Durch Anhängen einer Einheit an die Zahl kann jedoch auch jede andere Einheit verwendet werden, wie am Anfang dieses Dokuments erläutert.

Beispiel:

global
    expose-experimental-directives
    force-cfg-parser-pause 10s

quick-exit

quick-exit

Beschleunigt beim Neuladen das Beenden des alten Prozesses, indem die Freigabe von Speicherobjekten und Listenern übersprungen wird. Diese Ressourcen werden beim Beenden des Prozesses ohnehin vom Betriebssystem zurückgewonnen. Der Zeitgewinn ist nur gering und beträgt selbst bei sehr großen Konfigurationen höchstens einige hundert Millisekunden. Der eigentliche Haupteinsatzzweck besteht darin, einen gefundenen Fehler im deinit()-Code zu umgehen. Verwenden Sie diese Option möglichst nur auf Anweisung der Entwickler.

quiet

quiet

Unterdrückt alle Meldungen während des Starts. Entspricht dem Kommandozeilenargument “-q”.

warn-blocked-traffic-after <time>

warn-blocked-traffic-after <time>

Legt fest, nach welcher Verzögerung eine festhängende Task, die den Datenverkehr blockiert, eine Warnung auf der Standardfehlerausgabe auslöst. Die Verzögerung wird in Millisekunden angegeben und beträgt standardmäßig 100 ms. Zulässig sind Werte von einschließlich 1 ms bis einschließlich 1000 ms. Niedrigere Werte führen häufig, höhere Werte selten zu Warnungen. Der Watchdog beendet ohnehin eine außer Kontrolle geratene Task, die zweimal jeweils eine Sekunde lang nicht reagiert. Eine Warnverzögerung von 1000 ms löst daher normalerweise keine Warnung aus. Empfohlen werden Werte zwischen 10 und 100ms, um Konfigurationsfehler zu erkennen, die durch lange Antwortzeiten oder ruckelnde interaktive Sitzungen die Nutzung beeinträchtigen können. Solche Probleme können beispielsweise eine schlecht entworfene Lua-Sample-Fetch-Funktion mit aufwendigen Berechnungen oder eine sehr große map_reg- oder map_regm-Map-Datei mit hohen Auswertungskosten verursachen. Zum Vergleich: Ein TLS-Handshake kann zwischen einer und zwei Millisekunden beanspruchen, die Kompression eines 16kB großen HTTP-Antwortpuffers etwa eine Millisekunde. Die Ausgabe enthält einen Thread-Dump der verantwortlichen Task mit einem Backtrace und etwas Kontext, anhand dessen sich ermitteln lässt, wo die Zeit verbraucht wird.

zero-warning

zero-warning

Wenn diese Option gesetzt ist, verweigert HAProxy den Start, sobald beim Verarbeiten und Anwenden der Konfiguration eine Warnung ausgegeben wurde. Warnungen über ungeeignete Parameterkombinationen, sehr hohe Grenzen, die nicht gesetzt werden konnten, und ähnliche Probleme führen dann dazu, dass sich der Prozess beim Start mit einem Fehler beendet. Einige spät beim Start auftretende Warnungen kann diese Option nicht erfassen, etwa wenn beim Ändern der Gruppen-ID im Modus “daemon” oder “master-worker” zusätzliche Gruppen nicht abgelegt werden können oder wenn der Prozess nach fork() nicht als dumpbar markiert werden kann. Die Option erfasst keine Warnungen, die zur Laufzeit ausgegeben werden. Für Konfigurationen, die selten geändert werden, wird diese Option nachdrücklich empfohlen: Sie hilft, subtile Fehler zu erkennen und die Konfiguration sauber und mit künftigen Versionen kompatibel zu halten. Beachten Sie, dass auch “haproxy -c” in diesem Fall Fehler meldet. Diese Option entspricht dem Kommandozeilenargument “-dW”.

3.4. HTTPClient-Abstimmung

HTTPClient ist eine interne HTTP-Bibliothek, die von verschiedenen Subsystemen verwendet werden kann, beispielsweise in LUA-Skripten. HTTPClient wird nicht im Datenpfad eingesetzt und hat daher nichts mit dem HTTP-Datenverkehr zu tun, der HAProxy durchläuft.

httpclient.resolvers.disabled <on|off>

httpclient.resolvers.disabled <on|off>

Deaktiviert die DNS-Auflösung des httpclient. Verhindert die Erstellung des resolvers-Abschnitts “default”.

Der Standardwert ist off.

httpclient.resolvers.id <resolvers id>

httpclient.resolvers.id <resolvers id>

Legt den resolvers-Abschnitt fest, mit dem der httpclient die Namensauflösung versucht.

Standardmäßig wird die resolvers-ID “default” verwendet. Wenn diese Option nicht gesetzt ist und der Abschnitt nicht gefunden wird, wird lediglich die Namensauflösung deaktiviert.

Wird diese Option hingegen ausdrücklich gesetzt, führt ein Fehler beim Laden zu einem Konfigurationsfehler.

httpclient.resolvers.prefer <ipv4|ipv6>

httpclient.resolvers.prefer <ipv4|ipv6>

Mit dieser Option lässt sich die gewünschte IP-Adressfamilie für die Namensauflösung auswählen. Das ist nützlich, wenn IPv6 in Ihrem Netzwerk nicht verfügbar ist. Der Standardwert ist “ipv6”.

httpclient.retries <number>

httpclient.retries <number>

Legt fest, wie oft der httpclient eine fehlgeschlagene Anfrage erneut versucht. Die Wirkung entspricht der des Schlüsselworts “retries” in einem Backend.

Der Standardwert ist 3.

httpclient.ssl.ca-file <cafile>

httpclient.ssl.ca-file <cafile>

Legt die ca-file fest, die zur Überprüfung des Serverzertifikats verwendet werden soll. Die Option akzeptiert dieselben Parameter wie die Option “ca-file” in einer server-Zeile.

Wenn diese Option nicht gesetzt ist, gilt standardmäßig der Wert “@system-ca”, der versucht, die CA des Systems zu laden. Schlägt dies fehl, wird SSL für den httpclient deaktiviert.

Wird diese Option hingegen ausdrücklich gesetzt, führt ein Fehlschlag zu einem Konfigurationsfehler.

httpclient.ssl.verify [none|required]

httpclient.ssl.verify [none|required]

Funktioniert wie die Option verify in server-Zeilen. Bei ’none’ werden Serverzertifikate nicht überprüft. Der Standardwert ist “required”.

Wenn diese Option nicht gesetzt ist, gilt standardmäßig der Wert “required”. Schlägt dies fehl, wird SSL für den httpclient deaktiviert.

Wird diese Option hingegen ausdrücklich gesetzt, führt ein Fehlschlag zu einem Konfigurationsfehler.

httpclient.timeout.connect <timeout>

httpclient.timeout.connect <timeout>

Legt die standardmäßige maximale Wartezeit für einen Verbindungsversuch des httpclient fest.

Argumente:

<timeout> ist der Wert für die Zeitüberschreitung, standardmäßig in
          Millisekunden. Wird die Einheit an die Zahl angehängt, kann
          jedoch jede andere Einheit verwendet werden, wie am Anfang
          dieses Dokuments erläutert.

Der Standardwert ist 5000ms.

13 - 4. Proxys

Die Proxy-Konfiguration kann in einer Reihe von Abschnitten definiert werden:

• defaults [<name>] [ from <defaults_name> ]
• frontend <name> [ from <defaults_name> ]
• backend <name> [ from <defaults_name> ]
• listen <name> [ from <defaults_name> ]

Ein “frontend”-Abschnitt beschreibt eine Gruppe lauschender Sockets, die Clientverbindungen annehmen.

Ein “backend”-Abschnitt beschreibt eine Gruppe von Servern, mit denen der Proxy eine Verbindung herstellt, um eingehende Verbindungen weiterzuleiten.

Ein “listen”-Abschnitt definiert einen vollständigen Proxy, bei dem Frontend- und Backend-Teil in einem einzigen Abschnitt kombiniert sind. Dies ist im Allgemeinen für rein TCP-basierten Datenverkehr nützlich.

Ein “defaults”-Abschnitt setzt alle Einstellungen auf die dokumentierten Standardwerte zurück und legt neue Werte für die nachfolgenden Abschnitte fest. Alle “frontend”, “backend” und “listen”-Abschnitte beziehen ihre Anfangseinstellungen immer aus einem defaults-Abschnitt, standardmäßig den zuletzt vor dem neu erstellten Abschnitt definierten. Es ist möglich, explizit einen bestimmten “defaults”-Abschnitt anzugeben, von dem die Anfangseinstellungen geladen werden sollen, indem dessen Name in der Abschnittszeile nach dem optionalen Schlüsselwort “from” angegeben wird. Während “defaults”-Abschnitte keinen Namen erfordern, wird die Angabe eines Namens für bessere Lesbarkeit empfohlen. Dies ist auch die einzige Möglichkeit, einen bestimmten Abschnitt anstelle des Standardvorgängers anzugeben. Da “defaults”-Abschnittsnamen optional sind, wird standardmäßig eine sehr großzügige Prüfung auf deren Namen angewendet, und diese dürfen sogar überlappen. Wenn jedoch ein “defaults”-Abschnitt von einem anderen Abschnitt referenziert wird, muss dessen Name der Syntax entsprechen, die für alle Proxy-Namen gilt, und dieser Name muss innerhalb der defaults-Abschnitte eindeutig sein. Bitte beachten Sie, dass unabhängig davon, was derzeit erlaubt ist, generell von der Verwendung doppelter Abschnittsnamen abgeraten wird und die gleiche Syntax wie für Proxy-Namen eingehalten werden sollte. Diese Regel könnte in einer zukünftigen Version verbindlich werden. Zudem wird eine Warnung ausgegeben, wenn ein defaults-Abschnitt explizit von einem Proxy verwendet wird, während er gleichzeitig implizit von einem anderen Proxy verwendet wird, weil er der zuletzt definierte ist. Es wird dringend empfohlen, beide Verwendungsarten nicht zu mischen, sondern entweder stets explizite Referenzen zu verwenden oder einen letzten gemeinsamen defaults-Abschnitt bereitzustellen, der ausschließlich für implizite Verwendungen reserviert ist.

Beachten Sie, dass ein defaults-Abschnitt auch seine Anfangseinstellungen von einem anderen defaults-Abschnitt beziehen kann, und dadurch Einstellungen über mehrere Ebenen von defaults-Abschnitten vererbt werden können. Dies kann praktisch sein, um bestimmte Konfigurationsprofile zu erstellen, die Gruppen von Standardwerten enthalten (z. B. TCP oder HTTP sowie kurze oder lange Zeitüberschreitungen), kann aber schnell unübersichtlich werden.

Standardmäßig werden benannte defaults-Abschnitte nach der Konfigurationsanalyse beibehalten. Dies ermöglicht deren Wiederverwendung bei der dynamischen Erstellung von Backends. Dieses Verhalten kann global über das Schlüsselwort “tune.defaults.purge” geändert werden.

Alle Proxy-Namen müssen aus Groß- und Kleinbuchstaben, Ziffern, ‘-’ (Bindestrich), ‘_’ (Unterstrich), ‘.’ (Punkt) und ‘:’ (Doppelpunkt) gebildet werden. Bei ACL-Namen wird zwischen Groß- und Kleinschreibung unterschieden. Daher bezeichnen “www” und “WWW” zwei verschiedene Proxys.

Historisch gesehen konnten sich alle Proxy-Namen unter bestimmten Bedingungen überlappen (z. B. wenn sie nicht über dieselben Frontend- oder Backend-Funktionen verfügten), doch dies verursachte zu viele Probleme in den Protokollen sowie Verwirrung bei CLI-Operationen, Stick-Table-Namen und Statistikabfragen. Zwei Proxys müssen nun unabhängig von ihren jeweiligen Funktionen unterschiedliche Namen haben.

Derzeit werden zwei wesentliche Proxy-Modi unterstützt: “tcp”, auch bekannt als Schicht 4, und “http”, auch bekannt als Schicht 7. Im Modus für Schicht 4 leitet HAProxy bidirektionalen Datenverkehr einfach zwischen zwei Seiten weiter. Im Modus für Schicht 7 analysiert HAProxy das Protokoll und kann anhand beliebiger Kriterien damit interagieren, indem es beliebige Inhalte in Anfragen oder Antworten zulässt, blockiert, umschaltet, hinzufügt, ändert oder entfernt.

Im HTTP-Modus hängt die Verarbeitung von Anfragen und Antworten, die über eine Verbindung fließen, von der Kombination der HTTP-Optionen im Frontend und im Backend ab. HAProxy unterstützt 3 Verbindungsmodi:

• KAL: Keep-Alive (“option http-keep-alive”), der Standardmodus: Alle Anfragen und Antworten werden verarbeitet, und die Verbindungen bleiben zwischen Antworten und neuen Anfragen offen, aber inaktiv.

• SCL: Serververbindung schließen (“option http-server-close”): Die Verbindung zum Server wird geschlossen, nachdem das Ende der Antwort empfangen wurde; die Verbindung zum Client bleibt offen.

• CLO: Verbindung schließen (“option httpclose”): Die Verbindung wird nach Ende der Antwort geschlossen, und in beiden Richtungen wird “Connection: close” angehängt.

Der effektive Modus, der auf eine Verbindung angewendet wird, die durch ein Frontend und ein Backend läuft, kann je nach Proxy-Modus anhand der folgenden Matrix bestimmt werden, aber kurz gesagt sind die Modi symmetrisch, Keep-Alive ist die schwächste Option und das Schließen der Verbindung die stärkste.

               Backend-Modus

                | KAL | SCL | CLO
            ----+-----+-----+----
            KAL | KAL | SCL | CLO
            ----+-----+-----+----
   Modus    SCL | SCL | SCL | CLO
            ----+-----+-----+----
            CLO | CLO | CLO | CLO

Es ist möglich, ein TCP-Frontend an ein HTTP-Backend anzuschließen. Dies ist sinnlos, wenn nur HTTP-Verkehr behandelt wird. Es kann jedoch genutzt werden, um mehrere Protokolle innerhalb desselben Frontends zu verarbeiten. In diesem Fall wird die Clientverbindung zunächst als rohe TCP-Verbindung behandelt, bevor sie auf HTTP umgestellt wird. Vor dem Protokollwechsel werden die Inhaltsverarbeitungen auf Rohdaten durchgeführt. Nach dem Protokollwechsel werden die Daten analysiert und intern als HTX gespeichert, wodurch die Verwendung der Rohdarstellung nicht mehr möglich ist. Es gibt keine Möglichkeit, zurückzukehren.

Es gibt zwei Arten von Protokollwechseln: In-Place-Protokollwechsel und destruktive Protokollwechsel. Erstere beinhalten einen TCP-zu-HTTP/1-Protokollwechsel. In HTTP/1 werden die Anfrageverarbeitungen serialisiert, wodurch der anwendungsbezogene Datenstrom erhalten bleiben kann. Letztere beinhalten einen TCP-zu-HTTP/2-Protokollwechsel. Da es sich um ein multiplextes Protokoll handelt, kann der anwendungsbezogene Datenstrom keinem HTTP/2-Datenstrom zugeordnet werden und wird zerstört. Neue anwendungsbezogene Datenströme werden dann erstellt, wenn HAProxy neue HTTP/2-Datenströme auf der unteren Ebene im H2-Multiplexer empfängt. Es ist wichtig, diesen Unterschied zu verstehen, da dies die Art und Weise, wie Daten verarbeitet werden, grundlegend verändert. Bei einem HTTP/1-Protokollwechsel gehen die bereits auf Rohdaten durchgeführten Inhaltsverarbeitungen weder verloren noch werden sie erneut ausgeführt, während bei einem HTTP/2-Protokollwechsel die anwendungsbezogenen Datenströme getrennt sind und alle Frontend-Regeln systematisch auf jeden einzelnen angewendet werden. Wie bereits erwähnt, wird der erste Datenstrom, der TCP-Datenstrom, zerstört, jedoch erst nachdem die Frontend-Regeln ausgewertet wurden.

Bei der HTTP-Verarbeitung aus einem TCP-Proxy heraus ist außerdem zu beachten: HAProxy kann HTTP/1 während der tcp-request content-Regeln analysieren, aber nicht HTTP/2. Es ist lediglich möglich, die HTTP/2-Verbindungspräambel zu analysieren. Dies stellt eine erhebliche Einschränkung bezüglich der HTTP-Inhaltsanalyse im TCP-Modus dar. Konkret ist es nur möglich festzustellen, ob empfangene Daten HTTP sind. Zum Beispiel ist es nicht möglich, aufgrund des Host-Headers ein Backend auszuwählen, was in HTTP/1 trivial ist. Glücklicherweise gibt es eine Lösung, um diesen Nachteil zu mildern.

Es gibt zwei Möglichkeiten, einen HTTP-Protokollwechsel durchzuführen. Die erste, historische Methode, besteht darin, ein HTTP-Backend auszuwählen. Der Protokollwechsel erfolgt, wenn das Backend festgelegt wird. Für In-Place-Protokollwechsel wird nur die Backend-Konfiguration bei der HTTP-Datenverarbeitung berücksichtigt. Bei destruktiven Protokollwechseln wird der anwendungsbezogene Datenstrom zerstört, wodurch die Verarbeitung gestoppt wird. Mit dieser Methode sind die Möglichkeiten, ein Backend mit einer HTTP/2-Verbindung auszuwählen, wirklich begrenzt, wie oben erwähnt, und etwas sinnlos, da der Datenstrom zerstört wird. Die zweite Methode besteht darin, während der Auswertung der tcp-request content-Regeln den Protokollwechsel durchzuführen, mithilfe der Aktion “switch-mode http”. In diesem Fall erfolgt der Protokollwechsel im Frontend-Kontext, und es ist möglich, HTTP-Direktiven in diesem Frontend zu definieren. Für In-Place-Protokollwechsel bietet dies sofort die volle Leistungsfähigkeit der HTTP-Analyse. Das Verhalten ähnelt damit stark dem eines HTTP-Frontends. Bei destruktiven Protokollwechseln ändert sich nichts, außer dass es sinnlos ist, ein Backend auf Basis begrenzter Informationen auszuwählen. Dies ist natürlich die empfohlene Methode. Daher ist es ausreichend, im Rahmen der tcp-request content-Regeln den Anfrageprotokolltyp zu prüfen, um einen HTTP-Protokollwechsel durchzuführen. Alle verbleibenden HTTP-Manipulationen können dann in die http-request-Regelmenge des Frontends verlegt werden. Behalten Sie jedoch im Hinterkopf, dass die tcp-request content-Regeln weiterhin auf jedem Datenstrom ausgewertet werden, was sich nicht ändern lässt.

4.1. Matrix der Proxy-Schlüsselwörter

Die folgende Liste von Schlüsselwörtern wird unterstützt. Die meisten davon können nur in einem begrenzten Satz von Abschnittstypen verwendet werden. Einige sind als „veraltet“ markiert, da sie aus einer alten Syntax stammen, die verwirrend oder funktional eingeschränkt sein kann, und es gibt neue empfohlene Schlüsselwörter, die sie ersetzen sollen. Schlüsselwörter, die mit “(*)” markiert sind, können optional mit dem Präfix “no” invertiert werden, z. B. “no option contstats”. Dies ist sinnvoll, wenn die Option standardmäßig aktiviert ist und für einen bestimmten Fall deaktiviert werden muss. Solche Optionen können auch mit “default” präfixiert werden, um die Standardwerte unabhängig von vorherigen “defaults”-Abschnitten wiederherzustellen. Schlüsselwörter, die in defaults-Abschnitten unterstützt werden und mit “(!)” markiert sind, sind nur in benannten defaults-Abschnitten, nicht in anonymen, unterstützt.

Hinweis: Einige gefährliche und nicht empfohlene Direktiven sind bewusst nicht in der folgenden Matrix aufgeführt. Das ist beabsichtigt. Diese Direktiven sind dokumentiert. Doch durch ihre Nicht-Aufnahme in dieser Liste wird noch ein weiterer Weg geschaffen, um von ihrer Verwendung abzuraten.

 Schlüsselwort                        defaults   frontend   listen    backend
------------------------------------+----------+----------+---------+---------
acl                                       X (!)      X         X         X
backlog                                   X          X         X         -
balance                                   X          -         X         X
be-unpublished                            -          -         X         X
bind                                      -          X         X         -
capture cookie                            -          X         X         -
capture request header                    -          X         X         -
capture response header                   -          X         X         -
clitcpka-cnt                              X          X         X         -
clitcpka-idle                             X          X         X         -
clitcpka-intvl                            X          X         X         -
compression                               X          X         X         X
cookie                                    X          -         X         X
crt                                       -          X         X         -
declare capture                           -          X         X         -
default-server                            X          -         X         X
default_backend                           X          X         X         -
description                               -          X         X         X
disabled                                  X          X         X         X
dispatch                    (deprecated)  -          -         X         X
email-alert from                          X          X         X         X
email-alert level                         X          X         X         X
email-alert mailers                       X          X         X         X
email-alert myhostname                    X          X         X         X
email-alert to                            X          X         X         X
enabled                                   X          X         X         X
errorfile                                 X          X         X         X
errorfiles                                X          X         X         X
errorloc                                  X          X         X         X
errorloc302                               X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
errorloc303                               X          X         X         X
error-log-format                          X          X         X         -
external-check command                    X          -         X         X
external-check path                       X          -         X         X
force-persist                             -          -         X         X
force-be-switch                           -          X         X         -
filter                                    -          X         X         X
fullconn                                  X          -         X         X
guid                                      -          X         X         X
hash-balance-factor                       X          -         X         X
hash-preserve-affinity                    X          -         X         X
hash-type                                 X          -         X         X
http-after-response                       X (!)      X         X         X
http-check comment                        X          -         X         X
http-check connect                        X          -         X         X
http-check disable-on-404                 X          -         X         X
http-check expect                         X          -         X         X
http-check send                           X          -         X         X
http-check send-state                     X          -         X         X
http-check set-var                        X          -         X         X
http-check unset-var                      X          -         X         X
http-error                                X          X         X         X
http-request                              X (!)      X         X         X
http-response                             X (!)      X         X         X
http-reuse                                X          -         X         X
http-send-name-header                     X          -         X         X
id                                        -          X         X         X
ignore-persist                            -          -         X         X
load-server-state-from-file               X          -         X         X
log                                  (*)  X          X         X         X
log-format                                X          X         X         -
log-format-sd                             X          X         X         -
log-tag                                   X          X         X         X
log-steps                                 X          X         X         -
max-keep-alive-queue                      X          -         X         X
max-session-srv-conns                     X          X         X         -
maxconn                                   X          X         X         -
mode                                      X          X         X         X
monitor fail                              -          X         X         -
monitor-uri                               X          X         X         -
option abortonclose                  (*)  X          X         X         X
option allbackups                    (*)  X          -         X         X
option checkcache                    (*)  X          -         X         X
option clitcpka                      (*)  X          X         X         -
option contstats                     (*)  X          X         X         -
option disable-h2-upgrade            (*)  X          X         X         -
option dontlog-normal                (*)  X          X         X         -
option dontlognull                   (*)  X          X         X         -
-- keyword -------------------------- defaults - frontend - listen -- backend -
option external-check                     X          -         X         X
option forwardfor                         X          X         X         X
option forwarded                     (*)  X          -         X         X
option h1-case-adjust-bogus-client   (*)  X          X         X         -
option h1-case-adjust-bogus-server   (*)  X          -         X         X
option http-buffer-request           (*)  X          X         X         X
option http-drop-request-trailers    (*)  X          -         -         X
option http-drop-response-trailers   (*)  X          -         X         -
option http-ignore-probes            (*)  X          X         X         -
option http-keep-alive               (*)  X          X         X         X
option http-no-delay                 (*)  X          X         X         X
option http-pretend-keepalive        (*)  X          -         X         X
option http-restrict-req-hdr-names        X          X         X         X
option http-server-close             (*)  X          X         X         X
option http-use-proxy-header         (*)  X          X         X         -
option httpchk                            X          -         X         X
option httpclose                     (*)  X          X         X         X
option httplog                            X          X         X         -
option httpslog                           X          X         X         -
option idle-close-on-response        (*)  X          X         X         -
option independent-streams           (*)  X          X         X         X
option ldap-check                         X          -         X         X
option log-health-checks             (*)  X          -         X         X
option log-separate-errors           (*)  X          X         X         -
option logasap                       (*)  X          X         X         -
option mysql-check                        X          -         X         X
option nolinger                      (*)  X          X         X         X
option originalto                         X          X         X         X
option persist                       (*)  X          -         X         X
option pgsql-check                        X          -         X         X
option prefer-last-server            (*)  X          -         X         X
option redispatch                    (*)  X          -         X         X
option redis-check                        X          -         X         X
option smtpchk                            X          -         X         X
option socket-stats                  (*)  X          X         X         -
option splice-auto                   (*)  X          X         X         X
option splice-request                (*)  X          X         X         X
option splice-response               (*)  X          X         X         X
option spop-check                         X          -         X         X
option srvtcpka                      (*)  X          -         X         X
option ssl-hello-chk                      X          -         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
option tcp-check                          X          -         X         X
option tcp-smart-accept              (*)  X          X         X         -
option tcp-smart-connect             (*)  X          -         X         X
option tcpka                              X          X         X         X
option tcplog                             X          X         X         -
option transparent      (deprecated) (*)  X          -         X         X
option use-small-buffers             (*)  X          -         X         X
persist rdp-cookie                        X          -         X         X
quic-initial                              X (!)      X         X         -
rate-limit sessions                       X          X         X         -
redirect                                  -          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
retries                                   X          -         X         X
retry-on                                  X          -         X         X
server                                    -          -         X         X
server-state-file-name                    X          -         X         X
server-template                           -          -         X         X
source                                    X          -         X         X
srvtcpka-cnt                              X          -         X         X
srvtcpka-idle                             X          -         X         X
srvtcpka-intvl                            X          -         X         X
stats admin                               -          X         X         X
stats auth                                X          X         X         X
stats enable                              X          X         X         X
stats hide-version                        X          X         X         X
stats http-request                        -          X         X         X
stats realm                               X          X         X         X
stats refresh                             X          X         X         X
stats scope                               X          X         X         X
stats show-desc                           X          X         X         X
stats show-legends                        X          X         X         X
stats show-node                           X          X         X         X
stats show-version                        X          X         X         X
stats uri                                 X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
stick match                               -          -         X         X
stick on                                  -          -         X         X
stick store-request                       -          -         X         X
stick store-response                      -          -         X         X
stick-table                               -          X         X         X
tcp-check comment                         X          -         X         X
tcp-check connect                         X          -         X         X
tcp-check expect                          X          -         X         X
tcp-check send                            X          -         X         X
tcp-check send-lf                         X          -         X         X
tcp-check send-binary                     X          -         X         X
tcp-check send-binary-lf                  X          -         X         X
tcp-check set-var                         X          -         X         X
tcp-check unset-var                       X          -         X         X
tcp-request connection                    X (!)      X         X         -
tcp-request content                       X (!)      X         X         X
tcp-request inspect-delay                 X (!)      X         X         X
tcp-request session                       X (!)      X         X         -
tcp-response content                      X (!)      -         X         X
tcp-response inspect-delay                X (!)      -         X         X
timeout check                             X          -         X         X
timeout client                            X          X         X         -
timeout client-fin                        X          X         X         -
timeout client-hs                         X          X         X         -
timeout connect                           X          -         X         X
timeout http-keep-alive                   X          X         X         X
timeout http-request                      X          X         X         X
timeout queue                             X          -         X         X
timeout server                            X          -         X         X
timeout server-fin                        X          -         X         X
timeout tarpit                            X          X         X         X
timeout tunnel                            X          -         X         X
transparent                 (deprecated)  X          -         X         X
unique-id-format                          X          X         X         X
unique-id-header                          X          X         X         -
use_backend                               -          X         X         -
use-fcgi-app                              -          -         X         X
use-server                                -          -         X         X
------------------------------------+----------+----------+---------+---------
 Schlüsselwort                        defaults   frontend   listen    backend

4.2. Alphabetisch sortierte Schlüsselwortreferenz

Dieser Abschnitt enthält eine Beschreibung jedes Schlüsselworts und seiner Verwendung.

acl <aclname> <criterion> [flags] [operator] <value> ...

acl <aclname> <criterion> [flags] [operator] <value> ...

Eine Zugriffskontrollliste anlegen oder ergänzen.

Kann in folgenden Kontexten verwendet werden: tcp, http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja(!) | ja | ja | ja

Diese Anweisung ist nur in benannten defaults-Abschnitten verfügbar, nicht in anonymen. ACLs, die in einem defaults-Abschnitt definiert sind, sind aus anderen Abschnitten, die ihn verwenden, nicht sichtbar.

Beispiel:

acl invalid_src  src          0.0.0.0/7 224.0.0.0/3
acl invalid_src  src_port     0:1023
acl local_dst    hdr(host) -i localhost

Siehe Abschnitt 7 zur ACL-Verwendung.

backlog <conns>

backlog <conns>

Dem System Hinweise auf die ungefähre gewünschte Größe der Listen-Warteschlange geben

Kann in folgenden Kontexten verwendet werden: tcp, http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | nein

Argumente:

<conns>   ist die Zahl ausstehender Verbindungen. Je nach Betriebssystem
          kann dies bereits bestätigte Verbindungen, noch nicht bestätigte
          Verbindungen oder beide zusammen bezeichnen.

Diese Option ist nur für Stream-Listener, einschließlich QUIC-Listener, von Bedeutung. Bei QUIC-Instanzen verhält sie sich jedoch anders.

Für alle Listener außer QUIC besteht eine Möglichkeit zum Schutz vor SYN-Flood-Angriffen darin, die Größe des SYN-Backlogs des Systems zu erhöhen. Je nach System ist dies manchmal über einen Systemparameter einstellbar, manchmal nicht einstellbar und manchmal richtet sich das System nach Hinweisen, die die Anwendung beim Aufruf von listen() bereitstellt. Standardmäßig übergibt HAProxy den Wert von maxconn des Frontends an den listen()-Aufruf. Auf Systemen, die diesen Wert nutzen können, kann es gelegentlich sinnvoll sein, einen anderen Wert anzugeben, weshalb dieser backlog-Parameter existiert.

Unter Linux 2.4 wird der Parameter vom System ignoriert. Unter Linux 2.6 wird er als Hinweis verwendet, und das System akzeptiert Werte bis zur nächstgrößeren Zweierpotenz, jedoch nie oberhalb bestimmter Grenzen (üblicherweise 32768).

Für QUIC-Listener legt backlog eine gemeinsame Grenze für die maximale Anzahl aktiver Handshakes und Verbindungen fest, die darauf warten, angenommen zu werden. Die Handshake-Phase hängt hauptsächlich von der Netzwerklatenz zum entfernten Peer ab, während die zweite Phase ausschließlich von der Last von haproxy abhängt. Wenn eine dieser Grenzen erreicht ist, beginnt haproxy, empfangene INITIAL-Pakete zu verwerfen, wodurch keine neuen Verbindungen mehr angelegt werden können, bis der Überschuss an Verbindungen abnimmt. Dieser Zustand kann dazu führen, dass Browser stillschweigend auf eine ältere HTTP-Version wechseln und auf TCP umschalten.

Siehe auch: “maxconn” und die Optimierungshilfe des Zielbetriebssystems.

balance <algorithm> [ <arguments> ]

balance <algorithm> [ <arguments> ]
balance url_param <param> [check_post]

Den in einem Backend zu verwendenden Lastverteilungsalgorithmus festlegen.

Kann in folgenden Kontexten verwendet werden: tcp, http, log

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | nein | ja | ja

Argumente:

<algorithm> ist der Algorithmus zur Auswahl eines Servers für die
            Lastverteilung. Dies gilt nur, wenn keine Informationen zur
            Sitzungsbindung vorliegen oder eine Verbindung einem anderen
            Server neu zugewiesen wird. <algorithm> kann einer der folgenden
            Algorithmen sein:

  roundrobin  Jeder Server wird entsprechend seinem Gewicht abwechselnd
              verwendet. Dies ist der gleichmäßigste und fairste Algorithmus,
              solange die Verarbeitungszeiten der Server gleichmäßig verteilt
              bleiben. Dieser Algorithmus ist dynamisch: Servergewichte können
              im laufenden Betrieb angepasst werden, beispielsweise für einen
              langsamen Anlauf. Konstruktionsbedingt ist er auf 4095 aktive
              Server pro Backend begrenzt. In manchen großen Servergruppen
              kann es nach einem sehr kurzen Ausfall gelegentlich einige
              Hundert Anfragen dauern, bis ein wieder verfügbarer Server in
              die Gruppe aufgenommen wird und Datenverkehr empfängt. Das ist
              normal, wenn auch sehr selten. Dieser Hinweis soll vermeiden,
              dass Sie sich Sorgen machen, falls Sie dies beobachten.
              Hinweis: Bei Backends im LOG-Modus werden Gewichte ignoriert.

  static-rr   Jeder Server wird entsprechend seinem Gewicht abwechselnd
              verwendet. Dieser Algorithmus ähnelt roundrobin, ist jedoch
              statisch: Eine Änderung des Servergewichts im laufenden Betrieb
              hat keine Wirkung. Dafür gibt es keine konstruktionsbedingte
              Begrenzung der Serverzahl. Ein wieder verfügbarer Server wird
              unmittelbar wieder in die Gruppe aufgenommen, sobald die gesamte
              Zuordnung neu berechnet wurde. Außerdem benötigt dieser
              Algorithmus etwas weniger CPU-Leistung (etwa -1%). Er kann nicht
              im LOG-Modus verwendet werden.

  leastconn   Der Server mit den wenigsten Verbindungen erhält die Verbindung.
              Innerhalb von Gruppen gleich ausgelasteter Server wird
              Round-Robin verwendet, damit alle Server zum Einsatz kommen.
              Dieser Algorithmus wird für sehr lange Sitzungen empfohlen,
              etwa bei LDAP, SQL oder TSE. Für Protokolle mit kurzen Sitzungen
              wie HTTP eignet er sich dagegen weniger gut. Der Algorithmus
              ist dynamisch: Servergewichte können im laufenden Betrieb
              angepasst werden, beispielsweise für einen langsamen Anlauf.
              Neben bestehenden Verbindungen berücksichtigt er auch wartende
              Verbindungen, um Warteschlangen zu minimieren. Dieser Algorithmus
              kann nicht im LOG-Modus verwendet werden.

  first       Der erste Server mit freien Verbindungsplätzen erhält die
              Verbindung. Die Server werden vom kleinsten zum größten
              numerischen Bezeichner ausgewählt (siehe Serverparameter "id").
              Standardmäßig entspricht dieser der Position des Servers in der
              Gruppe. Sobald ein Server seinen maxconn-Wert erreicht, wird der
              nächste verwendet. Der Algorithmus ist ohne maxconn-Einstellung
              nicht sinnvoll. Er soll stets möglichst wenige Server verwenden,
              damit zusätzliche Server in Zeiten geringer Last ausgeschaltet
              werden können. Der Algorithmus ignoriert das Servergewicht und
              ist für lange Sitzungen wie RDP oder IMAP nützlicher als für
              HTTP, kann aber auch dort hilfreich sein. Für einen effizienten
              Einsatz wird empfohlen, dass eine Cloud-Steuerung die
              Serverauslastung regelmäßig prüft und ungenutzte Server abschaltet.
              Ebenso sollte sie die Backend-Warteschlange regelmäßig prüfen
              und bei wachsender Warteschlange weitere Server einschalten.
              Alternativ kann "http-check send-state" die Server über die
              Last informieren. Dieser Algorithmus kann nicht im LOG-Modus
              verwendet werden.

  hash        Erwartet als Argument einen regulären Sample-Ausdruck. Der
              Ausdruck wird für jede Anfrage ausgewertet und anhand des
              konfigurierten hash-type gehasht. Der Hash wird durch das
              Gesamtgewicht der laufenden Server geteilt, um den Server zu
              bestimmen, der die Anfrage erhält. Dies kann "source", "uri",
              "hdr()", "url_param()" oder "rdp-cookie" ersetzen, um etwa einen
              Konverter zu verwenden, die Auswertung zu verfeinern oder Daten
              aus lokalen Variablen zu extrahieren. Sind die Daten nicht
              verfügbar, wird Round-Robin verwendet. Dieser Algorithmus ist
              standardmäßig statisch: Eine Änderung des Servergewichts im
              laufenden Betrieb hat keine Wirkung. Mit "hash-type" lässt
              sich dies ändern. Der Algorithmus kann nicht für Backends im
              LOG-Modus verwendet werden; dafür ist "log-hash" vorgesehen.

  source      Die Quell-IP-Adresse wird gehasht und durch das Gesamtgewicht
              der laufenden Server geteilt, um den Server zu bestimmen, der
              die Anfrage erhält. Dadurch erreicht dieselbe Client-IP-Adresse
              immer denselben Server, solange kein Server ausfällt oder
              verfügbar wird. Ändert sich das Hash-Ergebnis, weil sich die
              Zahl laufender Server ändert, werden viele Clients einem anderen
              Server zugewiesen. Dieser Algorithmus wird meist im TCP-Modus
              verwendet, in dem kein Cookie eingefügt werden kann. Er kann
              auch im Internet verwendet werden, um Clients, die
              Sitzungscookies ablehnen, nach Möglichkeit an denselben Server
              zu binden. Der Algorithmus ist standardmäßig statisch: Eine
              Änderung des Servergewichts im laufenden Betrieb hat keine
              Wirkung. Mit "hash-type" lässt sich dies ändern. Siehe auch
              die Option "hash" oben. Dieser Algorithmus kann nicht für
              Backends im LOG-Modus verwendet werden.

  uri         Dieser Algorithmus hasht entweder den linken Teil der URI vor
              dem Fragezeichen oder die gesamte URI, wenn der Parameter
              "whole" vorhanden ist. Der Hash-Wert wird durch das
              Gesamtgewicht der laufenden Server geteilt. Das Ergebnis
              bestimmt, welcher Server die Anfrage erhält. Dadurch wird
              dieselbe URI immer demselben Server zugewiesen, solange kein
              Server verfügbar wird oder ausfällt. Dies wird bei Proxy-Caches
              und Virenschutz-Proxys verwendet, um die Cache-Trefferrate zu
              maximieren. Dieser Algorithmus kann nur in einem HTTP-Backend
              verwendet werden. Er ist standardmäßig statisch: Eine Änderung
              des Servergewichts im laufenden Betrieb hat keine Wirkung.
              Mit "hash-type" lässt sich dies ändern.

              Dieser Algorithmus unterstützt die optionalen Parameter "len"
              und "depth", jeweils gefolgt von einer positiven ganzen Zahl.
              Diese Optionen können helfen, wenn die Lastverteilung allein
              anhand des URI-Anfangs erfolgen soll. Der Parameter "len" gibt
              an, wie viele Zeichen am Anfang der URI der Algorithmus für
              die Hash-Berechnung berücksichtigen sollte. "len" auf 1 zu
              setzen, ist selten sinnvoll, da die meisten URIs mit "/"
              beginnen.

              Der Parameter "depth" gibt die maximale Verzeichnistiefe für
              die Hash-Berechnung an. Jeder Schrägstrich in der Anfrage zählt
              als eine Ebene. Sind beide Parameter angegeben, endet die
              Auswertung, sobald einer der Grenzwerte erreicht ist.

              Der Parameter "path-only" gibt an, dass der Hash-Schlüssel
              beim ersten '/' des Pfades beginnt. Damit lässt sich der
              Authority-Teil absoluter URIs ignorieren und sicherstellen,
              dass HTTP/1- und HTTP/2-URIs denselben Hash liefern. Siehe auch
              die Option "hash" oben.

  url_param   Der als Argument angegebene URL-Parameter wird in der
              Abfragezeichenfolge jeder HTTP-GET-Anfrage gesucht.

              Mit dem Modifikator "check_post" wird der Parameter im Inhalt
              einer HTTP-POST-Anfrage gesucht, falls er nicht in der
              Abfragezeichenfolge nach dem Fragezeichen ('?') in der URL
              gefunden wird. Die Analyse des Nachrichtenkörpers beginnt erst,
              wenn entweder die angekündigte Datenmenge empfangen wurde oder
              der Anfragepuffer voll ist. Im unwahrscheinlichen Fall einer
              Chunked-Kodierung wird nur der erste Chunk durchsucht. Durch
              eine Chunk-Grenze getrennte Parameterwerte werden gegebenenfalls
              zufällig verteilt. Dieses Schlüsselwort unterstützte früher
              einen optionalen Parameter <max_wait>, der heute ignoriert wird.

              Folgt auf den gefundenen Parameter ein Gleichheitszeichen ('=')
              mit einem Wert, wird der Wert gehasht und durch das
              Gesamtgewicht der laufenden Server geteilt. Das Ergebnis
              bestimmt, welcher Server die Anfrage erhält.

              Damit lassen sich Benutzerkennungen in Anfragen verfolgen und
              sicherstellen, dass dieselbe Benutzer-ID immer an denselben
              Server gesendet wird, solange kein Server verfügbar wird oder
              ausfällt. Wird kein Wert oder kein Parameter gefunden, wird
              Round-Robin verwendet. Dieser Algorithmus kann nur in einem
              HTTP-Backend verwendet werden. Er ist standardmäßig statisch:
              Eine Änderung des Servergewichts im laufenden Betrieb hat keine
              Wirkung. Mit "hash-type" lässt sich dies ändern. Siehe auch
              die Option "hash" oben.

  hdr(<name>) Der HTTP-Header <name> wird in jeder HTTP-Anfrage gesucht. Wie
              bei der entsprechenden ACL-Funktion 'hdr()' wird beim
              Headernamen in Klammern nicht zwischen Groß- und Kleinschreibung
              unterschieden. Fehlt der Header oder enthält er keinen Wert,
              wird stattdessen der Algorithmus roundrobin verwendet.

              Mit dem optionalen Parameter 'use_domain_only' lässt sich der
              Hash-Algorithmus bei bestimmten Headern wie 'Host' auf den
              Hauptteil der Domain beschränken. Im Host-Wert "haproxy.1wt.eu"
              wird beispielsweise nur "1wt" berücksichtigt.

              Der Algorithmus ist standardmäßig statisch: Eine Änderung des
              Servergewichts im laufenden Betrieb hat keine Wirkung.
              Mit "hash-type" lässt sich dies ändern. Siehe auch die
              Option "hash" oben.

  random
  random(<draws>)
              Als Schlüssel für die konsistente Hash-Funktion wird eine
              Zufallszahl verwendet. Dadurch werden die Servergewichte
              berücksichtigt; dynamische Gewichtsänderungen und neu
              hinzugefügte Server wirken sofort. Zufällige Lastverteilung
              kann bei großen Servergruppen oder häufigem Hinzufügen und
              Entfernen von Servern nützlich sein. Sie kann die Überlastung
              einzelner Server vermeiden, die roundrobin oder leastconn in
              dieser Situation verursachen könnten. Mit hash-balance-factor
              lässt sich die Fairness der Lastverteilung weiter verbessern,
              besonders bei stark schwankenden Antwortzeiten der Server.
              Ist das Argument <draws> vorhanden, muss es eine ganze Zahl
              von mindestens eins sein. Sie gibt die Zahl der Ziehungen an,
              bevor der am wenigsten ausgelastete dieser Server gewählt wird.
              Es wurde nachgewiesen, dass bereits die Auswahl des weniger
              ausgelasteten von zwei Servern die Fairness des Algorithmus
              deutlich verbessert: Der am stärksten ausgelastete Server
              einer Gruppe wird nie ausgewählt, und Verzerrungen durch eine
              ungleichmäßige Verteilung der konsistenten Liste entfallen.
              Höhere Werte N schließen die N-1 am stärksten ausgelasteten
              Server aus, kosten jedoch Leistung. Bei sehr hohen Werten
              nähert sich das Ergebnis dem von leastconn, wird aber viel
              langsamer berechnet. Bei großen Servergruppen mit sehr
              niedriger Last oder perfekter Verteilung führt der Lastvergleich
              zudem häufig zu Gleichständen. Haben alle verglichenen Server
              dieselbe Last, werden deshalb ihre Anfrageraten während der
              letzten Sekunde verglichen. Damit wird die Servernutzung im
              zeitlichen Verlauf ähnlich wie bei roundrobin besser verteilt,
              und Ungleichmäßigkeiten des konsistenten Hashings werden
              ausgeglichen. Der Standardwert ist 2 und liefert im Allgemeinen
              eine sehr gute Verteilung und Leistung. Bei großen Gruppen mit
              geringer Last, also weniger als einigen Anfragen pro Sekunde
              und Server, kann eine Erhöhung auf 3 oder sogar 4 helfen.
              Der Algorithmus ist auch als Power of Two Random Choices
              bekannt und wird hier beschrieben:
              http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf

              Bei Backends im LOG-Modus wird die Anzahl der Ziehungen
              ignoriert und nur eine Zufallszahl gezogen, da dort kein
              Konzept der Serverlast besteht. Zufällige Protokollverteilung
              kann bei großen Gruppen oder häufigem Hinzufügen und Entfernen
              von Servern aus dem Pool verfügbarer Server nützlich sein.
              Sie kann die Überlastung einzelner Server vermeiden, die
              roundrobin in dieser Situation verursachen könnte.

  rdp-cookie
  rdp-cookie(<name>)
              Das RDP-Cookie <name>, bei fehlender Angabe "mstshash", wird
              für jede eingehende TCP-Anfrage gesucht und gehasht. Wie bei
              der entsprechenden ACL-Funktion 'req.rdp_cookie()' wird bei
              seinem Namen nicht zwischen Groß- und Kleinschreibung
              unterschieden. Dieser Mechanismus ist als eingeschränkte Form
              der Sitzungsbindung nützlich, da derselbe Benutzer oder dieselbe
              Sitzungs-ID stets an denselben Server gesendet werden kann.
              Wird das Cookie nicht gefunden, wird stattdessen der normale
              Algorithmus roundrobin verwendet.

              Damit dies funktioniert, muss das Frontend sicherstellen, dass
              bereits ein RDP-Cookie im Anfragepuffer vorhanden ist. Dazu muss
              eine Regel 'tcp-request content accept' mit einer ACL
              'req.rdp_cookie_cnt' kombiniert werden.

              Der Algorithmus ist standardmäßig statisch: Eine Änderung des
              Servergewichts im laufenden Betrieb hat keine Wirkung.
              Mit "hash-type" lässt sich dies ändern. Siehe auch die
              Option "hash" oben.

  log-hash    Erwartet als Argument eine durch Kommas getrennte Liste von
              Konvertern. Diese werden nacheinander auf die eingehende
              Protokollnachricht angewendet. Das Ergebnis wird in eine
              Zeichenfolge umgewandelt und anschließend anhand des
              konfigurierten hash-type gehasht. Der resultierende Hash wählt
              den Zielserver unter den im Protokoll-Backend deklarierten
              Servern aus. Ziel des Algorithmus ist, mithilfe von
              Zeichenfolgenkonvertern einen Schlüssel aus der fertigen
              Protokollnachricht zu extrahieren und anhand seines Hashes
              denselben Server beizubehalten. Zurzeit werden nur
              "map-based"-Hashes unterstützt. Dieser Algorithmus kann nur
              für Backends im LOG-Modus verwendet werden; für andere ist
              stattdessen "hash" vorgesehen.

  sticky      Versucht, möglichst lange denselben Server zu verwenden. Der
              erste Server in der Liste verfügbarer Server erhält sämtliche
              Protokollnachrichten. Wechselt er in den Zustand DOWN, übernimmt
              der nächste Server in der Liste. Wird ein zuvor als DOWN
              markierter Server wieder UP, wird er am Listenende angefügt.
              Der gebundene Server ändert sich daher erst, wenn er DOWN wird.

<arguments> ist eine optionale Liste von Argumenten, die einige Algorithmen
            benötigen können. Zurzeit unterstützen nur "url_param", "uri"
            und "log-hash" ein optionales Argument.

Der Lastverteilungsalgorithmus eines Backends wird auf “random” festgelegt, wenn weder ein anderer Algorithmus noch ein Modus oder eine Option festgelegt wurde. Der Algorithmus darf für jedes Backend nur einmal festgelegt werden.

Bei Authentifizierungsschemata, die dieselbe Verbindung erfordern, wie NTLM, dürfen URI-basierte Algorithmen nicht verwendet werden, da dies dazu führen würde, dass nachfolgende Anfragen an verschiedene Backend-Server weitergeleitet werden, wodurch die ungültigen Annahmen verletzt würden, auf denen NTLM beruht.

TCP/HTTP-Beispiele:

balance roundrobin
balance url_param userid
balance url_param session_id check_post 64
balance hdr(User-Agent)
balance hdr(host)
balance hdr(Host) use_domain_only
balance hash req.cookie(clientid)
balance hash var(req.client_id)
balance hash req.hdr_ip(x-forwarded-for,-1),ipmask(24)

LOG-Backend-Beispiele:

global
  log backend@mylog-rrb local0 # send all logs to mylog-rrb backend
  log backend@mylog-hash local0 # send all logs to mylog-hash backend

backend mylog-rrb
  mode log
  balance roundrobin

  server s1 udp@127.0.0.1:514 # will receive 50% of log messages
  server s2 udp@127.0.0.1:514

backend mylog-hash
  mode log

  # extract "METHOD URL PROTO" at the end of the log message,
  # and let haproxy hash it so that log messages generated from
  # similar requests get sent to the same syslog server:
  balance log-hash 'field(-2,\")'

  # server list here
  server s1 127.0.0.1:514
  #...

Hinweis: Die folgenden Einschränkungen und Besonderheiten beim Einsatz der “check_post”-Erweiterung mit “url_param” müssen berücksichtigt werden:

- Alle POST-Anfragen kommen für die Prüfung infrage, da nicht feststellbar ist, ob die Parameter im Textkörper oder in der Entität enthalten sind, die binäre Daten enthalten kann. Daher kann eine andere Methode erforderlich sein, um die Prüfung von POST-Anfragen einzuschränken, die keine URL-Parameter im Textkörper enthalten. (siehe acl http_end)

- Die Verwendung eines `<max_wait>`-Werts, der größer als die Größe des Anfrage-Puffers ist, ergibt keinen Sinn und ist nutzlos. Die Puffergröße wird beim Kompilieren festgelegt und beträgt standardmäßig 16 kB.

- Content-Encoding wird nicht unterstützt, die Parametersuche wird wahrscheinlich fehlschlagen; die Lastverteilung fällt auf Round Robin zurück.

- Expect: 100-continue wird nicht unterstützt, die Lastverteilung fällt auf Round Robin zurück.

- Transfer-Encoding (RFC7230 3.3.1) wird nur im ersten Chunk unterstützt. Wenn der gesamte Parameterwert nicht im ersten Chunk enthalten ist, ist die Auswahl des Servers undefiniert (genauer gesagt wird sie dadurch bestimmt, wie wenig tatsächlich im ersten Chunk enthalten war).

- Diese Funktion unterstützt nicht die Erzeugung einer Antwort mit dem Status 100, 411 oder 501.

- In einigen Fällen kann die Aktivierung von "check_post" einen Versuch auslösen, den gesamten Inhalt eines Nachrichtenkörpers zu durchsuchen. Die Suche endet normalerweise, wenn lineare Leerraumzeichen oder Steuerzeichen gefunden werden, was auf das Ende einer möglichen Liste von URL-Parametern hinweist. Dies ist wahrscheinlich kein Problem bei SGML-artigen Nachrichtenkörpern.

Siehe auch: “dispatch”, “cookie”, “transparent”, “hash-type”.

be-unpublished

be-unpublished

Das Backend im unveröffentlichten Zustand starten.

Kann in folgenden Kontexten verwendet werden: tcp, http, log

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | nein | ja | ja

Dadurch werden alle use_backend- und default_backend-Regeln aus einem anderen Proxy, die auf den aktuellen Proxy verweisen, ignoriert, und die nächsten Regeln zur inhaltsabhängigen Umschaltung werden ausgewertet. Dies kann jedoch über eine “force-be-switch”-Regel umgangen werden.

Dieser Zustand ähnelt dem deaktivierten Zustand, unterscheidet sich jedoch in einigen Punkten. Erstens wird ein unveröffentlichtes Backend weiterhin vollständig initialisiert, einschließlich der Health Checks der Server, die weiterhin aktiv bleiben. Schließlich kann ein Backend mit dem Befehl “publish backend” über die CLI veröffentlicht werden. Siehe das Management-Handbuch.

Siehe auch: “force-be-switch”

bind [<address>]:<port_range> [, ...] [param*]

bind [<address>]:<port_range> [, ...] [param*]
bind /<path> [, ...] [param*]

Eine oder mehrere Adressen und/oder Ports festlegen, an denen ein Frontend lauscht.

Kann in folgenden Kontexten verwendet werden: tcp, http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | ja | ja | nein

Argumente:

<address>     ist optional und kann ein Hostname, eine IPv4-Adresse, eine
              IPv6-Adresse oder '*' sein. Sie bezeichnet die Adresse, an der
              das Frontend lauscht. Ohne Angabe werden alle IPv4-Adressen des
              Systems verwendet. Gleiches gilt für '*' oder die besondere
              Systemadresse "0.0.0.0". Die IPv6-Entsprechung lautet '::'. Für
              UDP sind beim Binden an mehrere Adressen bestimmte Funktionen
              des Betriebssystems (OS) erforderlich, damit Antworten die richtige
              Netzwerkschnittstelle und Quelladresse verwenden. QUIC-Listener
              daher nur auf ausreichend modernen Systemen an mehrere
              Adressen binden.

              Optional kann der Adresse ein Adressfamilienpräfix vorangestellt
              werden, um die Familie unabhängig vom Adressformat zu erzwingen.
              Damit lässt sich beispielsweise der Pfad zu einem Unix-Socket
              ohne Schrägstrich ('/') angeben. Zurzeit werden diese Präfixe
              unterstützt:
                - 'ipv4@'  -> Adresse ist immer IPv4
                - 'ipv6@'  -> Adresse ist immer IPv6
                - 'udp@'   -> Adresse wird als IPv4 oder IPv6 aufgelöst und
                  das Protokoll UDP verwendet. Diese Listener werden derzeit
                  nur in log-forward-Abschnitten unterstützt.
                - 'udp4@'  -> Adresse ist immer IPv4 und das Protokoll UDP
                  wird verwendet. Diese Listener werden derzeit nur in
                  log-forward-Abschnitten unterstützt.
                - 'udp6@'  -> Adresse ist immer IPv6 und das Protokoll UDP
                  wird verwendet. Diese Listener werden derzeit nur in
                  log-forward-Abschnitten unterstützt.
                - 'unix@'  -> Adresse ist ein Pfad zu einem lokalen Unix-Socket
                - 'abns@'  -> Adresse liegt im abstrakten Namensraum (nur Linux).
                - 'abnsz@'  -> Adresse liegt im abstrakten Namensraum (nur Linux),
                   wird jedoch ausdrücklich mit einem Nullzeichen beendet.
                   sun_path wird also nicht mit \0 aufgefüllt. Dies ist für
                   die Verbindung mit Programmen nützlich, die die von haproxy
                   standardmäßig verwendete abns-Namenslogik nicht umsetzen.
                - 'fd@<n>' -> vom übergeordneten Prozess geerbten Dateideskriptor
                  <n> verwenden. Der fd muss gebunden sein und kann bereits
                  lauschen, muss dies aber nicht.
                - 'sockpair@<n>'-> wie fd@, jedoch muss der fd eines verbundenen
                  Unix-Sockets oder eines Socketpaars verwendet werden. bind
                  wartet auf einen über den Unix-Socket empfangenen FD und
                  verwendet ihn wie den FD eines accept(). Sollte mit Vorsicht
                  verwendet werden.
                - 'quic4@' -> Adresse wird als IPv4 aufgelöst und das Protokoll
                  UDP verwendet. Für optimale Leistung bei hohem Datenverkehr
                  sollte "tune.quic.fe.sock-per-conn
                  default-on" beibehalten werden. Andernfalls werden
                  QUIC-Verbindungen über den Listener-Socket multiplexiert.
                  Alternativ können QUIC-Listener-Instanzen auf mehrere
                  Threads verteilt werden, beispielsweise mit "shards", um
                  zumindest die Konkurrenz zwischen Threads zu verringern.
                - 'quic6@' -> Adresse wird als IPv6 aufgelöst und das Protokoll
                  UDP verwendet. Der Leistungshinweis zu QUIC über IPv4 gilt
                  auch hier.
                - 'rhttp@' [ EXPERIMENTAL ] -> für umgekehrtes HTTP verwendet.
                  Die Adresse muss einen Server im Format
                  '<backend>/<server>' angeben. Über diesen Server werden
                  Verbindungen zu einer entfernten Adresse aufgebaut. Der
                  Listener versucht, "nbconn" Verbindungen aufrechtzuerhalten.
                  Diese Funktion ist experimentell und erfordert eine Zeile
                  mit "expose-experimental-directives" vor dieser bind-Zeile.

              Im Adressparameter können Umgebungsvariablen verwendet werden;
              siehe Abschnitt 2.3 zu Umgebungsvariablen.

<port_range>  ist entweder ein einzelner TCP-Port oder ein Portbereich, an dem
              der Proxy Verbindungen für die oben angegebene IP-Adresse
              annimmt. Für TCP-Listener ist der Port zwingend erforderlich.
              Bei einer IPv6-Adresse ist der Port immer die Zahl nach dem
              letzten Doppelpunkt (':'). Ein Bereich kann folgendermaßen
              angegeben werden:
               - als numerischer Port (z. B. '80')
               - als durch Bindestrich getrennter Portbereich mit ausdrücklich
                 angegebenen unteren und oberen Grenzen (z. B. '2000-2100'),
                 die beide zum Bereich gehören.

              Bei Portbereichen ist besondere Vorsicht erforderlich: Jedes
              Paar <address:port> belegt einen Socket, also einen
              Dateideskriptor. Ein einfacher Bereich kann daher viele
              Deskriptoren verbrauchen und alle verfügbaren Sockets aufbrauchen.
              Zudem darf jedes Paar <address:port> unter allen Instanzen auf
              demselben System nur einmal verwendet werden. Das Binden an
              Ports unter 1024 erfordert zum Programmstart im Allgemeinen
              besondere Berechtigungen, die vom Parameter 'uid' unabhängig sind.

<path>        ist ein UNIX-Socket-Pfad, der mit einem Schrägstrich ('/') beginnt.
              Dies ist eine Alternative zum TCP-Listener-Port. HAProxy nimmt
              dann UNIX-Verbindungen an dem Socket an diesem Pfad entgegen.
              Der Pfad muss mit einem Schrägstrich beginnen und ist
              standardmäßig absolut. Er kann relativ zu dem Präfix sein,
              das mit "unix-bind" im global-Abschnitt festgelegt ist. Die
              Gesamtlänge von Präfix und Socket-Pfad darf die Systemgrenzen
              für UNIX-Sockets nicht überschreiten; diese liegen häufig bei
              107 Zeichen.

<param*>      ist eine Liste von Parametern, die für alle auf derselben Zeile
              deklarierten Sockets gelten. Diese zahlreichen Parameter hängen
              vom Betriebssystem (OS) und den Build-Optionen ab und werden in einem
              eigenen Abschnitt beschrieben. Weitere Einzelheiten stehen in
              Abschnitt 5.

Es ist möglich, eine durch Kommas getrennte Liste von address:port-Kombinationen anzugeben. Das Frontend lauscht dann an allen diesen Adressen. Es gibt keine feste Grenze für die Anzahl der Adressen und Ports, an denen ein Frontend lauschen kann, ebenso wenig wie für die Anzahl der “bind”-Anweisungen in einem Frontend.

Beispiel:

listen http_proxy
    bind :80,:443
    bind 10.0.0.1:10080,10.0.0.1:10443
    bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy

listen http_https_proxy
    bind :80
    bind :443 ssl crt /etc/haproxy/site.pem

listen http_https_proxy_explicit
    bind ipv6@:80
    bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
    bind unix@ssl-frontend.sock user root mode 600 accept-proxy

listen external_bind_app1
    bind "fd@${FD_APP1}"

listen h3_quic_proxy
    bind quic4@10.0.0.1:8888 ssl crt /etc/mycrt

Hinweis: Bei Sockets im abstrakten Namensraum von Linux verwenden HAProxy-Sockets der Familie “abns” die gesamte Länge von sun_path als Adresslänge. Andere Programme wie socat verwenden standardmäßig nur die Länge der Zeichenkette. Übergeben Sie der Definition eines abstrakten Sockets in socat die Option “,unix-tightsocklen=0”, um Kompatibilität mit HAProxy zu erreichen, oder verwenden Sie stattdessen die HAProxy-Socket-Familie “abnsz”.

Siehe auch: “source”, “option forwardfor”, “unix-bind” und die PROXY-Protokoll-Dokumentation sowie Abschnitt 5 zu Bind-Optionen.

capture cookie <name> len <length>

capture cookie <name> len <length>

Ein Cookie in der Anfrage und in der Antwort erfassen und protokollieren.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | ja | ja | nein

Argumente:

<name>    ist der Anfang des Namens des zu erfassenden Cookies. Für einen
          exakten Namensvergleich genügt ein angehängtes Gleichheitszeichen
          ('='). Der vollständige Name erscheint im Protokoll. Dies ist bei
          Anwendungsservern nützlich, die sowohl Cookie-Name als auch -Wert
          anpassen (z. B. ASPSESSIONXXX).

<length>  ist die maximale Zahl protokollierter Zeichen, einschließlich
          Cookie-Name, Gleichheitszeichen und Wert im üblichen Format
          "name=value". Überschreitet die Zeichenfolge <length>, wird sie
          rechts abgeschnitten.

Es wird nur das erste Cookie erfasst. Sowohl die “cookie”-Anfrage-Header als auch die “set-cookie”-Antwort-Header werden überwacht. Dies ist besonders nützlich, um Anwendungsfehler zu erkennen, die zu Sitzungsüberschneidungen oder -diebstahl zwischen Benutzern führen, da die Cookies eines Benutzers normalerweise nur auf der Anmeldeseite geändert werden können.

Wenn das Cookie vom Client nicht übermittelt wurde, wird die zugehörige Protokollspalte mit “-” angezeigt. Wenn eine Anfrage keine Zuweisung eines Cookies durch den Server verursacht, wird in der Antwortspalte “-” angezeigt.

Die Erfassung erfolgt nur im Frontend, da sichergestellt werden muss, dass das Protokollformat für ein bestimmtes Frontend nicht je nach Backend wechselt. Dies könnte sich in Zukunft ändern. Es kann nur eine “capture cookie”-Anweisung pro Frontend geben. Die maximale Erfassungslänge wird durch die globale Einstellung “tune.http.cookielen” festgelegt und beträgt standardmäßig 63 Zeichen. Es ist nicht möglich, eine Erfassung in einem “defaults”-Abschnitt anzugeben.

Beispiel:

capture cookie ASPSESSION len 32

Siehe auch: “capture request header”, “capture response header” sowie Abschnitt 8 zur Protokollierung.

capture request header <name> len <length>

capture request header <name> len <length>

Das letzte Vorkommen des angegebenen Anfrageheaders erfassen und protokollieren.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | ja | ja | nein

Argumente:

<name>    ist der Name des zu erfassenden Headers. Bei Headernamen wird
          nicht zwischen Groß- und Kleinschreibung unterschieden. Üblicherweise
          werden sie jedoch wie in den Anfragen geschrieben, mit einem
          Großbuchstaben am Anfang jedes Wortes. Der Headername erscheint
          nicht im Protokoll, sondern nur sein Wert; die Position im Protokoll
          bleibt jedoch erhalten.

<length>  ist die maximale Zahl der Zeichen, die aus dem Wert extrahiert und
          protokolliert werden. Überschreitet die Zeichenfolge <length>, wird
          sie rechts abgeschnitten.

Der vollständige Wert des letzten Vorkommens des Headers wird erfasst. Der Wert wird in geschweiften Klammern (’{}’) in das Protokoll aufgenommen. Werden mehrere Header erfasst, werden sie durch einen senkrechten Strich (’|’) getrennt und in derselben Reihenfolge angezeigt, in der sie in der Konfiguration deklariert wurden. Nicht vorhandene Header werden als leere Zeichenkette protokolliert. Häufig erfasste Anfrageheader sind das Feld “Host” in Umgebungen mit virtuellem Hosting, “Content-length” bei Unterstützung von Uploads, “User-agent” zur schnellen Unterscheidung echter Benutzer von Robotern und “X-Forwarded-For” in Umgebungen mit vorgeschalteten Proxys, um den Ursprung der Anfrage festzustellen.

Beim Erfassen von Headern wie “User-agent” können auch Leerzeichen protokolliert werden, was die Protokollanalyse erschwert. Wählen Sie daher die protokollierten Werte sorgfältig aus, wenn Ihr Protokollparser die geschweiften Klammern nicht zuverlässig auswerten kann.

Weder die Anzahl noch die Länge der erfassten Anfrageheader ist begrenzt. Es ist jedoch sinnvoll, beide gering zu halten, um den Speicherbedarf pro Stream zu begrenzen. Damit das Protokollformat für ein bestimmtes Frontend einheitlich bleibt, kann die Headererfassung nur in einem Frontend deklariert werden. In einem “defaults”-Abschnitt kann keine Erfassung angegeben werden.

Beispiel:

capture request header Host len 15
capture request header X-Forwarded-For len 15
capture request header Referer len 15

Siehe auch: “capture cookie”, “capture response header” sowie Abschnitt 8 zur Protokollierung.

capture response header <name> len <length>

capture response header <name> len <length>

Das letzte Vorkommen des angegebenen Antwortheaders erfassen und protokollieren.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | ja | ja | nein

Argumente:

<name>    ist der Name des zu erfassenden Headers. Bei Headernamen wird
          nicht zwischen Groß- und Kleinschreibung unterschieden. Üblicherweise
          werden sie jedoch wie in der Antwort geschrieben, mit einem
          Großbuchstaben am Anfang jedes Wortes. Der Headername erscheint
          nicht im Protokoll, sondern nur sein Wert; die Position im Protokoll
          bleibt jedoch erhalten.

<length>  ist die maximale Zahl der Zeichen, die aus dem Wert extrahiert und
          protokolliert werden. Überschreitet die Zeichenfolge <length>, wird
          sie rechts abgeschnitten.

Der vollständige Wert des letzten Vorkommens des Headers wird erfasst. Das Ergebnis wird nach den erfassten Anfrageheadern in geschweiften Klammern (’{}’) in das Protokoll aufgenommen. Werden mehrere Header erfasst, werden sie durch einen senkrechten Strich (’|’) getrennt und in derselben Reihenfolge angezeigt, in der sie in der Konfiguration deklariert wurden. Nicht vorhandene Header werden als leere Zeichenkette protokolliert. Häufig erfasste Antwortheader sind “Content-length”, der die erwartete Anzahl zurückgegebener Bytes angibt, und “Location”, um Weiterleitungen nachzuverfolgen.

Weder die Anzahl noch die Länge der erfassten Antwortheader ist begrenzt. Es ist jedoch sinnvoll, beide gering zu halten, um den Speicherbedarf pro Stream zu begrenzen. Damit das Protokollformat für ein bestimmtes Frontend einheitlich bleibt, kann die Headererfassung nur in einem Frontend deklariert werden. In einem “defaults”-Abschnitt kann keine Erfassung angegeben werden.

Beispiel:

capture response header Content-length len 9
capture response header Location len 15

Siehe auch: “capture cookie”, “capture request header” sowie Abschnitt 8 zur Protokollierung.

clitcpka-cnt <count>

clitcpka-cnt <count>

Die maximale Anzahl von Keepalive-Prüfungen festlegen, die TCP auf der Clientseite senden soll, bevor es die Verbindung trennt.

Kann in folgenden Kontexten verwendet werden: tcp, http, log

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | nein

Argumente:

<count>   ist die maximale Zahl der Keepalive-Prüfungen.

Dieses Schlüsselwort entspricht der Socket-Option TCP_KEEPCNT. Wird es nicht angegeben, wird der systemweite TCP-Parameter (tcp_keepalive_probes) verwendet. Die Verfügbarkeit dieser Einstellung hängt vom Betriebssystem ab. Unter Linux funktioniert sie bekanntermaßen.

Siehe auch: “option clitcpka”, “clitcpka-idle”, “clitcpka-intvl”.

clitcpka-idle <timeout>

clitcpka-idle <timeout>

Die Zeit festlegen, die eine Verbindung inaktiv bleiben muss, bevor TCP Keepalive-Prüfungen sendet, sofern das Senden von TCP-Keepalive-Paketen auf der Clientseite aktiviert ist.

Kann in folgenden Kontexten verwendet werden: tcp, http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | nein

Argumente:

<timeout> ist die Zeit, die eine Verbindung inaktiv bleiben muss, bevor
          TCP Keepalive-Prüfungen sendet. Standardmäßig wird sie in Sekunden
          angegeben. Jede andere Einheit ist möglich, wenn sie wie am Anfang
          dieses Dokuments erläutert an die Zahl angehängt wird.

Dieses Schlüsselwort entspricht der Socket-Option TCP_KEEPIDLE. Wird es nicht angegeben, wird der systemweite TCP-Parameter (tcp_keepalive_time) verwendet. Die Verfügbarkeit dieser Einstellung hängt vom Betriebssystem ab. Unter Linux funktioniert sie bekanntermaßen.

Siehe auch: “option clitcpka”, “clitcpka-cnt”, “clitcpka-intvl”.

clitcpka-intvl <timeout>

clitcpka-intvl <timeout>

Den zeitlichen Abstand zwischen einzelnen Keepalive-Prüfungen auf der Clientseite festlegen.

Kann in folgenden Kontexten verwendet werden: tcp, http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | nein

Argumente:

<timeout> ist die Zeit zwischen einzelnen Keepalive-Prüfungen.
          Standardmäßig wird sie in Sekunden angegeben. Jede andere Einheit
          ist möglich, wenn sie wie am Anfang dieses Dokuments erläutert
          an die Zahl angehängt wird.

Dieses Schlüsselwort entspricht der Socket-Option TCP_KEEPINTVL. Wird es nicht angegeben, wird der systemweite TCP-Parameter (tcp_keepalive_intvl) verwendet. Die Verfügbarkeit dieser Einstellung hängt vom Betriebssystem ab. Unter Linux funktioniert sie bekanntermaßen.

Siehe auch: “option clitcpka”, “clitcpka-cnt”, “clitcpka-idle”.

compression algo <algorithm> ...

compression algo <algorithm> ...
compression algo-req <algorithm>
compression algo-res <algorithm>
compression type <mime type> ...

HTTP-Komprimierung aktivieren.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | ja

Argumente:

algo     gefolgt von der Liste unterstützter Kompressionsalgorithmen für
         Antworten (veraltetes Schlüsselwort).
algo-req gefolgt vom Kompressionsalgorithmus für Anfragen (es wird nur einer
  angegeben).
algo-res gefolgt von der Liste unterstützter Kompressionsalgorithmen für
         Antworten.
type     gefolgt von der Liste der MIME-Typen, die in Antworten komprimiert
         werden (veraltetes Schlüsselwort).
type-req gefolgt von der Liste der MIME-Typen, die in Anfragen komprimiert
         werden.
type-res gefolgt von der Liste der MIME-Typen, die in Antworten komprimiert
         werden.

Derzeit werden folgende Algorithmen unterstützt:

identity     dient hauptsächlich der Fehlersuche und war bei der Entwicklung
             der Kompressionsfunktion nützlich. Identity verändert die Daten
             nicht.

gzip         verwendet gzip-Kompression. Diese Einstellung ist nur verfügbar,
             wenn Unterstützung für zlib oder libslz einkompiliert wurde.

deflate      wie "gzip", jedoch mit dem deflate-Algorithmus und dem zlib-Format.
             Die Unterstützung dieses Algorithmus ist bei vielen Browsern
             unklar; neuere Browser unterstützen ihn überhaupt nicht. Von
             seiner Verwendung außerhalb von Experimenten wird dringend
             abgeraten. Diese Einstellung ist nur verfügbar, wenn Unterstützung
             für zlib oder libslz einkompiliert wurde.

raw-deflate  wie "deflate" ohne die zlib-Hülle; als Alternative verwendet,
             wenn der Browser "deflate" anfordert. Alle verbreiteten Browser
             verstehen dieses Format. Trotz des Verstoßes gegen die Standards
             funktioniert es bekanntermaßen besser als "deflate", zumindest
             in MSIE und einigen Safari-Versionen. Nicht zusammen mit
             "deflate" verwenden, sondern entweder das eine oder das andere,
             da beide auf dasselbe Accept-Encoding-Token reagieren. Diese
             Einstellung ist nur verfügbar, wenn Unterstützung für zlib oder
             libslz einkompiliert wurde.

Die Komprimierung wird abhängig vom Anfrageheader Accept-Encoding aktiviert. Bei identity wird dieser Header nicht berücksichtigt. Unterstützen die Backend-Server HTTP-Komprimierung, bleiben diese Direktiven wirkungslos: HAProxy erkennt die komprimierte Antwort und komprimiert sie nicht erneut. Unterstützen die Backend-Server keine HTTP-Komprimierung und enthält die Anfrage einen Accept-Encoding-Header, komprimiert HAProxy die zugehörige Antwort.

Die Komprimierung wird deaktiviert, wenn: * die Anfrage im Header “Accept-Encoding” keinen unterstützten Komprimierungsalgorithmus angibt * die Antwort nicht HTTP/1.1 oder höher verwendet * der HTTP-Statuscode keiner der Werte 200, 201, 202 oder 203 ist * die Antwort weder einen Header “Content-Length” noch einen Header “Transfer-Encoding” mit dem letzten Wert “chunked” enthält * die Antwort einen Header “Content-Type” enthält, dessen erster Wert mit “multipart” beginnt * die Antwort im Header “Cache-control” den Wert “no-transform” enthält * User-Agent auf “Mozilla/4” passt, sofern es sich nicht um MSIE 6 mit XP SP2 oder MSIE 7 und neuer handelt * die Antwort einen Header “Content-Encoding” enthält, der anzeigt, dass die Antwort bereits komprimiert ist (siehe compression offload) * die Antwort einen ungültigen Header “ETag” oder mehrere ETag-Header enthält * die Nutzdatengröße unter der Mindestgröße liegt (siehe compression minsize-res)

Hinweis: Die Komprimierung gibt keinen Warning-Header aus.

Beispiele:

compression algo gzip
compression type text/html text/plain

Siehe auch: “compression offload”, “compression direction”, “compression minsize-req” und “compression minsize-res”

compression minsize-req <size>

compression minsize-req <size>
compression minsize-res <size>

Die Mindestgröße der Nutzdaten in Bytes festlegen, ab der die Komprimierung angewendet wird.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | ja | ja | ja

Nutzdaten unterhalb dieser Größe werden nicht komprimiert. Dadurch entfällt unnötiger CPU-Aufwand für Daten, die von der Komprimierung nicht wesentlich profitieren würden. “minsize-req” gilt für Anfragen und “minsize-res” für Antworten. Der Standardwert ist 0.

compression offload

compression offload

HAProxy ausschließlich als Komprimierungsinstanz einsetzen.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend nein | ja | ja | ja

Die Einstellung “offload” bewirkt, dass HAProxy den Accept-Encoding-Header entfernt, um zu verhindern, dass Backend-Server Antworten komprimieren. Es wird dringend empfohlen, dies nicht zu tun, da sonst die gesamte Komprimierungsarbeit an der einzigen Stelle durchgeführt wird, an der HAProxy installiert ist. In bestimmten Bereitstellungsszenarien kann HAProxy jedoch vor einem fehlerhaften Gateway installiert sein, dessen fehlerhafte HTTP-Komprimierung nicht abgeschaltet werden kann. In diesem Fall kann HAProxy verwendet werden, um zu verhindern, dass das Gateway ungültige Nutzdaten ausgibt. In diesem Fall funktioniert das einfache Entfernen des Headers in der Konfiguration nicht, da es vor der Analyse des Headers angewendet wird und dadurch HAProxy am Komprimieren hindert. In solchen Szenarien sollte stattdessen die Einstellung “offload” verwendet werden.

Wird diese Einstellung in einem defaults-Abschnitt verwendet, wird eine Warnung ausgegeben und die Option ignoriert.

Siehe auch: “compression type”, “compression algo”, “compression direction”

compression direction <direction> (deprecated)

compression direction <direction> (deprecated)

Ermöglicht es HAProxy, sowohl Anfragen als auch Antworten zu komprimieren. Gültige Werte sind “request”, um nur Anfragen zu komprimieren, “response”, um nur Antworten zu komprimieren, oder “both”, wenn beide komprimiert werden sollen. Der Standardwert ist “response”.

Diese Anweisung ist nur relevant, wenn die veraltete “filter compression” aktiviert wurde. Bei expliziter Verwendung der Filter comp-req und comp-res ist die Komprimierungsrichtung redundant.

Kann in folgenden Kontexten verwendet werden: http

Siehe auch: “compression type”, “compression algo”, “compression offload”

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
              [ postonly ] [ preserve ] [ httponly ] [ secure ]
              [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
              [ dynamic ] [ attr <value> ]*

Cookiebasierte Sitzungsbindung in einem Backend aktivieren.

Kann in folgenden Kontexten verwendet werden: http

Kann in folgenden Abschnitten verwendet werden: defaults | frontend | listen | backend ja | nein | ja | ja

Argumente:

<name>    ist der Name des Cookies, das für die Sitzungsbindung überwacht,
          geändert oder eingefügt wird. Dieses Cookie wird dem Client in
          einem "Set-Cookie"-Header der Antwort gesendet und vom Client in
          allen Anfragen in einem "Cookie"-Header zurückgegeben. Der Name
          sollte besonders sorgfältig gewählt werden, damit er mit keinem
          möglichen Anwendungscookie kollidiert. Werden dieselben Backends
          möglicherweise von denselben Clients verwendet, etwa über HTTP/HTTPS,
          sollten außerdem für alle Backends unterschiedliche Cookie-Namen
          verwendet werden, wenn keine backendübergreifende Sitzungsbindung
          gewünscht ist.

rewrite   Dieses Schlüsselwort gibt an, dass der Server das Cookie bereitstellt
          und HAProxy dessen Wert ändern muss, um die Serverkennung darin
          einzutragen. Dieser Modus ist praktisch, wenn die Anwendung komplexe
          Kombinationen von "Set-cookie"- und "Cache-control"-Headern verwaltet.
          Sie kann dann entscheiden, ob ein Cookie zur Sitzungsbindung
          ausgegeben werden soll. Da alle Antworten überwacht werden sollten,
          funktioniert dieser Modus nicht im HTTP-Tunnelmodus. Sofern das
          Anwendungsverhalten nicht sehr komplex und/oder fehlerhaft ist,
          wird davon abgeraten, neue Installationen mit diesem Modus zu
          beginnen. Das Schlüsselwort ist mit "insert" und "prefix"
          unvereinbar.

insert    Dieses Schlüsselwort gibt an, dass HAProxy das Cookie zur
          Sitzungsbindung in Serverantworten einfügen muss, wenn der Client

          noch kein Cookie besitzt, das ihm den Zugriff auf diesen Server
          ermöglicht hätte. Ohne die Option "preserve" wird ein vom Server
          ausgegebenes Cookie desselben Namens vor der Verarbeitung entfernt.
          Daher lässt sich dieser Modus zur Umstellung bestehender
          Konfigurationen im Modus "rewrite" verwenden. Das Cookie ist nur
          ein Sitzungscookie und wird nicht auf dem Datenträger des Clients
          gespeichert. Standardmäßig sieht der Server die vom Client gesendeten
          Cookies, sofern nicht die Option "indirect" hinzugefügt wird.
          Wegen möglicher Cache-Effekte ist es im Allgemeinen sinnvoll, die
          Schlüsselwörter "nocache" oder "postonly" hinzuzufügen (siehe unten).
          Das Schlüsselwort "insert" ist mit "rewrite" und "prefix"
          unvereinbar.

prefix    Dieses Schlüsselwort gibt an, dass ein vorhandenes Cookie ergänzt
          wird, statt ein eigenes Cookie zur Sitzungsbindung zu verwenden.
          Dies kann in bestimmten Umgebungen erforderlich sein, wenn der
          Client nur ein einziges Cookie unterstützt und die Anwendung dieses
          bereits benötigt. Setzt der Server in diesem Fall ein Cookie namens
          <name>, werden ihm die Serverkennung und ein Trennzeichen vorangestellt.
          Dieses Präfix wird aus allen Clientanfragen entfernt, sodass der
          Server sein ursprüngliches Cookie vorfindet. Da alle Anfragen und
          Antworten verändert werden können, funktioniert dieser Modus nicht
          im Tunnelmodus. Das Schlüsselwort "prefix" ist mit "rewrite" und
          "insert" unvereinbar. Hinweis: Von der Kombination aus "indirect"
          und "prefix" wird dringend abgeraten, da Cookie-Aktualisierungen
          des Servers andernfalls nicht an Clients gesendet würden.

indirect  Mit dieser Option wird einem Client kein Cookie gesendet, wenn er
          bereits ein gültiges Cookie für den Server besitzt, der die Anfrage
          verarbeitet hat. Setzt der Server selbst ein solches Cookie, wird
          es entfernt, sofern nicht zusätzlich "preserve" gesetzt ist. Im
          Modus "insert" werden außerdem Cookies aus den an den Server
          übertragenen Anfragen entfernt. Für die Anwendung ist der Mechanismus
          zur Sitzungsbindung damit vollständig transparent. Hinweis: Von der
          Kombination aus "indirect" und "prefix" wird dringend abgeraten,
          da Cookie-Aktualisierungen des Servers andernfalls nicht an Clients
          gesendet würden.

nocache   Diese Option wird zusammen mit dem Modus insert empfohlen, wenn
          zwischen Client und HAProxy ein Cache liegt. Sie sorgt dafür, dass
          eine sonst cachebare Antwort als nicht cachebar markiert wird, wenn
          ein Cookie eingefügt werden muss. Dies ist wichtig: Werden etwa
          alle Cookies zur Sitzungsbindung auf einer cachebaren Startseite
          gesetzt, laden anschließend alle Kunden die Seite aus einem
          vorgeschalteten Cache. Alle hätten dann dasselbe Cookie zur
          Sitzungsbindung, sodass ein Server deutlich mehr Datenverkehr
          erhielte als die anderen. Siehe auch "insert" und "postonly".

postonly  Diese Option beschränkt das Einfügen von Cookies auf Antworten auf
          POST-Anfragen. Sie ist eine Alternative zu "nocache": Da
          POST-Antworten nicht cachebar sind, wird das Cookie zur
          Sitzungsbindung niemals im Cache gespeichert. Die meisten Websites
          benötigen vor der ersten POST-Anfrage, meist einer Anmeldung, keine
          Sitzungsbindung. Daher optimiert diese Methode das Caching sehr
          effizient, ohne ein Cookie zur Sitzungsbindung im Cache zu riskieren.
          Siehe auch "insert" und "nocache".

preserve  Diese Option kann nur mit "insert" und/oder "indirect" verwendet
          werden. Sie erlaubt dem Server, das Cookie zur Sitzungsbindung
          selbst auszugeben. Wird in diesem Fall ein Cookie in der Antwort
          gefunden, lässt HAProxy es unverändert. Damit lässt sich die
          Sitzungsbindung beispielsweise nach einer Abmeldeanfrage beenden.
          Der Server muss dazu lediglich ein Cookie mit einem ungültigen Wert,
          etwa einem leeren Wert, oder mit einem Datum in der Vergangenheit
          ausgeben. Zusammen mit der Prüfoption "disable-on-404" ermöglicht
          dieser Mechanismus ein vollständig geordnetes Herunterfahren, da
          Benutzer den Server nach der Abmeldung endgültig verlassen.

httponly  Diese Option weist HAProxy an, beim Einfügen eines Cookies das
          Cookie-Attribut "HttpOnly" hinzuzufügen. Dadurch gibt ein User-Agent
          das Cookie nicht an Komponenten außerhalb von HTTP weiter. Weitere
          Informationen zu diesem Attribut enthält RFC6265.

secure    Diese Option weist HAProxy an, beim Einfügen eines Cookies das
          Cookie-Attribut "Secure" hinzuzufügen. Dadurch sendet ein User-Agent
          dieses Cookie nie über ungesicherte Kanäle. Ein Cookie mit diesem
          Attribut wird somit ausschließlich über SSL/TLS-Verbindungen
          übermittelt. Weitere Informationen zu diesem Attribut enthält RFC6265.

domain    Mit dieser Option wird die Domain angegeben, für die ein Cookie
          eingefügt wird. Sie erfordert genau einen Parameter: einen gültigen
          Domainnamen. Beginnt die Domain mit einem Punkt, darf der Browser
          das Cookie für jeden Host verwenden, dessen Name so endet. Durch
          mehrfache Angabe der Option lassen sich auch mehrere Domainnamen
          angeben. Einige Browser erlauben nur wenige Domains; dabei ist
          also Vorsicht geboten. Zur Orientierung: 10 Domains funktionieren
          bei MSIE 6 und Firefox 2 wie erwartet.

maxidle   Mit dieser Option werden eingefügte Cookies nach einer gewissen
          Inaktivitätszeit ignoriert. Sie funktioniert nur für Cookies im
          Modus insert. Beim Senden eines Cookies an den Client wird auch
          sein Ausgabedatum mitgesendet. Wird das Cookie später erneut
          vorgelegt und liegt das Datum länger zurück als die im Parameter
          angegebene Zeit in Sekunden, wird es ignoriert. Andernfalls wird
          es bei Bedarf beim Senden der Antwort an den Client aktualisiert.
          Dies verhindert insbesondere, dass Benutzer, die ihren Browser nie
          schließen, zu lange an denselben Server gebunden bleiben, etwa
          nach einer Änderung der Gruppengröße. Ist diese Option gesetzt
          und enthält ein Cookie kein Datum, wird es immer akzeptiert, aber
          in der Antwort aktualisiert. So behalten Administratoren Zugriff
          auf ihre Websites. Cookies mit einem Datum mehr als 24 Stunden
          in der Zukunft werden ignoriert. Dadurch können Administratoren
          Zeitzonenprobleme beheben, ohne Benutzer von der Website auszuschließen.

maxlife   Mit dieser Option werden eingefügte Cookies nach einer gewissen
          Lebensdauer ignoriert, unabhängig davon, ob sie verwendet werden.
          Sie funktioniert nur für Cookies im Modus insert. Beim ersten
          Senden eines Cookies an den Client wird auch sein Ausgabedatum
          mitgesendet. Wird das Cookie später erneut vorgelegt und liegt
          das Datum länger zurück als die im Parameter angegebene Zeit in
          Sekunden, wird es ignoriert. Enthält das Cookie in der Anfrage
          kein Datum, wird es akzeptiert und mit einem Datum versehen.
          Cookies mit einem Datum mehr als 24 Stunden in der Zukunft werden
          ignoriert. Dadurch können Administratoren Zeitzonenprobleme beheben,
          ohne Benutzer von der Website auszuschließen. Anders als bei maxidle
          wird dieser Wert nicht aktualisiert; nur das Datum des ersten
          Besuchs zählt. maxidle und maxlife können gleichzeitig verwendet
          werden. Dies verhindert insbesondere, dass Benutzer, die ihren
          Browser nie schließen, zu lange an denselben Server gebunden bleiben,
          etwa nach einer Änderung der Gruppengröße. Diese Methode greift
          stärker als maxidle, da sie nach einer absoluten Zeitspanne eine
          Neuzuweisung erzwingt.

dynamic   Aktiviert dynamische Cookies. Für jeden Server wird anhand seiner
          IP-Adresse und seines Ports sowie eines geheimen Schlüssels
          dynamisch ein Sitzungscookie erzeugt. Der Schlüssel wird mit der
          Backend-Direktive "dynamic-cookie-key" angegeben.
          Bei jeder Änderung der IP-Adresse wird das Cookie neu erzeugt;
          die Erzeugung erfolgt nur für IPv4/IPv6.

attr      Diese Option weist HAProxy an, beim Einfügen eines Cookies ein
          zusätzliches Attribut hinzuzufügen. Der Attributwert kann beliebige
          Zeichen außer Steuerzeichen oder ";" enthalten. Diese Option kann
          mehrfach angegeben werden.