Module Apache mod_include

Activation des SSI

Les SSI sont impl�ment�s par le filtre INCLUDES. Si des documents contenant des directives SSI poss�dent une extension .shtml, les directives suivantes indiqueront � Apache de les interpr�ter et d'assigner le type MIME text/html au document obtenu :

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

L'option suivante doit �tre d�finie pour les r�pertoires qui contiennent les fichiers shtml (en g�n�ral dans une section <Directory>, mais cette option peut �galement �tre d�finie dans un fichier .htaccess si AllowOverride Options a �t� d�fini pour le r�pertoire consid�r�) :

Options +Includes

Pour des raisons de compatibilit� ascendante, le gestionnaire server-parsed peut aussi activer le filtre INCLUDES. Ainsi, Apache va activer le filtre INCLUDES pour tout document de type MIME text/x-server-parsed-html ou text/x-server-parsed-html3 (et le document obtenu aura pour type MIME text/html).

Pour plus d'informations, voyez notre Tutoriel SSI.

PATH_INFO et SSI

Les fichiers trait�s dans le cadre des SSI n'acceptent plus par d�faut les requ�tes avec PATH_INFO (les informations relatives au chemin en fin de requ�te). La directive AcceptPathInfo permet de configurer le serveur de fa�on � ce qu'il accepte ce genre de requ�te.

El�ments disponibles

Le document est interpr�t� comme un document HTML, avec des commandes sp�ciales incluses sous forme de commentaires SGML. La syntaxe d'une commande est la suivante :

Les valeurs sont souvent entour�es de guillemets, mais on peut aussi utiliser des apostrophes (') ou des apostrophes inverses (`). De nombreuses commandes n'acceptent qu'une seule paire attribut-valeur. Notez que le terminateur de commentaire (-->) doit �tre pr�c�d� d'un espace afin d'�tre s�r qu'il ne soit pas consid�r� comme un �l�ment de commande SSI. Notez aussi que le d�limiteur de d�but <!--# est un �l�ment de commande et ne doit donc pas contenir d'espace.

La table suivante contient la liste des �l�ments autoris�s :

Les �l�ments SSI peuvent �tre d�finis par d'autres modules que mod_include. � ce titre, l'�l�ment exec est fourni par mod_cgi, et ne sera disponible que si ce module est charg�.

L'�l�ment config

Cette commande contr�le divers aspects de l'interpr�tation. Les attributs valides sont :

echomsg (Versions 2.1 et sup�rieures d'Apache)

La valeur est un message qui sera envoy� au client si l'�l�ment echo tente d'afficher le contenu d'une variable non d�finie. Cet attribut l'emporte sur toute directive SSIUndefinedEcho.

<!--#config echomsg="[Valeur non d�finie]" -->

errmsg

La valeur est un message qui sera envoy� au client si une erreur survient lors de l'interpr�tation du document. Cet attribut l'emporte sur toute directive SSIErrorMsg.

<!--#config errmsg="[Zut, quelque chose s'est mal pass�.]" -->

sizefmt

La valeur d�finit l'unit� employ�e lors de l'affichage de la taille d'un fichier. Les valeurs possibles sont bytes pour une taille en octets, ou abbrev pour une taille en Ko ou Mo selon son importance ; par exemple, une taille de 1024 octets sera affich�e sous la forme "1K".

<!--#config sizefmt="abbrev" -->

timefmt

La valeur est une cha�ne que pourra utiliser la fonction de la biblioth�que standard strftime(3) lors de l'affichage des dates.

<!--#config timefmt=""%R, %B %d, %Y"" -->

L'�l�ment echo

Cette commande affiche le contenu d'une des variables include d�finies ci-dessous. Si la variable n'est pas d�finie, le r�sultat est d�termin� par la valeur de la directive SSIUndefinedEcho. Le format d'affichage des dates est d�fini par l'attribut timefmt de la commande config.

Attributs:

var

La valeur est le nom de la variable � afficher.

decoding

Sp�cifie si Apache doit effectuer un d�codage dans la variable avant son traitement ult�rieur. La valeur par d�faut est none, et dans ce cas, aucun d�codage n'est effectu�. Si la valeur est url, un d�codage de type URL sera effectu� (il s'agit du codage de type %-encoding utilis� dans les URLs des liens, etc...). Si la valeur est urlencoded, c'est un d�codage des �l�ments de type application/x-www-form-urlencode (que l'on trouve dans les cha�nes de param�tres) qui sera effectu�. Si la valeur est base64, un decodage de type base64 sera effectu�, et si elle est entity, c'est un d�codage des entit�s HTML qui sera effectu�. Ce d�codage est effectu� avant tout codage ult�rieur de la variable. Il est possible d'effectuer plusieurs d�codages en sp�cifiant plusieurs valeurs s�par�es par des virgules. Les sp�cifications de d�codages restent valables jusqu'au prochain attribut de d�codage, ou la fin de l'�l�ment.

Pour �tre pris en compte, l'attribut de d�codage doit pr�c�der l'attribut var correspondant.

encoding

Sp�cifie la mani�re dont Apache va coder les caract�res sp�ciaux que la variable contient avant leur affichage. S'il est d�fini � none, aucun codage ne sera effectu�. S'il est d�fini � url, un codage de type URL sera effectu� (aussi connu sous le nom de codage avec caract�res % , il convient pour les URLS des liens, etc...). S'il est d�fini � urlencoded, c'est un codage compatible application/x-www-form-urlencoded qui sera effectu� (� utiliser dans les cha�nes de param�tres). S'il est d�fini � base64, c'est un encodage de type base64 qui sera effectu�. Au d�but d'un �l�ment echo, la valeur par d�faut est d�finie � entity, ce qui correspond � un codage de type entit� (codage qui convient pour un �l�ment HTML de type bloc, comme le paragraphe d'un texte). Cette valeur par d�faut peut �tre modifi�e en ajoutant un attribut encoding, qui fera effet jusqu'� la d�finition d'un nouvel attribut encoding ou la fin de l'�l�ment echo.

Pour produire son effet, l'attribut encoding doit pr�c�der l'attribut var concern�.

Afin de pr�venir les attaques de type cross-site scripting, il est recommand� de toujours encoder les donn�es fournies par les utilisateurs.

Example

<!--#echo encoding="entity" var="QUERY_STRING" -->

L'�l�ment exec

La commande exec ex�cute la commande shell ou le script sp�cifi�. Elle n�cessite le chargement du module mod_cgi. Si Options IncludesNOEXEC est d�finie, cette commande est d�sactiv�e. Les attributs disponibles sont :

cgi

La valeur sp�cifie un chemin URL vers le script CGI (encod� avec caract�res %). Si le chemin ne commence pas par un slash (/), il est consid�r� comme relatif au document courant. Le document r�f�renc� par ce chemin est invoqu� en tant que script CGI, m�me s'il n'est pas cens� �tre reconnu comme tel par le serveur. Les scripts CGI doivent cependant �tre activ�s dans le r�pertoire qui contient les scripts (via la directive ScriptAlias ou l'Options ExecCGI).

Le PATH_INFO et la cha�ne d'arguments (QUERY_STRING) de la requ�te originale du client sont fournis au script CGI ; ils ne peuvent pas �tre sp�cifi�s dans le chemin de l'URL. Le script disposera des variables include en plus de l'environnement standard CGI.

Exemple

<!--#exec cgi="/cgi-bin/exemple.cgi" -->

Si, � la place d'un flux de sortie, le script renvoie un en-t�te Location:, ce dernier sera traduit en ancrage HTML.

L'�l�ment include virtual doit �tre pr�f�r� � exec cgi. En particulier, si vous devez transmettre des arguments suppl�mentaires � un programme CGI en utilisant la cha�ne d'arguments de la requ�te, c'est impossible avec exec cgi, mais vous pouvez y parvenir avec include virtual comme suit :

<!--#include virtual="/cgi-bin/exemple.cgi?argument=valeur" -->

cmd

Le serveur va ex�cuter la commande fournie en utilisant /bin/sh. La commande dispose des variables include, en plus du jeu habituel de variables CGI.

Il est toujours pr�f�rable d'utiliser #include virtual � la place de #exec cgi ou #exec cmd. #include virtual utilise le m�canisme standard des sous-requ�tes d'Apache pour inclure des fichiers ou des scripts. Il a fait l'objet de tests plus approfondis et sa maintenance est mieux suivie.

De plus, sur certaines plate-formes, comme Win32, et sous unix, si l'on utilise suexec, il est impossible de transmettre des arguments � une commande dans une directive exec, � moins d'ins�rer des espaces dans la commande. Ainsi, alors que ce qui suit fonctionnera sous unix avec une configuration sans suexec, l'effet produit ne sera pas celui d�sir� sous Win32, ou dans le cas de l'utilisation de suexec :

<!--#exec cmd="perl /chemin/vers/script_perl arg1 arg2" -->

L'�l�ment fsize

Cette commande permet d'afficher la taille du fichier sp�cifi� en fonction des sp�cifications de format de sizefmt. Attributs :

file

La valeur est le chemin du fichier, relatif au r�pertoire contenant le document en cours d'interpr�tation.

Ce fichier a une taille de <!--#fsize file="mod_include.html" --> octets.

La valeur de file ne peut pas faire r�f�rence � un fichier situ� � un niveau sup�rieur de l'arborescence du r�pertoire courant ou en dehors de la racine des documents ; il ne peut donc ni commencer par un slash, ni contenir la s�quence de caract�res ../. Si c'est le cas, le message d'erreur The given path was above the root path sera renvoy�.

virtual

La valeur est un chemin URL (cod� avec caract�res %). S'il ne commence pas par un slash (/), il est consid�r� comme relatif au document courant. Notez que cette commande n'affiche pas la taille de la sortie d'un programme CGI, mais la taille du programme CGI lui-m�me.

Notez que dans la plupart des cas, ces deux attributs sont identiques. Cependant, l'attribut file ne respecte pas les aliases URL-space.

L'�l�ment flastmod

Cette commande permet d'afficher la date de derni�re modification du fichier sp�cifi�, en fonction des sp�cifications de format de timefmt. Les attributs sont les m�mes que ceux de la commande fsize.

L'�l�ment include

Cette commande permet d'ins�rer le texte d'un autre document ou fichier dans le fichier en cours d'interpr�tation. Tout fichier inclus est soumis au contr�le d'acc�s habituel. Si Options IncludesNOEXEC est d�fini pour le r�pertoire contenant le fichier interpr�t�, seuls les documents poss�dant un type MIME de type texte (text/plain, text/html, etc...) seront inclus. Les scripts CGI, quant � eux, sont invoqu�s de mani�re habituelle en utilisant l'URL compl�te fournie avec la commande, y compris toute cha�ne d'arguments �ventuelle.

Un attribut d�finit le chemin du document � inclure, et peut appara�tre plusieurs fois dans l'�l�ment � inclure ; en retour, pour chaque attribut fourni � la commande include, une inclusion est effectu�e. Les attributs disponibles sont :

file

La valeur est un chemin relatif au r�pertoire contenant le fichier en cours d'interpr�tation. Elle ne peut ni contenir ../, ni �tre un chemin absolu. Ainsi, vous ne pouvez pas inclure de fichiers situ�s en dehors de l'arborescence du site web ou dans un niveau sup�rieur � celui du fichier courant dans cette arborescence. Il est toujours pr�f�rable d'utiliser l'attribut virtual.

virtual

La valeur est un chemin URL (cod� avec caract�res %). L'URL ne peut contenir qu'un chemin et une cha�ne d'arguments �ventuelle, � l'exclusion de tout protocole ou nom d'h�te. S'il ne commence pas par un slash (/), il est consid�r� comme relatif au document courant.

Une URL est construite � partir de l'attribut, et la sortie que renverrait le serveur si l'URL �tait acc�d�e par le client est incluse dans la sortie interpr�t�e. Les inclusions de fichiers peuvent ainsi �tre imbriqu�es.

Si l'URL sp�cifi�e correspond � un programme CGI, le programme sera ex�cut�, et son flux de sortie ins�r� � la place de la directive dans le fichier interpr�t�. Vous pouvez ins�rer une cha�ne d'arguments dans une URL correspond � un programme CGI :

<!--#include virtual="/cgi-bin/exemple.cgi?argument=valeur" -->

include virtual doit �tre pr�f�r� � exec cgi pour inclure le flux de sortie d'un programme CGI dans un document HTML.

Si la directive KeptBodySize est correctement d�finie et valide pour le fichier inclus, les tentatives de requ�tes POST vers le document HTML qui inclut des fichiers seront transmises aux sous-requ�tes en tant que requ�tes POST elles-m�mes. Sans cette directive, toutes les sous-requ�tes sont trait�es en tant que requ�tes GET.

onerror

La valeur est un chemin-URL (cod�-%) qui est affich� si une tentative pr�c�dente d'inclure un fichier ou un attribut virtuel a �chou�. Pour produire son effet, cet attribut doit �tre sp�cifi� apr�s le fichier ou les attributs virtuels concern�s. Si la tentative d'inclure le chemin onerror �choue, ou si onerror n'est pas sp�cifi�, c'est le message d'erreur par d�faut qui sera inclus.

# Exemple simple
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# Chemins onerror d�di�s
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

L'�l�ment printenv

Cette commande affiche la liste en mode texte de toutes les variables et de leurs valeurs. Les caract�res sp�ciaux sont encod�s entity avant d'�tre affich�s (se reporter � l'�l�ment echo pour plus de d�tails). Cette commande ne comporte pas d'attributs.

L'�l�ment set

Cette commande permet de d�finir la valeur d'une variable. Les attributs sont :

var

Le nom de la variable � d�finir.

value

La valeur � affecter � la variable.

decoding

Sp�cifie si Apache doit effectuer un d�codage dans la variable avant son traitement ult�rieur. La valeur par d�faut est none, et dans ce cas, aucun d�codage n'est effectu�. Si la valeur est url, urlencoded, base64 ou entity, c'est un d�codage de type URL, application/x-www-form-urlencoded, base64 ou entit� HTML qui sera respectivement effectu�. Il est possible d'effectuer plusieurs d�codages en sp�cifiant plusieurs valeurs s�par�es par des virgules. Les sp�cifications de d�codages restent valables jusqu'au prochain attribut de d�codage, ou la fin de l'�l�ment. Pour �tre pris en compte, l'attribut de d�codage doit pr�c�der l'attribut var correspondant.

encoding

Sp�cifie la mani�re dont Apache va encoder les caract�res sp�ciaux que la variable contient avant leur affichage. S'il est d�fini � none, aucun encodage ne sera effectu�. Si la valeur est url, urlencoding, base64 ou entity, c'est un encodage de type URL, application/x-www-form-urlencoded, base64 ou entit� HTML qui sera respectivement effectu�. Il est possible de sp�cifier plusieurs types d'encodage en les s�parant par des virgules. La sp�cification du type d'encodage fera effet jusqu'� la d�finition d'un nouvel attribut encoding ou la fin de l'�l�ment. Pour produire son effet, l'attribut encoding doit pr�c�der l'attribut var concern�. Les encodages sont effectu�s apr�s les op�rations de d�codage.

Variables include

� l'instar des variables de l'environnement CGI standard, ces variables sont mises � la disposition de la commande echo, des op�rateurs conditionnels if et elif, et de tout programme invoqu� par le document.

DATE_GMT

La date GMT (Greenwich Mean Time) courante.

DATE_LOCAL

La date locale courante.

DOCUMENT_NAME

Le nom de base du fichier demand� par l'utilisateur (sans son chemin).

DOCUMENT_URI

Le chemin URL (caract�res % d�cod�s) du document demand� par l'utilisateur. Notez que dans le cas d'inclusions de fichiers imbriqu�es, il ne s'agit pas de l'URL du document courant. Notez �galement que si l'URL est modifi�e en interne (par exemple via une directive alias ou directoryindex), c'est l'URL modifi�e que contiendra la variable.

LAST_MODIFIED

La date de derni�re modification du document demand� par l'utilisateur.

QUERY_STRING_UNESCAPED

Si une cha�ne d'arguments est pr�sente, elle sera affect�e � cette variable, les caract�res % d�cod�s, et �ventuellement �chapp�s pour qu'ils ne soient pas interpr�t�s par le shell (les caract�res sp�ciaux comme &,etc... sont pr�c�d�s d'anti-slashes).

Substitution de variable

Une substitution de variable � l'int�rieur d'une cha�ne entre guillemets s'effectue dans la plupart des situations o� cette derni�re peut raisonablement constituer un argument d'une directive SSI. Sont concern�es les directives config, exec, flastmod, fsize, include, echo, et set. Si la directive SSILegacyExprParser est d�finie � on, la substitution s'effectue aussi dans les arguments des op�rateurs conditionnels. Vous pouvez ins�rer un signe dollar en tant que caract�re litt�ral dans une cha�ne en utilisant un anti-slash :

Si une r�f�rence de variable doit �tre substitu�e au beau milieu d'une s�quence de caract�res qui pourrait �tre elle-m�me consid�r�e comme un identifiant valide, l'ambigu�t� peut �tre lev�e en entourant la r�f�rence d'accolades, � la mani�re du shell :

Dans cet exemple, la variable Zed se verra affecter la valeur "X_Y" si REMOTE_HOST et REQUEST_METHOD contiennent respectivement "X" et "Y".

El�ments de contr�le d'inclusion conditionnelle

Les �l�ments de base du contr�le d'inclusion conditionnelle sont :

L'�l�ment if fonctionne de la m�me mani�re que la directive if d'un langage de programmation. La condition est �valu�e et si le r�sultat est vrai, le texte qui suit jusqu'au prochain �l�ment elif, else ou endif sera inclus dans le flux de sortie.

Les �l�ments elif ou else permettent d'ins�rer du texte dans le flux de sortie si test_condition s'est r�v�l� faux. Ces �l�ments sont optionnels.

L'�l�ment endif termine le bloc de traitement conditionnel if et est obligatoire.

test_condition est une expression bool�enne qui emprunte la syntaxe ap_expr. La directive SSILegacyExprParser permet de modifier cette syntaxe pour la rendre compatible avec Apache HTTPD 2.2.x.

Le jeu de variables SSI avec l'�l�ment var sont export�es vers l'environnement de la requ�te et sont accessibles via la fonction reqenv. Pour faire simple, le nom de fonction v est aussi disponible dans le module mod_include.

Dans l'exemple suivant, "depuis le r�seau local" sera affich� si l'adresse IP du client appartient au sous-r�seau 10.0.0.0/8.

Dans l'exemple suivant, "foo vaut bar" sera affich� si la variable foo contient la valeur "bar".

Syntaxe des expressions h�rit�e

Cette section d�crit la syntaxe de l'�l�ment #if expr dans le cas o� la directive SSILegacyExprParser est d�finie � on.

cha�ne

vrai si cha�ne n'est pas vide

-A string

vrai si l'URL que contient la cha�ne est accessible du point de vue de la configuration, faux sinon. Il s'av�re utile lorsqu'un lien vers une URL doit �tre cach� aux utilisateurs qui ne sont pas autoris�s � voir cette URL. Notez que le test porte sur l'autorisation d'acc�s � l'URL, et non sur son existence.

Exemple

<!--#if expr="-A /prive" -->
Cliquez <a href="/prive">ici</a> pour acc�der aux informations priv�es.
<!--#endif -->

cha�ne1 = cha�ne2
cha�ne1 == cha�ne2
cha�ne1 != cha�ne2

Compare cha�ne1 � cha�ne2. Si cha�ne2 est de la forme /cha�ne2/, elle est trait�e comme une expression rationnelle. Les expressions rationnelles sont impl�ment�es par le moteur PCRE et poss�dent la m�me syntaxe que celles de perl 5. Notez que == n'est qu'un alias pour = et se comporte exactement de la m�me mani�re que ce dernier.

Si vous faites une comparaison directe (= ou ==), vous pouvez extraire des parties de l'expression rationnelle. Les parties extraites sont stock�es dans les variables sp�ciales $1 .. $9. L'ensemble de la cha�ne correspondant � l'expression rationnelle est stock� dans la variable sp�ciale $0.

Exemple

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->

cha�ne1 < cha�ne2
cha�ne1 <= cha�ne2
cha�ne1 > cha�ne2
cha�ne1 >= cha�ne2

Compare cha�ne1 � cha�ne2. Notez que les cha�nes sont compar�es de mani�re litt�rale (en utilisant strcmp(3)). Ainsi, la cha�ne "100" est inf�rieure � "20".

( test_condition )

vrai si test_condition est vrai

! test_condition

vrai si test_condition est faux

test_condition1 && test_condition2

vrai si test_condition1 et test_condition2 sont tous les deux vrais

test_condition1 || test_condition2

vrai si au moins un des tests test_condition1 ou test_condition2 est vrai

"=" et "!=" ont une priorit� sup�rieure � "&&" et "||". "!" a la priorit� la plus haute. Ainsi, les deux directives suivantes sont �quivalentes :

Les op�rateurs bool�ens && et || ont la m�me priorit�. Ainsi, si vous voulez augmenter la priorit� d'un de ces op�rateurs, vous devez utiliser des parenth�ses.

Tout ce qui n'est pas reconnu comme variable ou op�rateur est trait� comme une cha�ne. Les cha�nes peuvent aussi �tre entour�es d'apostrophes : 'cha�ne'. Les cha�nes sans apostrophe ne peuvent pas contenir d'espaces (espaces ou tabulations) car ceux-ci servent � s�parer certains �l�ments comme les variables. Si plusieurs cha�nes se trouvent dans une ligne, elles sont concat�n�es en utilisant des espaces. Ainsi,