[APACHE DOCUMENTATION]

Apache HTTP Server Version 1.3

Module mod_include

Ce module est contenu dans le fichier mod_include.c, et est compilé par défaut. Il permet la composition dynamique de documents HTML par le serveur. Plusieurs directives ont été rajoutées à celles définies dans la version NCSA originale à partir de la version 1.2 d'Apache - Ces directives sont identifiables ci-dessous par la mention "A partir de la version 1.2 d'Apache". Une de ces directives particulièrement significatives est celle gérant le contrôle conditionnel d'inclusion décrite à la fin de cette page.

Activer les Server-Side Includes

Si l'option Includes est définie, tout document associé au gestionnaire "server-parsed" sera composé par ce module. Si des documents contenant des directives SSI sont associés à une extension .shtml, les directives suivantes contrôleront comment Apache les compose et assignera au document résultant un type MIME text/html : 
AddType text/html .shtml
AddHandler server-parsed .shtml
La directive qui suit doit apparaître dans les descriptions de répertoires contenant des fichiers shtml (par exemple dans une section <Directory>, ou encore dans un fichier .htaccess si l'option de configuration AllowOverride Options est définie) :
Options +Includes
A l'inverse, la directive XBitHack pourra être utilisée pour composer des documents (text/html) normaux, suivant les droits des fichiers.

Pour des raisons de compatibilité descendante, les documents associés aux types MIME text/x-server-parsed-html ou text/x-server-parsed-html3 seront aussi pris en compte (le document résultant étant encore associé au type MIME text/html).

Eléments de base

Le document est traité comme un document HTML, mais qui dispose en plus de commandes spéciales exprimées sous la forme de commentaires SGML. Les commandes répondent à la syntaxe :

<!--#élément attribut=valeur attribut=valeur ... -->

La valeur sera souvent mise entre guillemets ; de nombreuses commandes ne permettront qu'un couple unique attribut/valeur. Notez que la marque de fin de commentaire (-->) doit être précédé d'un espace afin de s'assurer qu'il ne pourra être pris comme faisant partie d'un identifiant SSI.

Les éléments autorisés sont :

config
Cette commande contrôle plusieurs aspects de la composition. Les attributs valides sont :
errmsg
La valeur est un message qui sera renvoyé au client si une erreur intervient lors de la composition dynamique du document.
sizefmt
La valeur définit le format à utiliser lorsque l'on affiche la taille d'un fichier. Les valeurs autorisées sont bytes indiquant une expression de la taille en octets, ou abbrev pour une expression en Ko ou Mo selon le cas.
timefmt
La valeur est une chaîne devant être utilisée par la routine de librairie strftime(3) pour l'impression de dates.
echo
Cette commande affiche une des variables d'inclusion, telles que définies ci-dessous. Si la variable n'est pas définie, elle sera écrite (none). Toute impression de date se fera selon la configuration actuelle de timefmt. Attributs:
var
La valeur est le nom de la variable à afficher.
exec
La commande exec exécute une commande shell ou un script CGI donné. L'option de configuration IncludesNOEXEC désactive cette commande totalement. Les attributs valides sont :
cgi
Sa valeur spécifie une URL (encodée) donnant le chemin relatif vers un script CGI. Si le chemin d'accès ne commence pas par un (/), alors il sera considéré à partir du répertoire du document courant. Le document référencé par ce chemin est lancé comme un script CGI, même si le serveur refuserait de le reconnaître de cette nature en temps normal. Cependant, le répertoire contenant le script doit être explicitement déclaré au serveur en tant que répertoire de scripts CGI (grâce aux Options de configuration ScriptAlias ou ExecCGI).

Le serveur donnera au script CGI les chaînes PATH_INFO ainsi que la chaîne originale de la requête (QUERY_STRING) du client ; Celles-ci ne pouvant être spécifiées dans le chemin de l'URL. Les variables d'inclusion seront fournies au script en plus de l'environnement CGI standard.

Si le script renvoie une adresse : une en-tête http plutôt qu'une sortie HTML, alors cette adresse sera traduite sous forme d'un hyperlien HTML.

L'élément include virtual devra être utilisé de préférence à exec cgi.

cmd
Le serveur exécute la chaîne fournie comme une commande /bin/sh. Les variables d'inclusion sont accessibles à la commande lancée.
fsize
Cette commande affiche la taille du fichier spécifié, sous une forme définie par la spécification de format sizefmt. Attributs :
file
Sa valeur désigne un chemin d'accès relatif considéré relativement au répertoire du document en cours de composition.
virtual
Sa valeur est une URL (encodée) donnant le chemin relatif du document dont on affiche la taille. Si le chemin ne commence pas par un (/) alors il sera considéré relativement au document courant.
flastmod
Cette commande permet l'affichage de la date de dernière modification du fichier spécifié,sous une forme définie par la spécification de format timefmt. Les attributs sont les mêmes que ceux de la commande fsize.
include
Cette commande insère le texte d'un autre document ou fichier dans le document traité. Tout fichier inclus doit l'être selon les règles usuelles du contrôle des droits d'accès. Si l'option IncludesNOEXEC est marquée pour le répertoire contenant le document traité, et si l'inclusion elle-même induit l'exécution d'un programme, alors le document à inclure sera ignoré ; ceci évite l'exécution de scripts CGI par une voie détournée. Autrement, les scripts CGI seront invoqués normalement avec l'URL complète comme ligne de commande, cette dernière incluant la chaîne de requête.

Les attributs indiquent où se situent les documents à inclure ; l'inclusion est effectuée (selon les droits d'accès) pour chaque attribut donné dans la commande include. Les attributs autorisés sont :

file
Sa valeur est un chemin d'accès relativement au répertoire contenant le document actuellement diffusé. Ce chemin ne peut contenir de séquence ../, et ne peut non plus être exprimé comme un chemin absolu. Il sera toujours préférable d'utiliser l'attribut virtual plutôt que celui-ci.
virtual
Sa valeur est une URL (encodée) relativement à la position du document diffusé. L'URL ne peut contenir ni nom d'hôte, ni schéma d'authentification d'utilisateur, seulement un chemin d'accès et éventuellement une chaîne de requête. Si elle ne commence pas par un (/), alors l'URL sera considérée relativement au document diffusé.
Une URL est construite à partir de l'attribut, et le serveur inclut dans le document composé la sortie exacte de ce qu'il transmettrait si ce document était transmis directement à un client. De ce fait, les inclusions peuvent être cascadées sans problème.
printenv
Ceci affiche une liste de toutes les variables d'environnement actuellement définies. Pas d'attributs.
Par exemple: <!--#printenv -->
A partir de la version 1.2 d'Apache.
set
Définit la valeur d'une variable. Attributs :
var
Le nom de la variable à modifier.
valeur
La valeur à affecter à la variable.
Par exemple: <!--#set var="category" value="help" -->
A partir de la version 1.2 d'Apache.

Variables d'inclusion

En plus des variables de l'environnement CGI standard, ces variables sont accessibles à la commande echo, aux instructions if et elif, et à tout programme appelé dans le document.

DATE_GMT
La date courante absolue (Référence de Greenwich).
DATE_LOCAL
La date courante locale.
DOCUMENT_NAME
Le nom du fichier (chemin d'accès non compris) du document requis par l'utilisateur.
DOCUMENT_URI
L'URL décodée donnant le chemin d'accès du document demandé par l'utilisateur. Notez que dans le cas d'imbrications en cascade, il ne s'agit pas alors nécessairement de l'URL du document courant.
LAST_MODIFIED
La date de dernière modification du document demandé par l'utilisateur.

Substitution de variables

La substitution de variable est opérée dans les chaînes entre guillemets, dans la plupart des cas dans le cadre d'arguments de directives SSI. Ceci inclue les directives config, exec, flastmod, fsize, include, et set, ainsi que les arguments d'opérateurs conditionnels. Vous pouvez néanmoins insérer un dollar littéral dans une chaîne en le faisant précéder du caractère d'échappement "\" : 

<!--#if expr="$a = \$test" -->

Si une référence à une variable doit être substituée à l'intérieur d'une chaîne de caractères et qu'une ambiguïté peut apparaître avec un autre identificateur plus long, cette dernière peut être levée en encapsulant l'identificateur de variable dans des accolades, comme pour une substitution shell : 

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

Le résultat de cet exemple est que la variable Zed devient "X_Y" si REMOTE_HOST vaut "X" et REQUEST_METHOD vaut "Y".

Exemple : l'exemple ci-dessous affichera "dans foo" si le DOCUMENT_URI vaut /foo/file.html, "dans bar" si il vaut /bar/file.html et sinon, "dans aucun" : 

<!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> dans foo
<!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> dans bar
<!--#else --> dans aucun
<!--#endif -->

Eléments de contrôle conditionnel

Ceux-ci sont disponibles à partir de la version 1.2 d'Apache. Les éléments de contrôle conditionnel d'inclusion de base sont : 
<!--#if expr="condition_test" -->
<!--#elif expr="condition_test" -->
<!--#else -->
<!--#endif -->

L'élément if fonctionne comme l'instruction "if" des langages de programmation courants. La condition test est évaluée, et si le résultat est vrai, le texte situé entre cet élément et le prochain élément elif, else. ou endif est écrit dans le flux de sortie.

Les éléments elif ou else seront utilisés pour insérer le texte dans le flux si la condition associée au if est fausse. Ces éléments sont optionnels dans une syntaxe conditionnelle.

L'élément endif termine la syntaxe conditionnelle initiée par l'élément if et est obligatoire.

condition_test peut être l'une des expressions suivantes :

chaîne
vraie si chaîne n'est pas vide
chaîne1 = chaîne2
chaîne1 != chaîne2
chaîne1 < chaîne2
chaîne1 <= chaîne2
chaîne1 > chaîne2
chaîne1 >= chaîne2
Compare chaîne1 et chaîne2. Si chaîne2 est de la forme /chaîne/ alors elle est considérée comme une "expression régulière". Les "expression régulières" ont la même syntaxe que celles utilisée avec la commande grep() sous UNIX.
( condition_test )
vraie si condition_test est vraie
! condition_test
vraie si condition_test est fausse
condition_test1 && condition_test2
vraie si condition_test1 et condition_test2 sont simultanément vraies
condition_test1 || condition_test2
vraie si condition_test1 est vraie ou condition_test2 est vraie

"=" et "!=" sont considérés avant "&&" et "||". "!" est l'opérateur de plus haute précédence. Ainsi, les expressions suivantes sont équivalentes : 

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

Tout ce qui n'est pas reconnu comme un nom de variable ou un opérateur licite est considéré comme une chaîne de texte. Les chaînes de caractères peuvent aussi être exprimées entre apostrophes : 'string'. Les chaînes non cotées ne peuvent contenir de séparateurs (espaces ou tabulation) dans la mesure où ceux-ci sont utilisés pour séparer les "tokens". Si plusieurs chaînes se suivent dans un ligne, elles seront concaténées avec insertion d'un espace. Ainsi, 

     chaîne1    chaîne2  devient chaîne1 chaîne2
    'chaîne1    chaîne2' devient chaîne1    chaîne2

Directives

Directive : XBitHack

Syntaxe : XBitHack statut
Défaut : XBitHack off
Contexte : configuration serveur, hôtes virtuels, répertoire, .htaccess
Surcharge : Options
Statut : Base
Module : mod_include

La directive XBitHack contrôle la composition dynamique de documents HTML ordinaires. Cette directive n'affecte que les fichiers associés à un type MIME text/html. Statut peut prendre les valeurs suivantes :

off
Pas de traitement spécial des exécutables.
on
Tout fichier disposant d'un droit à l'exécution par l'utilisateur (u+x) sera considéré comme un fichier HTML dynamique.
full
Comme on mais teste en plus le statut d'exécution de groupe (g+x). S'il est marqué, alors la date de dernière modification renvoyée est la date effective de dernière modification du fichier. Sinon, aucune date de dernière modification n'est envoyée au client. Marquer ce bit permet aux clients et aux proxies d'enregistrer le résultat de la requête dans leur cache.

Note : cette fonctionnalité devra être désactivée, par exemple, lorsque vous incluez un appel à un CGI qui produit des sorties différentes à chaque appel (ou dont la sortie dépend de la requête).

Apache HTTP Server Version 1.3

Index Home

Adaptation française © Valery Fremaux / EISTI 1998