Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_filter

Description: | Module de configuration de filtre intelligent sensible au contexte
Statut: | Base
Identificateur de Module: | filter_module
Fichier Source: | mod_filter.c
Compatibilité: | Versions 2.1 et supérieures

### Sommaire

Ce module permet une configuration intelligente et dépendant du contexte des filtres de contenu en sortie. Par exemple, Apache peut être configuré pour faire traiter différents types de contenus par différents filtres, même lorsque le type de contenu n'est pas connu à l'avance (par exemple dans un serveur mandataire).

Le fonctionnement de `mod_filter` consiste à introduire des branchements dans la chaîne de filtrage. Plutôt que d'insérer directement des filtres dans la chaîne, on insère un sélecteur de filtre qui va effectuer un branchement conditionnel vers un fournisseur de filtre. `mod_filter` peut utiliser tout filtre de contenu comme fournisseur ; aucune modification des modules de filtrage existants n'est nécessaire (bien qu'il soit tout de même possible de les simplifier).

### Sujets

- Filtrage intelligent
- Déclarations de filtres, fournisseurs et chaînes
- Configuration de la chaîne de filtrage
- Filtrage et statut de la réponse
- Mise à jour depuis une configuration du serveur HTTP Apache 2.2
- Exemples
- Gestion de protocole

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

## Filtrage intelligent

Dans le modèle de filtrage traditionnel, les filtres sont insérés sans condition à l'aide de la directive `AddOutputFilter` et des directives apparentées. Chaque filtre doit ensuite déterminer s'il doit s'exécuter ou non, et les administrateurs du serveur disposent de peu de souplesse pour faire en sorte que la chaîne soit traitée de manière dynamique.

`mod_filter`, à l'opposé, fournit aux administrateurs du serveur un grand degré de souplesse pour configurer la chaîne de filtrage. Concrètement, la décision d'insérer un filtre peut être prise en fonction d'une expression booléenne complexe. Ceci généralise le fonctionnement relativement souple de la directive `AddOutputFilterByType`.

## Déclarations de filtres, fournisseurs et chaînes

Figure 1: Le modèle de filtrage traditionnel

Dans le modèle traditionnel, les filtres en sortie constituent une simple chaîne s'étendant depuis le générateur de contenu (ou gestionnaire) jusqu'au client. Ce fonctionnement peut convenir s'il permet d'atteindre le but recherché, mais pose problème lorsque cette chaîne doit être configurée dynamiquement en fonction de la sortie du gestionnaire.

Figure 2: Le modèle de fonctionnement de `mod_filter`

Le fonctionnement de `mod_filter` consiste à introduire des branchements dans la chaîne de filtrage. Plutôt que d'insérer directement des filtres dans la chaîne, on insère un sélecteur de filtre qui va effectuer un branchement conditionnel vers un fournisseur de filtre. `mod_filter` peut utiliser tout filtre de contenu comme fournisseur ; aucune modification des modules de filtrage existants n'est nécessaire (bien qu'il soit tout de même possible de les simplifier). Il peut y avoir plusieurs fournisseurs pour un seul filtre, mais un seul fournisseur sera choisi pour chaque requête.

Une chaîne de filtrage peut comporter autant d'instances du sélecteur de filtre que l'on souhaite, chacune d'entre elles pouvant disposer de plusieurs fournisseurs. Un sélecteur de filtre possédant un seul fournisseur dont le choix est inconditionnel constitue un cas particulier : cette situation est équivalente à l'insertion directe du filtre dans la chaîne.

## Configuration de la chaîne de filtrage

Trois étapes sont nécessaires pour configurer une chaîne de filtrage avec `mod_filter`. Voir ci-dessous la description détaillée des directives.

Déclaration des filtres
  La directive `FilterDeclare` permet de déclarer un filtre en lui assignant un nom et un type. Elle n'est obligatoire que si le filtre n'est pas du type par défaut AP_FTYPE_RESOURCE.
Enregistrement des fournisseurs
  La directive `FilterProvider` permet d'associer un fournisseur à un filtre. Le filtre a été éventuellement déclaré à l'aide de la directive `FilterDeclare` ; si ce n'est pas le cas, FilterProvider va le déclarer implicitement avec le type par défaut AP_FTYPE_RESOURCE. Le fournisseur doit avoir été enregistré à l'aide de `ap_register_output_filter` par un module quelconque. Le dernier argument de la directive `FilterProvider` est une expression : le fournisseur s'exécutera pour une requête si et seulement si l'expression est évaluée vraie. L'expression peut évaluer une requête HTTP ou les en-têtes de la réponse, des variables d'environnement, ou le gestionnaire utilisé par cette requête. À la différence des version précédentes, mod_filter supporte désormais les expressions complexes associant des critères multiples au moyen d'une logique AND / OR (&& / ||) et de parenthèses. Pour les détails sur la syntaxe de l'expression, voir la documentation sur ap_expr.
Configuration de la chaîne de filtrage
  Les directives ci-dessus permettent d'élaborer les éléments d'une chaîne de filtrage intelligente, mais pas de les configurer en vue de leur exécution. La directive `FilterChain` élabore une chaîne de filtrage à partir de filtres intelligents déclarés, permettant avec souplesse d'insérer des filtres au début ou à la fin de la chaîne, de supprimer un filtre ou même la chaîne complète.

## Filtrage et statut de la réponse

Normalement, mod_filter n'applique les filtres qu'aux réponses possédant un statut HTTP 200 (OK). Pour pouvoir filtrer des documents possédant un autre statut, vous devez définir la variable d'environnement filter-errordocs, les réponses étant alors filtrées sans se préoccuper de leur statut. Pour définir ce comportement de manière plus fine, vous pouvez utiliser des conditions dans la directive `FilterProvider`.

## Mise à jour depuis une configuration du serveur HTTP Apache 2.2

La directive `FilterProvider` a été modifiée par rapport à httpd 2.2 : les arguments match et dispatch ont été remplacés par l'argument unique expression plus polyvalent. En général, il est possible de convertir une paire match/dispatch vers les deux côtés d'une expression, de la manière suivante :

`"dispatch = 'match'"`

Les en-têtes de requête et de réponse et les variables d'environnement sont maintenant interprétés selon les syntaxes respectives %{req:foo}, %{resp:foo} et %{env:foo}. Les variables %{HANDLER} et %{CONTENT_TYPE} sont également supportées.

Notez que l'évaluation de l'expression ne supporte plus les comparaisons de sous-chaînes. Ces dernières peuvent être remplacées par des comparaisons d'expressions rationnelles.

## Exemples

Inclusions côté serveur (SSI)
  Un exemple simple de remplacement de la directive `AddOutputFilterByType`

      FilterDeclare SSI
      FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
      FilterChain SSI

Inclusions côté serveur (SSI)
  Même exemple que ci-dessus, mais envoi vers un gestionnaire (comportement classique des SSI ; les fichiers .shtml sont traités).

      FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
      FilterChain SSI

Émulation de mod_gzip avec mod_deflate
  Insertion du filtre INFLATE seulement si l'en-tête Accept-Encoding a une valeur autre que "gzip". Ce filtre s'exécute avec le type ftype CONTENT_SET.

      FilterDeclare gzip CONTENT_SET
      FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
      FilterChain gzip

Diminution de la résolution d'une image
  Supposons que nous voulions réduire la résolution de toutes les images web, et que nous disposions de filtres pour les images GIF, JPEG et PNG.

      FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
      FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
      FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"

      FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
      FilterProtocol downsample "change=yes"

      FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
      FilterProvider repack gif_pack  "%{CONTENT_TYPE} = 'image/gif'"
      FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
      <Location "/image-filter">
          FilterChain unpack downsample repack
      </Location>

## Gestion de protocole

Historiquement, tout filtre doit s'assurer que toute modification qu'il effectue est correctement représentée dans les en-têtes de la réponse HTTP, et qu'il ne s'exécutera pas si cette exécution résultait en une modification interdite. Ceci impose aux auteurs de filtres la corvée de réimplémenter certaines fonctionnalités communes dans chaque filtre :

- De nombreux filtres modifient les contenus, et de ce fait invalident les balises de ces contenus, leur somme de contrôle, leur condensé (hash) existant, ainsi que leur taille.
- Les filtres qui nécessitent une réponse entière et non tronquée en entrée, doivent s'assurer qu'il n'ont pas reçu une réponse à une requête partielle.
- Les filtres qui modifient la sortie d'un autre filtre doivent s'assurer qu'ils ne violent pas la directive d'un en-tête `Cache-Control: no-transform` éventuel.
- Les filtres peuvent agir sur des réponses de façon à ce qu'elles ne puissent plus être mises en cache.

`mod_filter` a pour but de gérer de manière générale ces détails de l'implémentation des filtres, réduisant par là-même la complexité des modules de filtrage de contenu. Le travail permettant d'atteindre ce but est cependant toujours en cours ; la directive `FilterProtocol` implémente certaines de ces fonctionnalités à des fins de compatibilité ascendante avec les modules d'Apache 2.0. Pour les versions 2.1 et supérieures de httpd, les API `ap_register_output_filter_protocol` et `ap_filter_protocol` permettent aux modules de filtrage de définir leurs propres comportements.

Cependant, `mod_filter` ne doit pas interférer avec un filtre qui gère déjà tous les aspects du protocole. Par défaut (c'est à dire en l'absence de toute directive `FilterProtocol`), `mod_filter` ne modifiera donc pas les en-têtes.

Au moment où ces lignes sont écrites, cette fonctionnalité a été très peu testée, car les modules d'usage courant ont été conçus pour fonctionner avec httpd 2.0. Les modules qui l'utilisent devront donc l'expérimenter avec précautions.

## Directive AddOutputFilterByType

Description: | assigne un filtre en sortie pour un type de média particulier
Syntaxe: | `AddOutputFilterByType filtre[;filtre...] type_de_média [type_de_média] ...`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_filter
Compatibilité: | Présentait de sévères limitations avant d'être déplacé dans `mod_filter` dans la version 2.3.7

Cette directive active un filtre en sortie particulier pour une requête en fonction du type de média de la réponse.

L'exemple suivant active le filtre `DEFLATE` qui est fourni par le module `mod_deflate`. Il va compresser toute sortie dont le type MIME est `text/html` ou `text/plain` avant de l'envoyer au client.

    AddOutputFilterByType DEFLATE text/html text/plain

Si vous voulez assigner plusieurs filtres au contenu, leurs noms doivent être séparés par des points-virgules. On peut aussi utiliser une directive `AddOutputFilterByType` pour chacun des filtres à assigner.

La configuration ci-dessous impose le traitement de toute sortie de script dont le type MIME est `text/html` en premier lieu par le filtre `INCLUDES`, puis par le filtre `DEFLATE`.

    <Location "/cgi-bin/">
        Options Includes
        AddOutputFilterByType INCLUDES;DEFLATE text/html
    </Location>

### Voir aussi

- `AddOutputFilter`
- `SetOutputFilter`
- Les filtres

## Directive FilterChain

Description: | Configure la chaîne de filtrage
Syntaxe: | `FilterChain [+=-@!]nom_filtre ...`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet de configurer une chaîne de filtrage composée de filtres déclarés. `FilterChain` accepte un nombre illimité d'arguments, chacun d'entre eux étant précédé d'un caractère de contrôle unique qui détermine l'action à entreprendre :

`+nom filtre`
  Ajoutenom filtre à la fin de la chaîne de filtrage
`@nom filtre`
  Ajoute nom filtre au début de la chaîne de filtrage
`-nom filtre`
  Supprime nom filtre de la chaîne de filtrage
`=nom filtre`
  Supprime tous les filtres de la chaîne de filtrage existante et les remplace par nom filtre
`!`
  Supprime tous les filtres de la chaîne de filtrage existante
`nom filtre`
  Équivalent à `+nom filtre`

## Directive FilterDeclare

Description: | Déclare un filtre intelligent
Syntaxe: | `FilterDeclare nom_filtre [type]`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet de déclarer un filtre en sortie associé à un en-tête ou une variable d'environnement qui déterminera les conditions de son exécution. Le premier argument est le nom du filtre destiné à être utilisé dans les directives `FilterProvider`, `FilterChain` et `FilterProtocol`.

Le dernier argument (optionnel) est le type du filtre, et peut prendre les valeurs de `ap_filter_type`, à savoir `RESOURCE` (valeur par défaut), `CONTENT_SET`, `PROTOCOL`, `TRANSCODE`, `CONNECTION` ou `NETWORK`.

## Directive FilterProtocol

Description: | Vérifie le respect du protocole HTTP
Syntaxe: | `FilterProtocol nom_filtre [nom_fournisseur] drapeaux_protocole`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet à `mod_filter` de s'assurer qu'un filtre ne s'exécutera pas s'il ne doit pas le faire, et que les en-têtes de la réponse HTTP sont définis correctement en tenant compte des effets du filtre.

Cette directive se présente sous deux formes. Avec trois arguments, elle s'applique de manière spécifique à un nom filtre et un nom fournisseur pour ce filtre. Avec deux arguments, elle s'applique à un nom filtre pour tout fournisseur qu'il actionne.

Les drapeaux spécifiés sont fusionnés avec les drapeaux que les fournisseurs sous-jacents ont éventuellement enregistrés avec `mod_filter`. Par exemple, un filtre peut avoir spécifié en interne un drapeau équivalent à `change=yes`, mais une configuration particulière du module peut le surcharger en spécifiant `change=no`.

drapeaux_protocole peut contenir un ou plusieurs drapeaux parmi les suivants :

`change=yes|no`
  Indique si le filtre doit modifier le contenu, y compris éventuellement sa taille
`change=1:1`
  Le filtre modifie le contenu, mais pas sa taille
`byteranges=no`
  Le filtre ne peut pas traiter de réponses à des sous-requêtes et nécessite des réponses complètes en entrée
`proxy=no`
  Le filtre ne doit pas s'exécuter dans un contexte de mandataire
`proxy=transform`
  Le filtre transforme la réponse de manière incompatible avec l'en-tête HTTP `Cache-Control: no-transform`
`cache=no`
  Le filtre fait en sorte que la sortie ne puisse pas être mise en cache (par exemple en introduisant des modifications de contenu aléatoires)

## Directive FilterProvider

Description: | Enregistre un filtre de contenu
Syntaxe: | `FilterProvider nom_filtre nom_fournisseur expression`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet d'associer un fournisseur au filtre intelligent. Le fournisseur sera invoqué si et seulement si l'expression est évaluée vraie lorsque le sélecteur de filtre est appelé pour la première fois.

nom fournisseur doit avoir été enregistré au cours du chargement d'un module à l'aide de `ap_register_output_filter`.

expression est une expression ap_expr.

### Voir aussi

- Les expressions dans le serveur HTTP Apache, pour une référence complète et d'autres exemples.
- `mod_include`

## Directive FilterTrace

Description: | Obtention d'informations de débogage/diagnostique en provenance de `mod_filter`
Syntaxe: | `FilterTrace nom_filtre niveau`
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_filter

Cette directive permet d'obtenir des informations de débogage en provenance de `mod_filter`. Elle est conçue pour aider à tester et déboguer les fournisseurs (ou modules de filtrage) ; elle peut aussi apporter une aide à l'utilisation de `mod_filter` lui-même.

La sortie de débogage dépend de la définition d'argument level :

`0` (valeur par défaut)
  Aucune information de débogage n'est générée.
`1`
  `mod_filter` va enregistrer les ensembles de conteneurs de données (buckets and brigades) qui traversent le filtre dans le journal des erreurs, avant que le fournisseur ne les traite. Ces informations sont similaires à celles générées par mod_diagnostics.
`2` (pas encore implémenté)
  Ce niveau permettra d'enregistrer l'ensemble des données qui traversent le filtre dans un fichier temporaire avant de les envoyer au fournisseur. Pour un débogage mono-utilisateur seulement ; l'enregistrement des données concernant plusieurs requêtes simultannées ne sera pas supporté.