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