Module Apache mod_ext_filter

Langues Disponibles: en | fr | ja | ko

Description:	Fait traiter le corps de la rï¿½ponse par un programme externe avant de l'envoyer au client
Statut:	Extension
Identificateurï¿½deï¿½Module:	ext_filter_module
Fichierï¿½Source:	mod_ext_filter.c

Sommaire

mod_ext_filter reprï¿½sente un modï¿½le de programmation simple et bien connu pour les filtres. Avec ce module, tout programme qui lit l'entrï¿½e standard stdin et ï¿½crit sur la sortie standard stdout (autrement dit une commande filtre de style Unix) peut servir de filtre pour Apache. Ce mï¿½canisme de filtrage est beaucoup plus lent qu'un filtre spï¿½cialement ï¿½crit pour l'API d'Apache et faisant partie intï¿½grante du processus du serveur Apache, mais il prï¿½sente les avantages suivants :

le modï¿½le de programmation est beaucoup plus simple
tout langage de script ou de programmation peut ï¿½tre utilisï¿½, pourvu qu'il permette au programme de lire l'entrï¿½e standard et d'ï¿½crire sur la sortie standard.
on peut utiliser des programmes existants comme filtres Apache sans modification.

Mï¿½me dans le cas oï¿½ le niveau de performance est insuffisant pour une utilisation en production, on peut utiliser mod_ext_filter comme prototype d'environnement pour les filtres.

Exemples

Gï¿½nï¿½rer du HTML ï¿½ partir d'un autre type de contenu

# la directive de mod_ext_filter dï¿½finissant un filtre
# permettant de mettre des fichiers text/c au format HTML en
# utilisant le programme externe /usr/bin/enscript, le type du
# fichier rï¿½sultant ï¿½tant dï¿½fini ï¿½ text/html
ExtFilterDefine c-to-html mode=output \
    intype=text/c outtype=text/html \
    cmd="/usr/bin/enscript --color -W html -Ec -o - -"

<Directory "/export/home/trawick/apacheinst/htdocs/c">
    # directive de base permettant de traiter la sortie avec le
    # nouveau filtre
    SetOutputFilter c-to-html

    # directive de mod_mime dï¿½finissant le type des fichiers dont
    # le nom possï¿½de l'extension .c ï¿½ text/c
    AddType text/c .c
</Directory>

Implï¿½mentation d'un filtre de codage de contenu

Note : cet exemple avec gzip n'est fourni qu'ï¿½ titre d'illustration. Veuillez vous reporter ï¿½ la documentation de mod_deflate pour un exemple d'implï¿½mentation plus rï¿½aliste.

# la directive de mod_ext_filter qui dï¿½finit le filtre externe
ExtFilterDefine gzip mode=output cmd=/bin/gzip

<Location /gzipped>

    # directive de base permettant de traiter la sortie avec le
    # filtre gzip
    SetOutputFilter gzip

    # la directive de mod_headers permettant d'ajouter le champ
    # d'en-tï¿½te "Content-Encoding: gzip"
    Header set Content-Encoding gzip
</Location>

Ralentissement du serveur

# directive de mod_ext_filter dï¿½finissant un filtre qui fait
# passer tous les flux en sortie par la commande cat ; cat ne
# modifie rien ; elle ne fait que compliquer le cheminement des
# flux et consommer des ressources supplï¿½mentaires
ExtFilterDefine slowdown mode=output cmd=/bin/cat \
    preservescontentlength

<Location />
    # directive de base permettant de traiter plusieurs fois la
    # sortie avec le filtre slowdown
    #
    SetOutputFilter slowdown;slowdown;slowdown
</Location>

Utilisation de sed pour remplacer du texte dans la rï¿½ponse

# directive de mod_ext_filter dï¿½finissant un filtre qui
# remplace du texte dans la rï¿½ponse
#
ExtFilterDefine fixtext mode=output intype=text/html \
    cmd="/bin/sed s/verdana/arial/g"

<Location />
    # directive de base permettant de traiter la sortie avec le
    # filtre fixtext
    SetOutputFilter fixtext
</Location>

Tracer un autre filtre

# Trace les donnï¿½es lues et ï¿½crites par mod_deflate pour un
# client particulier (IP 192.168.1.31) qui a des problï¿½mes de
# compression.
# Ce premier filtre va tracer ce qui entre dans mod_deflate.
ExtFilterDefine tracebefore \
    cmd="/bin/tracefilter.pl /tmp/tracebefore" \
    EnableEnv=trace_this_client

# Ce second filtre va tracer ce qui sort de mod_deflate.
# Notez que sans le paramï¿½tre ftype, le type de filtre par
# dï¿½faut AP_FTYPE_RESOURCE placerait le filtre *avant*
# mod_deflate dans la chaï¿½ne de filtrage. Le fait d'affecter
# ï¿½ ce paramï¿½tre une valeur numï¿½rique sensiblement supï¿½rieure ï¿½
# AP_FTYPE_CONTENT_SET permet de s'assurer que le filtre sera
# placï¿½ aprï¿½s mod_deflate.
ExtFilterDefine traceafter \
    cmd="/bin/tracefilter.pl /tmp/traceafter" \
    EnableEnv=trace_this_client ftype=21

<Directory /usr/local/docs>
    SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
    SetOutputFilter tracebefore;deflate;traceafter
</Directory>

Voici le filtre qui trace les donnï¿½es :

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
    or die "can't open $ARGV[0]: $?";

while (<STDIN>) {
    print SAVE $_;
    print $_;
}

close(SAVE);

ExtFilterDefine Directive

Description:	Dï¿½finit un filtre externe
Syntaxe:	`ExtFilterDefine nom filtre paramï¿½tres`
Contexte:	configuration du serveur
Statut:	Extension
Module:	mod_ext_filter

La directive ExtFilterDefine permet de dï¿½finir les caractï¿½ristiques d'un filtre externe, et en particulier le programme ï¿½ exï¿½cuter ainsi que ses arguments.

nom filtre spï¿½cifie le nom du filtre en cours de dï¿½finition. On peut ensuite utiliser ce nom pour rï¿½fï¿½rencer le filtre dans les directives SetOutputFilter. Il doit ï¿½tre unique parmi les noms de tous les filtres enregistrï¿½s. Pour le moment, aucune erreur n'est signalï¿½e par l'API register-filter, si bien qu'un problï¿½me de noms dupliquï¿½s ne sera pas portï¿½ ï¿½ la connaissance de l'utilisateur.

Viennent ensuite un ou plusieurs paramï¿½tres dans un ordre indï¿½fini, qui permettent de spï¿½cifier la commande externe ï¿½ exï¿½cuter et certaines autres caractï¿½ristiques. Le seul paramï¿½tre obligatoire est cmd=. Voici la liste de ces paramï¿½tres :

cmd=ligne de commande: Le mot-clï¿½ cmd= permet de spï¿½cifier la commande externe ï¿½ exï¿½cuter. Si la ligne de commande comporte des arguments, elle doit ï¿½tre entourï¿½e de guillemets (par exemple cmd="/bin/mypgm arg1 arg2"). Les guillemets habituels du shell ne sont pas nï¿½cessaires car le programme est lancï¿½ directement, sans passer par le shell. Les arguments du programme doivent ï¿½tre sï¿½parï¿½s par des espaces. Si un argument contient des espaces, ces derniers doivent ï¿½tre ï¿½chappï¿½s par un antislash '\'. Si un argument contient des antislashes '\', ces derniers doivent ï¿½tre eux-mï¿½mes ï¿½chappï¿½s par un antislash '\'. Outre les variables d'environnement CGI standards, les variables DOCUMENT_URI, DOCUMENT_PATH_INFO, et QUERY_STRING_UNESCAPED seront aussi dï¿½finies pour le programme.
mode=mode: Utilisez mode=output (valeur par dï¿½faut) pour les filtres qui traitent les rï¿½ponses. Utilisez mode=input pour les filtres qui traitent les requï¿½tes. mode=input est disponible depuis la version 2.1 d'Apache.
intype=type MIME: Ce paramï¿½tre permet de spï¿½cifier le type de mï¿½dium Internet (c'est ï¿½ dire le type MIME) des documents qui doivent ï¿½tre filtrï¿½s. Par dï¿½faut, tous les documents sont filtrï¿½s. Tous les documents possï¿½dant un type MIME autre que celui spï¿½cifiï¿½ par intype= ne seront pas filtrï¿½s.
outtype=type MIME: Ce paramï¿½tre permet de spï¿½cifier le type de mï¿½dium Internet (c'est ï¿½ dire le type MIME) des documents filtrï¿½s. Il intervient lorsque les opï¿½rations de filtrage comprennent une modification du type MIME. Par dï¿½faut, le type MIME n'est pas modifiï¿½.
PreservesContentLength: Le mot-clï¿½ PreservesContentLength indique que le filtre doit conserver la taille du contenu. Ce n'est pas le comportement par dï¿½faut, car la plupart des filtres modifient cette taille. Ce mot-clï¿½ doit ï¿½tre spï¿½cifiï¿½ si le filtre ne doit pas modifier la taille du contenu.
ftype=type de filtre: Ce paramï¿½tre permet de spï¿½cifier une valeur numï¿½rique reprï¿½sentant le type de filtre sous lequel le filtre doit ï¿½tre enregistrï¿½. La valeur par dï¿½faut, AP_FTYPE_RESOURCE, convient dans la plupart des situations. Si le filtre doit opï¿½rer dans la chaï¿½ne de filtrage ï¿½ un autre point que les filtres de ressources, ce paramï¿½tre est nï¿½cessaire. Voir les dï¿½finitions de AP_FTYPE_... dans util_filter.h pour trouver une valeur appropriï¿½e.
disableenv=env: Ce paramï¿½tre permet de spï¿½cifier le nom d'une variable d'environnement qui, si elle est dï¿½finie, va dï¿½sactiver le filtre.
enableenv=env: Ce paramï¿½tre permet de spï¿½cifier le nom d'une variable d'environnement qui doit ï¿½tre dï¿½finie pour que le filtre ne soit pas dï¿½sactivï¿½.

ExtFilterOptions Directive

Description:	Configure les options de `mod_ext_filter`
Syntaxe:	`ExtFilterOptions option [option] ...`
Dï¿½faut:	`ExtFilterOptions NoLogStderr`
Contexte:	rï¿½pertoire
Statut:	Extension
Module:	mod_ext_filter

La directive ExtFilterOptions permet de spï¿½cifier des options de traitement particuliï¿½res pour mod_ext_filter. Les arguments option peuvent contenir :

LogStderr | NoLogStderr: Le mot-clï¿½ LogStderr indique que les messages envoyï¿½s par le programme de filtrage externe sur la sortie d'erreurs standard doivent ï¿½tre enregistrï¿½s dans le journal des erreurs d'Apache. NoLogStderr inverse ce comportement.
Onfail=[abort|remove]: Indique la marche ï¿½ suivre si le programme de filtrage externe ne peut pas dï¿½marrer. Avec abort (la valeur par dï¿½faut), la requï¿½te sera abandonnï¿½e. Avec remove, le filtre est supprimï¿½, et le traitement de la requï¿½te se poursuit sans lui.

ExtFilterOptions LogStderr

Les messages envoyï¿½s vers la sortie d'erreurs standard du filtre seront enregistrï¿½s dans le journal des erreurs d'Apache.