9. Filtres pris en charge

Voici la liste des filtres officiellement pris en charge, accompagnée de la liste des paramètres qu’ils acceptent. En fonction des options de compilation, certains de ces filtres pourraient être indisponibles. La liste des filtres disponibles est indiquée dans HAProxy -vv.

Voir aussi : « filter »

9.1. Trace

filtre trace [nom <name>] [redirection aléatoire] [nombre maximal de redirections <max>] [affichage hexadécimal]

Arguments :

<name>               is an arbitrary name that will be reported in
                     messages. If no name is provided, "TRACE" is used.

<quiet>              inhibits trace messages.

<random-forwarding>  enables the random forwarding of parsed data. By
                     default, this filter forwards all previously parsed
                     data. With this parameter, it only forwards a random
                     amount of the parsed data.

<max>                is the maximum amount of data that can be forwarded at
                     a time. "max-fwd" option can be combined with the
                     random forwarding. <max> must be an positive integer.
                     0 means there is no limit.

<hexdump>             dumps all forwarded data to the server and the client.

Ce filtre peut servir de base pour développer de nouveaux filtres. Il définit toutes les fonctions de rappel et affiche un message sur le flux d’erreur standard (stderr) contenant des informations utiles pour chacune d’elles. Il peut être utile pour déboguer l’activité d’autres filtres ou, tout simplement, l’activité d’HAProxy.

Utiliser les paramètres <random-parsing> et/ou <random-forwarding> est une bonne manière de tester le comportement d’un filtre qui analyse les données échangées entre un client et un serveur en ajoutant des latences dans le traitement.

9.2. Compression HTTP

filtre comp-req

Active le filtre qui tente explicitement de compresser les requêtes HTTP selon les paramètres « compression ». Définit implicitement « compression direction request ».

filtre comp-res

Active le filtre qui tente explicitement de compresser les réponses HTTP selon les paramètres « compression ». Définit implicitement « compression direction response »

filtre de compression (obsolète)

Alias à des fins de compatibilité descendante, équivalent fonctionnellement à l’activation simultanée des filtres « comp-req » et « comp-res ». Le mot-clé « compression » doit être utilisé pour configurer le comportement approprié :

La compression HTTP a été déplacée dans un filtre à partir de HAProxy 1.7. Le mot-clé « compression » doit toujours être utilisé pour activer et configurer la compression HTTP. Et lorsqu’aucun autre filtre n’est utilisé, cela suffit. Lorsqu’il est utilisé avec le cache ou l’application FCGI activés, cela suffit également. Dans ce cas, la compression est toujours effectuée après que la réponse a été stockée dans le cache. Toutefois, il est obligatoire d’utiliser explicitement une ligne de filtre pour activer la compression HTTP lorsqu’au moins un filtre autre que le cache ou l’application FCGI est utilisé pour le même écouteur/frontal/backend. Il est important de connaître l’ordre d’évaluation des filtres.

Voir également : « compression », section 9.4 concernant le filtre de cache et section 9.5 concernant le filtre fcgi-app.

9.3. Moteur de traitement de flux (SPOE)

filtre spoe [moteur <name>] config <file>

Arguments :

<name>      is the engine name that will be used to find the right scope in
            the configuration file. If not provided, all the file will be
            parsed.

<file>      is the path of the engine configuration file. This file can
            contain configuration of several engines. In this case, each
            part must be placed in its own scope.

Le moteur de traitement de flux (SPOE) est un filtre communiquant avec des composants externes. Il permet de déporter certains traitements spécifiques sur les flux dans les applications hiérarchisées. Ces composants externes et les informations échangées avec eux sont configurés dans des fichiers dédiés, pour la majeure partie. Il nécessite également des backends dédiés, définis dans la configuration HAProxy.

SPOE communique avec les composants externes à l’aide d’un protocole binaire interne, le Stream Processing Offload Protocol (SPOP).

Lorsque le SPOE est utilisé sur un flux, un flux dédié est créé pour gérer la communication avec le composant externe. Le flux principal est le flux parent de ce flux « SPOE ». Cela signifie qu’il est possible de récupérer les variables du flux principal depuis le flux « SPOE ». Voir section 2.8 concernant les variables pour plus de détails.

Pour toute information concernant la configuration SPOE et la spécification SPOP, consultez « doc/SPOE.txt ».

9.4. Mise en cache

filtre cache <name>

Arguments :

<name>      is name of the cache section this filter will use.

Le cache utilise un filtre pour stocker les réponses pouvant être mises en cache. Les règles HTTP « cache-store » et « cache-use » doivent être utilisées pour définir comment et quand utiliser un cache. Par défaut, le filtre correspondant est défini implicitement. Lorsqu’aucun autre filtre que fcgi-app ou compression n’est utilisé, cela suffit. Dans ce cas, le filtre de compression est toujours évalué après le filtre de cache. Toutefois, il est obligatoire d’utiliser explicitement une ligne de filtre pour activer un cache lorsqu’au moins un filtre autre que la compression ou fcgi-app est utilisé pour le même écouteur, frontal ou backend. Il est important de connaître l’ordre d’évaluation des filtres.

Voir également : section 9.2 concernant le filtre de compression, section 9.5 concernant le filtre fcgi-app et section 6 concernant le cache.

9.5. Application Fcgi

filtre fcgi-app <name>

Arguments :

<name>      is name of the fcgi-app section this filter will use.

L’application FastCGI utilise un filtre pour évaluer tous les paramètres personnalisés sur le chemin de la requête, et pour traiter les en-têtes sur le chemin de la réponse. Le <name> doit faire référence à une section fcgi-app existante. La directive « use-fcgi-app » doit être utilisée pour définir l’application à utiliser. Par défaut, le filtre correspondant est implicitement défini. Et lorsqu’aucun autre filtre que le cache ou la compression n’est utilisé, cela suffit. Mais il est obligatoire d’utiliser explicitement une ligne de filtre pour une fcgi-app lorsqu’au moins un filtre autre que la compression ou le cache est utilisé pour le même backend. Il est important de connaître l’ordre d’évaluation des filtres.

Voir également : « use-fcgi-app », section 9.2 concernant le filtre de compression, section 9.4 concernant le filtre de mise en cache et section 10 concernant l’application FastCGI.

9.6. OpenTracing

Le filtre OpenTracing ajoute un support natif de la traçabilité distribuée dans HAProxy. Ce support est activé en envoyant une requête conforme à OpenTracing à l’un des traceurs pris en charge, tels que Datadog, Jaeger, Lightstep ou Zipkin. Veuillez noter : les traceurs ne sont pas listés selon une préférence, mais par ordre alphabétique.

Cette fonctionnalité n’est activée que si HAProxy a été compilé avec USE_OT=1.

L’activation du filtre OpenTracing s’effectue de manière explicite en le spécifiant dans la configuration HAProxy. Si cela n’est pas fait, le filtre OpenTracing ne participe en aucune manière au fonctionnement de HAProxy.

filtre opentracing [id <id>] config <file>

Arguments :

<id>        is the OpenTracing filter id that will be used to find the
            right scope in the configuration file. If no filter id is
            specified, 'ot-filter' is used as default.  If scope is not
            specified in the configuration file, it applies to all defined
            OpenTracing filters.

<file>      is the path of the OpenTracing configuration file. The same
            file can contain configurations for multiple OpenTracing
            filters simultaneously. In that case we do not need to define
            scope so the same configuration applies to all filters or each
            filter must have its own scope defined.

Une documentation plus détaillée relative à l’opération, à la configuration et à l’utilisation du filtre est disponible dans le répertoire addons/ot.

Note : Le filtre OpenTracing ne doit pas être utilisé pour de nouveaux designs, car OpenTracing n’est plus maintenu ni soutenu par ses auteurs. En conséquence, OpenTracing sera déprécié à partir de la version 3.3 et supprimé à partir de la version 3.5. Un filtre de remplacement basé sur OpenTelemetry est disponible depuis la version 3.4, avec des instructions de compilation complètes actuellement disponibles à :

https://github.com/haproxytech/haproxy-opentelemetry/

9.7. Limitation de débit

filter bwlim-in <name> limite-par-défaut <size> période-par-défaut <time> [taille-min <sz>] filter bwlim-out <name> limite-par-défaut <size> période-par-défaut <time> [taille-min <sz>] filter bwlim-in <name> limite <size> clé <pattern> [table <table>] [taille-min <sz>] filter bwlim-out <name> limite <size> clé <pattern> [table <table>] [taille-min <sz>]

Arguments :

<name>      is the filter name that will be used by 'set-bandwidth-limit'
            actions to reference a specific bandwidth limitation filter.

<size>      is max number of bytes that can be forwarded over the period.
            The value must be specified for per-stream and shared bandwidth
            limitation filters. It follows the HAProxy size format and is
            expressed in bytes.

<pattern>   is a sample expression rule as described in section 7.3. It
            describes what elements will be analyzed, extracted, combined,
            and used to select which table entry to update the counters. It
            must be specified for shared bandwidth limitation filters only.

<table>     is an optional table to be used instead of the default one,
            which is the stick-table declared in the current proxy. It can
            be specified for shared bandwidth limitation filters only.

<time>      is the default time period used to evaluate the bandwidth
            limitation rate. It can be specified for per-stream bandwidth
            limitation filters only. It follows the HAProxy time format and
            is expressed in milliseconds.

<min-size>  is the optional minimum number of bytes forwarded at a time by
            a stream excluding the last packet that may be smaller. This
            value can be specified for per-stream and shared bandwidth
            limitation filters. It follows the HAProxy size format and is
            expressed in bytes.

Les filtres de limitation de débit doivent être utilisés pour restreindre la vitesse de transfert des données au niveau du flux. Par extension, de tels filtres limitent la bande passante réseau consommée par une ressource. Plusieurs filtres de limitation de débit peuvent être utilisés. Par exemple, il est possible de définir une limite par adresse source afin de garantir qu’un client ne consomme jamais toute la bande passante réseau, ce qui pourrait pénaliser d’autres clients, et une autre limite par flux afin de pouvoir gérer équitablement plusieurs connexions pour un même client.

L’ordre de définition de ces filtres est important. Si plusieurs filtres de limitation de débit sont activés sur un flux, le filtrage s’applique dans l’ordre de leur définition. Il est également important de comprendre que l’ordre de définition des autres filtres a une influence. Par exemple, selon que le filtre de compression HTTP est défini avant ou après un filtre de limitation de débit, la limite s’appliquera sur le contenu compressé ou non. Il en va de même pour le filtre de mise en cache.

Il existe deux types de filtres de limitation de débit. Le premier impose une limite par défaut et est appliqué par flux. Le second utilise une table de persistance pour appliquer une limite répartie également entre tous les flux partageant la même entrée dans la table.

En outre, selon le mot-clé utilisé pour un filtre, la limitation peut s’appliquer aux données entrantes, reçues du client puis transmises au serveur, ou aux données sortantes, reçues du serveur puis envoyées au client. Utilisez « bwlim-in » pour limiter les données entrantes et « bwlim-out » pour les données sortantes. Dans chaque cas, la limitation s’applique aux données transmises, au niveau du flux.

La limitation de débit est appliquée au niveau du flux et non au niveau de la connexion. Pour les protocoles multiplexés (H2, H3 et FastCGI), les flux de la même connexion peuvent avoir des limites différentes.

Pour un filtre de limitation de débit par flux, les valeurs par défaut de la période et de la limite doivent être définies. Comme leur nom l’indique, il s’agit des valeurs par défaut utilisées pour configurer le débit maximal autorisé pour un flux. Toutefois, pour ce type de filtre et uniquement pour celui-ci, il est possible de redéfinir ces valeurs à l’aide d’expressions d’échantillonnage lorsque le filtre est activé par une action TCP/HTTP « set-bandwidth-limit ».

Pour un filtre de limitation de bande passante partagée, selon qu’il est appliqué sur les données entrantes ou sortantes, le tableau de persistance utilisé doit stocker les informations correspondantes sur le débit en octets. Le compteur “bytes_in_rate(<period>)” doit être stocké afin de limiter les données entrantes, et le compteur “bytes_out_rate(<period>)” doit être utilisé afin de limiter les données sortantes.

Enfin, il est possible de définir le nombre minimum d’octets qu’un filtre de limitation de débit peut transmettre à chaque fois pour un flux donné. Cette option doit être utilisée pour éviter de transmettre une quantité trop faible de données, afin de réduire la charge du processeur. Elle doit être définie avec soin. Une valeur trop faible peut augmenter la charge du processeur. Une valeur trop élevée peut augmenter la latence. Elle est également fortement liée à la limite de débit définie. Si elle est trop proche de la limite de débit, des pauses peuvent survenir afin de ne pas dépasser la limite, car trop d’octets seraient consommés à chaque fois. Elle dépend fortement de la configuration du filtre. Une bonne approche consiste à commencer par une valeur d’environ 2 fois la taille maximale d’un segment TCP (MSS), généralement 2896 octets, puis à l’ajuster après quelques expérimentations.

Exemple :

frontend http
    bind *:80
    mode http

    # If this filter is enabled, the stream will share the download limit
    # of 10m/s with all other streams with the same source address.
    filter bwlim-out limit-by-src key src table limit-by-src limit 10m

    # If this filter is enabled, the stream will be limited to download at 1m/s,
    # independently of all other streams.
    filter bwlim-out limit-by-strm default-limit 1m default-period 1s

    # Limit all streams to 1m/s (the default limit) and those accessing the
    # internal API to 100k/s. Limit each source address to 10m/s. The shared
    # limit is applied first. Both are limiting the download rate.
    http-request set-bandwidth-limit limit-by-strm
    http-request set-bandwidth-limit limit-by-strm limit 100k if { path_beg /internal }
    http-request set-bandwidth-limit limit-by-src
    ...

backend limit-by-src
    # The stickiness table used by <limit-by-src> filter
    stick-table type ip size 1m expire 3600s store bytes_out_rate(1s)

Voir également : « tcp-request content set-bandwidth-limit », « tcp-response content set-bandwidth-limit », « http-request set-bandwidth-limit » et « http-response set-bandwidth-limit ».