3. Section globale
Les paramètres de la section « global » sont applicables à l’ensemble du processus et souvent spécifiques au système d’exploitation. Ils sont généralement définis une fois pour toutes et n’exigent pas de modification une fois correctement configurés. Certains d’entre eux ont des équivalents en ligne de commande.
Les mots-clés suivants sont pris en charge dans la section « global » :
Gestion des processus et sécurité
- 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.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
- fournisseur-ssl
- chemin-fournisseur-ssl
- niveau-sécurité-ssl
- vérification-serveur-ssl
- ignorer-ca-auto-signé-ssl
- statistiques
- fichier-statistiques
- limites-strictes
- uid
- limite-ressources-n
- liaison-unix
- supprimer-variable-environnement
- utilisateur
- taille-cache-wurfl
- fichier-données-wurfl
- liste-informations-wurfl
- séparateur-liste-informations-wurfl
Optimisation des performances
- 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 (obsolète)
- tune.quic.cc-hystart (obsolète)
- tune.quic.disable-tx-pacing (obsolète)
- tune.quic.disable-udp-gso (obsolète)
- 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.frontal.max-idle-timeout
- tune.quic.frontal.sec.glitches-threshold
- tune.quic.frontal.sec.retry-threshold
- tune.quic.frontal.sock-per-conn
- tune.quic.frontal.stream.data-ratio
- tune.quic.frontal.stream.max-concurrent
- tune.quic.frontal.stream.max-total
- tune.quic.frontal.stream.rxbuf
- tune.quic.frontal.tx.pacing
- tune.quic.frontal.tx.udp-gso
- tune.quic.frontal.max-data-size (obsolète)
- tune.quic.frontal.max-idle-timeout (obsolète)
- tune.quic.frontal.max-streams-bidi (obsolète)
- tune.quic.frontal.max-tx-mem (obsolète)
- tune.quic.frontal.stream-data-ratio (obsolète)
- tune.quic.frontal.default-max-window-size (obsolète)
- tune.quic.ecoute
- tune.quic.max-frame-loss (obsolète)
- tune.quic.mem.tx-max
- tune.quic.reorder-ratio (obsolète)
- tune.quic.retry-threshold (obsolète)
- tune.quic.socket-owner (obsolète)
- 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 (obsolète)
- 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 (obsolète)
- tune.ssl.ocsp-update.mindelay (obsolète)
- 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
Débogage
- 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. Gestion des processus et sécurité
51degrees-data-file <file path>
Chemin du fichier de données 51Degrees à utiliser pour fournir les services de détection de périphérique. Le fichier doit être décompressé et accessible par HAProxy, avec les autorisations appropriées.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.
51degrees-property-name-list [<string> ...]
Une liste de noms de propriétés 51Degrees à charger à partir de l’ensemble de données. Une liste complète des noms est disponible sur le site web 51Degrees : https://51degrees.com/resources/property-dictionary
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.
51degrees-property-separator <char>
Caractère ajouté à la fin de chaque valeur de propriété dans un en-tête de réponse contenant des résultats 51Degrees. Si non défini, la valeur par défaut est « , ».
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.
51degrees-cache-size <number>
Définit la taille du cache du convertisseur 51Degrees à <number> entrées. Il s’agit d’un cache LRU qui conserve les détections précédentes de périphériques et leurs résultats. Par défaut, ce cache est désactivé.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES.
51degrees-use-performance-graph { on | off }
Active (‘on’) ou désactive (‘off’) l’utilisation du graphe de performance dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.
51degrees-use-predictive-graph { on | off }
Active (‘on’) ou désactive (‘off’) l’utilisation du graphe prédictif dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.
51degrees-drift <number>
Définit la valeur de dérive que la détection peut autoriser.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.
51degrees-difference <number>
Définit la valeur de différence autorisée par une détection.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.
51degrees-allow-unmatched { on | off }
Active (‘on’) ou désactive (‘off’) l’utilisation des nœuds non appariés dans le processus de détection. La valeur par défaut dépend de la bibliothèque 51Degrees.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_51DEGREES et 51DEGREES_VER=4.
acme.scheduler { auto | off }
Active ou désactive le planificateur ACME.
Le planificateur ACME démarre au démarrage de HAProxy. Il parcourt les certificats et lance une tâche de renouvellement ACME lorsque la valeur notAfter est dépassée de curtime + (notAfter - notBefore) / 12, ou de 7 jours si notBefore n’est pas définie. Le planificateur s’endort ensuite et se réveille après 12 heures.
La valeur par défaut est « auto ».
Voir aussi : acme
ca-base <dir>
Attribue un répertoire par défaut pour récupérer les certificats CA et les listes de révocation de certificats (CRL) lorsqu’un chemin relatif est utilisé avec les directives « ca-file », « ca-verify-file » ou « crl-file ». Les emplacements absolus spécifiés dans « ca-file », « ca-verify-file » et « crl-file » ont la priorité et ignorent « ca-base ».
chroot { <jail dir> | auto }
Change le répertoire courant vers <jail dir> et effectue un chroot() dans ce répertoire avant de réduire les privilèges.
Cela augmente le niveau de sécurité en cas d’exploitation d’une vulnérabilité inconnue, car cela rend très difficile pour l’attaquant d’exploiter le système. Il est essentiel de s’assurer que <jail dir> est à la fois vide et non accessible en écriture par quiconque. Lorsque le processus est lancé avec des privilèges de superutilisateur, le chroot() est effectué directement. Sur Linux, lorsqu’il est lancé sans privilèges, HAProxy tente de l’effectuer depuis un nouvel espace utilisateur créé avec unshare(CLONE_NEWUSER); si ce mécanisme n’est pas disponible, le chroot() échoue avec l’erreur habituelle.
En tant que cas particulier, <jail dir> peut être défini sur « auto », auquel cas HAProxy crée un répertoire temporaire anonyme, le supprime, puis effectue un chroot dedans. La prison résultante n’a pas de nom dans le système de fichiers, est vide et en lecture seule, ce qui élimine la nécessité de préparer un répertoire dédié pour la prison.
Lorsque HAProxy est lancé avec des privilèges de superutilisateur, un avertissement est affiché si aucun chroot n’est utilisé, afin d’encourager les utilisateurs à toujours utiliser ce mécanisme. Si, pour une raison quelconque, il existe une raison impérative de ne pas utiliser chroot (par exemple, l’accès à un serveur via un socket UNIX dont le chemin est peu pratique), il reste possible de supprimer l’avertissement en ajoutant explicitement « chroot / », ce qui présente l’avantage d’être visible dans la configuration.
close-spread-time <time>
Définir une fenêtre de temps pendant laquelle les connexions inactives et les connexions actives en cours de fermeture sont réparties en cas d’arrêt doux. Après la réception d’un SIGUSR1 et l’expiration de la période de grâce (le cas échéant), les connexions inactives seront toutes fermées en même temps si cette option n’est pas définie, et les connexions HTTP actives ou HTTP2 seront terminées après la réception de la requête suivante, soit en ajoutant une ligne « Connection: close » à la réponse HTTP, soit en envoyant un cadre GOAWAY en cas de HTTP2. Lorsque cette option est définie, la fermeture des connexions sera répartie sur cette fenêtre <time>. Si le délai de répartition de la fermeture est défini sur « infinite », la fermeture des connexions actives pendant un arrêt doux sera désactivée. L’en-tête « Connection: close » ne sera plus ajouté aux réponses HTTP (ni GOAWAY pour HTTP2) et les connexions inactives ne seront fermées qu’une fois leur délai d’expiration atteint (selon les délais configurés).
Arguments :
Il est recommandé de définir ce paramètre à une valeur inférieure à celle utilisée dans l’option « hard-stop-after », si celle-ci est utilisée, afin que toutes les connexions aient la possibilité de se fermer correctement avant l’arrêt du processus.
Voir aussi : grace, hard-stop-after, idle-close-on-response
cluster-secret <secret>
Définir une chaîne ASCII secrète partagée entre plusieurs nœuds appartenant au même cluster. Elle peut être utilisée à différentes fins. Elle est notamment utilisée pour dériver des jetons de réinitialisation sans état pour toutes les connexions QUIC instanciées par ce processus. C’est également le cas pour dériver les secrets utilisés pour chiffrer les jetons Retry.
Si ce paramètre n’est pas défini, une valeur aléatoire sera sélectionnée au démarrage du processus. Cela permet d’utiliser des fonctionnalités qui en dépendent, bien que certaines limitations s’appliquent.
cpu-map [auto:]<thread-group>[/<thread-set>] <cpu-set>[,...] [...]
Sur certains systèmes d’exploitation, il est possible d’attribuer un groupe de threads ou un thread à un ensemble spécifique de processeurs. Cela signifie que les threads désignés ne s’exécuteront jamais sur d’autres processeurs. La directive « cpu-map » spécifie les ensembles de processeurs pour des threads individuels ou des groupes de threads. Le premier argument est une plage de groupes de threads, suivie éventuellement d’un ensemble de threads. Ces plages ont le format suivant :
<number> doit être un nombre compris entre 1 et 32 ou 64, selon la taille mot de la machine. Tous les identifiants de groupe au-dessus de « thread-groups » et tous les identifiants de thread au-dessus de la taille mot de la machine sont ignorés. Tous les numéros de thread sont relatifs au groupe auquel ils appartiennent. Il est possible de spécifier une plage en utilisant deux tels nombres séparés par un trait d’union (’-’). Il est également possible de spécifier tous les threads à la fois en utilisant « all », uniquement les nombres impairs en utilisant « odd » ou les nombres pairs en utilisant « even », tout comme avec la directive « thread » bind. Les seconds et futurs arguments sont des ensembles de processeurs. Chaque ensemble de processeurs est soit un nombre unique commençant à 0 pour le premier processeur, soit une plage composée de deux tels nombres séparés par un trait d’union (’-’). Ces numéros de processeur et plages peuvent être répétés en les séparant par des virgules ou en ajoutant de nouvelles plages en tant qu’arguments supplémentaires sur la même ligne. Hors des systèmes d’exploitation Linux et BSD, il peut y avoir une limitation sur l’indice maximal de processeur à 31 ou 63. Plusieurs directives « cpu-map » peuvent être spécifiées, mais chaque directive « cpu-map » remplace les précédentes lorsqu’elles se chevauchent.
Les plages peuvent être définies partiellement. La borne supérieure peut être omise. Dans ce cas, elle est remplacée par la valeur maximale correspondante, 32 ou 64 selon la taille du mot machine.
Le préfixe « auto: » peut être ajouté avant l’ensemble de threads pour permettre à HAProxy de lier automatiquement un ensemble de threads à un processeur en incrémentant les threads et les ensembles de processeurs. Pour être valide, les deux ensembles doivent avoir la même taille. Quel que soit l’ordre de déclaration des ensembles de processeurs, le lien s’établit du plus bas au plus élevé. Il n’est pas pris en charge d’avoir à la fois un groupe et une plage de threads avec le préfixe « auto: ». Une seule plage est prise en charge ; l’autre doit être un nombre fixe.
Notez que les plages de groupes sont prises en charge pour des raisons historiques. De nos jours, un nombre isolé désigne un groupe de threads et doit valoir 1 si les groupes de threads ne sont pas utilisés, et spécifier une plage ou un nombre de threads exige d’ajouter “1/” devant s’ils ne sont pas utilisés. Enfin, “1” est strictement équivalent à “1/all” et désigne tous les threads du groupe.
Exemples :
cpu-affinity <affinity>
Définit la manière dont les threads doivent être liés aux processeurs. Il accepte actuellement les valeurs suivantes :
- par-cœur : chaque thread sera lié à tous les threads matériels d’un cœur.
- par-groupe : chaque thread sera lié à tous les threads matériels du groupe. C’est le comportement par défaut, sauf si « threads-per-core 1 » est utilisé dans « cpu-policy ». « par-groupe » accepte un argument facultatif, permettant de préciser la manière dont les processeurs doivent être alloués. Lorsqu’une liste de processeurs est plus grande que le nombre maximal de processeurs par groupe autorisé et doit être répartie entre plusieurs groupes, une option supplémentaire permet de choisir la manière dont les groupes seront liés à ces processeurs :
- auto : chaque groupe de threads ne sera affecté qu’à une part équitable de cœurs processeurs contigus, dédiés exclusivement à ce groupe et non partagés avec d’autres groupes. C’est le comportement par défaut, car il est généralement plus optimal.
- lache : chaque groupe pourra toujours utiliser n’importe quel processeur de la liste. Cela entraîne généralement plus de contention, mais peut parfois aider à mieux gérer les charges parasites s’exécutant sur les mêmes processeurs.
- auto : la valeur « per-group » sera utilisée, sauf si « threads-per-core 1 » est spécifié dans « cpu-policy », auquel cas la valeur « per-core » sera utilisée. Cette option est la valeur par défaut.
- per-thread : chaque thread sera lié à un seul thread matériel. Si « threads-per-core 1 » est utilisé dans « cpu-policy », chaque thread sera lié à un thread matériel d’un cœur différent.
- per-ccx : chaque thread sera lié à tous les threads matériels d’un CCX.
cpu-policy <policy> [threads-per-core 1 | auto]
Sélectionne la politique d’allocation du CPU à utiliser.
Sur les systèmes multi-CPU, plusieurs raisons peuvent justifier de ne pas utiliser tous les cœurs disponibles, and/or afin de les regrouper en groupes de threads distincts, pour des raisons de performance, de latence, de coût ou de gestion des ressources au niveau du système. La directive « cpu-set » permet déjà d’exclure un certain nombre de cœurs, mais une fois cette opération effectuée, il est nécessaire de décider comment affecter les cœurs restants aux threads et groupes de threads.
Ce mappage est généralement effectué à l’aide de la directive « cpu-map », bien qu’il puisse être particulièrement difficile à maintenir sur des systèmes hétérogènes.
La directive « cpu-policy » permet de choisir parmi un petit nombre de politiques d’allocation à utiliser à la place lorsque « cpu-map » n’est pas utilisée. Les politiques suivantes sont actuellement prises en charge, « performance » étant la politique par défaut :
none aucun post-traitement particulier n’est effectué. Tous les processeurs activés seront utilisables, et si le nombre de threads n’est pas défini, il sera fixé au nombre de processeurs disponibles, mais sans dépasser 32 sur les systèmes 32 bits ou 64 sur les systèmes 64 bits, par groupe de threads. Le nombre de groupes de threads, s’il n’est pas défini, sera fixé à 1.
efficacité, exactement comme « group-by-ccx » ci-dessous, sauf que les clusters de CPU composés de cœurs dont les performances dépassent de plus de 25 % celles du cœur suivant moins performant sont exclus. Ce sont généralement des cœurs « big » ou « performance ». Cela signifie qu’en cas de détection de plusieurs types de cœurs de CPU, seul le cœur efficace sera utilisé. Cette configuration peut être pertinente en cas de charges modérées lorsque les cœurs les plus puissants doivent être disponibles pour une application ou un composant de sécurité. Certains processeurs modernes disposent d’un grand nombre de tels cœurs efficaces, capables collectivement de fournir un niveau de performance acceptable tout en consommant moins d’énergie.
premier nœud utilisable si les processeurs n’ont pas été précédemment restreints au démarrage (par exemple à l’aide de l’outil “taskset”), et si la directive “nbthread” n’a pas été définie, alors le premier nœud NUMA ayant des processeurs activés sera utilisé, et ce nombre de processeurs sera utilisé comme nombre de threads. Un seul groupe de threads sera activé avec tous ceux-ci, dans la limite de 32 ou 64 selon le système.
group-by-2-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les deux CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX comportant peu de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.
group-by-2-clusters : identique à « group-by-cluster », mais crée un groupe tous les deux clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre les clusters est lente. Cette option est généralement déconseillée.
group-by-3-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les trois CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX à faible nombre de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.
group-by-3-clusters : identique à « group-by-cluster », mais crée un groupe tous les trois clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer un trop grand nombre de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets néfastes sur les performances lorsque la communication entre les clusters est lente. Cette configuration est généralement déconseillée.
group-by-4-ccx identique à « group-by-ccx » ci-dessous, mais crée un groupe tous les quatre CCX. Cela peut être pertinent sur des processeurs disposant de nombreux CCX à faible nombre de cœurs chacun, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’une telle configuration peut entraîner des effets très négatifs sur les performances lorsque la communication entre CCX est lente. Cette option est généralement déconseillée.
group-by-4-clusters : identique à « group-by-cluster », mais crée un groupe tous les quatre clusters. Cela peut être pertinent sur des processeurs disposant de nombreux clusters comprenant chacun peu de cœurs, afin d’éviter de créer trop de groupes, ou pour lisser légèrement la répartition lorsque tous les cœurs ne sont pas utilisés. Veuillez noter qu’il peut entraîner des effets très négatifs sur les performances lorsque la communication entre les clusters est lente. Cette option est généralement déconseillée.
group-by-ccx si ni « nbthread » ni « nbtgroups » ne sont définis, un groupe de threads est créé pour chaque complexe de processeurs (« CCX ») disposant de processeurs disponibles, chaque groupe comportant autant de threads que de processeurs. Un CCX regroupe des processeurs ayant un accès similairement rapide à la mémoire cache de niveau supérieur (« LLC »), généralement la L3 cache. Sur la plupart des machines modernes, il est essentiel pour les performances de ne pas mélanger des processeurs provenant de CCX éloignés au sein du même groupe de threads. Tous les threads d’un groupe sont ensuite liés à tous les processeurs du CCX, afin que les communications intra-groupe restent locales au CCX sans imposer un lien trop strict. Les limites par groupe de threads et les limites des groupes de threads sont respectées. Cette configuration est recommandée sur les systèmes multi-socket et NUMA, ainsi que sur les processeurs présentant des latences inter-CCX élevées.
group-by-cluster si ni « nbthread » ni « nbtgroups » ne sont définis, un groupe de threads est créé pour chaque cluster de processeur disposant de processeurs disponibles, chacun avec autant de threads que de processeurs. Tous les threads d’un groupe sont liés à tous les processeurs du cluster afin que les communications intra-groupe restent locales au cluster sans imposer une liaison trop stricte. Les limites par groupe de threads et les limites des groupes de threads sont respectées. Cette configuration est recommandée sur les systèmes multi-socket et NUMA, ainsi que sur les processeurs présentant de mauvaises latences inter-CCX. Sur la plupart des machines serveur, les clusters et les CCX sont identiques, mais sur les machines hétérogènes (« performance » vs « efficacité » ou « big » vs « little »), un cluster est généralement constitué d’une partie d’un CCX composée uniquement de processeurs très similaires (même type, différence de fréquence maximale de +/-5%). Cette différence est visible sur les ordinateurs portables et les postes de travail modernes utilisés par les développeurs et les administrateurs pour valider les configurations.
performances identiques à celles de « group-by-ccx » ci-dessus, à ceci près que les clusters CPU composés de cœurs dont les performances sont inférieures à 80 % de celles du cœur suivant plus performant sont exclus. Ce sont généralement des cœurs « petits » ou « efficaces », dont l’ajout apporte généralement peu de gains significatifs et peut facilement être contre-productif (par exemple, lors des échanges TLS). En général, conserver ces cœurs pour d’autres tâches, comme la gestion du réseau, s’avère bien plus efficace. Sur les systèmes de développement, ils peuvent également être utilisés pour exécuter des outils auxiliaires tels que des générateurs de charge ou des outils de surveillance. Il s’agit de la politique par défaut.
ressource qui fonctionne comme « group-by-cluster » ci-dessus, sauf que seul le cluster CPU le plus petit et le plus efficace sera utilisé, tandis que tous les autres seront ignorés. Cela peut être utilisé pour limiter l’utilisation des ressources au strict minimum permettant encore des performances décentes, par exemple pour réduire davantage la consommation d’énergie ou minimiser le nombre de cœurs nécessaires sur certains systèmes loués dans une configuration sidecar, afin de faciliter la mise à l’échelle du système vers le bas. Notez qu’en cas de présence d’un seul cluster, celui-ci sera toutefois entièrement utilisé.
Un mot-clé facultatif peut être ajouté : « threads-per-core ». Il peut accepter deux valeurs : « 1 » et « auto ». Si réglé sur « 1 », alors une seule thread par cœur sera créée, indépendamment du nombre de threads matériels que possède le cœur. Si réglé sur « auto », alors une thread sera créée par thread matériel. Si aucune affinité n’est spécifiée et que « threads-per-core 1 » est utilisé, alors l’affinité sera par défaut par cœur.
Voir aussi : « cpu-map », « cpu-set », « nbthread »
cpu-set <directive>...
Permet de décrire de manière symbolique les ensembles de processeurs sur lesquels s’exécuter. La directive prend en charge les mots-clés suivants : - reset : annule toute limitation précédente qui aurait pu être héritée par un gestionnaire de services ou une commande « taskset », par exemple. - drop-cpu <set> : ne pas lier aux processeurs de cet ensemble. - only-cpu <set> : ne pas lier aux processeurs n’appartenant pas à cet ensemble. - drop-node <set> : ne pas lier aux processeurs appartenant à cette nœud NUMA. - only-node <set> : ne pas lier aux processeurs n’appartenant pas à ce nœud NUMA. - drop-cluster <set> : ne pas lier aux processeurs de ce numéro de cluster matériel. - only-cluster <set> : ne pas lier aux processeurs d’autres numéros de cluster matériel. - drop-core <set> : ne pas lier aux processeurs de ce numéro de cœur matériel. - only-core <set> : ne pas lier aux processeurs d’autres numéros de cœur matériel. - drop-thread <set> : ne pas lier aux processeurs de ce numéro de thread matériel. - only-thread <set> : ne pas lier aux processeurs d’autres numéros de thread matériel.
Voir également : « cpu-policy »
crt-base <dir>
Attribue un répertoire par défaut pour récupérer les certificats SSL lorsqu’un chemin relatif est utilisé avec les directives crtfile ou crt. Les emplacements absolus spécifiés prévalent et ignorent crt-base.
daemon
Met le processus en arrière-plan. Il s’agit du mode de fonctionnement recommandé. Il équivaut à l’argument de ligne de commande “-D”. Il peut être désactivé par l’argument de ligne de commande “-db”. Cette option est ignorée en mode systemd.
default-path { current | config | parent | origin <path> }
Par défaut, HAProxy charge tous les fichiers dont le chemin est relatif à partir du répertoire depuis lequel le processus est lancé. Dans certains cas, il peut être souhaitable de forcer tous les chemins relatifs à commencer à partir d’un emplacement différent, comme si le processus avait été lancé depuis cet emplacement. C’est précisément l’objectif de cette directive. Techniquement, elle effectue un changement temporaire de répertoire (chdir()) vers l’emplacement désigné pendant le traitement de chaque fichier de configuration, puis revient au répertoire d’origine après avoir traité chaque fichier. Elle prend un argument indiquant la politique à appliquer lors du chargement des fichiers dont le chemin ne commence pas par une barre oblique (’/’): - “current” indique que tous les fichiers relatifs doivent être chargés à partir du répertoire depuis lequel le processus est lancé ; c’est la valeur par défaut.
- "config" indique que tous les fichiers relatifs doivent être chargés à partir du répertoire contenant le fichier de configuration. Plus précisément, si le fichier de configuration contient une barre oblique ('/'), la plus longue partie jusqu'à la dernière barre oblique est utilisée comme répertoire de changement, sinon le répertoire courant est utilisé. Ce mode est pratique pour regrouper des cartes, des fichiers d'erreur, des certificats et des scripts Lua dans des paquets déplaçables. Lorsque plusieurs fichiers de configuration sont chargés, le répertoire est mis à jour pour chacun d'eux.
- « parent » indique que tous les fichiers relatifs doivent être chargés depuis le répertoire parent du répertoire contenant le fichier de configuration. Plus précisément, si le fichier de configuration contient une barre oblique ('/'), ".." est ajouté au plus long segment jusqu'à la dernière barre oblique, qui est utilisé comme répertoire de changement, sinon le répertoire est "..". Ce mode est pratique pour regrouper des cartes, des fichiers d'erreur, des certificats et des scripts Lua ensemble sous forme de paquets déplaçables, tout en permettant à chaque composant d'être situé dans un sous-répertoire différent (par exemple, « config/ », « certs/ », « maps/ », ...).
- « origin » indique que tous les fichiers relatifs doivent être chargés à partir du chemin désigné (obligatoire). Cette option peut être utilisée pour simplifier la gestion de plusieurs instances HAProxy s'exécutant en parallèle sur un système, où chaque instance utilise un préfixe différent, tout en rendant le reste des sections facilement déplaçables.
Chaque directive « default-path » remplace instantanément toute directive précédente et peut entraîner un changement de répertoire. Bien que cela doive toujours entraîner le comportement souhaité, il ne s’agit pas d’une bonne pratique d’utiliser plusieurs directives default-path, et si elles sont utilisées, la politique doit rester cohérente dans tous les fichiers de configuration.
Avertissement : certains éléments de configuration, tels que les cartes ou les certificats, sont identifiés de manière unique par leur chemin configuré. En utilisant une disposition déplaçable, il devient possible que plusieurs d’entre eux se retrouvent avec le même nom unique, ce qui rend difficile leur mise à jour en cours d’exécution, en particulier lorsque plusieurs fichiers de configuration sont chargés depuis des répertoires différents. Il est essentiel d’observer une stratégie stricte de nommage de fichiers sans collision avant d’adopter des chemins relatifs. Une approche robuste pourrait consister à préfixer tous les noms de fichiers par le nom du site correspondant, ou à le faire au niveau du répertoire.
description <text>
Ajoutez un texte qui décrit l’instance.
Veuillez noter qu’il est nécessaire d’échapper certains caractères (par exemple #) et que ce texte est inséré dans une page HTML, vous devez donc éviter d’utiliser les caractères “<” et “>”.
deviceatlas-json-file <path>
Définit le chemin du fichier de données JSON DeviceAtlas à charger par l’API. Le chemin doit désigner un fichier JSON valide et être accessible au processus HAProxy.
deviceatlas-log-level <value>
Définit le niveau d’information retourné par l’API. Cette directive est facultative et vaut 0 par défaut si non définie.
deviceatlas-properties-cookie <name>
Définit le nom du cookie client utilisé pour détecter si le composant côté client DeviceAtlas a été utilisé lors de la requête. Cette directive est facultative et vaut DAPROPS par défaut si elle n’est pas définie.
deviceatlas-separator <char>
Définit le séparateur de caractères pour les résultats des propriétés de l’API. Cette directive est facultative et vaut | par défaut si elle n’est pas définie.
dns-accept-family <family>[,...]
Par défaut, les résolveurs DNS acceptent à la fois les adresses IPv4 et IPv6. Ce comportement peut être influencé par les mots-clés « resolve-prefer » dans les lignes server, ainsi que par l’argument family de l’action « do-resolve », mais il s’agit uniquement d’une préférence qui ne bloque pas l’utilisation de l’autre famille lorsque celle-ci est la seule disponible. Dans certains environnements où le double empilement n’est pas utilisable, la découverte d’un enregistrement DNS inaccessible uniquement en IPv6 peut entraîner des problèmes importants, car il remplacerait un enregistrement IPv4 précédent qui aurait pu continuer à fonctionner jusqu’à la requête suivante. L’option globale « dns-accept-family » permet d’imposer l’utilisation d’une seule famille d’adresses (ou des deux). L’argument est une liste séparée par des virgules des mots suivants : - « ipv4 » : interroger et accepter les adresses IPv4 (enregistrements « A ») - « ipv6 » : interroger et accepter les adresses IPv6 (enregistrements « AAAA ») - « auto » : utiliser IPv4, et IPv6 si le système dispose d’une passerelle par défaut pour celle-ci. Le résultat de la dernière vérification est mis en cache pendant 30 secondes.
Lorsqu’une seule famille est utilisée, aucune requête n’est envoyée aux résolveurs pour l’autre famille, et toute réponse provenant de cette dernière est ignorée. La valeur par défaut depuis la version 3.3 est « auto », qui active effectivement les deux familles uniquement une fois que l’IPv6 a été vérifié comme routable, sinon elle reste sur IPv4. Voir également : « resolve-prefer », « do-resolve »
expose-deprecated-directives
Cette instruction doit apparaître avant d’utiliser certains directives marquées comme obsolètes afin de supprimer les avertissements et de garantir que le fichier de configuration ne sera pas rejeté. Toutes les directives obsolètes ne sont pas concernées, uniquement celles pour lesquelles aucune solution de remplacement n’existe.
expose-experimental-directives
Cette directive doit apparaître avant toute utilisation de directives marquées comme expérimentales, faute de quoi le fichier de configuration sera rejeté. Veuillez noter que les fonctionnalités couvertes par cette option ne sont pas garanties d’être stables et peuvent présenter des dysfonctionnements pendant le cycle de maintenance. Les développeurs les maintiendront dans un état de meilleur effort pendant la mise au point de la prochaine version, et s’efforceront de toute évidence d’éviter toute rupture, sans garantie. Pour ces raisons, ces fonctionnalités ne sont pas censées être prises en charge au-delà du lancement de la prochaine version LTS. Les utilisateurs souhaitant expérimenter ces fonctionnalités sont invités à effectuer une mise à jour rapide afin de bénéficier des améliorations apportées à ces fonctionnalités. Pour savoir si cette directive est encore nécessaire, il est simple : si elle est activée sans être utilisée par une telle fonctionnalité, un avertissement sera émis pour suggérer de la désactiver. Ainsi, en l’absence d’avertissement, cela signifie qu’elle est encore nécessaire.
external-check [preserve-env]
Permet d’utiliser un agent externe pour effectuer les contrôles d’état. Cette fonctionnalité est désactivée par défaut en tant que mesure de sécurité, et même activée, les contrôles peuvent échouer sauf si « insecure-fork-wanted » est également activé. Si le programme lancé utilise un exécutable setuid (ce qui devrait en réalité être évité), vous devrez peut-être également définir « insecure-setuid-wanted » dans la section globale. Par défaut, les contrôles démarrent dans un environnement propre ne contenant que les variables définies dans la commande « external-check » de la section backend. Il peut parfois être souhaitable de préserver l’environnement, par exemple lorsque des scripts complexes récupèrent leurs chemins ou informations supplémentaires à partir de celui-ci. Cela peut être réalisé en ajoutant le mot-clé « preserve-env ». Dans ce cas, il est fortement conseillé de ne pas exécuter le programme en tant qu’utilisateur setuid ni en tant qu’utilisateur privilégié, afin d’éviter toute exposition à des attaques potentielles. Voir « option external-check », « insecure-fork-wanted » et « insecure-setuid-wanted » pour plus de détails.
fd-hard-limit <number>
Définit une limite supérieure au nombre maximum de descripteurs de fichiers utilisés par le processus, indépendamment des limites système. Bien que les paramètres « ulimit-n » et « maxconn » puissent être utilisés pour imposer une valeur, lorsque ces paramètres ne sont pas définis, le processus sera limité à la limite dure du paramètre RLIMIT_NOFILE tel que rapporté par la commande « ulimit -n -H ». Toutefois, certains systèmes d’exploitation modernes autorisent désormais des valeurs extrêmement élevées ici (de l’ordre d’un milliard), ce qui consommerait bien trop de mémoire vive pour une utilisation régulière. Le paramètre fd-hard-limit est fourni afin d’imposer une limite éventuellement plus basse à cette limite. Cela signifie qu’il respectera toujours les limites imposées par le système lorsqu’elles sont inférieures à <number>, mais utilisera la valeur spécifiée si les limites imposées par le système sont plus élevées. Par défaut, fd-hard-limit est défini à 1048576. Cette valeur par défaut peut être modifiée via la variable de compilation DEFAULT_MAXFD, qui peut servir de limite maximale (noyau) système, si la limite dure RLIMIT_NOFILE est extrêmement élevée. La définition de fd-hard-limit dans la section globale permet de remplacer temporairement la valeur fournie via DEFAULT_MAXFD au moment de la compilation. Dans l’exemple ci-dessous, aucune autre configuration n’est spécifiée et la valeur de maxconn s’ajustera automatiquement à la plus faible entre « fd-hard-limit » et la limite RLIMIT_NOFILE.
Voir aussi : ulimit-n, maxconn
gid <number>
Change l’identifiant de groupe du processus en <number>. Il est recommandé que cet identifiant de groupe soit dédié à HAProxy ou à un petit ensemble de démons similaires. HAProxy doit être lancé avec un utilisateur appartenant à ce groupe, ou avec des privilèges de superutilisateur. Notez qu’en cas de lancement depuis un utilisateur ayant des groupes supplémentaires, HAProxy ne pourra supprimer ces groupes que s’il est lancé avec des privilèges de superutilisateur. Voir également « group » et « uid ».
grace <time>
Définit un délai entre SIGUSR1 et l’arrêt doux réel.
Arguments :
Cela est utilisé pour assurer la compatibilité avec les environnements hérités où le processus HAProxy doit être arrêté, mais où certains composants externes doivent détecter l’état avant que les écouteurs ne soient déliés. Le principe consiste à définir la variable interne « stopping » (qui est rapportée par la fonction d’extraction d’échantillon « stopping ») à true, tout en maintenant l’acceptation des connexions par les écouteurs sans interruption, jusqu’à expiration du délai, après quoi l’arrêt doux classique s’effectuera. Cette option ne doit pas être utilisée avec des processus qui sont rechargés, car cela empêcherait le processus ancien de se délier, et pourrait empêcher le nouveau processus de démarrer, ou simplement provoquer des problèmes.
Exemple :
Veuillez noter qu’une approche plus souple et durable consisterait, pour un système d’orchestration, à définir une variable globale depuis la ligne de commande, à utiliser cette variable pour répondre aux vérifications externes, puis à envoyer le signal SIGUSR1 après un délai.
Exemple :
Voir aussi : hard-stop-after, monitor
group <group name>
Similaire à « gid » mais utilise le GID du nom de groupe <group name> provenant de /etc/group.. Voir également « gid » et « user ».
h1-accept-payload-with-any-method
N’interdit pas les requêtes HTTP/1.0 GET/HEAD/DELETE dont le corps provoque une réponse HTTP 413 Payload Too Large.
Bien que cela soit explicitement autorisé dans HTTP/1.1, HTTP/1.0 ne précise pas clairement ce point, et certains serveurs anciens ne s’attendent pas à avoir de charge utile et ne vérifient jamais la longueur du corps (via les en-têtes Content-Length ou Transfer-Encoding). Cela signifie que certains intermédiaires peuvent correctement gérer la charge utile pour les requêtes HTTP/1.0 GET/HEAD/DELETE, tandis que d’autres peuvent la ignorer totalement. Cela peut entraîner des problèmes de sécurité, car une attaque de camouflage de requête est possible. Par conséquent, par défaut, HAProxy rejette les requêtes HTTP/1.0 GET/HEAD/DELETE comportant une charge utile.
Toutefois, cela peut poser problème avec certains clients anciens. Dans ce cas, cette option globale peut être configurée.
h1-do-not-close-on-insecure-transfer-encoding
Conformément à la spécification HTTP/1.1 (RFC9112#6.1), la présence simultanée d’un champ d’en-tête Transfer-Encoding et d’un champ d’en-tête Content-Length dans un même message représente un risque sérieux d’attaque par camouflage de contenu si un agent HTTP/1.0 se trouve dans la chaîne en amont ou en aval, et, en pareil cas, un agent doit absolument fermer la connexion après la réponse afin d’éviter toute exploitation. Toutefois, cela peut avoir un impact sur les performances avec certains clients très anciens, notamment s’ils doivent renégocier une connexion TLS pour chaque requête. Cette option est mise à disposition afin de demander à HAProxy de ne pas appliquer cette règle, et de ne faire que nettoyer le message tout en maintenant la connexion ouverte après la réponse. Cette action ne peut être entreprise que si l’on est absolument certain qu’aucun agent HTTP/1.0 n’est présent dans la chaîne et que toutes les implémentations situées en amont d’HAProxy sont pleinement conformes à HTTP/1.1 aux règles applicables à ces champs d’en-tête. Dans tous les cas, HAProxy continuera à ignorer et à supprimer le champ Content-Length superflu afin de ne pas induire en erreur le prochain saut.
Lorsqu’on active cette option pour contourner un client ou un serveur ancien défectueux, il est essentiel de comprendre que, qu’il en soit besoin ou non, un tel agent qui enfreint cette règle court le risque d’avoir ses messages tronqués par des agents anciens qui considèrent Content-Length et ignorent Transfer-Encoding, car la taille cumulée des tailles des tronçons encodés n’est pas prise en compte. En conséquence, la règle ci-dessus n’est pas seulement une question de sécurité, mais aussi une mesure visant à éliminer les agents susceptibles de rencontrer des problèmes de communication en raison d’incompatibilités avec des versions plus anciennes.
h1-case-adjust <from> <to>
Définit l’ajustement de casse à appliquer, lorsqu’il est activé, au nom de l’en-tête <from>, pour le convertir en <to> avant de l’envoyer aux clients ou serveurs HTTP/1. <from> doit être en minuscules, et <from> ainsi que <to> doivent ne différer que par leur casse. Cette directive peut être répétée si plusieurs noms d’en-tête doivent être ajustés. Les entrées en double ne sont pas autorisées. Si un grand nombre de noms d’en-tête doivent être ajustés, il peut être plus pratique d’utiliser « h1-case-adjust-file ». Veuillez noter qu’aucune transformation ne sera appliquée à moins que « option h1-case-adjust-bogus-client » ou « option h1-case-adjust-bogus-server » ne soit spécifiée dans un proxy.
Il n’existe pas de cas standard pour les noms d’en-têtes, car, comme indiqué dans RFC7230, ils sont insensibles à la casse. Les applications doivent donc les traiter de manière insensible à la casse. Toutefois, certaines applications incorrectes violent les normes et s’appuient erronément sur les cas les plus couramment utilisés par les navigateurs. Ce problème devient critique avec HTTP/2 car tous les noms d’en-têtes doivent être échangés en minuscules, et HAProxy adopte la même convention. Tous les noms d’en-têtes sont envoyés en minuscules aux clients et aux serveurs, indépendamment de la version HTTP.
Les applications qui ne traitent pas correctement les requêtes ou les réponses peuvent nécessiter l’utilisation temporaire de telles solutions de contournement afin d’ajuster les noms d’en-têtes envoyés pendant la durée nécessaire à la correction de l’application. Veuillez noter qu’une application qui requiert de telles solutions de contournement pourrait être vulnérable aux attaques d’envoi de contenu masqué et doit être corrigée absolument.
Exemple :
Voir « h1-case-adjust-file », « option h1-case-adjust-bogus-client » et « option h1-case-adjust-bogus-server ».
h1-case-adjust-file <hdrs-file>
Définit un fichier contenant une liste de paires key/value utilisées pour ajuster la casse de certains noms d’en-têtes avant de les envoyer aux clients ou serveurs HTTP/1. Le fichier <hdrs-file> doit contenir deux noms d’en-têtes par ligne. Le premier doit être en minuscules, et les deux doivent différer uniquement par leur casse. Les lignes commençant par ‘#’ sont ignorées, tout comme les lignes vides. Les tabulations et espaces en début et fin de ligne sont supprimés. Les entrées en double ne sont pas autorisées. Veuillez noter qu’aucune transformation ne sera appliquée à moins que « option h1-case-adjust-bogus-client » ou « option h1-case-adjust-bogus-server » soit spécifiée dans un proxy.
Si cette directive est répétée, seule la dernière sera traitée. Il s’agit d’une alternative à la directive « h1-case-adjust » lorsque de nombreux noms d’en-têtes doivent être ajustés. Veuillez lire les risques associés à son utilisation.
Voir « h1-case-adjust », « option h1-case-adjust-bogus-client » et « option h1-case-adjust-bogus-server ».
h2-workaround-bogus-websocket-clients
- Cela désactive l’annonce de la prise en charge des websockets h2 aux clients. Cela peut être utilisé pour contourner les clients présentant des problèmes lors de l’implémentation du RFC8441 relativement récent, tels que Firefox . Pour permettre aux clients de passer automatiquement à http/1.1 pour le tunnel websocket, spécifiez la prise en charge de h2 dans la ligne bind en utilisant “alpn” sans mot-clé explicite “proto”. Si cette option était précédemment activée, elle peut être désactivée en préfixant le mot-clé par “no”.
hard-stop-after <time>
Définit le temps maximum autorisé pour effectuer une extinction douce propre.
Arguments :
Cela peut être utilisé pour garantir que l’instance s’arrête même si des connexions restent ouvertes pendant un arrêt doux (par exemple avec des délais d’expiration longs pour un proxy en mode tcp). Cela s’applique aussi bien en mode TCP qu’en mode HTTP.
Exemple :
Voir aussi : grace
harden.reject-privileged-ports.tcp { on | off }
Protection par protocole activée/désactivée, qui interdit les communications avec les clients utilisant des ports privilégiés comme port source. Cette plage de ports est définie conformément au RFC 6335. Par défaut, la protection est active pour le protocole QUIC, car ce comportement est suspect et peut être utilisé dans le cadre d’une attaque d’usurpation d’identité ou d’amplification DNS/NTP.
http-err-codes [+-]<range>[,...] [...]
Remplace, réduit ou étend la liste des codes d’état qui définissent une erreur selon les codes de terminaison et le compteur “http_err_cnt” dans les tables de persistance. La plage par défaut pour les erreurs est 400 à 499, mais dans certains contextes, certains utilisateurs préfèrent exclure des codes spécifiques, notamment lors du suivi des erreurs client (par exemple, 404 sur des systèmes à contenus générés dynamiquement). Voir également « http-fail-codes » et “http_err_cnt”.
Une plage spécifiée sans ‘+’ ni ‘-’ redéfinit la plage existante par la nouvelle plage. Une plage commençant par ‘+’ étend la plage existante pour inclure également la plage spécifiée, qui peut chevaucher ou non la plage existante. Une plage commençant par ‘-’ retire la plage spécifiée de la plage existante. Une plage est composée d’un nombre compris entre 100 et 599, suivi éventuellement de “-” et d’un autre nombre supérieur ou égal au premier pour indiquer la borne supérieure de la plage. Plusieurs plages peuvent être séparées par des virgules pour une même opération add/del/replace.
Exemple :
http-fail-codes [+-]<range>[,...] [...]
Remplace, réduit ou étend la liste des codes d’état qui définissent une erreur selon les codes de terminaison et le compteur “http_fail_cnt” dans les tables de persistance. La plage par défaut des erreurs est comprise entre 500 et 599, à l’exception des codes 501 et 505, qui peuvent être déclenchés par les clients et indiquent normalement une erreur du serveur pour traiter la requête. Certains utilisateurs préfèrent exclure certains codes dans certains contextes où ils sont connus pour ne pas être pertinents, par exemple le code 500 dans certains environnements SOAP, où il ne traduit pas nécessairement une erreur du serveur. La syntaxe est identique à celle de http-err-codes ci-dessus. Voir également « http-err-codes » et “http_fail_cnt”.
insecure-fork-wanted
Par défaut, HAProxy s’efforce de prévenir toute création de thread ou de processus après son démarrage. Cette mesure est particulièrement importante lors de l’utilisation de fichiers Lua d’origine incertaine, ainsi que lors de l’expérimentation avec des versions de développement pouvant encore contenir des bogues dont l’exploitabilité est incertaine. En général, il s’agit d’une bonne pratique pour s’assurer qu’aucune activité en arrière-plan imprévue ne puisse être déclenchée par le trafic. Toutefois, cela empêche les vérifications externes de fonctionner et peut rompre certains scripts Lua très spécifiques qui dépendent activement de la capacité à fork. Cette option permet de désactiver cette protection. Notez qu’il est une mauvaise idée de la désactiver, car une vulnérabilité dans une bibliothèque ou dans HAProxy lui-même deviendra plus facile à exploiter une fois désactivée. En outre, le fork depuis Lua ou n’importe où ailleurs n’est pas fiable, car le processus forké peut aléatoirement héberger un verrou défini par un autre thread et ne jamais parvenir à terminer une opération. Il est donc fortement recommandé de ne jamais utiliser cette option et de reconsidérer toute charge de travail nécessitant un fork, en la transférant vers une solution plus sûre (comme des agents au lieu de vérifications externes). Cette option prend en charge le préfixe « no » pour la désactiver. Elle peut également être activée via “-dI” en ligne de commande HAProxy.
insecure-setuid-wanted
HAProxy n’a pas besoin d’appeler d’exécutables au moment de l’exécution (sauf lors de l’utilisation de vérifications externes, qui sont fortement déconseillées), et doit même être isolé dans un environnement chroot vide. En conséquence, il n’existe pratiquement aucune raison valable de permettre l’appel d’un exécutable setuid sans que l’utilisateur en soit pleinement conscient des risques. Dans une situation où HAProxy devrait appeler des vérifications externes and/or, la désactivation du chroot pourrait permettre l’exécution d’un programme externe si une vulnérabilité est présente dans une bibliothèque ou dans HAProxy lui-même. Sur Linux, il est possible de verrouiller le processus de manière à ignorer tout bit setuid présent sur un tel exécutable. Cela réduit fortement le risque d’élévation de privilèges dans une telle situation. C’est précisément ce que HAProxy fait par défaut. Si cela pose problème à une vérification externe (par exemple une qui nécessiterait la commande « ping »), il est possible de désactiver cette protection en ajoutant explicitement cette directive dans la section global. Si activée, il est possible de la désactiver à nouveau en préfixant la directive par le mot-clé « no ».
issuers-chain-path <dir>
Attribue un répertoire pour charger la chaîne de certificats afin de compléter l’émetteur. Tous les fichiers doivent être au format PEM. Pour les certificats chargés avec « crt » ou « crt-list », si la chaîne de certificats n’est pas incluse dans le PEM (appelée couramment certificat intermédiaire), HAProxy complétera la chaîne si l’émetteur du certificat correspond au premier certificat de la chaîne chargée via « issuers-chain-path ». Un fichier « crt » contenant Clé privée + Certificat + IntermediateCA2 + IntermediateCA1 peut être remplacé par Clé privée + Certificat. HAProxy complétera la chaîne si un fichier contenant IntermediateCA2 + IntermediateCA1 est présent dans le répertoire « issuers-chain-path ». Tous les autres certificats ayant le même émetteur partageront la chaîne en mémoire.
Les fonctionnalités OCSP sont capables d’utiliser la chaîne complète lorsqu’aucun champ .issuer n’a été utilisé, ou lorsqu’aucune chaîne n’a été fournie au format PEM.
jwt.decrypt_alg_list <list>
Définir la liste des algorithmes autorisés dans les convertisseurs jwt_decrypt_XXX. Les jetons JWT utilisant un algorithme non pris en charge ou désactivé ne seront jamais déchiffrés. Les algorithmes spécifiés doivent avoir le même format que celui décrit dans la section 4.1 de RFC7518 et être séparés par des deux-points. Le nom spécial « ALL » peut être utilisé pour activer tous les algorithmes pris en charge (voir le convertisseur “jwt_decrypt_jwk” pour la liste complète), et un « ! » peut être ajouté au nom d’un algorithme pour le désactiver explicitement. Veuillez noter qu’à moins que « ALL » ne soit spécifié, l’utilisation de cette option désactivera tout algorithme non explicitement mentionné dans la liste fournie.
Exemples :
jwt.decrypt_enc_list <list>
Définissez la liste des algorithmes de chiffrement autorisés dans les convertisseurs jwt_decrypt_XXX. Les jetons JWT utilisant un algorithme de chiffrement non pris en charge ou désactivé ne seront jamais déchiffrés. Les algorithmes spécifiés doivent avoir le même format que celui indiqué dans section 5.1 de RFC7518 et être séparés par des deux-points. Le nom spécial « ALL » peut être utilisé pour activer tous les algorithmes pris en charge (voir le convertisseur “jwt_decrypt_jwk” pour la liste complète) et un « ! » peut être ajouté au nom d’un algorithme pour le désactiver explicitement. Veuillez noter qu’à moins que « ALL » ne soit spécifié, l’utilisation de cette option désactivera tout algorithme non explicitement mentionné dans la liste fournie.
Exemples :
key-base <dir>
Attribue un répertoire par défaut pour récupérer les clés privées SSL lorsque l’option « key » utilise un chemin relatif. Les emplacements absolus spécifiés prévalent et ignorent « key-base ». Cette option ne fonctionne qu’avec une ligne de chargement « crt-store ».
limited-quic
Ce paramètre doit être utilisé pour activer explicitement les liaisons d’écouteur QUIC lorsque haproxy est compilé avec une version d’OpenSSL ne prenant pas en charge QUIC. Il active une couche de compatibilité interne à HAProxy qui doit avoir été sélectionnée au moment de la compilation avec USE_QUIC_OPENSSL_COMPAT=1. Cette couche de compatibilité prend en charge la plupart des opérations TLS nécessaires, bien qu’elle ne permette pas la fonctionnalité QUIC 0-RTT.
Cette fonctionnalité est principalement destinée à OpenSSL antérieur à la version 3.5.2, où l’API QUIC n’était pas implémentée ou seulement partiellement. La couche de compatibilité peut toutefois être activée pour les versions 3.5.2 et ultérieures, mais cela est probablement inutile.
Si l’option limited-quic est définie, mais que la couche de compatibilité n’a pas été sélectionnée au moment de la compilation, l’option est ignorée sans message et les opérations QUIC TLS s’appuient sur la bibliothèque TLS.
localpeer <name>
Définit le nom de l’instance locale. Ce paramètre sera ignoré si l’argument en ligne de commande “-L” est spécifié ou si cette directive est utilisée après la définition de la section “peers”. Dans ces cas, un message d’avertissement sera émis pendant l’analyse de la configuration.
Cette option définit également la variable d’environnement HAPROXY_LOCALPEER. Voir également “-L” dans le guide de gestion et la section « peers » ci-dessous.
log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
Ajoute un serveur syslog global. Plusieurs serveurs globaux peuvent être définis. Ils recevront les journaux relatifs aux démarrages et arrêts, ainsi que tous les journaux des proxies configurés avec « log global ». Voir l’option « log » pour les proxies pour plus de détails.
log-send-hostname [<string>]
Définit le champ nom d’hôte dans l’en-tête syslog. Si le paramètre facultatif « string » est défini, l’en-tête est défini sur le contenu de la chaîne, sinon il utilise le nom d’hôte du système. Généralement utilisé lorsqu’on ne relaie pas les journaux via un serveur syslog intermédiaire ou pour personnaliser simplement le nom d’hôte affiché dans les journaux.
log-tag <string>
Définit le champ tag dans l’en-tête syslog à cette chaîne. La valeur par défaut est le nom du programme tel qu’il a été lancé depuis la ligne de commande, qui est généralement « HAProxy ». Il peut parfois être utile de distinguer plusieurs processus s’exécutant sur le même hôte. Voir également la directive « log-tag » par proxy.
lua-load <file> [ <arg1> [ <arg2> [ ... ] ] ]
Ce directive globale charge et exécute un fichier Lua dans le contexte partagé, visible par tous les threads. Toute variable définie dans ce contexte est accessible depuis n’importe quel thread. Il s’agit de la méthode la plus simple et recommandée pour charger des programmes Lua, mais elle ne se prête pas bien à une grande quantité d’appels Lua, car un seul thread peut s’exécuter à la fois sur l’état global. Un programme chargé de cette manière verra toujours la valeur 0 dans la variable “core.thread”. Cette directive peut être utilisée plusieurs fois.
Les arguments sont disponibles dans le fichier Lua à l’aide du code ci-dessous, placé dans le corps du fichier. N’oubliez pas que les tableaux Lua commencent à l’index 1. Une variable déclarée en tant que « local » dans un fichier est disponible dans l’ensemble du fichier et non dans les autres fichiers.
local args = table.pack(...)
lua-load-per-thread <file> [ <arg1> [ <arg2> [ ... ] ] ]
Ce directive global charge et exécute un fichier Lua dans chaque thread démarré. Toute variable globale a une visibilité locale au thread, de sorte que chaque thread peut voir une valeur différente. Il est donc fortement recommandé de ne pas utiliser de variables globales dans les programmes chargés de cette manière. Une copie indépendante est chargée et initialisée pour chaque thread, tout est effectué séquentiellement et dans l’ordre numérique des threads de 1 à nbthread. Si certaines opérations doivent être effectuées une seule fois, le programme doit vérifier la variable “core.thread” afin de déterminer quel thread est en cours d’initialisation. Les programmes chargés de cette manière s’exécutent en parallèle sur tous les threads et sont hautement évolutifs. Il s’agit de la méthode recommandée pour charger des fonctions simples qui enregistrent des collectes d’échantillons, des convertisseurs, des actions ou des services, une fois assuré que le programme ne dépend pas de variables globales. Pour des raisons de simplicité, la directive est disponible même si un seul thread est utilisé, ou même si les threads sont désactivés (auquel cas elle équivaut à lua-load). Cette directive peut être utilisée plusieurs fois.
Voir lua-load pour l’utilisation des arguments.
lua-prepend-path <string> [<type>]
Préfixe la chaîne donnée suivie d’un point-virgule à la variable Lua package.<type>. <type> doit être soit “path” soit “cpath”. Si <type> n’est pas fourni, sa valeur par défaut est “path”.
Les chemins Lua sont des listes séparées par des points-virgules spécifiant comment la fonction require tente de localiser le fichier source d’une bibliothèque. Les points d’interrogation (?) figurant dans un motif sont remplacés par le nom du module. Le chemin est évalué de gauche à droite. Cela implique que les chemins ajoutés en tête seront vérifiés en premier.
Par exemple, en spécifiant le chemin suivant :
Lorsque require "example" est appelé, Lua tentera d’abord de charger le script /usr/share/haproxy-lua/example.lua. Si celui-ci n’existe pas, le script /usr/share/haproxy-lua/example/init.lua sera tenté, puis les chemins par défaut, si celui-ci n’existe pas non plus.
Voir https://www.lua.org/pil/8.1.html pour les détails dans la documentation Lua.
master-worker (deprecated)
Mode maître-worker. Il est équivalent à l’argument de ligne de commande “-W”.
Ce mot-clé est obsolète. Veuillez démarrer en mode master-worker en utilisant “-W” ou “-Ws”.
Ce mode lancera un « master » qui fera fork d’un « worker » après lecture de la configuration, afin de traiter le trafic. Le master sert de gestionnaire de processus et surveillera les « workers ».
Utilisez ce mode pour recharger HAProxy directement en envoyant le signal SIGUSR2 au processus principal. Le rechargement demande au processus principal de lire à nouveau la configuration et de créer un nouveau processus worker. Le processus worker précédent sera conservé jusqu’à la fin de ses tâches.
Le mode master-worker est compatible avec le mode en premier plan ou le mode démon.
Par défaut, si un worker quitte avec un code de retour incorrect, par exemple en cas de segmentation fault, tous les workers seront tués et le processus principal s’arrêtera. Il est pratique de combiner ce comportement avec Restart=on-failure dans un fichier d’unité systemd afin de relancer l’ensemble du processus. Si vous ne souhaitez pas ce comportement, vous devez utiliser le mot-clé « no-exit-on-failure ».
Voir également “-W” dans le guide de gestion.
master-worker no-exit-on-failure
En mode maître-worker, par défaut, si un worker se termine avec un code de retour incorrect, par exemple en cas de violation d’accès mémoire, tous les workers seront tués et le maître quittera également. Il est pratique de combiner ce comportement avec Restart=on-failure dans un fichier d’unité systemd afin de relancer l’ensemble du processus.
Ce mot-clé permet de maintenir les processus restants en vie lorsque un worker a planté, au lieu de tuer tout le monde. Il doit être utilisé avec précaution, car il n’est destiné qu’à la débogage et pourrait mettre le processus principal dans un état anormal.
max-threads-per-group <number>
Définit le nombre maximal de threads dans un groupe de threads. À moins que le nombre de groupes de threads ne soit fixé avec la directive « thread-groups », HAProxy créera autant de groupes de threads qu’il en faut pour satisfaire le nombre de threads demandé. La valeur minimale est 1, et la valeur maximale est 64 (sur les systèmes 64 bits), ou 32 (sur les systèmes 32 bits). Des valeurs plus faibles réduisent la contention provoquée par les opérations atomiques sur les états partagés, mais peuvent augmenter le nombre de sockets nécessaires pour créer tous les écouteurs et maintenir les connexions backend inactives. Des valeurs plus élevées réduisent ces coûts, au prix d’une utilisation CPU plus élevée en cas de contention, et d’un débit de connexions plus faible. La valeur par défaut est 16, qui représente le meilleur compromis trouvé expérimentalement sur divers systèmes testés, y compris des processeurs x86_64 de plusieurs constructeurs, ainsi que des systèmes Arm64 de grande taille, qu’ils soient exécutés en natif ou sous hyperviseur.
mworker-max-reloads <number>
En mode maître-ouvrier, cette option limite le nombre de fois qu’un ouvrier peut survivre à une relecture. Si l’ouvrier ne quitte pas après une relecture, une fois que son nombre de relectures dépasse cette valeur, il recevra un SIGTERM. Cette option permet de maintenir sous contrôle le nombre d’ouvrages. Voir également « show proc » dans le guide d’administration.
Par défaut, cette valeur est définie à 50.
nbthread <number>
Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il fait exécuter HAProxy sur <number> threads. Le paramètre « nbthread » fonctionne également lorsque HAProxy est lancé en mode frontal. Sur certaines plates-formes prenant en charge l’affinité processeur, la valeur par défaut de « nbthread » est automatiquement ajustée au nombre de processeurs auxquels le processus est lié au démarrage. Cela signifie que le nombre de threads peut être facilement ajusté depuis le processus appelant à l’aide de commandes telles que « taskset » ou « cpuset ». Sinon, cette valeur par défaut est égale à 1. La valeur par défaut est indiquée dans la sortie de la commande « HAProxy -vv ». Notez que les valeurs définies ici ou détectées automatiquement sont soumises à la limite fixée par « thread-hard-limit » (le cas échéant).
numa-cpu-mapping
Lorsqu’il est exécuté sur une plateforme sensible au NUMA, cette option permet à la directive « cpu-policy » d’inspecter la topologie afin de déterminer l’ensemble optimal de processeurs à utiliser ainsi que le nombre correspondant de threads. Toutefois, si l’affectation appliquée n’est pas optimale sur une architecture particulière, elle peut être désactivée à l’aide de l’instruction « no numa-cpu-mapping ». Ce lien automatique n’est pas appliqué non plus si une directive « nbthread » est présente dans la configuration, si l’affinité du processus est déjà définie (par exemple via la directive « cpu-map » ou l’outil taskset), ou si la directive « cpu-policy » est définie sur une autre valeur. Voir également « cpu-map », « cpu-policy », « cpu-set ».
ocsp-update.disable [ on | off ]
Désactive complètement le mécanisme ocsp-update dans HAProxy. Toute configuration ocsp-update sera ignorée. Valeur par défaut : « off ». Voir l’option « ocsp-update » pour plus d’informations sur le mécanisme de mise à jour automatique.
ocsp-update.httpproxy <address>[:port]
Permet d’utiliser un proxy HTTP pour les mises à jour OCSP. Cela ne fonctionne qu’avec HTTP ; HTTPS n’est pas pris en charge. Cette option permet à l’updater OCSP d’envoyer une URI absolue dans la requête au proxy.
ocsp-update.maxdelay <number>
Définit l’intervalle maximal entre deux mises à jour automatiques de la même réponse OCSP. Cette durée est exprimée en secondes et vaut 3600 par défaut (1 heure). Elle doit être définie à une valeur supérieure à “ocsp-update.mindelay”. Pour plus d’informations sur le mécanisme de mise à jour automatique, voir l’option « ocsp-update ».
ocsp-update.mindelay <number>
Définit l’intervalle minimal entre deux mises à jour automatiques de la même réponse OCSP. Cette durée est exprimée en secondes et vaut 300 par défaut (5 minutes). Elle est particulièrement utile pour les réponses OCSP ne disposant pas de temps d’expiration explicite. Elle doit être définie à une valeur inférieure à “ocsp-update.maxdelay”. Pour plus d’informations sur le mécanisme de mise à jour automatique, voir l’option « ocsp-update ».
ocsp-update.mode [ on | off ]
Définit le mode par défaut d’actualisation OCSP pour tous les certificats utilisés dans la configuration. Cette option globale peut être remplacée par l’option « ocsp-update » du bloc crt-list. Cette option est définie sur « off » par défaut. Voir l’option « ocsp-update » pour plus d’informations sur le mécanisme d’actualisation automatique.
pidfile <pidfile>
Écrit les PID de tous les démons dans le fichier <pidfile> en mode démon, ou le PID du processus principal dans le fichier <pidfile> en mode principal-travailleur. Cette option est équivalente à l’argument en ligne de commande “-p”. Le fichier doit être accessible à l’utilisateur lançant le processus. Voir également « daemon » et « master-worker ».
pp2-never-send-local
Une erreur dans l’implémentation du protocole PROXY v2 était présente dans HAProxy jusqu’à la version 2.1, provoquant l’émission d’une commande PROXY au lieu d’une commande LOCAL pour les contrôles d’état. Cela est particulièrement mineur mais perturbe les journaux de certains serveurs. Malheureusement, cette erreur a été découverte très tardivement, révélant que certains serveurs, qui n’avaient éventuellement testé leur implémentation du protocole PROXY qu’avec HAProxy, ne gèrent pas correctement la commande LOCAL, et restent définitivement en état « down » lorsque HAProxy les vérifie. Lorsque cela se produit, il est possible d’activer cette option globale afin de revenir temporairement au comportement antérieur (incorrect) pendant le temps nécessaire à la mise en contact des fournisseurs des composants concernés et à leur correction. Cette option est désactivée par défaut et s’applique à tous les serveurs ayant la directive « send-proxy-v2 ».
presetenv <name> <value>
Définit la variable d’environnement <name> avec la valeur <value>. Si la variable existe, elle n’est PAS remplacée. Les modifications prennent effet immédiatement, de sorte que la ligne suivante dans le fichier de configuration voit la nouvelle valeur. Voir également « setenv », « resetenv » et « unsetenv ».
prealloc-fd
Effectue une ouverture unique du descripteur de fichier maximum, ce qui entraîne une pré-allocation des structures de données du noyau. Cela évite les pauses brèves lorsque nbthread > 1 et qu’HAProxy ouvre un descripteur de fichier nécessitant une extension des structures de données du noyau.
resetenv [<name> ...]
Supprime toutes les variables d’environnement sauf celles spécifiées en argument. Cela permet d’utiliser un environnement propre et contrôlé avant de définir de nouvelles valeurs avec setenv ou unsetenv. Veuillez noter que certaines fonctions internes peuvent utiliser certaines variables d’environnement, telles que les fonctions de manipulation du temps, OpenSSL ou encore les vérifications externes. Cette directive doit être utilisée avec une extrême prudence et uniquement après validation complète. Les modifications prennent effet immédiatement, de sorte que la ligne suivante du fichier de configuration voit le nouvel environnement. Voir également « setenv », « presetenv » et « unsetenv ».
server-state-base <directory>
Spécifie le préfixe de répertoire à ajouter devant les noms de fichiers d’état des serveurs, pour ceux qui ne commencent pas par un ‘/’. Voir également « server-state-file », « load-server-state-from-file » et « server-state-file-name ».
server-state-file <file>
Spécifie le chemin vers le fichier contenant l’état des serveurs. Si le chemin commence par une barre oblique (’/’), il est considéré comme absolu, sinon il est considéré comme relatif au répertoire spécifié par « server-state-base » (le cas échéant) ou au répertoire courant. Avant de recharger HAProxy, il est possible de sauvegarder l’état actuel des serveurs en utilisant la commande de statistiques « show servers state ». La sortie de cette commande doit être écrite dans le fichier pointé par <file>. Lors du démarrage, avant de traiter le trafic, HAProxy lira, chargera et appliquera l’état de chaque serveur présent dans le fichier et disponible dans sa configuration en cours d’exécution. Voir également « server-state-base » et « show servers state », « load-server-state-from-file » et « server-state-file-name »
set-dumpable [ on | off | libs ]
Cette option permet de choisir le comportement en cas de panne du processus. Les options disponibles sont :
: cela active le débogage en mémoire au niveau du processus si celui-ci était auparavant désactivé.
off désactive le débogage en mode noyau, précédemment activé.
libs active la génération de fichiers de débogage contenant une copie intégrée des binaires et des bibliothèques nécessaires. Cette fonction peut être demandée par les développeurs. Dans ce cas, HAProxy tentera de charger les bibliothèques dont il dépend en mémoire et de les conserver en mémoire. Si le processus se bloque, ces éléments seront inclus dans le fichier de débogage, ce qui évite de devoir les récupérer depuis le système de fichiers et élimine tout risque de désynchronisation avec le fichier de débogage. Cette fonction consomme quelques mégaoctets à une dizaine de mégaoctets supplémentaires de mémoire RAM, il est donc préférable de ne pas l’utiliser sur les systèmes à ressources limitées.
Cette option est préférable laissée désactivée par défaut et activée uniquement sur demande d’un développeur. Par défaut, elle est désactivée. Sans argument, elle est par défaut définie sur « on ». Si elle a été activée, elle peut toutefois être fortement désactivée en la préfixant par le mot-clé « no » ou en la définissant sur « off ». Elle n’a aucune incidence sur les performances ni la stabilité, mais tente activement de réactiver les dumps de noyau qui auraient pu être désactivés par des limites de taille de fichier (ulimit -f), des limites de taille de dump (ulimit -c) ou la « dumpabilité » d’un processus après avoir modifié son UID/GID (comme /proc/sys/fs/suid_dumpable sous Linux). Les dumps de noyau peuvent toutefois être limités par les permissions du répertoire courant (vérifiez quel répertoire est utilisé pour le démarrage du fichier), les permissions du répertoire chroot (il peut être nécessaire de désactiver temporairement la directive chroot ou de le déplacer vers un emplacement dédié et accessible en écriture), ou toute autre contrainte spécifique au système. Par exemple, certaines distributions Linux sont réputées pour remplacer le chemin par défaut du fichier de dump par un chemin vers un exécutable non installé sur le système (vérifiez /proc/sys/kernel/core_pattern). En général, il suffit souvent d’écrire « core », « core.%p » ou « /var/log/core/core.%p » pour résoudre le problème. Lorsqu’on tente d’activer cette option en attendant la réapparition d’un problème rare, il est souvent judicieux de d’abord essayer d’obtenir un tel dump en émettant, par exemple, « kill -11 » au processus « HAProxy » et de vérifier qu’un dump est bien généré à l’endroit attendu lors de sa mort.
set-var <var-name> <expr>
Définit la variable globale ‘<var-name>’ avec le résultat de l’évaluation de l’expression d’extraction <expr>. La variable ‘<var-name>’ ne peut être qu’une variable globale (utilisant le préfixe ‘proc.’). Son fonctionnement est identique à l’action « set-var » dans les règles TCP ou HTTP, à ceci près que l’expression est évaluée au moment de l’analyse de la configuration et que la variable est immédiatement définie. Les fonctions d’extraction d’échantillon et convertisseurs autorisés dans l’expression ne sont que ceux utilisant des données internes, typiquement « int(valeur) » ou « str(valeur) ». Il est également possible de référencer des variables précédemment allouées. Ces variables pourront alors être lues (et modifiées) depuis les ensembles de règles réguliers.
Exemple :
set-var-fmt <var-name> <fmt>
Définit la variable globale ‘<var-name>’ à la chaîne résultant de l’évaluation du format de journal <fmt>. La variable ‘<var-name>’ ne peut être qu’une variable globale (en utilisant le préfixe ‘proc.’). Elle fonctionne exactement comme l’action ‘set-var-fmt’ dans les règles TCP ou HTTP, sauf que l’expression est évaluée au moment de l’analyse de la configuration et que la variable est immédiatement définie. Les fonctions d’extraction d’échantillon et convertisseurs autorisés dans l’expression sont uniquement ceux utilisant des données internes, typiquement ‘int(valeur)’ ou ‘str(valeur)’. Il est possible de référencer des variables précédemment allouées. Ces variables seront ensuite accessibles (et modifiables) depuis les ensembles de règles réguliers. Voir la section 8.2.6
pour les détails sur la syntaxe des formats de journal personnalisés.
Exemple :
setcap <name>[,<name>...]
Définit une liste de capacités à préserver lors du démarrage et de l’exécution, soit en tant qu’utilisateur non root (uid > 0), soit en démarrant avec uid 0 (root) puis en basculant vers un utilisateur non root. Par défaut, toutes les permissions sont perdues lors du changement d’uid, mais certaines sont souvent nécessaires lors de la connexion à un serveur depuis une adresse étrangère en mode proxy transparent, ou lors de la liaison à un port inférieur à 1024, par exemple lors de l’utilisation de « tune.quic.fe.sock-per-conn default-on », entraînant des configurations s’exécutant entièrement sous uid 0. Affecter des capacités est généralement une solution plus sûre, car seules les capacités nécessaires sont conservées. Cette fonctionnalité est spécifique à l’OS et n’est activée que sous Linux lorsque USE_LINUX_CAP=1 est défini au moment de la compilation. La liste des capacités prises en charge dépend également de l’OS et est indiquée par le message d’erreur affiché en cas de passage d’un nom de capacité invalide ou vide. Plusieurs capacités peuvent être spécifiées, séparées par des virgules. Parmi celles couramment utilisées, “cap_net_raw” permet de lier de manière transparente à une adresse étrangère, et “cap_net_bind_service” permet de lier à un port privilégié et peut être utilisé par QUIC. Si le processus est lancé et exécuté sous le même utilisateur non root, les capacités nécessaires doivent être définies sur le binaire HAProxy à l’aide de setcap, en conjonction avec cette directive. Pour plus de détails sur la configuration des capacités sur le binaire HAProxy, se référer à la section 13.1 Prise en charge des capacités Linux du guide de gestion.
Exemple :
setenv <name> <value>
Définit la variable d’environnement <name> avec la valeur <value>. Si la variable existe, elle est remplacée.
Les modifications prennent effet immédiatement, de sorte que la ligne suivante dans le fichier de configuration voit la nouvelle valeur.
Voir également « presetenv », « resetenv » et « unsetenv ».
shm-stats-file <name>
Lorsque cette directive est définie, elle active l’utilisation de la mémoire partagée pour le stockage des compteurs de statistiques. <name> est utilisé comme argument de shm_open() pour ouvrir la mémoire partagée à un emplacement unique. Cela signifie également que la directive n’est disponible que sur les systèmes qui prennent en charge shm_open(). Lorsque la mémoire partagée est utilisée pour les statistiques, tous les compteurs partageables des frontaux, backends, écouteurs et serveurs seront stockés dans la mémoire partagée, à condition qu’ils disposent d’un GUID défini. Lors du rechargement de HAProxy, le nouveau processus tentera de scanner la mémoire partagée afin de trouver des objets pouvant être associés aux objets définis dans la configuration, en fonction du GUID et du type ; l’objectif est de pouvoir conserver certaines valeurs de compteurs lors du rechargement. En revanche, lorsque HAProxy est arrêté correctement, les objets de mémoire partagée sont libérés, ce qui signifie que les compteurs sont effectivement réinitialisés. Il est également possible de supprimer manuellement le fichier avant de démarrer un nouveau processus afin de forcer une réinitialisation.
Voir également « guid », « guid-prefix » et « shm-stats-file-max-objects »
shm-stats-file-max-objects <number>
Ce paramètre définit le nombre maximum d’objets que la mémoire partagée utilisée pour les compteurs partagés pourra stocker par groupe de threads. Il est directement lié à la taille maximale de la shm et sert à « prémapper » la shm à une taille donnée afin d’éviter un remappage en cours d’exécution. Sa valeur par défaut est de 2k, ce qui convient à la plupart des configurations sans risquer une utilisation mémoire inappropriée, mais peut être facilement modifié si nécessaire. haproxy signalera une erreur au démarrage si cette valeur est trop faible pour enregistrer les objets attendus dans la mémoire partagée. Ce paramètre n’est pertinent que lorsque « shm-stats-file » a été défini.
Voir également « thread-groups »
ssl-default-bind-ciphers <ciphers>
Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement (“cipher suite”) négociés lors de l’échange SSL/TLS jusqu’à TLSv1.2 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL. Pour des informations complémentaires et des recommandations, consulter par exemple (https://wiki.mozilla.org/Security/Server_Side_TLS ) et (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Pour la configuration des chiffrements TLSv1.3, se référer à la directive « ssl-default-bind-ciphersuites ». Pour plus d’informations, consulter la directive « bind ».
ssl-default-bind-ciphersuites <ciphersuites>
Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré et si OpenSSL 1.1.1 ou une version ultérieure a été utilisée pour compiler HAProxy. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement (“cipher suite”) négociés lors de la négociation TLSv1.3 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL, dans la section « ciphersuites ». Pour la configuration des chiffrements TLSv1.2 et versions antérieures, veuillez consulter le mot-clé « ssl-default-bind-ciphers ». Ce paramètre peut accepter des suites de chiffrement TLSv1.2, mais cette fonctionnalité n’est pas documentée et n’est pas recommandée, car elle pourrait être incohérente ou défaillante. Les suites de chiffrement TLSv1.3 par défaut d’OpenSSL sont : “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256”
TLSv1.3 ne prend en charge que 5 suites de chiffrement :
- 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
Veuillez consulter le mot-clé « bind » pour plus d’informations.
Exemple :
ssl-default-bind-client-sigalgs <sigalgs>
Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature liés à l’authentification du client pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_client_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.
ssl-default-bind-curves <curves>
Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de courbes elliptiques (“suite de courbes”) négociés lors de l’échange SSL/TLS avec ECDHE. Le format de la chaîne est une liste séparée par des deux-points de noms de courbes. Veuillez consulter le mot-clé « bind » pour plus d’informations.
ssl-default-bind-options [<option>]...
Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit les options SSL par défaut pour forcer leur activation sur toutes les lignes « bind ». Veuillez consulter le mot-clé « bind » pour consulter les options disponibles.
Exemple :
ssl-default-bind-sigalgs <sigalgs>
Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature négociés pendant les échanges TLSv1.2 et TLSv1.3 pour toutes les lignes “bind” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.
ssl-default-server-ciphers <ciphers>
Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement négociés lors de l’échange SSL/TLS jusqu’à TLSv1.2 avec le serveur, pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL. Pour des informations complémentaires et des recommandations, consulter par exemple (https://wiki.mozilla.org/Security/Server_Side_TLS ) et (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Pour la configuration des algorithmes de chiffrement TLSv1.3, se référer à la directive « ssl-default-server-ciphersuites ». Voir également la directive « server » pour plus d’informations.
ssl-default-server-ciphersuites <ciphersuites>
Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré et si OpenSSL 1.1.1 ou une version ultérieure a été utilisée pour compiler HAProxy. Il définit la chaîne par défaut décrivant la liste des algorithmes de chiffrement négociés lors de l’échange TLSv1.3 avec le serveur, pour toutes les lignes « server » qui ne définissent pas explicitement leur propre liste. Le format de la chaîne est défini dans « man 1 ciphers » des pages de documentation OpenSSL, dans la section « ciphersuites ». Pour la configuration des chiffrements TLSv1.2 et versions antérieures, veuillez consulter le mot-clé « ssl-default-server-ciphers ». Veuillez consulter le mot-clé « server » pour plus d’informations.
ssl-default-server-client-sigalgs <sigalgs>
Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature liés à l’authentification du client pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_client_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.
ssl-default-server-curves <curves>
Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit la chaîne par défaut décrivant la liste des algorithmes de courbes elliptiques (“suite de courbes”) négociés lors de l’échange SSL/TLS avec ECDHE. Le format de la chaîne est une liste séparée par des deux-points de noms de courbes. Veuillez consulter le mot-clé « server » pour plus d’informations.
ssl-default-server-options [<option>]...
Ce paramètre n’est disponible que si le support d’OpenSSL a été intégré. Il définit les options SSL par défaut pour forcer l’activation sur toutes les lignes « server ». Veuillez consulter le mot-clé « server » pour connaître les options disponibles.
ssl-default-server-sigalgs <sigalgs>
Ce paramètre n’est disponible que si la prise en charge d’OpenSSL a été intégrée. Il définit la chaîne par défaut décrivant les algorithmes de signature négociés pendant les échanges TLSv1.2 et TLSv1.3 avec le serveur pour toutes les lignes “server” qui ne définissent pas explicitement leur propre liste. La chaîne est une liste d’algorithmes de signature séparés par des deux-points. Chaque algorithme peut prendre l’une des deux formes suivantes : un nom de schéma de signature TLS1.3 (“rsa_pss_rsae_sha256”) ou la forme algorithme de clé publique + condensat (“ECDSA+SHA256”). Une même liste peut contenir les deux formes. Pour plus d’informations sur le format, consultez SSL_CTX_set1_sigalgs(3). Une liste d’algorithmes de signature figure également dans la section 4.2.3 de RFC8446 et dans le fichier ssl/t1_lib.c d’OpenSSL. Ce paramètre ne s’applique pas à TLSv1.1 ni aux versions antérieures du protocole, car les algorithmes de signature n’y sont pas négociés séparément. Il est déconseillé de le modifier, sauf si la compatibilité avec un boîtier intermédiaire l’exige.
ssl-dh-param-file <file>
Ce paramètre n’est disponible que si le support OpenSSL a été intégré. Il définit les paramètres DH par défaut utilisés lors de l’échange de clés Diffie-Hellman éphémère (DHE) pendant la négociation SSL/TLS, pour toutes les lignes “bind” qui ne définissent pas explicitement leurs propres paramètres. Il sera remplacé par des paramètres DH personnalisés trouvés dans un fichier de certificat si présent. Si des paramètres DH personnalisés ne sont pas spécifiés, ni par l’option ssl-dh-param-file, ni en les définissant directement dans le fichier de certificat, les chiffres DHE ne seront pas utilisés, sauf si tune.ssl.default-dh-param est défini. Dans ce dernier cas, des paramètres DH prédéfinis de la taille spécifiée seront utilisés. L’utilisation de paramètres DH personnalisés est recommandée, car ils sont connus pour être plus sécurisés. Les paramètres DH personnalisés peuvent être générés à l’aide de la commande OpenSSL « openssl dhparam <size> », où la taille doit être d’au moins 2048, car les paramètres DH de 1024 bits ne doivent plus être considérés comme sécurisés.
ssl-passphrase-cmd <cmd> <args> ...
Ce paramètre n’est disponible que si le support OpenSSL a été inclus lors de la compilation. Il permet de définir une ligne de commande complète appelée lors du chargement d’un certificat chiffré pendant l’initialisation. La commande peut être un script ou tout autre programme. Elle reçoit comme premier paramètre le chemin vers la clé privée chiffrée, puis les paramètres « args » définis par l’utilisateur, et doit écrire la phrase de passe permettant de déchiffrer la clé privée sur la sortie standard. À chaque chargement d’une nouvelle clé privée chiffrée durant l’initialisation, HAProxy tente d’abord chaque phrase de passe déjà connue, puis appelle à nouveau la commande de phrase de passe si aucune ne fonctionne.
ssl-propquery <query>
Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de définir une chaîne de propriétés par défaut utilisée lors de la récupération des algorithmes dans les fournisseurs. Il se comporte de la même manière que l’option openssl propquery et suit la même syntaxe (décrite dans https://www.openssl.org/docs/man3.0/man7/property.html ). Par exemple, si deux fournisseurs sont chargés, celui nommé foo et le fournisseur par défaut, la chaîne propquery “?provider=foo” permet de sélectionner par défaut les implémentations d’algorithmes fournies par le fournisseur foo, et de revenir à celles du fournisseur par défaut en cas d’absence.
ssl-provider <name>
Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de charger un fournisseur lors de l’initialisation. Si le chargement réussit, les fonctionnalités fournies par le fournisseur chargé peuvent être utilisées par HAProxy. Plusieurs options ssl-provider peuvent être spécifiées dans un fichier de configuration. Les fournisseurs seront chargés dans l’ordre de leur apparition.
Veuillez noter qu’un chargement explicite d’un fournisseur empêche OpenSSL de charger automatiquement le fournisseur « default ». OpenSSL permet également de définir les fournisseurs à charger directement dans son fichier de configuration (par exemple OpenSSL.cnf), de sorte qu’il n’est pas nécessaire d’utiliser l’option « ssl-provider » pour charger des fournisseurs. La commande CLI « show ssl providers » peut être utilisée pour afficher tous les fournisseurs ayant été chargés avec succès.
Le chemin de recherche par défaut du fournisseur OpenSSL est indiqué dans la sortie de la commande « OpenSSL version -a ». Si le fournisseur se trouve dans un autre répertoire, vous pouvez définir la variable d’environnement OPENSSL_MODULES, qui précise le répertoire où se trouve votre fournisseur.
Voir également « ssl-propquery » et « ssl-provider-path ».
ssl-provider-path <path>
Ce paramètre n’est disponible que lorsque le support OpenSSL a été intégré et que la version d’OpenSSL est au moins 3.0. Il permet de spécifier le chemin de recherche utilisé par OpenSSL pour localiser les fournisseurs. Il se comporte de la même manière que la variable d’environnement OPENSSL_MODULES. Il sera utilisé pour toute option ‘ssl-provider’ ultérieure, jusqu’à ce qu’une nouvelle option ‘ssl-provider-path’ soit définie. Voir également « ssl-provider ».
ssl-load-extra-del-ext
Ce paramètre permet de configurer la manière dont HAProxy effectue la recherche des fichiers SSL supplémentaires. Par défaut, HAProxy ajoute une nouvelle extension au nom de fichier (par exemple, avec “foobar.crt” charge “foobar.crt.key”). Avec cette option activée, HAProxy supprime l’extension avant d’ajouter la nouvelle (par exemple, avec “foobar.crt” charge “foobar.key”).
Votre fichier crt doit porter une extension “.crt” pour que cette option fonctionne.
Cette option n’est pas compatible avec les extensions de bundle (.ecdsa, .rsa, .dsa) et ne tentera pas de les supprimer.
Cette option est désactivée par défaut. Voir également « ssl-load-extra-files ».
ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*
Ce paramètre modifie la manière dont HAProxy recherche les fichiers non spécifiés lors du chargement des certificats SSL. Cette option s’applique aux certificats associés aux lignes « bind » ainsi qu’aux lignes « server », mais certains fichiers supplémentaires n’auront aucun impact fonctionnel pour les certificats des lignes « server ».
Par défaut, HAProxy découvre automatiquement un grand nombre de fichiers non spécifiés dans la configuration, et vous pouvez souhaiter désactiver ce comportement afin d’optimiser le temps de démarrage.
“none” : charger uniquement les fichiers spécifiés dans la configuration. Ne pas essayer de charger un ensemble de certificats si le fichier n’existe pas. Dans le cas d’un répertoire, ne pas essayer de regrouper les certificats s’ils ont le même nom de base.
« all » : ce comportement est par défaut ; il tente de charger tout : les paquets, sctl, ocsp, l’émetteur, la clé.
“bundle” : Lorsqu’un fichier spécifié dans la configuration n’existe pas, HAProxy tentera de charger un « cert bundle ». Les bundles de certificats ne sont gérés qu’au niveau du frontal et ne fonctionnent pas pour les certificats du backend.
À compter de HAProxy 2.3, les bundles ne sont plus chargés dans le même magasin de certificats OpenSSL ; au lieu de cela, chaque certificat est chargé dans un magasin distinct, ce qui équivaut à déclarer plusieurs directives « crt ». OpenSSL 1.1.1 est requis pour cette fonctionnalité. Cela signifie que les bundles ne sont désormais utilisés qu’à des fins de compatibilité descendante et ne sont plus obligatoires pour configurer une liaison hybride RSA/ECC.
Pour associer ces fichiers PEM à un « bundle de certificats » reconnu par HAProxy, ils doivent être nommés selon la convention suivante : tous les fichiers PEM à regrouper doivent partager le même nom de base, accompagné d’un suffixe indiquant le type de clé. Actuellement, trois suffixes sont pris en charge : rsa, dsa et ecdsa. Par exemple, si www.example.com comporte deux fichiers PEM, un fichier RSA et un fichier ECDSA, ils doivent être nommés : “example.pem.rsa” et “example.pem.ecdsa”. La première partie du nom de fichier est arbitraire ; seul le suffixe est pertinent. Pour charger ce bundle dans HAProxy, indiquez uniquement le nom de base :
Exemple : bind:8443 ssl crt example.pem
Notez que le suffixe n’est pas fourni à HAProxy ; cela indique à HAProxy de rechercher un bundle de certificats.
HAProxy chargera tous les fichiers PEM du bundle comme s’ils étaient configurés séparément dans plusieurs directives « crt ».
Le chargement du bundle n’a plus d’impact sur le chargement du répertoire, puisque les fichiers sont chargés séparément.
En ligne de commande, les bundles sont considérés comme des fichiers distincts, et l’extension du bundle est obligatoire pour les valider.
Les fichiers OCSP (.ocsp), les fichiers émetteurs (.issuer), la transparence des certificats (.sctl) ainsi que les clés privées (.key) sont pris en charge avec le regroupement de plusieurs certificats.
sctl : Essayer de charger “<basename>.sctl” pour chaque mot-clé crt. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.
“ocsp”: Essayer de charger “<basename>.ocsp” pour chaque mot-clé crt. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.
“issuer”: Essayer de charger “<basename>.issuer” si l’émetteur du fichier OCSP n’est pas fourni dans le fichier PEM. Si fourni pour un certificat backend, il sera chargé mais n’aura aucun impact fonctionnel.
“key”: Si la clé privée n’a pas été fournie par le fichier PEM, essayez de charger un fichier “<basename>.key” contenant une clé privée.
Le comportement par défaut est « all ».
Exemple :
Voir aussi : « crt », section 5.1 concernant les options de liaison et section 5.2 concernant les options de serveur.
ssl-security-level <number>
Ce directive permet de choisir le niveau de sécurité OpenSSL tel qu’il est décrit dans https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html . Le niveau de sécurité sera appliqué à chaque contexte SSL dans HAProxy. Seuls les valeurs comprises entre 0 et 5 sont prises en charge.
La valeur par défaut dépend de votre version d’OpenSSL, de votre distribution et de la manière dont la bibliothèque a été compilée.
Ce directive nécessite au moins OpenSSL 1.1.1.
ssl-server-verify [none|required]
Comportement par défaut de la vérification SSL côté serveur. Si défini sur « none », les certificats des serveurs ne sont pas vérifiés. La valeur par défaut est « required », sauf si elle est forcée via l’option en ligne de commande ‘-dV’.
ssl-skip-self-issued-ca
Autorité de certification auto-délivrée, également appelée CA racine x509, constitue l’élément d’ancrage pour la validation de chaîne : en tant que serveur, elle est inutile à envoyer, le client doit la posséder. La configuration standard ne doit pas inclure une telle CA dans le fichier PEM. Cette option permet de conserver une telle CA dans le fichier PEM sans la transmettre au client. Cas d’utilisation : fournir l’émetteur pour OCSP sans nécessiter de fichier ‘.issuer’ et pouvoir le partager via ‘issuers-chain-path’. Cela concerne tous les certificats ne comportant pas de certificats intermédiaires. Cette option est inutile pour BoringSSL ; le champ .issuer est ignoré car les bits OCSP n’en ont pas besoin. Nécessite au moins OpenSSL 1.0.2.
stats calculate-max-counters [on|off]
Active ou désactive le calcul des compteurs max des statistiques. Si vous n’en avez pas besoin, les désactiver peut légèrement améliorer les performances. La valeur par défaut est activée.
stats maxconn <connections>
Par défaut, la socket de statistiques est limitée à 10 connexions simultanées. Il est possible de modifier cette valeur en utilisant « stats maxconn ».
stats socket [<address:port>|<path>] [param*]
Lie un socket UNIX à <path> ou une adresse TCPv4/v6 à <address:port>. Les connexions à ce socket renvoient diverses sorties de statistiques et permettent même d’envoyer certains commandes afin de modifier certains paramètres en cours d’exécution. Veuillez consulter la section 9.3 « Commandes de socket Unix » du guide d’administration pour plus de détails.
Tous les paramètres pris en charge par les lignes « bind » sont pris en charge, par exemple pour restreindre l’accès à certains utilisateurs ou leurs droits d’accès. Veuillez consulter section 5.1 pour plus d’informations.
stats timeout <timeout, in milliseconds>
Le délai d’expiration par défaut sur la socket de statistiques est fixé à 10 secondes. Il est possible de modifier cette valeur à l’aide de « stats timeout ». La valeur doit être indiquée en millisecondes, ou être suivie d’une unité de temps parmi { us, ms, s, m, h, d }.
stats-file <path>
Chemin vers un fichier de statistiques HAProxy généré. Au démarrage, HAProxy charge les valeurs dans ses compteurs internes. Utilisez la commande en ligne de commande « dump stats-file » pour produire un tel fichier. Voir le manuel de gestion pour plus de détails.
stress-level <level>
Activez un code alternatif destiné à exercer une charge sur le binaire HAProxy. Le niveau est un entier compris entre 0 et 9. La valeur par défaut 0 désactive toute exécution de charge. Les niveaux de 1 à 9 augmentent progressivement la pression de charge appliquée au binaire HAProxy. Notez qu’utiliser un niveau positif peut fortement réduire les performances. Ce paramètre doit donc être activé uniquement à des fins de débogage et sur demande explicite d’un développeur.
strict-limits
Fait échouer le processus au démarrage en cas d’échec de setrlimit. HAProxy tente de définir la meilleure valeur setrlimit selon les calculs effectués. En cas d’échec, un avertissement est émis. Cette option garantit un échec explicite de HAProxy lorsque ces limites échouent. Elle est activée par défaut. Elle peut toutefois être désactivée de force en préfixant le mot-clé par « no ».
thread-group <group> [<thread-range>...]
Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il définit la liste des threads qui composeront le groupe de threads <group>. Les numéros de thread et de groupe commencent à 1. Les plages de threads sont définies soit en indiquant un seul numéro de thread, soit en spécifiant les bornes inférieure et supérieure séparées par un trait d’union ‘-’ (par exemple, « 1-16 »). Les threads non affectés seront automatiquement affectés aux groupes de threads non affectés, et les groupes de threads définis avec cette directive ne recevront jamais plus de threads que ceux définis. Définir plusieurs fois le même groupe remplace les définitions précédentes par la nouvelle. Voir également « nbthread » et « thread-groups ».
thread-groups <number>
Ce paramètre n’est disponible que si le support des threads a été inclus lors de la compilation. Il permet à HAProxy de répartir ses threads en <number> groupes indépendants. Actuellement, la valeur par défaut est 1. Les groupes de threads permettent de réduire le partage entre threads afin de limiter les conflits, au prix d’une configuration plus complexe. C’est également la seule manière d’utiliser plus de 64 threads, car jusqu’à 64 threads par groupe peuvent être configurés. Le nombre maximum de groupes est configuré au moment de la compilation et vaut 16 par défaut. Voir également « nbthread ».
thread-hard-limit <number>
Ce paramètre sert à imposer une limite au nombre de threads, qu’il s’agisse de threads détectés ou configurés. Il est particulièrement utile sur les systèmes d’exploitation où le nombre de threads est détecté automatiquement, lorsque l’on souhaite un nombre de threads inférieur au nombre de processeurs dans des configurations génériques et portables. En effet, bien que « nbthread » impose un nombre de threads qui entraîne un avertissement et de mauvaises performances si supérieur au nombre de processeurs disponibles, « thread-hard-limit » ne fait que limiter le maximum à cette valeur, en ajustant automatiquement le nombre de threads à une valeur inférieure ou égale à celle-ci, sans toutefois augmenter les valeurs inférieures. Si « nbthread » est forcé à une valeur supérieure, « thread-hard-limit » l’emporte, et un avertissement est émis afin que l’anomalie de configuration puisse être corrigée. Par défaut, aucune limite n’est appliquée. Voir également « nbthread ».
uid <number>
Change l’identifiant utilisateur du processus en <number>. Il est recommandé que cet identifiant utilisateur soit dédié à HAProxy ou à un petit ensemble de démons similaires. HAProxy doit être lancé avec des privilèges de superutilisateur afin de pouvoir basculer vers un autre identifiant. Voir également « gid » et « user ».
ulimit-n <number>
Définit le nombre maximal de descripteurs de fichiers par processus à <number>. Par défaut, il est calculé automatiquement, il est donc recommandé de ne pas utiliser cette option. Si l’objectif est uniquement de limiter le nombre de descripteurs de fichiers, il est préférable d’utiliser « fd-hard-limit » à la place.
Notez que les serveurs dynamiques ne sont pas pris en compte dans ce calcul automatique des ressources. Si vous utilisez un grand nombre de serveurs dynamiques, il peut être nécessaire de spécifier cette valeur manuellement.
Voir aussi : fd-hard-limit, maxconn
unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] [ group <group> ] [ gid <gid> ]
Fixe les paramètres courants pour les sockets UNIX déclarés dans les instructions « bind ». Cela sert principalement à simplifier la déclaration de ces sockets UNIX et à réduire le risque d’erreurs, car ces paramètres sont fréquemment requis mais sont également spécifiques au processus. Le paramètre <prefix> peut être utilisé pour forcer tous les chemins de socket à être relatifs à ce répertoire. Cela peut être nécessaire pour accéder à un composant situé dans un chroot. Notez que ces chemins sont résolus avant que HAProxy ne s’isole dans un chroot, donc ils sont absolus. Les paramètres <mode>, <user>, <uid>, <group> et <gid> ont tous la même signification que leurs homonymes utilisés dans l’instruction « bind ». Si les deux sont spécifiés, l’instruction « bind » a priorité, ce qui signifie que les paramètres « unix-bind » peuvent être considérés comme des paramètres par défaut au niveau du processus.
unsetenv [<name> ...]
Supprime les variables d’environnement spécifiées dans les arguments. Cela peut être utile pour masquer certaines informations sensibles qui sont parfois héritées de l’environnement utilisateur lors de certaines opérations. Les variables n’existant pas sont ignorées sans avertissement, de sorte qu’après l’opération, il est certain qu’aucune de ces variables ne reste. Les modifications prennent effet immédiatement, de sorte que la ligne suivante du fichier de configuration ne verra plus ces variables. Voir également « setenv », « presetenv » et « resetenv ».
user <user name>
Similaire à « uid » mais utilise l’UID du nom d’utilisateur <user name> provenant de /etc/passwd.. Voir également « uid » et « group ».
node <name>
Seuls les lettres, chiffres, traits d’union et traits de soulignement sont autorisés, comme dans les noms DNS.
Cette instruction est utile dans les configurations HA où deux ou plusieurs processus ou serveurs partagent la même adresse IP. En attribuant un nom de nœud différent à chaque nœud, il devient facile d’identifier instantanément quel serveur traite le trafic.
wurfl-cache-size <size>
Définit la taille du cache des agents utilisateurs WURFL. Pour des recherches plus rapides, les agents utilisateurs déjà traités sont conservés dans un cache LRU :
- “0” : aucun cache n’est utilisé.
<size>: taille du cache LRU en éléments.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.
wurfl-data-file <file path>
Chemin du fichier de données WURFL à utiliser pour fournir les services de détection de périphérique. Le fichier doit être accessible par HAProxy, avec les autorisations appropriées.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.
wurfl-information-list [<capability>]*
Une liste séparée par des espaces de capacités WURFL, capacités virtuelles et noms de propriétés que nous prévoyons d’utiliser dans les en-têtes injectés. Une liste complète des noms de capacité et de capacité virtuelle est disponible sur le site web Scientiamobile :
Propriétés WURFL valides :
wurfl_id Contient l’identifiant du périphérique correspondant.
wurfl_root_id Contient l’identifiant racine du périphérique correspondant.
wurfl_isdevroot Indique si le périphérique correspondant est un périphérique racine. Les valeurs possibles sont « TRUE » ou « FALSE ».
wurfl_useragent L’agent utilisateur d’origine associé à cette requête web particulière.
wurfl_api_version Contient une chaîne représentant la version actuellement utilisée de l’API Libwurfl.
wurfl_info Chaîne contenant des informations sur le fichier wurfl.xml analysé et son chemin complet.
wurfl_last_load_time Contient l’horodatage UNIX du dernier chargement réussi de WURFL.
wurfl_normalized_useragent L’agent utilisateur normalisé.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.
wurfl-information-list-separator <char>
Caractère utilisé pour séparer les valeurs dans un en-tête de réponse contenant les résultats WURFL. Si non défini, une virgule (’,’) sera utilisée par défaut.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.
wurfl-patch-file [<file path>]
Une liste des chemins des fichiers de correctifs WURFL. Notez que les correctifs sont chargés au démarrage, donc avant le chroot.
Veuillez noter que cette option n’est disponible que si HAProxy a été compilé avec USE_WURFL=1.
3.2. Optimisation des performances
busy-polling
Dans certaines situations, notamment lorsqu’il s’agit de faibles latences sur des processeurs à fréquence variable ou lorsqu’on exécute dans des machines virtuelles, chaque fois que le processus attend un I/O via le poller, le processeur retourne en veille ou est attribué à une autre machine virtuelle pendant une durée prolongée, ce qui entraîne des latences excessivement élevées. Cette option propose une solution consistant à empêcher le processeur de passer en veille en utilisant toujours un délai d’expiration nul sur les pollers. Cela permet une réduction significative de la latence (de 30 à 100 microsecondes observées), au prix d’un risque accru de surchauffe du processeur. Elle peut même être utilisée avec des threads, auquel cas des threads mal affectés peuvent provoquer de fortes conflits, entraînant une performance dégradée et des valeurs élevées pour les champs CPU stolen dans la sortie de la commande “show info”, indiquant les threads mal configurés. Il est important de ne pas faire exécuter le processus sur le même processeur que les interruptions réseau lorsque cette option est activée. Il est également préférable de ne pas l’utiliser sur plusieurs threads de processeur partageant le même cœur. Cette option est désactivée par défaut. Si elle a été activée, elle peut toutefois être fortement désactivée en la préfixant par le mot-clé “no”. Elle est ignorée par les pollers “select” et “poll”.
Cette option est automatiquement désactivée sur les anciens processus dans le cadre d’un redémarrage sans interruption ; elle évite des conflits CPU excessifs lorsque plusieurs processus persistent pendant un certain temps en attendant la fin de leurs connexions actuelles.
max-spread-checks <delay in milliseconds>
Par défaut, HAProxy tente de répartir le démarrage des contrôles d’état sur l’intervalle de contrôle d’état le plus petit de tous les serveurs d’une ferme. Le principe vise à éviter de surcharger les services exécutés sur le même serveur. Toutefois, lorsqu’on utilise des intervalles de contrôle importants (10 secondes ou plus), les derniers serveurs de la ferme mettent un certain temps avant de commencer à être testés, ce qui peut poser problème. Ce paramètre sert à imposer une limite supérieure au délai entre le premier et le dernier contrôle, même si les intervalles de contrôle des serveurs sont plus longs. Lorsque les serveurs fonctionnent avec des intervalles plus courts, leurs intervalles sont respectés toutefois.
maxcompcpuusage <number>
Définit l’utilisation maximale du CPU que HAProxy peut atteindre avant de cesser la compression des nouvelles requêtes ou de réduire le niveau de compression des requêtes en cours. Fonctionne comme « maxcomprate », mais mesure l’utilisation du CPU au lieu du débit de données entrantes. La valeur est exprimée en pourcentage de CPU utilisé par HAProxy. Une valeur de 100 désactive la limite. La valeur par défaut est 100. Une valeur inférieure empêchera le traitement de compression de ralentir l’ensemble du processus et d’introduire des latences élevées.
maxcomprate <number>
Définit le taux maximal d’entrée de compression par processus à <number> kilo-octets par seconde. Pour chaque flux, si la limite est atteinte, le niveau de compression sera réduit pendant le flux. Si la limite est atteinte au début d’un flux, celui-ci ne sera pas compressé du tout. Si la limite n’est pas atteinte, le niveau de compression sera augmenté jusqu’à tune.comp.maxlevel. Une valeur nulle signifie qu’aucune limite n’est appliquée, ce qui est la valeur par défaut.
maxconn <number>
Définit le nombre maximal de connexions simultanées par processus vers <number>. Cela équivaut à l’argument en ligne de commande “-n”. La valeur fournie via l’argument en ligne de commande “-n” a priorité sur la valeur maxconn définie dans la section globale. Le processus HAProxy peut également être compilé avec la variable de compilation SYSTEM_MAXCONN, qui sert alors de limite maximale système pour maxconn. Encore une fois, l’argument en ligne de commande “-n” permet, à l’exécution, de contourner la limite définie par SYSTEM_MAXCONN, si elle est configurée. Les proxies cessent d’accepter de nouvelles connexions lorsque maxconn est atteint. La limite douce des descripteurs de fichiers du processus (obtenue avec la commande “ulimit -n”) est automatiquement ajustée en fonction de la valeur maxconn fournie. Voir également “ulimit-n”. Remarque : le poller “select” ne peut pas utiliser de manière fiable plus de 1024 descripteurs de fichiers sur certaines plates-formes. Si votre plate-forme ne prend en charge que “select” et affiche “select FAILED” au démarrage, vous devez réduire la valeur de maxconn jusqu’à ce qu’elle fonctionne (généralement légèrement inférieure à 500). Si la valeur de maxconn n’est pas définie, elle sera calculée automatiquement en fonction des limites actuelles des descripteurs de fichiers, telles que rapportées par la commande “ulimit -nH” (nous prenons la valeur maximale entre les limites dures et douces), puis cette valeur automatique peut être réduite par “fd-hard-limit” et par la limite mémoire, si celle-ci a été imposée via l’option en ligne de commande “-m”. La valeur automatique dépend également de la taille des tampons, de la mémoire allouée à la compression, de la taille du cache SSL, ainsi que de l’utilisation ou non de SSL et de la valeur correspondante maxsslconn (qui peut également être automatique).
Voir aussi : fd-hard-limit, ulimit-n
maxconnrate <number>
Définit le nombre maximal de connexions par seconde par processus pour <number>. Les proxies cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter la capacité globale, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car il n’y aura pas nécessairement une répartition équitable entre les frontaux lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. En outre, réduire tune.maxaccept peut améliorer la justesse de répartition.
maxpipes <number>
Définit le nombre maximal de tubes par processus à <number>. Actuellement, les tubes ne sont utilisés que par le splice TCP basé sur le noyau. Étant donné qu’un tube contient deux descripteurs de fichiers, la valeur de « ulimit-n » sera augmentée en conséquence. La valeur par défaut est maxconn/4, qui semble suffisante pour la plupart des utilisations intensives. Le code de splice alloue et libère dynamiquement les tubes, et peut revenir à une copie standard, aussi une valeur trop faible peut-elle uniquement affecter les performances.
maxsessrate <number>
Définit le nombre maximal de sessions par processus et par seconde à <number>. Les proxies cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter la capacité globale, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car il n’y aura pas nécessairement une répartition équitable entre les frontaux lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. En outre, réduire tune.maxaccept peut améliorer la justesse de répartition.
maxsslconn <number>
Définit le nombre maximal de connexions SSL concurrentes par processus à <number>. Par défaut, aucune limite spécifique SSL n’est appliquée, ce qui signifie que le paramètre maxconn global s’applique à toutes les connexions. Définir cette limite évite que OpenSSL n’utilise trop de mémoire et ne plante lorsque malloc retourne NULL (car il ne vérifie pas de manière fiable ces conditions). Notez que la limite s’applique aussi bien aux connexions entrantes qu’aux sortantes, de sorte qu’une connexion qui est déchiffrée puis chiffrée compte pour 2 connexions SSL. Si cette valeur n’est pas définie, mais qu’une limite mémoire est imposée, cette valeur sera automatiquement calculée en fonction de la limite mémoire, de maxconn, de la taille du tampon, de la mémoire allouée à la compression, de la taille du cache SSL, et de l’utilisation de SSL dans les frontaux, les backends ou les deux. Si ni maxconn ni maxsslconn ne sont spécifiés alors qu’une limite mémoire est présente, HAProxy ajustera automatiquement ces valeurs afin que 100 % des connexions puissent être établies en SSL sans risque, et tiendra compte des côtés où SSL est activé (frontal, backend, les deux).
maxsslrate <number>
Définit le nombre maximal de sessions SSL par processus et par seconde à <number>. Les écouteurs SSL cessent d’accepter des connexions lorsque cette limite est atteinte. Cette option peut être utilisée pour limiter l’utilisation globale du CPU SSL, indépendamment de la capacité de chaque frontal. Il est important de noter qu’elle ne peut servir qu’à protéger le service, car les frontaux ne seront pas nécessairement équitablement partagés lorsque la limite est atteinte ; il est donc recommandé de limiter également chaque frontal à une valeur proche de sa part attendue. Il est également important de noter que les sessions sont comptabilisées avant leur entrée dans la pile SSL, et non après, ce qui protège également la pile contre des échanges malformés. Réduire tune.maxaccept peut également améliorer l’équité.
maxzlibmem <number>
Définit la quantité maximale de mémoire RAM en mégaoctets par processus utilisable par zlib. Lorsque cette quantité maximale est atteinte, les flux futurs ne seront pas compressés tant que de la mémoire ne sera pas disponible. Si la valeur est définie à 0, aucune limite n’est appliquée. La valeur par défaut est 0. Cette valeur est disponible en octets via le socket UNIX avec la commande « show info », sur la ligne « MaxZlibMemUsage » ; la mémoire utilisée par zlib est indiquée par « ZlibMemUsage » en octets.
no-memory-trimming
Désactive le découpage de mémoire (“malloc_trim”) à certains moments où des tentatives sont effectuées pour récupérer une grande quantité de mémoire (en cas de pénurie de mémoire ou lors d’un rechargement). Le découpage de mémoire force l’allocateur du système à parcourir toutes les zones inutilisées et à les libérer. Cette opération est généralement considérée comme une bonne pratique, afin de laisser plus de mémoire disponible à un nouveau processus alors que l’ancien est peu susceptible d’en faire un usage significatif. Toutefois, certains systèmes gérant des dizaines à des centaines de milliers de connexions concurrentes peuvent subir une fragmentation mémoire importante, ce qui peut rendre cette opération de libération extrêmement longue. Pendant cette période, aucune nouvelle demande ne passe par le processus, les nouvelles connexions ne sont plus acceptées, certaines vérifications de santé peuvent échouer, et le superviseur peut même déclencher la mort du processus inactif, laissant une énorme image mémoire. Si cela se produit, il est conseillé d’utiliser cette option pour désactiver le découpage et cesser de tenter d’être bienveillant envers le nouveau processus. Notez que les allocateurs mémoire avancés ne souffrent généralement pas de ce problème.
noepoll
Désactive l’utilisation du système de sondage d’événements « epoll » sous Linux. Équivalent à l’argument en ligne de commande « -de ». Le système de sondage suivant utilisé sera généralement « poll ». Voir également « nopoll ».
noevports
Désactive l’utilisation du système de sondage d’événements par ports sur les systèmes SunOS dérivés de Solaris 10 et versions ultérieures. Cela équivaut à l’argument en ligne de commande “-dv”. Le système de sondage suivant utilisé sera généralement “poll”. Voir également “nopoll”.
nogetaddrinfo
Désactive l’utilisation de getaddrinfo(3) pour la résolution de noms. Équivalent à l’argument en ligne de commande « -dG ». La fonction gethostbyname(3) dépréciée sera utilisée.
nokqueue
Désactive l’utilisation du système de sondage d’événements “kqueue” sur BSD. Équivalent à l’argument en ligne de commande “-dk”. Le système de sondage suivant utilisé sera généralement “poll”. Voir également “nopoll”.
noktls
Désactive l’utilisation de ktls. Cela équivaut à l’argument de ligne de commande “-dT”.
nopoll
Désactive l’utilisation du système de sondage d’événements « poll ». Cela équivaut à l’argument en ligne de commande « -dp ». Le système de sondage suivant utilisé sera « select ». Il ne devrait jamais être nécessaire de désactiver « poll », car il est disponible sur toutes les plates-formes prises en charge par HAProxy. Voir également « nokqueue », « noepoll » et « noevports ».
noreuseport
Désactive l’utilisation de SO_REUSEPORT – voir socket(7). Cela équivaut à l’argument en ligne de commande « -dR ».
nosplice
Désactive l’utilisation du splice TCP du noyau entre sockets sous Linux. Cela équivaut à l’argument en ligne de commande “-dS”. Les données seront alors copiées à l’aide d’appels recv/send conventionnels et plus portables. Le splice TCP du noyau est limité à certaines versions récentes du noyau 2.6. La plupart des versions comprises entre 2.6.25 et 2.6.28 présentent des bogues et transmettent des données corrompues, elles ne doivent donc pas être utilisées. Cette option facilite la désactivation globale du splice du noyau en cas de doute. Voir également « option splice-auto », « option splice-request » et « option splice-response ».
profiling.memory { on | off }
Active (‘on’) ou désactive (‘off’) le profilage mémoire par fonction. Cela permet de conserver des statistiques d’utilisation des appels à malloc/calloc/realloc/free dans tout le processus (y compris dans les bibliothèques), qui seront rapportées en ligne de commande via la commande « show profiling ». Cette fonction est principalement destinée à être utilisée lorsqu’une utilisation mémoire anormale est observée et qu’elle ne peut être expliquée par les pools ou d’autres informations disponibles. La perte de performance est généralement d’environ 1 %, peut-être un peu plus sur des machines fortement multithreadées, ce qui la rend normalement adaptée à une utilisation en production. Le même effet peut également être obtenu en temps réel en ligne de commande à l’aide de la commande « set profiling memory », consulter le manuel de gestion.
profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*
Active (‘on’) ou désactive (‘off’) le profilage CPU par tâche. Lorsque cette option est définie sur ‘auto’, le profilage s’active automatiquement sur un thread lorsqu’il commence à subir une latence moyenne de 1000 microsecondes ou plus, comme indiqué dans le champ d’activité “avg_loop_us”, et se désactive automatiquement lorsque la latence redescend en dessous de 990 microsecondes (valeur moyenne calculée sur les 1024 itérations précédentes, ce qui empêche toute variation rapide et atténue fortement les pics brusques). Il peut également se déclencher spontanément de temps à autre sur des systèmes surchargés, des conteneurs ou machines virtuelles, ou lorsque le système échange (ce qui doit absolument ne jamais se produire sur un répartiteur de charge).
Lorsque le profilage des tâches est activé, HAProxy peut également collecter le temps passé par chaque tâche avec un verrou détenu ou en attente d’un verrou, ainsi que le temps passé en attente d’une allocation mémoire réussie en cas de perte dans le cache de pool. Cela peut parfois aider à comprendre certaines causes de latence. Pour cela, les mots-clés supplémentaires « lock » (pour activer la collecte du temps passé avec un verrou), « no-lock » (pour la désactiver), « memory » (pour activer la collecte du temps d’allocation mémoire) ou « no-memory » (pour la désactiver) peuvent être utilisés. Par défaut, ils ne sont pas activés, car ils peuvent avoir un impact CPU non négligeable sur les systèmes fortement sollicités (3 à 10 %). Notez que la surcharge n’est prise en compte que lorsque le profilage est effectivement en cours d’exécution, de sorte qu’en mode « auto », elle n’apparaît que lorsque HAProxy décide de l’activer.
Le profilage CPU par tâche peut être très utile pour identifier où le temps est consommé et quelles requêtes ont quel effet sur d’autres requêtes. Activer cette fonctionnalité affecte généralement les performances globales de moins de 1 %, aussi est-il recommandé de la laisser sur la valeur par défaut « auto » afin qu’elle ne s’active que lorsqu’un problème est détecté. Cette fonctionnalité nécessite un système prenant en charge l’appel système clock_gettime(2) avec les identifiants d’horloge CLOCK_MONOTONIC et CLOCK_THREAD_CPUTIME_ID ; sinon, le temps rapporté sera nul. Cette option peut être modifiée en cours d’exécution à l’aide de la commande « set profiling » en ligne de commande.
spread-checks <0..50, in percent>
Parfois, il est souhaitable d’éviter d’envoyer les agents et les contrôles d’état aux serveurs à des intervalles exacts, par exemple lorsque de nombreux serveurs logiques sont situés sur le même serveur physique. Grâce à ce paramètre, il devient possible d’ajouter une certaine aléatoire à l’intervalle de contrôle, compris entre 0 et +/- 50 %. Une valeur comprise entre 2 et 5 semble donner de bons résultats. La valeur par défaut reste à 0.
ssl-engine <name> [algo <comma-separated list of algorithms>]
Définit le moteur OpenSSL à <name>. La liste des valeurs valides pour <name> peut être obtenue à l’aide de la commande « openssl engine ». Cette instruction peut être utilisée plusieurs fois ; elle active simplement plusieurs moteurs cryptographiques. Référencer un moteur non pris en charge empêchera HAProxy de démarrer. Notez que de nombreux moteurs entraînent une performance HTTPS inférieure à celle du logiciel pur avec les processeurs récents. L’option « algo » définit les algorithmes par défaut fournis par un ENGINE à l’aide de la fonction OPENSSL ENGINE_set_default_string(). Une valeur de « ALL » utilise le moteur pour toutes les opérations cryptographiques. Si aucune liste d’algorithmes n’est spécifiée, la valeur « ALL » est utilisée. Une liste séparée par des virgules d’algorithmes différents peut être indiquée, notamment : RSA, DSA, DH, EC, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. Ce format est identique à celui utilisé dans le fichier de configuration OpenSSL :
https://www.openssl.org/docs/man1.0.2/apps/config.html
HAProxy version 2.6 a désactivé la prise en charge des moteurs dans la version par défaut. Cette option n’est disponible que si HAProxy a été compilé avec cette fonctionnalité. Si le moteur ssl est requis, HAProxy peut être recompilé avec le drapeau USE_ENGINE=1.
ssl-mode-async
Ajoute le mode SSL_MODE_ASYNC au contexte SSL. Cela active les opérations TLS asynchrones I/O si des moteurs SSL capables de traitement asynchrone sont utilisés. L’implémentation actuelle prend en charge un maximum de 32 moteurs. L’API ASYNC d’OpenSSL ne prend pas en charge le déplacement des tampons read/write et n’est pas conforme à la gestion des tampons de HAProxy. Par conséquent, le mode asynchrone est désactivé pour les opérations read/write (il n’est activé que lors des échanges d’initialisation et de renégociation).
tune.applet.zero-copy-forwarding { on | off }
Active (« on ») ou désactive (« off ») le transfert zéro-copie des données pour les applets. Il est activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding.
tune.buffers.limit <number>
Définit une limite rigide sur le nombre de tampons pouvant être alloués par processus. La valeur par défaut est zéro, ce qui signifie sans limite. La limite est automatiquement ajustée afin de respecter les tampons réservés en cas d’urgence, de sorte que l’utilisateur n’ait pas à effectuer des calculs complexes. Forcer cette valeur peut être particulièrement utile pour limiter la quantité de mémoire qu’un processus peut utiliser, tout en conservant un comportement raisonnable. Lorsque cette limite est atteinte, une tâche demandant un tampon attend qu’un autre soit libéré. En général, le temps d’attente est très court et imperceptible, à condition que les limites restent raisonnables. Toutefois, certaines limitations historiques ont affaibli ce mécanisme au fil des versions, et il est connu qu’en cas de pénurie prolongée, certaines tâches peuvent se bloquer jusqu’à expiration de leur délai d’expiration, il est donc préférable d’éviter d’utiliser cette option sauf si strictement nécessaire.
tune.buffers.reserve <number>
Définit le nombre de tampons par thread qui sont pré-alloués et réservés pour une utilisation exclusive en cas de pénurie de mémoire entraînant des échecs d’allocation. La valeur minimale est 0 et la valeur par défaut est 4. Aucune raison ne justifie qu’un utilisateur modifie cette valeur, sauf si un développeur principal le recommande pour une raison très spécifique.
tune.bufsize <size>
Définit la taille de tampon à cette valeur (en octets). Des valeurs plus faibles permettent à plus de flux de coexister dans la même quantité de mémoire RAM, tandis que des valeurs plus élevées permettent à certaines applications avec des cookies très volumineux de fonctionner. La valeur par défaut est 16384 et peut être modifiée au moment de la compilation. Il est fortement recommandé de ne pas modifier cette valeur par défaut, car des valeurs trop basses peuvent interrompre certains services tels que les statistiques, et des valeurs supérieures à la taille par défaut augmentent l’utilisation de la mémoire, pouvant entraîner une exhaustion de la mémoire système. Il est nécessaire de diminuer au moins le paramètre global maxconn du même facteur que celui-ci est augmenté. En outre, l’utilisation de HTTP/2 impose que cette valeur soit au moins 16384. Si une requête HTTP est plus grande que (tune.bufsize - tune.maxrewrite), HAProxy renvoie une erreur HTTP 400 (Requête incorrecte). De même, si une réponse HTTP est plus grande que cette taille, HAProxy renvoie une erreur HTTP 502 (Bad Gateway). Notez que la valeur définie par ce paramètre est automatiquement arrondie à la multiple suivante de 8 sur les machines 32 bits et de 16 sur les machines 64 bits.
tune.bufsize.large <size>
Définit la taille en octets des tampons volumineux. Par défaut, le support des tampons volumineux n’est pas activé ; il doit être activé explicitement en définissant cette valeur.
Ces tampons sont conçus pour être utilisés dans certains contextes spécifiques où une quantité de données supérieure doit être tamponnée sans modifier la taille des tampons réguliers. Les tampons volumineux ne sont pas utilisés implicitement.
Notez qu’en cas de configuration de grands tampons, trois tampons spéciaux de grande taille seront alloués pour chaque thread au démarrage, à usage interne.
tune.bufsize.small <size>
Définit la taille en octets des tampons petits. La valeur par défaut est 1024.
Ces tampons sont conçus pour être utilisés dans certains contextes spécifiques où la consommation mémoire est limitée, mais où il semble inutile d’allouer un tampon complet. Si toutefois un petit tampon s’avère insuffisant, une réallocation est effectuée automatiquement afin de passer à un tampon de taille standard.
Pour l’instant, il est utilisé automatiquement uniquement par le protocole HTTP/3 pour émettre les en-têtes de réponse. Sinon, le support des petits tampons peut être activé pour des proxies spécifiques via l’option « use-small-buffers ».
Voir aussi : option use-small-buffers
tune.cli.max-payload-size <size>
Définit la taille maximale autorisée pour le chargement utile transmis à une commande en ligne de commande.
En ligne de commande, une ligne de commande est limitée par la taille de la mémoire tampon. Cela signifie que toutes les commandes et leurs arguments doivent tenir dans une mémoire tampon pour être traitées, à l’exclusion de la charge utile qui peut être transmise à la dernière commande de la ligne de commande. Cette charge utile peut être allouée dans une zone dédiée si nécessaire. Sa taille est limitée par ce paramètre. La valeur par défaut est 128 Ko.
Bien que cette valeur doive être suffisamment élevée pour la plupart des utilisations, si elle est modifiée, elle doit être choisie avec soin. Une valeur excessive peut avoir un impact sur les performances de HAProxy. Selon la commande utilisée, une charge importante peut nécessiter un traitement long et risquer de déclencher le watchdog.
Veuillez consulter le manuel de gestion pour obtenir les détails concernant l’interface en ligne de commande.
tune.comp.maxlevel <number>
Définit le niveau de compression maximal. Le niveau de compression influence l’utilisation du processeur pendant la compression. Cette valeur affecte l’utilisation du processeur pendant la compression. Chaque flux utilisant la compression initialise l’algorithme de compression avec cette valeur. La valeur par défaut est 1.
tune.defaults.purge
Pour prendre en charge les backends dynamiques, toutes les sections de paramètres par défaut nommés sont désormais conservées en mémoire après analyse. Cela est nécessaire car les backends ajoutés en temps réel doivent être basés sur un ensemble de paramètres par défaut nommé pour leur configuration.
Cela peut consommer une quantité importante de mémoire si le nombre d’instances defaults est important. Dans ce cas, et si la fonctionnalité de backend dynamique n’est pas nécessaire, il est possible d’utiliser cette option pour forcer la suppression de la section defaults après son analyse. Il reste toutefois obligatoire de conserver la section defaults référencée, qui contient des paramètres ne pouvant pas être copiés par les proxies qui la référencent. Par exemple, c’est le cas si la section defaults définit des règles TCP/HTTP ou un jeu de règles tcpcheck.
tune.disable-fast-forward
Désactive le transfert accéléré des données. Il s’agit d’un mécanisme d’optimisation du transfert de données consistant à acheminer les données directement d’un côté à l’autre sans réveiller le flux. Grâce à cette directive, il est possible de désactiver cette optimisation. Notez qu’elle désactive également tout transfert par assemblage TCP noyau ainsi que le transfert sans copie. Cette commande n’est pas destinée à une utilisation régulière ; elle sera généralement proposée uniquement par les développeurs lors de sessions de débogage complexes.
tune.disable-zero-copy-forwarding
Désactive globalement le transfert zéro-copie des données. Il s’agit d’un mécanisme d’optimisation du transfert rapide des données en évitant l’utilisation du tampon du canal. Grâce à cette directive, il est possible de désactiver cette optimisation. Notez qu’elle désactive également tout transfert direct TCP du noyau.
Voir aussi : 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[,...]>
Au fil de l’histoire d’HAProxy, plusieurs problèmes complexes ont été rencontrés, dus à des bogues dans le mécanisme epoll du noyau Linux. Ces problèmes sont généralement très rares et impossibles à reproduire en dehors de l’environnement du rapporteur, et ne peuvent être contournés que par la désactivation d’epoll au profit de poll, ce qui n’est pas satisfaisant dans les environnements exigeant de hautes performances. Chaque fois, ces problèmes affectent uniquement des types d’événements très spécifiques (et rares), et la possibilité de masquer ces événements peut constituer une solution de contournement plus acceptable. Cette option permet cette possibilité en autorisant l’ignoration silencieuse de quelques événements peu courants, qu’elle remplace par une entrée (qui indique un événement entrant non spécifié). L’effet est d’éviter les chemins rapides de traitement des erreurs dans certaines parties du code, et de ne recourir qu’aux chemins communs. Cette option ne doit jamais être utilisée, sauf sur recommandation explicite d’un expert chargé de diagnostiquer ou de contourner un bogue du noyau.
L’option prend un seul argument, qui est une liste séparée par des virgules de mots, chacun désignant un événement à masquer. La liste des événements actuellement pris en charge est la suivante : - « err » : masque l’événement EPOLLERR - « hup » : masque les événements EPOLLHUP - « rdhup » : masque les événements EPOLLRDHUP
Exemple :
tune.events.max-events-at-once <number>
Définit le nombre d’événements pouvant être traités simultanément par un gestionnaire de tâche asynchrone (via l’API event_hdl). <number> doit être compris entre 1 et 10 000. Une valeur élevée peut entraîner une contention de threads en raison du traitement intensif de la tâche sans interruption, tandis qu’une valeur faible peut entraîner un réamorçage constant de la tâche, car elle ne parvient pas à consommer suffisamment d’événements par exécution et ne parvient pas à suivre le producteur d’événements. La valeur par défaut peut être imposée au moment de la compilation, sinon elle est définie par défaut à 100.
tune.fail-alloc
Si compilé avec DEBUG_FAIL_ALLOC ou démarré avec “-dMfail”, indique le pourcentage de chances qu’une tentative d’allocation échoue. Doit être compris entre 0 (aucun échec) et 100 (aucun succès). Cela est utile pour déboguer et s’assurer que les échecs de mémoire sont gérés correctement. Si non défini, le ratio est de 0. Toutefois, l’option en ligne de commande “-dMfail” le fixe automatiquement à un taux d’échec de 1 %, de sorte qu’il n’est pas nécessaire de modifier la configuration pour les tests.
tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]
Active (‘on’) ou désactive (‘off’) le mode de sondage déclenché par bord pour les descripteurs de fichiers (FD) qui le supportent. Ce paramètre n’est actuellement pris en charge qu’avec epoll. Il peut réduire notablement le nombre d’appels à epoll_ctl() et améliorer légèrement les performances dans certains scénarios. Cette fonctionnalité reste expérimentale : elle peut entraîner des connexions bloquées en cas de bogues non corrigés, et est désactivée par défaut.
tune.glitches.kill.cpu-usage <number>
Définit le seuil minimal d’utilisation du CPU compris entre 0 et 100, au-delà duquel les connexions présentant trop de perturbations seront tuées. Cela s’applique aux connexions ayant atteint leur seuil de perturbations. Dans les environnements où des connexions très longues se comportent souvent mal sans avoir d’impact sur les performances, il peut être souhaitable de les conserver malgré leur mauvais comportement, à condition qu’elles n’entraînent pas de dégradation, et de ne commencer à les tuer uniquement lorsque l’utilisation du CPU devient élevée. Ce paramètre permet de spécifier qu’une connexion atteignant son seuil de perturbations sera activement tuée lorsque l’utilisation du CPU atteint ou dépasse ce niveau, mais jamais lorsqu’elle est inférieure. Notez que l’utilisation du CPU est mesurée par thread, de sorte qu’une seule connexion malveillante peut être tuée. La valeur par défaut est zéro, ce qui signifie qu’une connexion atteignant son seuil de perturbations sera automatiquement tuée. Une règle empirique consisterait à définir cette valeur à deux fois l’utilisation du CPU habituelle, ou à l’utilisation courante du CPU plus la moitié de l’utilisation en veille (par exemple, si le CPU atteint habituellement 60 %, une valeur de 80 peut être pertinente). Ce paramètre n’a aucun effet sans tune.h2.fe.glitches-threshold, tune.quic.fe.sec.glitches-threshold ou tune.h1.fe.glitches-threshold. Voir également les paramètres globaux “tune.h2.fe.glitches-threshold”, “tune.h1.fe.glitches-threshold” et “tune.quic.fe.sec.glitches-threshold”.
tune.h1.be.glitches-threshold <number>
Définit le seuil du nombre d’anomalies sur une connexion backend HTTP/1, au-delà duquel cette connexion sera automatiquement fermée. Cela permet de fermer automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Les événements courants incluent des en-têtes mal formés qui ont toutefois été acceptés par “accept-unsafe-violations-in-http-response”. Une valeur non nulle doit généralement être placée dans les centaines ou les milliers pour être efficace sans affecter les serveurs légèrement défectueux. Il est également possible de ne fermer les connexions que lorsque la consommation CPU dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’une connexion légèrement défaillante cessera d’être utilisée après un certain temps sans risquer d’interrompre les transferts en cours.
Voir également : tune.h1.fe.glitches-threshold, bc_glitches et tune.glitches.kill.cpu-usage
tune.h1.fe.glitches-threshold <number>
Définit le seuil du nombre d’incidents sur une connexion frontale HTTP/1 au-delà duquel cette connexion sera automatiquement fermée. Cela permet de fermer automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Les événements courants incluent des en-têtes mal formés qui ont toutefois été acceptés par “accept-unsafe-violations-in-http-request”. Une valeur non nulle doit généralement être fixée à plusieurs centaines ou milliers pour être efficace sans affecter les clients légèrement erronés. Il est également possible de ne fermer les connexions que lorsque la consommation du processeur dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’un client légèrement non conforme aura l’opportunité de créer une nouvelle connexion et de continuer à fonctionner sans être affecté, sans jamais déclencher une fermeture brutale qui risquerait d’interrompre des transferts en cours.
Voir également : tune.h1.be.glitches-threshold, fc_glitches et tune.glitches.kill.cpu-usage
tune.h1.zero-copy-fwd-recv { on | off }
Active (« on ») ou désactive (« off ») les réceptions en copie zéro des données pour le multiplexeur H1. Activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-send
tune.h1.zero-copy-fwd-send { on | off }
Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur H1. Il est activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-recv
tune.h2.be.glitches-threshold <number>
Définit le seuil du nombre de glitchs sur une connexion backend, au-delà duquel cette connexion sera automatiquement interrompue. Cela permet d’interrompre automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Attention, certains serveurs H2 peuvent occasionnellement provoquer quelques glitchs sur des connexions longues, aussi toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les serveurs légèrement défaillants. Il est également possible de ne tuer les connexions qu’après dépassement d’un certain seuil d’utilisation du CPU, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture gracieuse est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’une connexion légèrement défaillante cessera d’être utilisée après un certain temps sans risquer d’interrompre les transferts en cours.
Voir également : tune.h2.fe.glitches-threshold, bc_glitches et tune.glitches.kill.cpu-usage
tune.h2.be.initial-window-size <number>
Définit la taille initiale de la fenêtre HTTP/2 pour les connexions sortantes, soit le nombre d’octets que le serveur peut envoyer avant d’attendre une confirmation de la part de HAProxy. Ce paramètre n’a d’effet que sur le contenu du payload, et non sur les en-têtes. En l’absence de réglage, la valeur par défaut commune définie par tune.h2.initial-window-size s’applique. Il peut être pertinent d’augmenter légèrement cette valeur afin d’accélérer les téléchargements ou de réduire la charge CPU sur les serveurs, au prix d’une injustice entre clients. Il est préférable d’utiliser tune.h2.be.rxbuf à la place, qui ne provoque aucune injustice. Ce paramètre n’affecte pas la consommation de ressources.
Voir également : tune.h2.initial-window-size.
tune.h2.be.max-concurrent-streams <number>
Définit le nombre maximum de flux simultanés par connexion sortante (HTTP/2) (c’est-à-dire le nombre de requêtes en attente sur une connexion unique vers un serveur). Si ce paramètre n’est pas défini, la valeur par défaut définie par tune.h2.max-concurrent-streams s’applique. Une valeur inférieure à la valeur par défaut de 100 peut améliorer la réactivité d’un site au détriment de la maintenance de plus nombreuses connexions établies vers les serveurs. Lorsque l’option « http-reuse » est définie sur « always », il est recommandé de réduire cette valeur afin d’éviter de mélanger trop de clients différents sur la même connexion, car si un client est plus lent que les autres, un mécanisme connu sous le nom de « blocage en tête de file » a tendance à provoquer un effet en cascade sur la vitesse de téléchargement de tous les clients partageant une connexion (dans ce cas, il est conseillé de maintenir tune.h2.be.initial-window-size faible). Il est fortement recommandé de ne pas augmenter cette valeur ; certains pourraient trouver optimal de fonctionner avec des valeurs faibles (généralement 1 à 5).
tune.h2.be.max-frames-at-once <number>
Définit le nombre maximal de trames entrantes HTTP/2 traitées simultanément sur une connexion backend. Il peut être utile de le définir à une valeur faible (quelques dizaines à quelques centaines) lorsqu’on traite des tampons très volumineux, afin de maintenir une faible latence et une meilleure équité entre plusieurs connexions. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.
tune.h2.be.rxbuf <size>
Définit la taille de la mémoire tampon de réception HTTP/2 pour les connexions sortantes, en octets. Cette taille sera arrondie au multiple suivant de tune.bufsize et sera partagée entre toutes les transmissions de données (cadres HEADERS et DATA). Dans tous les cas, une mémoire tampon sera toujours attribuée à chaque flux, et 7/8 des mémoires tampons non utilisées seront partagées entre les flux en téléchargement de charge utile, permettant d’améliorer significativement les performances de téléchargement et d’éviter le blocage par tête de file (HoL) sur les connexions backend partagées entre plusieurs clients lorsque http-reuse est défini sur « always ». La fenêtre par flux annoncée est automatiquement ajustée pour refléter l’espace disponible, de sorte qu’en pratique il ne sera pas nécessaire de modifier tune.h2.be.initial-window-size. Si la valeur définie est inférieure à celle requise pour gérer tous les flux, la valeur minimale sera utilisée. La valeur par défaut est d’environ 1600k (100 flux avec des tampons de 16ko chacun).
Voir aussi : tune.h2.be.initial-window-size, tune.h2.fe.rxbuf, http-reuse.
tune.h2.fe.glitches-threshold <number>
Définit le seuil du nombre de perturbations sur une connexion frontale, au-delà duquel cette connexion sera automatiquement interrompue. Cela permet d’interrompre automatiquement les connexions défaillantes sans avoir à écrire des règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, de sorte qu’aucun événement ne provoquera la fermeture d’une connexion. Prenez garde que certains clients H2 peuvent occasionnellement provoquer quelques perturbations sur des connexions longues, aussi toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les clients légèrement défectueux. Il est également possible de n’interrompre les connexions qu’au-delà d’un certain seuil d’utilisation du processeur, en utilisant “tune.glitches.kill.cpu-usage”. Notez qu’une fermeture correcte est tentée à 75 % du seuil configuré en annonçant un GOAWAY pour un flux futur. Cela garantit qu’un client légèrement non conforme aura l’opportunité de créer une nouvelle connexion et de continuer à fonctionner sans être affecté, sans jamais déclencher la fermeture brutale, ce qui risquerait d’interrompre les transferts en cours.
Voir également : tune.h2.be.glitches-threshold, fc_glitches et tune.glitches.kill.cpu-usage
tune.h2.fe.initial-window-size <number>
Définit la taille initiale de fenêtre HTTP/2 pour les connexions entrantes, soit le nombre d’octets que le client peut envoyer avant d’attendre une confirmation de la part de HAProxy. Ce paramètre n’a d’effet que sur le contenu du corps (c’est-à-dire le corps des requêtes POST), et non sur les en-têtes. Si ce paramètre n’est pas défini, la valeur par défaut commune définie par tune.h2.initial-window-size s’applique. Il peut être pertinent d’augmenter cette valeur afin de permettre des téléchargements plus rapides. La valeur par défaut est égale à tune.bufsize (16384), ce qui permet au moins 1,25 Mbps de bande passante par flux avec un temps de ping de 100 ms, ou 125 Mbps avec un temps de ping de 1 ms. Ce paramètre n’affecte pas l’utilisation des ressources. Utiliser des valeurs trop élevées peut entraîner une perte de réactivité côté client si des pages sont chargées en parallèle avec de grands téléchargements. Il est préférable d’utiliser tune.h2.fe.rxbuf à la place, qui ne provoque aucune injustice.
Voir également : tune.h2.initial-window-size.
tune.h2.fe.max-concurrent-streams <number> [args...]
Définit le nombre maximum de flux simultanés par connexion entrante (HTTP/2) (c’est-à-dire le nombre de requêtes en attente sur une connexion unique depuis un client). Si ce paramètre n’est pas défini, la valeur par défaut définie par tune.h2.max-concurrent-streams s’applique. Une valeur plus élevée que la valeur par défaut de 100 peut parfois améliorer légèrement le temps de chargement des pages pour des sites complexes comportant de nombreux objets de petite taille sur des réseaux à forte latence, mais peut également entraîner une utilisation accrue de la mémoire en permettant au client d’allouer plus de ressources en même temps. La valeur par défaut de 100 est généralement appropriée, et il est recommandé de ne pas modifier cette valeur. Une concurrence plus élevée a également un impact sur la charge de traitement et la latence lors de la gestion d’un grand nombre de connexions qui utilisent elles-mêmes de nombreux flux, et peut réduire la barrière contre les attaques par déni de service. La commande prend en charge les arguments optionnels suivants après le nombre :
- rq-load {
<number>| auto | ignore } :
- min
<number>:
Exemple :
tune.h2.fe.max-frames-at-once <number>
Définit le nombre maximal de trames entrantes HTTP/2 traitées simultanément sur une connexion frontale. Il peut être utile de le définir à une valeur faible (quelques dizaines à quelques centaines) lors de la gestion de très grands tampons afin de maintenir une faible latence et une meilleure équité entre plusieurs connexions. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.
tune.h2.fe.max-rst-at-once <number>
Définit le nombre maximal de HTTP/2 entrants RST_STREAM qui seront traités simultanément sur une connexion frontale. Dès réception du nombre spécifié de trames RST_STREAM, le gestionnaire de connexion sera placé dans une file d’attente à faible priorité et traité après toutes les autres tâches. Il peut être utile de le définir à une valeur très faible (1 ou quelques unités) afin de réduire significativement les impacts des inondations RST_STREAM. Les RST_STREAM se produisent effectivement lorsque l’utilisateur clique sur le bouton Arrêter dans son navigateur, mais les quelques millisecondes supplémentaires dues à ce ré-empilement sont généralement imperceptibles, tout en étant généralement efficaces pour réduire fortement la charge provoquée par de telles inondations. La valeur par défaut est zéro, ce qui signifie qu’aucune limitation n’est appliquée.
tune.h2.fe.max-total-streams <number>
Définit le nombre maximal de flux totaux traités par connexion entrante pour HTTP/2. Dès que cette limite est atteinte, HAProxy envoie un cadre GOAWAY gracieux informant le client qu’il fermera la connexion après la fermeture de tous les flux en cours. En pratique, les clients ferment généralement aussi rapidement que possible lorsqu’ils reçoivent ce cadre, puis établissent une nouvelle connexion pour les requêtes suivantes. Cette approche peut être utile et souhaitable dans des situations où les clients restent connectés très longtemps et provoquent un déséquilibre au sein d’une ferme. Par exemple, dans certains environnements hautement dynamiques, il est possible qu’un nouveau répartiteur de charge soit instancié en temps réel pour s’adapter à une augmentation de charge, et qu’une fois la charge redescendue, il doive être arrêté sans rompre les connexions établies. En définissant une limite ici, les connexions auront une durée de vie limitée et seront régulièrement renouvelées, certaines pouvant être établies vers d’autres nœuds, afin que les ressources existantes soient rapidement libérées.
Il est important de comprendre qu’il existe une relation implicite entre cette limite et “tune.h2.fe.max-concurrent-streams” ci-dessus. En effet, HAProxy acceptera toujours le traitement de toutes les connexions potentiellement en cours entre le client et le frontal, de sorte que la limite annoncée sera toujours automatiquement augmentée de la valeur configurée dans max-concurrent-streams, qui servira de limite stricte au-delà de laquelle une violation par un client non conforme entraînera la fermeture de la connexion. Ainsi, lors du comptage du nombre de requêtes par connexion à partir des journaux, tout nombre compris entre max-total-streams et (max-total-streams + max-concurrent-streams) peut être observé, selon la vitesse à laquelle les connexions sont créées par le client.
La valeur par défaut est zéro, ce qui impose aucune limite au-delà de celles implicites par le protocole (2^30 ≈ 1,07 milliard). Des valeurs autour de 1000 peuvent déjà entraîner une renouvellement fréquent des connexions sans provoquer de latence perceptible pour la plupart des clients. Définir cette valeur trop basse peut entraîner une augmentation de la charge CPU due aux reconnexions TLS fréquentes, ainsi qu’une augmentation du temps de chargement des pages. Veuillez noter que certains outils de test de charge ne prennent pas en charge les reconnexions et peuvent signaler des erreurs avec ce paramètre ; il peut donc être nécessaire de le désactiver lors de l’exécution de benchmarks de performance. Voir également “tune.h2.fe.max-concurrent-streams”.
tune.h2.fe.rxbuf <size>
Définit la taille de la mémoire tampon de réception HTTP/2 pour les connexions entrantes, en octets. Cette taille sera arrondie au multiple suivant de tune.bufsize et sera partagée entre toutes les transmissions de données (cadres HEADERS et DATA). Dans tous les cas, une mémoire tampon sera toujours attribuée à chaque flux, et 7/8 des mémoires tampons non utilisées seront partagées entre les flux transmettant des charges utiles, permettant d’améliorer significativement les performances de transmission. La fenêtre par flux annoncée est automatiquement ajustée pour refléter l’espace disponible, de sorte qu’en pratique il ne devrait pas être nécessaire de modifier tune.h2.fe.initial-window-size. Si la valeur définie est inférieure à celle requise pour gérer tous les flux, la valeur minimale sera utilisée. La valeur par défaut de 1600k (100 flux avec des tampons de 16 ko chacun) permet une vitesse de transmission d’environ 130 Mbps pour un client ayant un RTT de 100 ms.
Voir également : tune.h2.fe.initial-window-size et tune.h2.be.rxbuf.
tune.h2.header-table-size <number>
Définit la taille du tableau dynamique d’en-têtes HTTP/2. La valeur par défaut est de 4096 octets et ne peut pas dépasser 65536 octets. Une valeur plus élevée peut aider certains clients à envoyer des requêtes plus compactes, selon leurs capacités. Cette quantité de mémoire est consommée pour chaque connexion HTTP/2. Il est recommandé de ne pas la modifier.
tune.h2.initial-window-size <number>
Définit la valeur par défaut de la taille initiale de la fenêtre HTTP/2, sur les connexions entrantes et sortantes. Cette valeur est utilisée pour les connexions entrantes lorsque tune.h2.fe.initial-window-size n’est pas définie, et pour les connexions sortantes lorsque tune.h2.be.initial-window-size n’est pas définie. Ce paramètre est utilisé à la fois comme valeur initiale et comme minimum par flux. La valeur par défaut est égale à 16384 (tune.bufsize), ce qui permet, pour les téléchargements, une bande passante d’au moins 1,25 Mbps par flux sur un réseau affichant un temps de ping de 100 ms, ou 125 Mbps sur un réseau local à 1 ms. Lorsque le nombre de tampons reçus est inférieur au maximum, dans les limites définies par tune.h2.be.rxbuf et tune.h2.fe.rxbuf, les tampons non utilisés sont partagés entre les flux en réception. En conséquence, il n’est normalement pas utile de modifier cette valeur par défaut. Étant donné qu’un changement de cette valeur par défaut augmente à la fois les vitesses de téléchargement et provoque une plus grande injustice entre les clients lors des téléchargements, il est recommandé d’utiliser plutôt les paramètres spécifiques aux côtés tune.h2.fe.initial-window-size et tune.h2.be.initial-window-size.
tune.h2.log-errors { none | connection | stream }
Définit le niveau d’erreurs dans le démultiplexeur H2 qui déclenchera une journalisation. La valeur par défaut est « stream », ce qui signifie que toute erreur de décodage rencontrée dans le démultiplexeur entraînera l’émission d’un journal. La valeur « connection » indique que seules les erreurs entraînant l’invalidation de la connexion produiront une journalisation. Enfin, « none » indique qu’aucune erreur de décodage ne produira de journal. Il est recommandé de définir au moins « connection » afin de détecter les anomalies protocolaires, même si cela implique de passer temporairement à « none » pendant les périodes difficiles.
tune.h2.max-concurrent-streams <number>
Définit le nombre maximal par défaut de flux simultanés par connexion (HTTP/2) (c’est-à-dire le nombre de requêtes en cours sur une connexion unique). Cette valeur est utilisée pour les connexions entrantes lorsque tune.h2.fe.max-concurrent-streams n’est pas définie, et pour les connexions sortantes lorsque tune.h2.be.max-concurrent-streams n’est pas définie. La valeur par défaut est 100. L’impact varie selon le côté ; veuillez consulter les deux paramètres ci-dessus pour plus de détails. Il est recommandé de ne pas utiliser ce paramètre et de passer aux paramètres par côté à la place. Une valeur nulle désactive la limite, permettant à un client unique de créer autant de flux qu’autorisé par HAProxy. Il est fortement recommandé de ne pas modifier cette valeur.
tune.h2.max-frame-size <number>
Définit la taille maximale de trame HTTP/2 que HAProxy annonce être prêt à recevoir de ses pairs. La valeur par défaut est la plus grande entre 16384 et la taille de tampon (tune.bufsize). En tout état de cause, HAProxy n’annonce pas de prise en charge de tailles de trames supérieures à celles des tampons. Le principal objectif de ce paramètre est de permettre de limiter la taille maximale de trame lorsqu’on utilise des tampons de grande taille. Des tailles de trames trop importantes peuvent avoir un impact sur les performances ou provoquer un comportement anormal chez certains pairs. Il est fortement recommandé de ne pas modifier cette valeur.
tune.h2.zero-copy-fwd-send { on | off }
Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur H2. Activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding
tune.http.cookielen <number>
Définit la longueur maximale des cookies capturés. Il s’agit de la valeur maximale autorisée pour la directive « capture cookie xxx len yyy », toute valeur supérieure étant automatiquement tronquée à cette valeur. Il est important de ne pas définir une valeur trop élevée, car toutes les captures de cookies allouent toujours cette taille, quelle que soit leur valeur configurée (elles partagent un même pool). Cette valeur est par requête et par réponse, donc la mémoire allouée est deux fois cette valeur par connexion. Si non spécifié, la limite est fixée à 63 caractères. Il est recommandé de ne pas modifier cette valeur.
tune.http.logurilen <number>
Définit la longueur maximale de l’URI de requête dans les journaux. Cela empêche le troncature des URI de requête longs contenant des chaînes de requête précieuses dans les lignes de journal. Ceci n’est pas lié aux limites syslog. Si vous augmentez cette limite, vous pouvez également augmenter le paramètre ’log … len yyy’. Votre démon syslog peut également nécessiter des directives de configuration spécifiques. La valeur par défaut est 1024.
tune.http.maxhdr <number>
Définit le nombre maximal d’en-têtes autorisés dans les messages HTTP reçus. Lorsqu’un message contient un nombre d’en-têtes supérieur à cette valeur (y compris la première ligne), il est rejeté avec un code d’état « 400 Bad Request » pour une requête, ou « 502 Bad Gateway » pour une réponse. La valeur par défaut est 101, suffisante pour toutes les utilisations, étant donné que le serveur Apache largement déployé utilise la même limite. Il peut être utile d’augmenter cette limite temporairement afin de permettre le fonctionnement d’une application défectueuse jusqu’à sa correction. La plage acceptée est 1..32767. Prenez en compte que chaque nouvel en-tête consomme 32 bits de mémoire par flux, n’augmentez donc pas cette limite de manière excessive.
Notez que HTTP/1.1 est un protocole texte, il n’existe donc aucune limite particulière lors de l’envoi du message. La limite appliquée lors de l’analyse du message est suffisante. HTTP/2 et HTTP/3 sont des protocoles binaires et nécessitent une étape de codage. Une limite est également définie lors du codage des en-têtes afin de respecter les contraintes imposées par les protocoles. Cette limite est suffisamment élevée, mais n’est pas documentée intentionnellement. La même limite s’applique aux premières étapes du décodage, pour la même raison.
tune.idle-pool.shared { full | on | off }
Contrôle le partage des pools de connexions inactives entre les threads pour un même serveur. Il peut être activé pour tous les threads d’un même groupe de threads (‘on’), activé pour tous les threads (‘full’) ou désactivé (‘off’). La valeur par défaut consiste à partager les pools entre les threads du même groupe de threads (‘on’), afin de minimiser le nombre de connexions persistantes vers un serveur et d’optimiser le taux de réutilisation des connexions. Le partage avec des threads provenant d’autres groupes de threads peut avoir un impact sur les performances, et n’est pas activé par défaut, mais peut être utile si la réutilisation maximale des connexions est une priorité. Pour faciliter le débogage ou en cas de suspicion de bug dans HAProxy concernant la réutilisation des connexions, il peut être pratique de désactiver de force le partage des pools inactifs entre plusieurs threads, et de forcer cette option à « off ». Il est fortement déconseillé de désactiver cette option sans définir une valeur conservatrice sur « pool-low-conn » pour tous les serveurs qui dépendent de la réutilisation des connexions afin d’atteindre un haut niveau de performance, sinon les connexions pourraient être fermées très fréquemment à mesure que le nombre de threads augmente.
tune.idletimer <timeout>
Définit la durée après laquelle HAProxy considère qu’un tampon vide est probablement associé à un flux inactif. Cela permet d’ajuster de manière optimale certaine taille de paquets lors du transfert de données importantes et petites de façon alternée. La décision d’utiliser splice() ou d’envoyer des tampons volumineux en SSL est influencée par ce paramètre. La valeur est exprimée en millisecondes, comprise entre 0 et 65535. Une valeur nulle signifie que HAProxy ne tentera pas de détecter les flux inactifs. La valeur par défaut est 1000, qui semble correctement détecter les pauses utilisateur (par exemple, lire une page avant de cliquer). Il n’y a aucune raison de modifier cette valeur. Veuillez consulter tune.ssl.maxrecord ci-dessous.
tune.listener.default-shards { by-process | by-thread | by-group }
Par défaut, toutes les lignes « bind » créent une seule partition, c’est-à-dire un seul socket que tous les threads du processus écoutent. Avec un grand nombre de threads, cela n’est pas très efficace et peut même entraîner un surcroît important de charge dans le noyau pour mettre à jour l’état de surveillance ou distribuer les événements aux différents threads. Les systèmes d’exploitation modernes prennent en charge l’équilibrage des connexions entrantes, un mécanisme qui permet de lier plusieurs sockets à la même adresse et au même port, et de répartir uniformément toutes les connexions entrantes entre ces sockets afin que chaque thread ne voie que les connexions en attente dans le socket auquel il est lié. Cela réduit considérablement la charge côté noyau et améliore les performances dans le chemin des connexions entrantes. Ce mécanisme est généralement activé dans HAProxy à l’aide de l’option « shards » sur les lignes « bind », qui vaut 1 par défaut, ce qui signifie qu’un écouteur est unique par processus. Sur les systèmes disposant de nombreux processeurs, il peut être plus pratique de modifier ce paramètre par défaut en « by-thread » afin de toujours créer un socket d’écoute par thread, ou en « by-group » afin de toujours créer un socket d’écoute par groupe de threads. Faites attention à l’utilisation des descripteurs de fichiers avec « by-thread », car chaque écouteur nécessite autant de sockets qu’il y a de threads. Certains systèmes d’exploitation (par exemple FreeBSD) limitent à 256 le nombre de sockets sur une même adresse. Notez que « by-group » reste équivalent à « by-process » pour les configurations par défaut impliquant un seul groupe de threads, et revient à partager le même socket sur les systèmes qui ne prennent pas en charge ce mécanisme. La valeur par défaut est « by-group », avec un retour à « by-process » pour les systèmes ou familles de sockets qui ne prennent pas en charge les liaisons multiples.
tune.listener.multi-queue { on | fair | off }
Active (‘on’ / ‘fair’) ou désactive (‘off’) le mécanisme d’acceptation multi-file d’écouteur, qui répartit le trafic entrant sur tous les threads auxquels une directive « bind » est autorisée, plutôt que de les réserver à lui seul. Cela permet une répartition plus uniforme du trafic et une meilleure évolutivité, en particulier dans les environnements où les threads peuvent être déséquilibrés en charge en raison d’activités externes (par exemple, des interruptions réseau qui convergent sur un même thread). Le mode par défaut, « on », optimise le choix du thread en sélectionnant, parmi un échantillon, celui qui possède le moins de connexions. Il s’agit souvent du meilleur choix lorsque les connexions sont longues, car il parvient à maintenir tous les threads occupés. Un deuxième mode, « fair », parcourt tous les threads indépendamment de leur charge instantanée. Il peut être plus adapté aux connexions de courte durée, ou sur des machines disposant d’un très grand nombre de threads, où la probabilité de trouver le thread le moins chargé avec le mode « on » est faible. Enfin, il est possible de désactiver de force le mécanisme de redistribution en utilisant « off », notamment pour le dépannage, ou dans les cas où les connexions sont de courte durée et où l’on estime que le système d’exploitation assure déjà une répartition suffisamment efficace. La valeur par défaut est « on ».
tune.lua.bool-sample-conversion { normal | pre-3.1-bug }
Indiquez explicitement à HAProxy comment gérer les objets d’extraction d’échantillon lors de leur transmission à Lua. En effet, lors de l’utilisation des convertisseurs natifs, les extraits d’échantillons ou les variables provenant de scripts Lua (parmi d’autres) sont convertis du type interne smp en type Lua équivalent. En raison d’une implémentation historique, une ambiguïté existe concernant la gestion des booléens : lors de la conversion Lua → HAProxy smp, les booléens sont correctement conservés, mais lors de la conversion HAProxy smp → Lua, les booléens étaient par erreur convertis en entiers. Cela signifie qu’une extraction d’échantillon ou un convertisseur retournant un booléen renverrait un entier 0 ou 1 lorsqu’il est utilisé depuis Lua. Malheureusement, en Lua, les booléens et les entiers ne sont pas interchangeables. Ainsi, pour éviter toute ambiguïté, “tune.lua.bool-sample-conversion” doit être explicitement défini sur « normal » (ce qui signifie abandonner le comportement historique pour une meilleure cohérence) ou sur “pre-3.1-bug” (forcer le comportement historique afin de prévenir les dysfonctionnements des scripts existants). Si l’option n’est pas définie explicitement et qu’un script Lua est chargé à partir de la configuration, HAProxy émettra un avertissement, et l’option passera implicitement à “pre-3.1-bug” afin de conserver le comportement historique. Il est recommandé de définir cette option sur « normal » après avoir vérifié que les scripts Lua en cours d’utilisation gèrent correctement les échantillons HAProxy booléens comme des booléens.
Ce paramètre doit être défini avant toute directive « lua-load » ou « lua-load-per-thread » pour être pris en compte, sinon il est ignoré.
tune.lua.burst-timeout <timeout>
Le délai d’expiration « burst » s’applique à tout gestionnaire Lua. Si le gestionnaire ne parvient pas à se terminer ou à effectuer une suspension avant l’expiration du délai, il sera interrompu afin d’éviter les conflits de thread, d’empêcher le trafic de ne pas être servi trop longtemps, et d’empêcher finalement le processus de planter en raison de l’activation du watchdog. Contrairement aux autres délais d’expiration Lua, qui sont cumulatifs lors des suspensions, le délai d’expiration « burst » garantit que le temps passé dans une seule fenêtre d’exécution Lua ne dépasse pas le délai configuré.
Ici, « yield » signifie que l’exécution Lua est effectivement interrompue, soit par un appel explicite à une fonction de type lua-yielding, telle que core.(m)sleep() ou core.yield(), soit suite à une interruption forcée automatique (voir tune.lua.forced-yield), et qu’elle sera reprise ultérieurement lorsque la tâche associée sera remise en planification. Tous les gestionnaires Lua ne peuvent pas effectuer de yield : il convient de distinguer les gestionnaires pouvant effectuer un yield de ceux qui ne peuvent pas.
Pour les gestionnaires récupérables (tâches, actions…), atteindre le délai d’expiration signifie que “tune.lua.forced-yield” pourrait être trop élevé pour le système ; le réduire pourrait améliorer la situation, mais il pourrait aussi être pertinent de vérifier si l’ajout de rendus manuels à certains points clés au sein de la fonction Lua aide ou non. Cela peut également indiquer que le gestionnaire passe trop de temps dans une fonction spécifique de la bibliothèque Lua qui ne peut pas être interrompue.
Pour les gestionnaires intransigeants (convertisseurs Lua, extraits d’échantillon), cela peut simplement indiquer que le gestionnaire effectue trop de calculs, ce qui peut résulter d’une conception inappropriée, étant donné que ces gestionnaires, qui bloquent souvent le flux d’exécution de la requête, doivent se terminer rapidement afin de permettre la progression du traitement de la requête. Une approche courante de résolution consisterait à optimiser davantage la fonction Lua en termes de vitesse, car réduire “tune.lua.forced-yield” n’aiderait pas.
Ce délai d’expiration ne prend en compte que l’exécution pure du runtime Lua. Si Lua effectue un appel à core.sleep, le temps d’attente n’est pas pris en compte. Le délai d’expiration par défaut est de 1000 ms.
Note : si un cycle de ramasse-miettes Lua est initié depuis le gestionnaire (soit explicitement demandé, soit déclenché automatiquement par Lua après un certain temps), la durée de ce cycle sera également prise en compte.
En effet, il n’existe aucun moyen de déduire la durée du cycle de ramassage automatique (GC), ce qui peut entraîner certains faux positifs sur des systèmes saturés (où le GC peine à suivre et consomme la majeure partie du temps d’exécution disponible). Si tel était le cas, voici quelques pistes de résolution :
- vérification de la possibilité d'optimiser le script afin de réduire l'utilisation mémoire Lua
- ajustement des paramètres de GC Lua et/ou demande de cycles de GC manuels
(voir : https://www.lua.org/manual/5.4/manual.html#pdf-collectgarbage)
- augmentation de tune.lua.burst-timeout
Définir la valeur à 0 désactive entièrement cette protection.
tune.lua.forced-yield <number>
Ce directive force le moteur Lua à effectuer une suspension à chaque <number> d’instructions exécutées.
Cela permet d’interrompre un script long et permet au planificateur HAProxy de traiter d’autres tâches, comme l’acceptation de connexions ou le transfert de trafic. La valeur par défaut est de 10 000 instructions pour les scripts chargés avec « lua-load-per-thread » et de MAX(500, 10 000 / nbthread) instructions pour les scripts chargés avec « lua-load » (valeur optimale pour les performances tout en évitant les conflits de thread dus à la concurrence pour le verrou global Lua).
Si HAProxy exécute fréquemment du code Lua mais que plus de réactivité est nécessaire, cette valeur peut être réduite. Si le code Lua est assez long et que son résultat est absolument nécessaire pour traiter les données, la valeur de <number> peut être augmentée, mais celle-ci doit être définie avec prudence, car dans un contexte multithreadé, elle pourrait accroître la contention.
tune.lua.log.loggers { on | off }
Active (‘on’) ou désactive (‘off’) la journalisation de la sortie des scripts LUA via les journaux applicables au proxy actuel, le cas échéant.
Par défaut, ‘on’.
tune.lua.log.stderr { on | auto | off }
Active (‘on’) ou désactive (‘off’) la journalisation de la sortie des scripts LUA via stderr. Lorsqu’elle est définie sur ‘auto’, la journalisation via stderr est activée de manière conditionnelle si l’une des conditions suivantes est remplie :
- tune.lua.log.loggers est défini sur « off »
- le script est exécuté dans un contexte non proxy sans logger global
- le script est exécuté dans un contexte proxy sans logger attaché
Veuillez noter que, lorsqu’elle est activée, cette journalisation s’ajoute à la journalisation configurée via tune.lua.log.loggers.
Valeur par défaut : « auto ».
tune.lua.maxmem <number>
Définit la quantité maximale de mémoire RAM en mégaoctets par processus utilisable par Lua. Par défaut, elle est nulle, ce qui signifie sans limite. Il est important de définir une limite afin d’assurer qu’une erreur dans un script ne provoque pas l’épuisement de la mémoire du système.
tune.lua.openlibs [all | none | <lib>[,<lib>...]]
Sélectionne les bibliothèques standard Lua à charger lors de l’initialisation de l’état Lua. L’argument est une liste séparée par des virgules de noms de bibliothèques provenant de l’ensemble suivant : table, io, os, string, math, utf8, package, debug. Les valeurs spéciales « all » et « none » peuvent être utilisées à la place d’une liste. « none » ne peut pas être combinée avec des noms de bibliothèques. La valeur par défaut est « all ».
Les bibliothèques base et coroutine sont toujours chargées, quelle que soit cette configuration : base fournit les fonctions Lua de base sur lesquelles HAProxy s’appuie, et coroutine est requise car HAProxy remplace coroutine.create() par une implémentation sécurisée propre à son environnement.
Notez que les appels à fork() et la création de nouveaux threads sont déjà bloqués par défaut dans HAProxy, quelle que soit cette configuration, et ne peuvent être réactivés qu’à l’aide de la directive globale « insecure-fork-wanted ». Restreindre l’ensemble des bibliothèques chargées réduit davantage la surface d’attaque exposée aux scripts Lua. En particulier : - l’omission de « os » empêche l’utilisation de os.execute() et os.exit() - l’omission de « io » empêche l’utilisation de io.open() et io.popen() - l’omission de « package » empêche le chargement de modules C natifs via require() - l’omission de « debug » empêche l’inspection interne de HAProxy via debug.getupvalue(), debug.getmetatable() ou debug.sethook()
Exemples :
Ce paramètre doit être défini avant toute directive « lua-load », « lua-load-per-thread » ou « lua-prepend-path », faute de quoi une erreur de parsing est renvoyée.
tune.lua.service-timeout <timeout>
Ce délai d’expiration correspond à l’exécution des services Lua. Il est utile pour empêcher les boucles infinies ou des durées d’exécution trop longues en Lua. Ce délai ne prend en compte que le runtime pur Lua. Si le code Lua effectue une pause, celle-ci n’est pas prise en compte. La valeur par défaut est de 4 s.
tune.lua.session-timeout <timeout>
Ce délai d’expiration correspond à l’exécution des sessions Lua. Il est utile pour empêcher les boucles infinies ou des durées d’exécution trop longues en Lua. Ce délai ne prend en compte que l’exécution réelle du runtime Lua. Si la session Lua effectue une pause, celle-ci n’est pas prise en compte. La valeur par défaut est de 4 s.
tune.lua.task-timeout <timeout>
Le but est le même que “tune.lua.session-timeout”, mais ce délai d’expiration est dédié aux tâches. Par défaut, ce délai d’expiration n’est pas défini, car une tâche peut rester active pendant toute la durée de vie de HAProxy. Par exemple, une tâche utilisée pour vérifier les serveurs.
tune.max-checks-per-thread <number>
Définit le nombre de contrôles d’état actifs par thread au-delà duquel un thread tentera activement de rechercher un thread moins chargé pour exécuter le contrôle d’état, ou le mettra en file d’attente jusqu’à ce que le nombre de contrôles d’état actifs en cours d’exécution sur ce thread diminue. La valeur par défaut est zéro, ce qui signifie qu’aucune limite n’est définie. Ce paramètre peut être nécessaire dans certains environnements exécutant un très grand nombre de contrôles coûteux avec de nombreux threads lorsque la charge semble inégale, ce qui peut entraîner des délais d’expiration aléatoires des contrôles d’état au démarrage, notamment lors de l’utilisation d’OpenSSL 3.0, qui est environ 20 fois plus intensif en ressources CPU pour les contrôles d’état que les versions antérieures. Cela permettra de répartir équitablement le travail des contrôles d’état sur tous les threads. La grande majorité des configurations n’a pas besoin de modifier ce paramètre. Veuillez noter qu’une valeur trop faible peut considérablement ralentir les contrôles d’état si ces derniers sont lents à s’exécuter.
tune.maxaccept <number>
Définit le nombre maximal de connexions consécutives qu’un processus peut accepter d’affilée avant de passer à d’autres tâches. En mode mono-processus, des valeurs plus élevées permettaient d’obtenir de meilleures performances aux débits de connexion élevés, bien que cela ne soit plus pertinent avec la mise en file d’attente multiple. Cette valeur s’applique individuellement à chaque écouteur, de sorte que le nombre de processus auxquels un écouteur est lié est pris en compte. Sa valeur par défaut est 4, qui a montré les meilleurs résultats. Si une valeur nettement plus élevée a été héritée d’une configuration ancienne, il peut être utile de la supprimer, car cela améliore à la fois les performances et réduit le temps de réponse. En mode multi-processus, cette valeur est divisée par deux fois le nombre de processus auxquels l’écouteur est lié. Affecter la valeur -1 désactive complètement cette limitation. Il est normalement inutile de modifier cette valeur.
tune.maxpollevents <number>
Définit le nombre maximal d’événements pouvant être traités simultanément lors d’un appel au système de sondage. La valeur par défaut est adaptée au système d’exploitation. Il a été observé qu’une réduction de cette valeur en dessous de 200 tend à diminuer légèrement la latence au détriment de la bande passante réseau, tandis qu’une augmentation au-dessus de 200 tend à échanger latence contre une bande passante légèrement accrue. La valeur configurée doit être inférieure ou égale à 1000000.
tune.maxrewrite <number>
Définit l’espace mémoire réservé à cette taille en octets. Cet espace réservé est utilisé pour la réécriture ou l’ajout d’en-têtes. Les premières lectures sur les sockets ne rempliront jamais plus de bufsize-maxrewrite. Historiquement, cette valeur était définie par défaut à la moitié de bufsize, bien que cela n’ait pas beaucoup de sens puisqu’il est rare d’avoir un grand nombre d’en-têtes à ajouter. Une valeur trop élevée empêche le traitement des requêtes ou réponses volumineuses. Une valeur trop faible empêche l’ajout d’en-têtes supplémentaires aux requêtes déjà importantes ou aux requêtes POST. Il est généralement conseillé de la définir à environ 1024. Elle est automatiquement ajustée à la moitié de bufsize si elle est supérieure à cette valeur. Cela signifie que vous n’avez pas à vous soucier de cette option lors du changement de bufsize.
tune.max-rules-at-once <number>
Définit le nombre maximum de règles pouvant être évaluées simultanément dans les fonctions d’évaluation de règlesets, à condition qu’elles prennent en charge la suspension. En effet, il n’est pas rare de rencontrer des configurations comportant un grand nombre de règles telles que « tcp-request content » ou « http-request ». Un grand nombre de règles combiné à des actions exigeant beaucoup de ressources processeur (par exemple, des actions agissant sur le contenu) peut entraîner une contention de thread, car toutes les règles d’un même règleset sont évaluées dans la même boucle d’interrogation si l’évaluation n’est pas interrompue. Cette option garantit qu’au plus <number> règles ne peuvent être exécutées dans la même boucle d’interrogation pour les règlesets orientés contenu (ceux qui prennent déjà en charge la suspension en raison de l’inspection du contenu). Elle force ainsi la fonction d’évaluation à suspendre, de manière à revenir dans la boucle d’interrogation suivante pour poursuivre l’évaluation.
Les jeux de règles affectés sont :
- “tcp-request content”
- “tcp-response content”
- “http-request”
- “http-response”
La valeur par défaut est 50.
tune.memory.hot-size <number>
Définit la quantité de mémoire par thread qui sera conservée en cache local et qui ne pourra jamais être récupérée par d’autres threads. L’accès à cette mémoire est très rapide (sans verrouillage), et en disposer d’une quantité suffisante est essentiel pour maintenir un bon niveau de performance en cas de forte contention de threads. La valeur est exprimée en octets, et sa valeur par défaut est configurée au moment de la compilation via CONFIG_HAP_POOL_CACHE_SIZE, qui vaut par défaut 524288 (512 ko). Une valeur plus élevée peut améliorer les performances dans certains scénarios d’utilisation, notamment lorsque les profils de performance indiquent une forte contrainte d’allocation mémoire. L’expérience montre qu’une valeur optimale se situe entre une et deux fois la taille du cache L2 par cœur processeur. Des valeurs trop élevées ont un impact négatif sur les performances en provoquant une utilisation inefficace des caches L3 des processeurs, et consomment davantage de mémoire. Il est recommandé de ne pas modifier cette valeur, ou de le faire par petites incréments. Pour désactiver complètement les caches CPU par thread, une valeur très faible pourrait fonctionner, mais il est préférable d’utiliser “-dMno-cache” en ligne de commande.
tune.notsent-lowat.client <size>
Ajuste le tamponage par socket du noyau afin de signaler que le côté émetteur d’une socket est plein dès que la quantité de données tamponnées atteint cette valeur augmentée de la taille de fenêtre mesurée. Le principe consiste à maintenir dans les tampons socket la quantité strictement nécessaire de données, plus une petite marge correspondant à ce qui serait envoyé au moment où haproxy tente de réémettre. Une valeur faible (généralement proche de tune.bufsize) permet de réduire significativement la consommation mémoire dans les tampons système et de diminuer la latence au niveau de l’application due au vidage des données tamponnées. Cette configuration est généralement plus efficace et plus précise que tune.sndbuf.client et tune.sndbuf.client sur les systèmes qui la supportent. Elle s’applique par connexion (connexion depuis un client ou connexion vers un serveur selon le paramètre) et n’est utilisée que pour les connexions TCP. La valeur par défaut est zéro, ce qui signifie sans limite. Cette option n’est disponible que sous Linux.
tune.pattern.cache-size <number>
Définit la taille du cache de recherche de motifs à <number> entrées. Il s’agit d’un cache LRU qui conserve les recherches précédentes et leurs résultats. Ce cache est utilisé par les ACLs et les cartes lors de recherches de motifs lentes, à savoir celles utilisant les méthodes de correspondance « sub », « reg », « dir », « dom », « end », « bin », ainsi que les chaînes insensibles à la casse. Il s’applique aux expressions de motif, ce qui signifie qu’il peut mémoriser le résultat d’une recherche parmi tous les motifs spécifiés sur une ligne de configuration (y compris ceux chargés à partir de fichiers). Il invalide automatiquement les entrées mises à jour via des actions HTTP ou en ligne de commande. La taille par défaut du cache est fixée à 10 000 entrées, ce qui limite son empreinte à environ 5 Mo par process/thread sur les systèmes 32 bits et 8 Mo par process/thread sur les systèmes 64 bits, les caches étant thread/process locaux. Le risque de collision dans ce cache est très faible, de l’ordre de la taille du cache divisée par 2^64. En pratique, avec 10 000 requêtes par seconde et une taille de cache par défaut de 10 000 entrées, il y a 1 % de chance qu’une attaque par force brute provoque une collision unique après 60 ans, ou 0,1 % après 6 ans. Ce risque est considéré comme bien inférieur à celui d’une corruption mémoire causée par des composants vieillissants. Si ce niveau de risque n’est pas acceptable, le cache peut être désactivé en définissant ce paramètre à 0.
tune.peers.max-updates-at-once <number>
Définit le nombre maximal de mises à jour de table de persistance que HAProxy tentera de traiter en une seule fois lors de l’envoi de messages. Récupérer les données pour ces mises à jour nécessite des opérations de verrouillage qui peuvent être intensives en ressources CPU sur des machines fortement multithreadées si non limitées, et peuvent également augmenter la latence du trafic pendant le transfert initial par lots entre un processus plus ancien et un processus plus récent. À l’inverse, des valeurs faibles peuvent également entraîner un surcoût CPU plus élevé et prendre plus de temps à s’achever. La valeur par défaut est 200, et il est conseillé de ne pas la modifier.
tune.pipesize <size>
Définit la taille de la mémoire tampon du noyau pour les tubes à cette taille (en octets). Par défaut, les tubes ont la taille par défaut du système. Toutefois, dans certains cas, notamment lors de l’utilisation du découpage TCP, il peut améliorer les performances d’augmenter la taille des tubes, en particulier si l’on soupçonne que les tubes ne sont pas pleins et que de nombreuses appels à splice() sont effectués. Cela a une incidence sur la taille mémoire du noyau, donc cette valeur ne doit pas être modifiée si les impacts ne sont pas compris.
tune.pool-high-fd-ratio <number>
Ce paramètre définit le nombre maximal de descripteurs de fichiers (en pourcentage) utilisés globalement par HAProxy par rapport au nombre maximal de descripteurs de fichiers que HAProxy peut utiliser avant de commencer à tuer les connexions inactives lorsque nous ne pouvons pas réutiliser une connexion et devons en créer une nouvelle. La valeur par défaut est 25 (un quart du nombre de descripteurs signifie qu’environ la moitié du nombre maximal de connexions frontales peut maintenir une connexion inactif derrière, tout au-delà de ce seuil ne semble généralement pas pertinent dans le cas général lorsqu’on cible la réutilisation des connexions).
tune.pool-low-fd-ratio <number>
Ce paramètre définit le nombre maximal de descripteurs de fichiers (en pourcentage) utilisés globalement par HAProxy par rapport au nombre maximal de descripteurs de fichiers que HAProxy peut utiliser avant de cesser de placer les connexions dans le pool inactif pour réutilisation. La valeur par défaut est 20.
tune.pt.zero-copy-forwarding { on | off }
Active (‘on’) ou désactive (‘off’) le transfert zéro-copie des données pour le multiplexeur en pass-through. À utiliser uniquement si le splice du noyau est également configuré. Activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding, option splice-auto, option splice-request et option splice-response
tune.quic.be.cc.cubic-min-losses <number>
Définit le nombre de paquets perdus nécessaires pour que l’algorithme de contrôle de congestion Cubic considère réellement un événement de perte. En règle générale, tout événement de perte est considéré comme le résultat d’une congestion et suffisant pour que Cubic reparte d’une fenêtre plus petite. Toutefois, des expérimentations montrent qu’il existe diverses causes de pertes qui ne sont pas du tout dues à une congestion et qui peuvent simplement être qualifiées de pertes erronées, pour lesquelles l’ajustement de la fenêtre n’a aucun effet, sauf à ralentir la communication. Une mauvaise qualité du signal radio, une livraison hors ordre, une utilisation élevée du CPU par un client entraînant des délais aléatoires, ainsi que des imprécisions du timer système peuvent être parmi les causes courantes de ce phénomène. Ce paramètre permet de rendre Cubic un peu plus tolérant aux pertes erronées en modifiant le nombre minimum de pertes cumulées entre deux ACKs nécessaires pour considérer un événement de perte, qui est par défaut de 1. Des gains significatifs ont été observés expérimentalement, mais toujours accompagnés d’une augmentation de la bande passante gaspillée par les retransmissions et d’un risque accru de saturation des liens congestionnés. La valeur 2 peut être utilisée ponctuellement pour comparer certains métriques. N’allez jamais au-delà de 2 sans une analyse préalable par un expert. La valeur par défaut et minimale est 1. Utilisez toujours 1.
tune.quic.cc.cubic.min-losses <number> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.cc.hystart { on | off }
Active (‘on’) ou désactive (‘off’) l’algorithme HyStart++ (RFC 9406) pour les connexions QUIC, utilisé comme substitution à la phase de démarrage lent des algorithmes de contrôle de congestion, qui peut entraîner une perte élevée de paquets. Il est désactivé par défaut.
tune.quic.cc-hystart { on | off } (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.cc.max-frame-loss <number>
Définit la limite à partir de laquelle un cadre QUIC unique peut être marqué comme perdu. Si cette limite est dépassée, la connexion est considérée comme défaillante et est fermée immédiatement.
La valeur par défaut est 10.
tune.quic.max-frame-loss <number> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.cc.max-win-size <size>
Définit la taille maximale par défaut de la fenêtre du contrôleur de congestion pour une connexion QUIC unique, côté frontal ou backend. La valeur doit être indiquée sous forme d’entier, éventuellement suivie d’un suffixe « k », « m » ou « g ». Elle doit être comprise entre 10k et 4g.
Le multiplexeur QUIC utilise également la taille actuelle de la fenêtre de congestion pour déterminer s’il peut allouer de nouveaux tampons de flux lors de l’émission de données. En conséquence, la taille maximale de la fenêtre de congestion sert également de limite à cet allocateur.
La valeur par défaut est de 480 ko.
Voir également les options de liaison et de serveur « quic-cc-algo ».
tune.quic.frontend.default-max-window-size <size> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.cc.reorder-ratio <0..100, in percent>
Le ratio appliqué au seuil de réordonnancement des paquets calculé. Il peut déclencher une détection de perte de paquets élevée lorsqu’il est trop petit.
La valeur par défaut est 50.
tune.quic.reorder-ratio <0..100, in percent> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.max-idle-timeout <timeout>
Définit le paramètre de transport QUIC max_idle_timeout sur le côté frontal ou backend. Il suit le format de temps HAProxy et s’exprime en millisecondes. Ce paramètre détermine la durée après laquelle une connexion est fermée silencieusement si elle est restée inactif pendant une période effective. Les deux extrémités s’appuient sur la même valeur négociée : - le minimum des deux paramètres si les deux ne sont pas nuls, - le maximum si seulement l’un des deux n’est pas nul, - si les deux paramètres sont nuls, cette fonctionnalité est désactivée.
Valeur par défaut : 30 s.
tune.quic.frontend.max-idle-timeout <timeout> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.sec.glitches-threshold <number>
Définit le seuil du nombre de glitchs par connexion, côté frontal ou backend, au-delà duquel la connexion est automatiquement interrompue. Cela permet de tuer automatiquement les connexions défaillantes sans avoir à écrire de règles explicites pour elles. La valeur par défaut est zéro, ce qui indique qu’aucun seuil n’est défini, donc aucune occurrence ne provoquera la fermeture d’une connexion. Attention, certains clients QUIC peuvent occasionnellement provoquer quelques glitchs sur des connexions longues, donc toute valeur non nulle ici devrait probablement être de l’ordre des centaines ou des milliers pour être efficace sans affecter les clients légèrement défaillants. Il est également possible de ne tuer les connexions que lorsque la consommation du CPU dépasse un certain seuil, en utilisant “tune.glitches.kill.cpu-usage”.
Voir aussi : fc_glitches, tune.glitches.kill.cpu-usage
tune.quic.frontend.glitches-threshold <number> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.fe.sec.retry-threshold <number>
Active dynamiquement la fonctionnalité Retry pour tous les écouteurs QUIC configurés dès que ce nombre de connexions en demi-ouverture est atteint. Une connexion en demi-ouverture est une connexion dont la négociation n’a pas encore été correctement terminée ni échouée. Pour être fonctionnel, ce paramètre nécessite que le secret de cluster soit défini ; sinon, il sera ignoré silencieusement (voir le paramètre « cluster-secret »). Ce paramètre sera également ignoré silencieusement si l’utilisation du Retry QUIC a été forcée (voir le paramètre « quic-force-retry »).
La valeur par défaut est 100.
Consultez https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 pour plus d’informations sur la réessai QUIC.
tune.quic.retry-threshold <number> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.fe.sock-per-conn { default-on | force-off }
Spécifie globalement la manière dont les connexions frontend QUIC utiliseront le socket pour les opérations receive/send. Les connexions peuvent partager le socket de l’écouteur ou chacune peut allouer son propre socket.
Valeur par défaut : « default-on ». Cette option permet d’attribuer une socket dédiée à chaque connexion QUIC. Elle est recommandée pour obtenir les meilleurs performances avec un trafic QUIC important. Elle est également la seule manière d’assurer correctement l’arrêt doux sans perte de données pour les connexions QUIC, et de gérer efficacement les erreurs temporaires lors de l’opération sendto(). Toutefois, cette option dépend de fonctionnalités avancées du pilote réseau UDP. Si la plateforme est jugée incompatible, HAProxy basculera automatiquement en mode « force-off » au démarrage. Veuillez noter que les écouteurs QUIC sur des ports privilégiés peuvent nécessiter d’être exécutés en tant qu’uid 0, ou une configuration spécifique au système pour autoriser l’uid cible à lier ces ports, comme des capacités système. Voir également la directive globale « setcap ».
La valeur « force-off » indique que les transferts QUIC se produiront sur le socket d’écoute partagé. Cette option peut constituer un bon compromis pour un trafic faible, car elle permet de réduire la consommation de descripteurs de fichiers. Toutefois, les performances ne seront pas optimales en raison d’une utilisation accrue du CPU si les écouteurs sont partagés entre de nombreux threads ou si un grand nombre de connexions QUIC peuvent être utilisées simultanément.
Ce paramètre s’applique conjointement à chaque option de liaison « quic-socket ». Si le mode « default-on » est utilisé dans le réglage global, il est activé pour chaque écouteur, sauf pour ceux configurés avec « quic-socket listener ». En revanche, si « force-off » est utilisé globalement, il s’applique à chaque instance d’écouteur, indépendamment de leur configuration individuelle.
tune.quic.socket-owner { connection | listener } (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. La nouvelle option s’appelle “tune.quic.fe.sock-per-conn”, avec la valeur héritée « connection » correspondant à « default-on » et « listener » à « force-off ».
tune.quic.be.stream.data-ratio <0..100, in percent>
Ce paramètre permet de configurer la limite maximale du nombre d’octets de données en transit sur chaque flux. Il est exprimé en pourcentage par rapport au paramètre de connexion QUIC rxbuf du flux, le résultat étant arrondi vers le haut à bufsize.
La valeur par défaut est 90. Cette valeur convient à la plupart des scénarios web courants, où les téléchargements sont effectués uniquement pour un ou quelques flux, tandis que les autres sont utilisés uniquement pour les téléchargements. Si la limite de connexion rxbuf reste à un niveau raisonnable, cela garantit qu’uniquement une partie des flux ouverts peut atteindre sa capacité maximale.
Dans le cas d’une application utilisant de nombreux flux de téléchargement en parallèle et souffrant d’un manque d’équité entre ces flux, il peut être pertinent de réduire ce ratio, afin d’améliorer l’équité et de réduire la bande passante par flux.
Voir aussi : “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)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.stream.max-concurrent <number>
Du côté frontal, cette valeur est utilisée comme valeur du paramètre de transport initial_max_streams_bidi annoncé. Elle est imposée comme nombre maximal de flux bidirectionnels que le pair distant sera autorisé à ouvrir simultanément pendant la durée de vie de la connexion. Cela limite effectivement le nombre de requêtes clientes HTTP/3 simultanées.
Valeur par défaut : 100. Notez que si vous la réduisez, cela peut limiter les capacités de mise en mémoire tampon des flux en réception, ce qui entraînerait un débit de téléchargement médiocre. Cette situation peut être corrigée en augmentant le paramètre de connexion QUIC stream rxbuf.
Du côté backend, cela est appliqué localement par HAProxy afin de limiter le nombre de requêtes simultanées multiplexées sur une seule connexion. Ce paramètre peut être restreint davantage par le contrôle de flux du pair. Il peut être nécessaire de réduire la valeur par défaut de 100 afin d’améliorer la réactivité d’un site, au prix d’un nombre plus élevé de connexions backend ouvertes. De même que du côté frontal, ce paramètre influence directement la capacité de tamponnage en réception, mais cette fois-ci en limitant la capacité de téléchargement HTTP. La taille du tampon de réception des flux QUIC peut être augmentée lorsqu’on traite principalement des réponses HTTP dont la taille dépasse “tune.bufsize”.
Voir aussi : “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>
Définit le nombre maximal de requêtes pouvant être traitées par une connexion QUIC unique. Dès que ce seuil est atteint, la connexion est fermée de manière propre. Dans HTTP/3, cela se traduit par un cadre GOAWAY. La connexion est définitivement fermée une fois toutes les transmissions restantes terminées.
Ce paramètre est appliqué comme une limite stricte sur la connexion via le mécanisme de contrôle de flux QUIC. Si un pair la violer, la connexion sera immédiatement fermée.
Ce paramètre peut être utilisé pour obliger les clients à ouvrir de nouvelles connexions de temps à autre afin de poursuivre l’émission de requêtes et éviter de maintenir des connexions trop longtemps. Toutefois, des valeurs faibles augmenteront la latence du côté client, ainsi que la consommation CPU des deux côtés en raison des échanges TLS.
La valeur par défaut est 0, ce qui signifie qu’aucune limite spécifique n’est appliquée, en dehors de la limitation imposée par le protocole QUIC (2^60, soit plus d’un milliard de milliards).
tune.quic.frontend.max-streams-bidi <number> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.stream.rxbuf <size>
Ce paramètre constitue la limite maximale stricte du nombre d’octets de données en transit sur une connexion QUIC au niveau du frontal. Il est réutilisé comme valeur du paramètre de transport initial_max_data. Il influence directement le débit de téléchargement du pair, en fonction de la latence et de la consommation mémoire par connexion dans HAProxy.
Par défaut, la valeur est définie à 0, ce qui indique qu’elle doit être générée automatiquement comme le produit de max-concurrent et de bufsize. Cette valeur peut être augmentée, par exemple, si une application backend dépend de transferts massifs sur des réseaux à forte latence.
Voir aussi : “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)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.tx.pacing { on | off }
Active (‘on’) ou désactive (‘off’) le support du réglage du débit pour l’émission QUIC. Par défaut, il est activé. Le but du réglage du débit est de lisser l’émission des données afin de réduire les pertes réseau. Dans la plupart des scénarios, il améliore significativement le débit en évitant les retransmissions. Toutefois, il peut être utile de le désactiver sur des réseaux présentant des caractéristiques de latence très élevées bandwidth/low afin d’éviter des délais indésirables et de réduire la consommation CPU.
Voir également les options de liaison et de serveur « quic-cc-algo ».
tune.quic.disable-tx-pacing (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.be.tx.udp-gso { on | off }
Active (‘on’) ou désactive (‘off’) la prise en charge du GSO UDP pour l’émission QUIC. Par défaut, cette fonctionnalité est activée. Ce mécanisme du noyau permet d’émettre plusieurs datagrammes en une seule appel système, ce qui est plus efficace pour les transferts volumineux. Il peut être utile de la désactiver sur recommandation d’un développeur lorsqu’une anomalie est suspectée lors de l’émission.
tune.quic.disable-udp-gso (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.listen { on | off }
Désactive le protocole de transport QUIC du côté frontal. Tous les écouteurs QUIC seront toujours créés, mais ils n’écouteront pas les datagrammes entrants. Ainsi, aucun trafic QUIC ne sera traité par HAProxy du côté frontal.
Valeur par défaut : « on ». Si un problème est suspecté avec le trafic QUIC, cette option permet de basculer facilement les écouteurs QUIC sans modifier chaque ligne de configuration individuellement.
Voir également l’extraction d’échantillon “quic_enabled”.
tune.quic.mem.tx-max <size>
Définit la quantité maximale de mémoire utilisable par la pile QUIC au niveau du transport pour l’émission. Cela sert à la fois de limite aux octets en vol et aux tampons de sortie du multiplexeur. Notez que, afin d’éviter les conflits entre threads, cette limite n’est pas strictement appliquée, ce qui permet qu’elle soit dépassée occasionnellement. En outre, chaque connexion pourra toujours utiliser une fenêtre d’au moins 2 datagrammes, aussi une valeur appropriée de maxconn doit-elle être utilisée en complément.
tune.quic.frontend.max-tx-mem <size> (deprecated)
Ce mot-clé est obsolète depuis la version 3.3 et sera supprimé dans la version 3.5. Il fait partie du processus d’unification de la configuration QUIC. Si utilisé, ce paramètre ne sera appliqué qu’aux connexions frontal.
tune.quic.zero-copy-fwd-send { on | off }
Active (« on ») ou désactive (« off ») l’envoi en copie zéro des données pour le multiplexeur QUIC. Il est activé par défaut.
Voir aussi : tune.disable-zero-copy-forwarding
tune.renice.runtime <number>
Cette option de configuration prend une valeur comprise entre -20 et 19. Elle applique une priorité de planification telle que documentée dans man 2 setpriority. Cette priorité est appliquée après l’analyse de la configuration, ce qui signifie qu’elle ne s’applique qu’au processus worker ou au processus autonome. Elle est généralement configurée pour attribuer une priorité supérieure à celle d’un processus effectuant l’analyse de configuration (tune.renice.startup).
Voir aussi : tune.renice.startup
tune.renice.startup <number>
Cette option de configuration prend une valeur comprise entre -20 et 19. Elle applique une priorité de planification telle que documentée dans man 2 setpriority. Cette priorité est appliquée avant l’application du reste de la configuration, ce qui peut être utile si vous souhaitez réduire la priorité pendant l’analyse de la configuration. Cette priorité est appliquée au processus autonome ou au worker avant l’analyse de la configuration. Une fois la configuration analysée, la priorité précédente est restaurée, sauf si tune.renice.runtime est utilisé.
Voir aussi : tune.renice.runtime
tune.rcvbuf.backend <size>
Pour la taille du tampon de réception du socket noyau sur les sockets non connectés, jusqu’à cette taille. Cela peut être utilisé avec QUIC en mode écouteur et avec le transfert de journaux sur le frontal. Les tampons système par défaut peuvent parfois être trop petits pour les sockets recevant une forte charge de trafic agrégé, entraînant des pertes et éventuellement des retransmissions (dans le cas de QUIC), ce qui peut ralentir la mise en place des connexions sous une charge élevée. La valeur est exprimée en octets, appliquée à chaque socket. En mode écouteur, les sockets sont partagés entre toutes les connexions, et le nombre total de sockets dépend de la valeur « shards » de la ligne « bind ». Il n’existe pas de valeur optimale ; une bonne valeur correspond au produit de la taille attendue par connexion multipliée par le nombre attendu de connexions. Le noyau peut réduire les valeurs trop grandes. Voir également “tune.rcvbuf.client” et “tune.rcvbuf.server” pour leurs équivalents sur les sockets connectés, ainsi que “tune.sndbuf.backend” et “tune.sndbuf.frontend” pour le paramètre d’envoi.
tune.rcvbuf.client <size>
Force la taille du tampon de réception socket du noyau du côté client ou serveur à la valeur spécifiée, en octets. Cette valeur s’applique à tous les frontaux et backends TCP/HTTP. Elle devrait normalement jamais être définie, et la taille par défaut (0) permet au noyau d’ajuster automatiquement cette valeur en fonction de la mémoire disponible. Toutefois, il peut parfois être utile de la définir à des valeurs très faibles (par exemple 4096) afin de réduire l’utilisation de la mémoire noyau en empêchant celui-ci de tamponner des quantités trop importantes de données reçues. Des valeurs plus faibles augmentent toutefois significativement l’utilisation du CPU.
tune.recv_enough <size>
HAProxy utilise certains indicateurs pour détecter qu’une lecture courte indique la fin des tampons de socket. L’un d’eux est qu’une lecture retourne plus de <recv_enough> octets, valeur par défaut de 10136 (7 segments de 1448 chacun). Cette valeur par défaut peut être modifiée par ce paramètre afin de mieux gérer les charges de travail comportant de nombreuses messages courts, comme les sessions telnet ou SSH.
tune.ring.queues <number>
Définit le nombre de files d’écriture situées devant les tampons circulaires. Cela peut influer sur l’utilisation du CPU lors des sessions de débogage, et une valeur trop faible ou trop élevée peut avoir un impact important. La valeur optimale a été déterminée expérimentalement par les développeurs, et il n’y a aucune raison de la modifier sauf si explicitement indiqué afin de résoudre des problèmes spécifiques. Ce paramètre ne doit pas être conservé dans la configuration après une mise à jour de version, car sa valeur optimale peut évoluer au fil du temps.
tune.runqueue-depth <number>
Définit le nombre maximal de tâches pouvant être traitées simultanément lors de l’exécution des tâches. La valeur par défaut dépend du nombre de threads, mais se situe entre 35 et 280, des valeurs qui tendent à offrir les débits de requêtes les plus élevés et les latences les plus faibles. Augmenter cette valeur peut entraîner une augmentation de la latence lors du traitement de I/Os, tandis qu’une valeur trop faible peut engendrer un surcoût. Les nombres élevés de threads bénéficient de valeurs plus faibles. Lors de l’expérimentation avec des valeurs beaucoup plus élevées, il peut être utile d’activer également tune.sched.low-latency et éventuellement tune.fd.edge-triggered afin de limiter la latence maximale au niveau le plus bas possible.
tune.sched.low-latency { on | off }
Active (‘on’) ou désactive (‘off’) le planificateur de tâches à faible latence. Par défaut, HAProxy traite les tâches de plusieurs classes une classe à la fois, car c’est la méthode la plus efficace. Toutefois, lorsqu’on utilise de grandes valeurs pour tune.runqueue-depth, cela peut avoir un effet mesurable sur la latence des requêtes ou des connexions. Lorsque ce paramètre à faible latence est activé, les tâches des classes de priorité inférieure sont toujours exécutées avant les autres, si elles existent. Cela permet de réduire la latence maximale subie par de nouvelles requêtes ou connexions au milieu d’un trafic massif, au prix d’un impact plus élevé sur ce trafic important. Pour une utilisation régulière, il est préférable de le laisser désactivé. La valeur par défaut est off.
tune.sndbuf.backend <size>
Pour la taille de la mémoire tampon d’envoi du socket noyau sur les sockets non connectés, jusqu’à cette taille. Cela peut être utilisé pour la journalisation UNIX et UDP côté backend, ainsi que pour QUIC en mode écouteur côté frontal. Les tampons système par défaut peuvent parfois être trop petits pour les sockets partagés entre de nombreuses connexions (ou émetteurs de journaux), entraînant des pertes et éventuellement des retransmissions, ce qui ralentit la mise en place de nouvelles connexions sous fort trafic. La valeur est exprimée en octets, appliquée à chaque socket. En mode écouteur, les sockets sont partagés entre toutes les connexions, et le nombre total de sockets dépend de la valeur « shards » de la ligne « bind ». Il n’existe pas de valeur optimale ; une bonne valeur correspond au produit de la taille attendue par connexion multipliée par le nombre attendu de connexions. Le noyau peut réduire les valeurs trop grandes. Voir également “tune.sndbuf.client” et “tune.sndbuf.server” pour leurs équivalents sur les sockets connectés, ainsi que “tune.rcvbuf.backend” et “tune.rcvbuf.frontend” pour le paramètre de réception.
tune.sndbuf.client <size>
Force la taille du tampon d’envoi socket du noyau du côté client ou serveur à la valeur spécifiée en octets. Cette valeur s’applique à tous les frontaux et backends TCP/HTTP. Elle devrait normalement ne jamais être définie, et la taille par défaut (0) permet au noyau d’ajuster automatiquement cette valeur en fonction de la mémoire disponible. Toutefois, il peut parfois être utile de la définir à des valeurs très faibles (par exemple 4096) afin de réduire l’utilisation de la mémoire noyau en empêchant celui-ci de tamponner des quantités trop importantes de données reçues. Des valeurs plus faibles augmentent toutefois significativement l’utilisation du CPU. Un autre cas d’usage consiste à éviter les délais d’expiration d’écriture avec des clients extrêmement lents, en empêchant le noyau d’attendre qu’une grande partie du tampon soit lue avant de notifier à nouveau HAProxy. Voir également tune.notsent-lowat.client et tune.notsent-lowat.server pour des paramètres plus efficaces permettant de contrôler plus finement l’utilisation de la mémoire et la réactivité sous Linux sans nuire aux performances.
tune.ssl.cachesize <number>
Définit la taille du cache global des sessions SSL, en nombre de blocs. Un bloc est suffisamment grand pour contenir une session encodée sans certificat de pair. Une session encodée avec certificat de pair est stockée dans plusieurs blocs, selon la taille du certificat de pair. Un bloc utilise environ 200 octets de mémoire (selon le calcul sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE utilisé pour la fonction shctx_init). La valeur par défaut peut être imposée au moment de la compilation, sinon elle vaut 20000. Lorsque le cache est plein, les entrées les moins utilisées sont supprimées et réaffectées. Des valeurs plus élevées réduisent la fréquence de cette suppression, donc le nombre de négociations SSL coûteuses en ressources CPU, en garantissant que toutes les utilisations conservent leur session aussi longtemps que possible. Toutes les entrées sont pré-allouées au démarrage. Définir cette valeur à 0 désactive le cache des sessions SSL.
tune.ssl.capture-buffer-size <number>
Définit la taille maximale de la mémoire tampon utilisée pour capturer la liste des chiffres du client hello, la liste des extensions, la liste des courbes elliptiques et les formats de points de courbe elliptique. Si la valeur est 0 (valeur par défaut), la capture est désactivée ; sinon, une mémoire tampon est allouée pour chaque connexion SSL/TLS.
tune.ssl.certificate-compression { auto | off }
Ce paramètre permet de configurer la prise en charge de la compression des certificats, une extension (RFC 8879) du TLS 1.3.
Lorsqu’il est défini sur « auto », la valeur par défaut de la bibliothèque TLS est utilisée.
Avec « off », HAProxy tente de désactiver explicitement le support de la fonctionnalité. HAProxy ne tentera plus d’envoyer des certificats compressés ni d’accepter des certificats compressés.
Configure les côtés backend et frontal.
Ce mot-clé est pris en charge par OpenSSL >= 3.2.0.
La valeur par défaut est auto.
tune.ssl.default-dh-param <number>
Définit la taille maximale des paramètres de Diffie-Hellman utilisés pour générer la clé ephemeral/temporary en cas d’échange de clés DHE. La taille finale tentera de correspondre à la taille de la clé RSA (ou DSA) du serveur (par exemple, une clé DH temporaire de 2048 bits pour une clé RSA de 2048 bits), mais ne dépassera pas cette valeur maximale. Seules les valeurs égales ou supérieures à 1024 sont autorisées. Des valeurs plus élevées augmenteront la charge CPU, et les valeurs supérieures à 1024 bits ne sont pas prises en charge par les clients Java 7 et antérieurs. Cette valeur n’est pas utilisée si des paramètres de Diffie-Hellman statiques sont fournis directement dans le fichier de certificat ou à l’aide de la directive ssl-dh-param-file. Si ni default-dh-param ni ssl-dh-param-file n’est défini, et si le fichier PEM du serveur d’un frontal donné ne spécifie pas ses propres paramètres DH, alors les chiffres DHE seront indisponibles pour ce frontal.
tune.ssl.force-private-cache
Cette option désactive le partage du cache de session SSL entre tous les processus. Elle ne devrait normalement pas être utilisée, car elle entraîne de nombreuses renegotiations du fait que les clients accèdent à un processus aléatoire. Toutefois, elle peut être nécessaire sur certains systèmes d’exploitation où aucune méthode de synchronisation du cache SSL n’est disponible. Dans ce cas, l’ajout d’une première couche de répartition de charge basée sur un hachage avant la couche SSL peut limiter l’impact de l’absence de partage de session.
tune.ssl.hard-maxrecord <number>
Définit le nombre maximal d’octets passés à SSL_write() à tout moment. La valeur par défaut 0 signifie qu’aucune limite n’est appliquée. Contrairement à tune.ssl.maxrecord, ce paramètre ne sera pas ajusté dynamiquement. Des enregistrements plus petits peuvent réduire le débit, mais peuvent être nécessaires lors de la gestion de clients à faible empreinte.
tune.ssl.keylog { on | off }
Cette option active la journalisation des clés TLS. Elle doit être utilisée avec précaution, car elle consomme davantage de mémoire par session SSL et peut réduire les performances. Elle est désactivée par défaut.
Ces extractions d’échantillon doivent être utilisées pour générer le fichier SSLKEYLOGFILE nécessaire pour décrypter le trafic avec Wireshark.
https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html
La variable SSLKEYLOG est une série de lignes formatées de cette manière :
Le ClientRandom est fourni par l’extraction d’échantillon %[ssl_fc_client_random,hex], le secret et l’étiquette peuvent être trouvés dans le tableau ci-dessous. Vous devez générer un fichier SSLKEYLOGFILE contenant toutes les étiquettes de ce tableau.
Les extraits d’échantillons suivants sont des chaînes hexadécimales et n’ont pas besoin d’être convertis.
Ces récupérations existent côté frontal (fc) ou côté backend (bc) ; remplacez « xx » par « fc » ou « bc » pour utiliser le bon côté.
Cela n’est disponible qu’avec OpenSSL 1.1.1, et est utile avec la session TLS1.3.
Si vous souhaitez générer le contenu d’un fichier SSLKEYLOGFILE avec TLS < 1.3, vous n’avez besoin que de cette ligne :
CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]
Une journalisation complète de clés pourrait être générée avec un format de journalisation de cette manière, même si cela n’est pas idéal pour syslog :
HAProxy fournit également les formats ci-dessus sous forme de variables d’environnement prédéfinies, pouvant être utilisées directement dans une directive « log-format » :
tune.ssl.keyupdate-rate-limit <limit>
Limite la quantité de KeyUpdate par seconde que nous acceptons à <limit> avant de la considérer comme une inondation, et de tuer la connexion. Le traitement des KeyUpdate est coûteux en ressources CPU, et il n’y a peu de raisons de recevoir un grand nombre de ces messages. Une valeur de « 0 » désactive la limitation de débit. La valeur par défaut est 100.
tune.ssl.lifetime <timeout>
Définit la durée pendant laquelle une session SSL mise en cache peut rester valide. Cette durée est exprimée en secondes et vaut 300 par défaut (5 minutes). Il est important de comprendre qu’elle ne garantit pas que les sessions resteront actives aussi longtemps, car si la mémoire tampon est pleine, les sessions inactives les plus anciennes seront supprimées, même si leur durée de vie configurée n’est pas atteinte. L’utilité réelle de ce paramètre est de prévenir l’utilisation de sessions trop longtemps.
tune.ssl.maxrecord <number>
Définit la quantité maximale d’octets transmis à SSL_write() au début du transfert de données. Valeur par défaut 0 signifie qu’aucune limite n’est appliquée. Au-delà de SSL/TLS, le client ne peut décrypter les données qu’une fois qu’il a reçu un enregistrement complet. Avec de grands enregistrements, cela signifie que les clients peuvent devoir télécharger jusqu’à 16 ko de données avant de commencer à les traiter. Limiter cette valeur peut améliorer les temps de chargement des pages sur les navigateurs situés sur des réseaux à haute latence ou à faible bande passante. Il est recommandé de trouver des valeurs optimales qui tiennent dans 1 ou 2 segments TCP (généralement 1448 octets sur Ethernet avec les horodatages TCP activés, ou 1460 lorsque les horodatages sont désactivés), en tenant compte de l’overhead ajouté par SSL/TLS. Des valeurs typiques de 1419 et 2859 ont donné de bons résultats lors des tests. Utilisez « strace -e trace=write » pour déterminer la meilleure valeur. HAProxy passera automatiquement à ce paramètre après avoir détecté une connexion inactif (voir tune.idletimer ci-dessus). Voir également tune.ssl.hard-maxrecord.
tune.ssl.ssl-ctx-cache-size <number>
Définit la taille du cache utilisé pour stocker les certificats générés, sur <number> entrées. Il s’agit d’un cache LRU. Comme la génération dynamique d’un certificat SSL est coûteuse, ceux-ci sont mis en mémoire tampon. La taille du cache par défaut est fixée à 1000 entrées.
tune.streams-elasticity <number>
Définit un pourcentage cible de flux par connexion frontale par rapport au nombre maximum de connexions simultanées (maxconn) lorsque toutes les connexions sont établies. Ce métrique s’applique aux protocoles multiplexés comme HTTP/2 ou QUIC, où chaque connexion peut recevoir plusieurs flux. Au moins un flux est toujours garanti, donc le pourcentage doit être d’au moins 100 %. Pendant la mise en place de la connexion, HAProxy annonce dynamiquement des flux supplémentaires jusqu’à la limite configurée, tout en maintenant le rapport cible. À l’établissement de la connexion, chaque connexion frontale reçoit au moins un flux ; les flux supplémentaires sont attribués selon le pourcentage cible et les limites de flux configurées. Cela garantit une allocation de flux efficace dans des conditions de charge variables (plus de flux en cas de faible charge, moins de flux en cas de forte charge).
Les sites très dynamiques, avec de nombreux objets par page, bénéficient de ratios élevés, permettant un grand nombre de flux par connexion. Les sites utilisant en moyenne moins de flux (WebSocket, code d’application) peuvent préférer des ratios plus faibles, proches de 120 ou 150 (20 à 50 % de flux supplémentaires par rapport aux connexions), afin d’éviter un nombre excessif de flux sous charge soutenue.
La valeur par défaut est 0, ce qui signifie qu’aucune restriction n’est appliquée à ce niveau, de sorte que seules les configurations H2 et QUIC s’appliquent (avec le paramètre par défaut de 100 flux par connexion, ce qui correspond à 10000 %). Ce paramètre reste recommandé pour les déploiements de petite taille (maxconn d’environ mille). Les configurations de taille modérée (quelques milliers à dizaines de milliers de connexions) fixent généralement ce ratio entre 1000 et 5000, permettant 10 à 50 flux par connexion en charge maximale. Les déploiements à grande échelle (centaines de milliers à millions de connexions) peuvent utiliser des valeurs plus faibles (120 à 200) afin de supporter en moyenne 1,2 à 2 flux par connexion en charge maximale.
Contrairement à HTTP/2, QUIC est capable d’ajuster dynamiquement le nombre de flux simultanés pendant la durée de vie de la connexion. Toutefois, le contrôle de flux QUIC est plus strict que celui de HTTP/2, aussi est-il préférable, lors de son utilisation, de spécifier des valeurs suffisamment élevées pour éviter une latence supplémentaire sur la connexion. Il existe également une limitation pour les écouteurs QUIC avec 0-RTT activé. Dans ce cas, la valeur initiale annoncée au pair ignorera l’élasticité des flux et se fondera uniquement sur le paramètre “tune.quic.fe.stream.max-concurrent”. Toutefois, le principe d’élasticité des flux restera effectif au-delà de cette annonce initiale pendant la durée de vie de la connexion.
Surveiller le nombre total de flux actifs sur les backends, y compris les files d’attente, constitue un indicateur pratique de charge cible durable et aide à éviter le surdimensionnement.
tune.stick-counters <number>
Définit le nombre de compteurs de persistance pouvant être suivis simultanément par une connexion ou une requête via les actions “track-sc*” dans les règles “tcp-request” ou “http-request”. La valeur par défaut est définie au moment de la compilation par la macro MAX_SESS_STK_CTR, et vaut 3. Il est possible de modifier cette valeur et d’ignorer celle fournie au moment de la compilation, mais celle-ci ne peut pas dépasser 100. L’augmentation de cette valeur peut être nécessaire lors du portage de configurations complexes vers HAProxy, mais les utilisateurs sont avertis des coûts associés : chaque entrée consomme 16 octets par connexion et 16 octets par requête, toutes lesquelles doivent être allouées et initialisées à zéro pour toutes les requêtes, même lorsque non utilisées. Ainsi, une valeur de 10 entraîne une augmentation de la consommation mémoire par requête de 320 octets et provoque l’effacement de cette mémoire pour chaque requête, ce qui a un impact mesurable sur le processeur. À l’inverse, lorsque aucune règle “track-sc” n’est utilisée, la valeur peut être réduite (0 étant autorisé pour désactiver entièrement les compteurs de persistance).
tune.takeover-other-tg-connections <value>
Par défaut, nous n’essaierons pas d’utiliser des connexions inactives provenant d’autres groupes de threads. Ce comportement peut toutefois être modifié. Les valeurs valides pour <value> sont : « none », la valeur par défaut, si elle est utilisée, aucune tentative ne sera faite pour utiliser des connexions inactives provenant d’autres groupes de threads, « restricted », dans lequel nous n’essaierons de récupérer une connexion inactives d’un autre groupe de thread que si nous utilisons des protocoles ne pouvant pas créer de nouvelles connexions, tels que le HTTP inversé, ainsi qu’en cas d’utilisation de strict-maxconn, ou « full », dans lequel nous chercherons toujours dans les autres groupes de threads des connexions inactives. Notez que l’utilisation de connexions provenant d’autres groupes de threads peut entraîner des pertes de performance, donc cette option ne doit être utilisée que si nécessaire. Notez que ce comportement est désormais contrôlé par tune.idle-pool.shared, et ce mot-clé est conservé uniquement pour assurer la compatibilité avec les configurations anciennes, et sera déprécié.
tune.vars.global-max-size <size>
Ces cinq paramètres permettent de gérer la quantité maximale de mémoire utilisée par le système de variables. « global » limite la quantité totale de mémoire disponible pour toutes les portées. « proc » limite la mémoire pour la portée processus, « sess » pour la portée session, « txn » pour la portée transaction, et « reqres » pour la mémoire allouée à chaque traitement de requête ou réponse. La comptabilité mémoire est hiérarchique, ce qui signifie que les limites plus grossières incluent les limites plus fines : « proc » inclut « sess », « sess » inclut « txn », et « txn » inclut « reqres ».
Par exemple, lorsque “tune.vars.sess-max-size” est limité à 100, “tune.vars.txn-max-size” et “tune.vars.reqres-max-size” ne peuvent pas dépasser 100 non plus. Si nous créons une variable “txn.var” contenant 100 octets, tout l’espace disponible est utilisé. Notez qu’un dépassement des limites en temps d’exécution ne provoque pas de message d’erreur, mais les valeurs pourraient être tronquées ou corrompues. Veillez donc à prévoir avec précision la quantité d’espace nécessaire pour stocker toutes vos variables.
tune.zlib.memlevel <number>
Définit le paramètre memLevel lors de l’initialisation de zlib pour chaque flux. Il détermine la quantité de mémoire à allouer pour l’état interne de compression. Une valeur de 1 utilise la mémoire minimale mais est lente et réduit le taux de compression, tandis qu’une valeur de 9 utilise la mémoire maximale pour une vitesse optimale. Peut être une valeur comprise entre 1 et 9. La valeur par défaut est 8.
tune.zlib.windowsize <number>
Définit la taille de fenêtre (la taille de la mémoire tampon d’historique) en tant que paramètre d’initialisation de zlib pour chaque flux. Des valeurs plus élevées de ce paramètre entraînent une meilleure compression au détriment de l’utilisation mémoire. Peut être une valeur comprise entre 8 et 15. La valeur par défaut est 15.
3.3. Débogage
anonkey <key>
Cela définit la clé d’anonymisation globale à <key>, qui doit être un nombre de 32 bits compris entre 0 et 4294967295. Il s’agit de la clé utilisée par défaut par les commandes en ligne de commande lorsque le mode anonymisé est activé. Cette clé peut également être définie en temps réel à partir de la commande en ligne de commande « set anon global-key ». Voir également l’argument de ligne de commande “-dC” dans le manuel de gestion.
debug.counters { on | off }
Active (‘on’) ou désactive (‘off’) la mise à jour des compteurs d’événements dans le code. Ces compteurs sont ceux rapportés sous le type “CNT” dans la commande CLI “debug counters”. Ces compteurs ne sont disponibles que si le code a été compilé avec DEBUG_COUNTERS défini à une valeur égale ou supérieure à 1. Avec la valeur 1, les compteurs ne sont pas mis à jour par défaut (“debug.counters off”), et avec la valeur 2, ils sont mis à jour par défaut (“debug.counters on”). Il n’existe normalement aucune raison de modifier ce paramètre, sauf si une demande est formulée par un développeur, ou si l’on soupçonne une consommation anormale de CPU (auquel cas, une remontée aux développeurs est nécessaire, accompagnée d’un dump des compteurs). Il est également possible de modifier cet état en temps réel à l’aide de la commande CLI “debug counters”. Veuillez consulter le manuel de gestion.
force-cfg-parser-pause <timeout>
Cette commande met en pause le parseur de configuration pendant <timeout> millisecondes. Cela est utile en développement ou pour tester les délais d’expiration des scripts d’initialisation, notamment pour simuler un rechargement très long. Elle nécessite que l’option expose-experimental-directives soit activée.
<timeout> est la valeur de délai d’expiration spécifiée en millisecondes par défaut, mais peut être exprimée dans toute autre unité si le nombre est suivi de l’unité, comme expliqué en haut de ce document.
Exemple :
quick-exit
Cela accélère la sortie du processus ancien lors d’un rechargement en ignorant la libération des objets mémoire et des écouteurs, puisque tous ces éléments sont récupérés par le système d’exploitation à la mort du processus. Les gains sont négligeables (de l’ordre de quelques centaines de millisecondes au maximum, pour des configurations très volumineuses). L’utilisation principale concerne en réalité le cas où un bug est détecté dans le code de deinit(), car cela permet de le contourner. Il est préférable de ne pas utiliser cette option sauf instruction explicite des développeurs.
quiet
N’affichez aucun message lors du démarrage. Cela équivaut à l’argument de ligne de commande “-q”.
warn-blocked-traffic-after <time>
Cela permet d’ajuster le délai après lequel une tâche bloquée, empêchant le trafic, déclenche l’envoi d’un avertissement sur la sortie d’erreur standard. Le délai est exprimé en millisecondes et vaut 100 ms par défaut. Les valeurs autorisées doivent être comprises entre 1 ms et 1000 ms inclus. Des valeurs plus faibles provoquent fréquemment des avertissements, tandis que des valeurs plus élevées les déclenchent rarement. Le watchdog tue quand même une tâche en erreur qui ne répond pas deux fois pendant une seconde, aussi un délai d’avertissement de 1000 ms ne déclenchera normalement aucun avertissement. Il est recommandé de garder des valeurs comprises entre 10 et 100 ms afin de détecter des anomalies de configuration pouvant dégrader l’expérience utilisateur, entraînant des temps de réponse longs ou des saccades lors des sessions interactives. Par exemple, une fonction Lua d’extraction mal conçue effectuant des calculs lourds, ou un fichier de carte map_reg ou map_regm très volumineux avec un coût d’évaluation élevé, peuvent provoquer de tels problèmes. Pour comparaison, une poignée de main TLS peut consommer entre un et deux millisecondes, et la compression d’un tampon de réponse HTTP de 16 ko est d’environ une milliseconde. La sortie contient un dump de thread de la tâche défaillante, avec un backtrace et certains contextes qui aident à identifier où le temps est consommé.
zero-warning
Lorsque cette option est définie, HAProxy refusera de démarrer si un avertissement a été émis lors du traitement de la configuration et de son application. Cela signifie que les avertissements concernant des combinaisons de paramètres incorrectes, les avertissements relatifs à des limites très élevées qui ne pouvaient pas être appliquées, etc., entraînent une sortie avec erreur au démarrage. Quelques avertissements tardifs au démarrage ne peuvent pas être détectés par cette option, tels que l’échec de suppression des groupes supplémentaires lors du changement d’ID de groupe en mode “daemon” ou “master-worker”, ou l’échec de marquer le processus comme dumpable après le fork(). Cette option ne détecte pas les avertissements émis en cours d’exécution. Il est fortement recommandé de définir cette option sur les configurations qui ne sont pas fréquemment modifiées, car elle aide à détecter des erreurs subtiles et à maintenir la configuration propre et compatible à long terme. Notez que “haproxy -c” signalera également des erreurs dans ce cas. Cette option est équivalente à l’argument en ligne de commande “-dW”.
3.4. Ajustement du client HTTP
HTTPClient est une bibliothèque HTTP interne, pouvant être utilisée par divers sous-systèmes, par exemple dans des scripts LUA. HTTPClient n’est pas utilisé dans le chemin de données, autrement dit, il n’a rien à voir avec le trafic HTTP passant par HAProxy.
httpclient.resolvers.disabled <on|off>
Désactive la résolution DNS du httpclient. Empêche la création de la section « default » des résolveurs.
Valeur par défaut : désactivé.
httpclient.resolvers.id <resolvers id>
Cette option définit la section resolvers avec laquelle le httpclient tentera de résoudre.
L’option par défaut est l’identifiant de résolveur « default ». Par défaut, si cette option n’est pas utilisée, la résolution est simplement désactivée si la section n’est pas trouvée.
Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée si elle échoue à charger.
httpclient.resolvers.prefer <ipv4|ipv6>
Cette option permet de choisir la famille d’IP à utiliser lors de la résolution, ce qui est pratique lorsque IPv6 n’est pas disponible sur votre réseau. L’option par défaut est « ipv6 ».
httpclient.retries <number>
Cette option permet de configurer le nombre d’essais de rétention du httpclient en cas d’échec d’une requête. Elle a le même effet que la directive « retries » dans un backend.
Valeur par défaut : 3.
httpclient.ssl.ca-file <cafile>
Cette option définit le fichier ca à utiliser pour vérifier le certificat du serveur. Elle accepte les mêmes paramètres que l’option « ca-file » sur la ligne serveur.
Par défaut, et lorsque cette option n’est pas utilisée, la valeur est « @system-ca », qui tente de charger les certificats de la autorité de certification du système. En cas d’échec, le protocole SSL sera désactivé pour le httpclient.
Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée en cas d’échec.
httpclient.ssl.verify [none|required]
Fonctionne de la même manière que l’option verify sur les lignes server. Si elle est définie sur « none », les certificats des serveurs ne sont pas vérifiés. L’option par défaut est « required ».
Par défaut, et lorsque cette option n’est pas utilisée, la valeur est « required ». Si l’échec se produit, le protocole SSL sera désactivé pour le httpclient.
Toutefois, lorsque cette option est activée explicitement, une erreur de configuration est générée en cas d’échec.
httpclient.timeout.connect <timeout>
Définir le délai maximal d’attente pour une tentative de connexion par défaut pour le client HTTP.
Arguments :
La valeur par défaut est de 5000 ms.