<-
Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

Module Apache mod_filter

Langues Disponibles:  en  |  fr 

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).

Directives

Sujets

top

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.

top

D´┐Żclarations de filtres, fournisseurs et cha´┐Żnes

[Cette image illustre le modŔle de filtrage traditionnel]
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.

[Cette image illustre le modŔle de fonctionnement de     mod_filter]
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.

top

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.
top

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.

top

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.

top

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>
top

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 :

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.

top

AddOutputFilterByType Directive

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

top

FilterChain Directive

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
top

FilterDeclare Directive

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.

top

FilterProtocol Directive

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)
top

FilterProvider Directive

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

top

FilterTrace Directive

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´┐Ż.

Langues Disponibles:  en  |  fr 

top

Commentaires

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.