mod_include - Serveur Apache HTTP Version 2.4

Apache Server 2.4

<-

Module Apache mod_include

Description:Documents html interprétés par le serveur (Server Side Includes ou SSI)
Statut:Base
Identificateur de Module:include_module
Fichier Source:mod_include.c

Sommaire

Ce module fournit un filtre qui va traiter les fichiers avant de les envoyer au client. Le traitement est contrôlé via des commentaires SGML spécialement formatés, aussi nommés éléments. Ces éléments permettent l'insertion conditionnelle de texte, l'inclusion d'autres fichiers ou programmes, ainsi que la définition et l'affichage de variables d'environnement.

top

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.

top

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.

top

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 :

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

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 :

ElémentDescription
comment commentaire SSI
config configure les formats de sortie
echo affiche le contenu de variables
exec exécute des programmes externes
fsize affiche la taille d'un fichier
flastmod affiche la date de dernière modification d'un fichier
include inclut un fichier
printenv affiche toutes les variables disponibles
set définit la valeur d'une variable

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 comment

Cette commande n'affiche aucune information. Elle n'a pour but que l'ajout de commentaires dans un fichier et ces commentaires ne sont pas affichés.

Cette syntaxe est disponible à partir de la version 2.4.21 du serveur HTTP Apache.

<!--#comment Blah Blah Blah -->

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.

Ce fichier a une taille de <!--#fsize virtual="/docs/mod/mod_include.html" --> octets.

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.

Exemple

<pre> <!--#printenv --> </pre>

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.

Exemple

<!--#set var="category" value="help" -->

top

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_ARGS
Cette variable contient la chaîne de paramètres de la requête du document SSI actif, ou la chaîne vide si aucune chaîne de paramètres de requête n'est incluse. Pour les sous-requêtes invoquées par la directive SSI include, QUERY_STRING contiendra la chaîne de paramètres de la sous-requête et DOCUMENT_ARGS la chaîne de paramètres du document SSI (disponible à partir de la version 2.4.19 du serveur HTTP Apache).
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 dans la requête pour le document SSI actif, 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). Cette variable n'est pas définie si aucune chaîne d'arguments n'est présente. Utilisez DOCUMENT_ARGS si l'échappement des caractères du shell n'est pas souhaité.
top

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 :

<!--#set var="cur" value="\$test" -->

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 :

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

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

top

Eléments de contrôle d'inclusion conditionnelle

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

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

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.

<!--#if expr='-R "10.0.0.0/8"' -->
depuis le réseau local
<!--#else -->
depuis ailleurs
<!--#endif -->

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

<!--#if expr='v("foo") = "bar"' -->
foo vaut bar
<!--#endif -->

Documentation de référence

Voir aussi Les expressions dans le serveur HTTP Apache pour une référence complète et des exemples. Les fonctions restricted ne sont pas disponibles dans mod_include.

top

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 :

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

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,

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

et

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

Optimisation des expressions booléennes

Si les expressions atteignent une complexité suffisante pour ralentir les traitements de manière significative, vous pouvez essayer de les optimiser en fonction des règles d'évaluation :

  • Les expressions sont évaluées de la gauche vers la droite
  • Les opérateurs booléens binaires (&& et ||) font l'objet d'une évaluation abrégée chaque fois que cela est possible. En d'autres termes, et selon la règle ci-dessus, mod_include évalue tout d'abord la partie gauche de l'expression. Si le résultat de l'évaluation de cette partie gauche suffit à déterminer le résultat final, l'évaluation s'arrête ici. Dans le cas contraire, la partie droite est évaluée, et le résultat final tient compte des résultats des évaluations des parties gauche et droite.
  • L'évaluation abrégée est désactivée tant qu'il reste des expressions régulières à traiter. Ces dernières doivent être évaluées afin de définir les variables correspondant aux références arrières ($1 .. $9).

Si vous voulez déterminer la manière dont une expression est traitée, vous pouvez recompiler mod_include en utilisant l'option de compilation -DDEBUG_INCLUDE. Ceci a pour effet d'insérer, pour chaque expression interprétée, des informations étiquetées, l'arbre d'interprétation et la manière dont elle est évaluée au sein du flux de sortie envoyé au client.

Slashes d'échappement dans les expressions rationnelles

Tous les caractères slashes qui ne sont pas des séparateurs dans votre expression rationnelle doivent être échappés, et ceci sans tenir compte de leur signification du point de vue du moteur d'expressions rationnelles.

Documentation de référence

Voir le document Les expressions dans le serveur HTTP Apache, pour une référence complète et des exemples.

top

Directive SSIEndTag

Description:Chaîne qui termine l'élément include
Syntaxe:SSIEndTag tag
Défaut:SSIEndTag "-->"
Contexte:configuration du serveur, serveur virtuel
Statut:Base
Module:mod_include

Cette directive permet de modifier la chaîne que mod_include interprète comme la fin d'un élément include.

SSIEndTag "%>"

Voir aussi

top

Directive SSIErrorMsg

Description:Message d'erreur affiché lorsqu'une erreur SSI survient
Syntaxe:SSIErrorMsg message
Défaut:SSIErrorMsg "[an error occurred while processing this directive]"
Contexte:configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:All
Statut:Base
Module:mod_include

La directive SSIErrorMsg permet de modifier le message d'erreur affiché lorsqu'une erreur SSI survient. Pour les serveurs en production, il est recommandé de modifier le message d'erreur par défaut en "<!-- Error -->", de façon à ce que le message ne soit pas présenté à l'utilisateur.

Cette directive a le même effet que l'élément <!--#config errmsg=message -->.

SSIErrorMsg "<!-- Error -->"
top

Directive SSIETag

Description:Définit si des en-têtes ETags sont générés par le serveur.
Syntaxe:SSIETag on|off
Défaut:SSIETag off
Contexte:répertoire, .htaccess
Statut:Base
Module:mod_include
Compatibilité:Disponible à partir de la version 2.2.15 du serveur HTTP Apache.

Dans le cas général, un fichier filtré par mod_include peut contenir des éléments soit générés dynamiquement, soit éventuellement modifiés indépendemment du fichier original. En conséquence, il est demandé par défaut au serveur de ne pas générer d'en-tête ETag à la réponse en ajoutant no-etag aux informations de requête.

Ce comportement peut être modifié via la directive SSIETag qui permet au serveur de générer un en-tête ETag. On peut aussi l'utiliser pour la mise en cache de la sortie. Notez qu'un serveur d'arrière-plan ou un générateur de contenu dynamique peut lui-même générer un en-tête ETag, en ignorant l'information no-etag, cet en-tête ETag étant transmis par mod_include sans tenir compte de la définition de la présente directive. La directive SSIETag peut prendre une des valeurs suivantes :

off
no-etag sera ajouté aux informations de requête, et il sera demandé au serveur de ne pas générer d'en-tête ETag. Lorsqu'un serveur ignore la valeur de no-etag et génère tout de même un en-tête ETag, ce dernier sera respecté.
on
Les en-têtes ETag existants seront respectés, et ceux générés par le serveur seront ajoutés à la réponse.
top

Directive SSILastModified

Description:Définit si des en-têtes Last-Modified sont générés par le serveur.
Syntaxe:SSILastModified on|off
Défaut:SSILastModified off
Contexte:répertoire, .htaccess
Statut:Base
Module:mod_include
Compatibilité:Disponible à partir de la version 2.2.15 du serveur HTTP Apache.

Dans le cas général, un fichier filtré par mod_include peut contenir des éléments soit générés dynamiquement, soit éventuellement modifiés indépendemment du fichier original. En conséquence, l'en-tête Last-Modified est supprimé par défaut de la réponse.

La directive SSILastModified permet de modifier ce comportement en faisant en sorte que l'en-tête Last-Modified soit respecté s'il est déjà présent, ou défini dans le cas contraire. On peut aussi l'utiliser pour la mise en cache de la sortie. La directive SSILastModified peut prendre une des valeurs suivantes :

off
L'en-tête Last-Modified sera supprimé des réponses, à moins que la directive XBitHack ne soit définie à full comme décrit plus loin.
on
L'en-tête Last-Modified sera respecté s'il est déjà présent, et ajouté à la réponse si cette dernière est un fichier et si l'en-tête est manquant. La directive SSILastModified l'emporte sur la directive XBitHack.
top

Directive SSILegacyExprParser

Description:Active le mode de compatibilité pour les expressions conditionnelles.
Syntaxe:SSILegacyExprParser on|off
Défaut:SSILegacyExprParser off
Contexte:répertoire, .htaccess
Statut:Base
Module:mod_include
Compatibilité:Disponible à partir de la version 2.3.13.

Depuis la version 2.3.13, mod_include a adopté la nouvelle syntaxe ap_expr pour ses expressions conditionnelles dans les éléments de contrôle de flux #if. Cette directive permet de réactiver l'ancienne syntaxe qui est compatible avec les versions 2.2.x et antérieures d'Apache HTTPD.

top

Directive SSIStartTag

Description:Chaîne qui marque le début d'un élément include
Syntaxe:SSIStartTag tag
Défaut:SSIStartTag "<!--#"
Contexte:configuration du serveur, serveur virtuel
Statut:Base
Module:mod_include

Cette directive permet de modifier la chaîne que mod_include interprète comme le début d'un élément include.

Cette option peut vous être utile si vous avez deux serveurs qui interprètent un fichier avec des commandes différentes (et éventuellement à des moments différents).

SSIStartTag "<%"
SSIEndTag   "%>"

Avec l'exemple ci-dessus, qui définit aussi une directive SSIEndTag, vous pourrez inscrire des directives SSI comme dans l'exemple suivant :

Directives SSI avec marques de début et de fin personnalisées

<%printenv %>

Voir aussi

top

Directive SSITimeFormat

Description:Configuration du format d'affichage des dates
Syntaxe:SSITimeFormat chaîne de formatage
Défaut:SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
Contexte:configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:All
Statut:Base
Module:mod_include

Cette directive permet de modifier le format d'affichage des variables d'environnement DATE. La chaîne de formatage est identique à celle de la fonction strftime(3) de la bibliothèque C standard.

Cette directive a le même effet que l'élément <!--#config timefmt=chaîne de formatage -->.

SSITimeFormat "%R, %B %d, %Y"

Avec l'exemple ci-dessus, les dates seront affichées dans le style "22:26, June 14, 2002".

top

Directive SSIUndefinedEcho

Description:Chaîne à afficher lorsqu'on tente d'extraire le contenu d'une variable non définie
Syntaxe:SSIUndefinedEcho chaîne
Défaut:SSIUndefinedEcho "(none)"
Contexte:configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:All
Statut:Base
Module:mod_include

Cette directive permet de modifier la chaîne affichée par mod_include lorsqu'on tente d'extraire le contenu d'une variable non définie.

SSIUndefinedEcho "<!-- nondef -->"
top

Directive XBitHack

Description:Interprète les directives SSI dans les fichiers dont le bit d'exécution est positionné
Syntaxe:XBitHack on|off|full
Défaut:XBitHack off
Contexte:configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:Options
Statut:Base
Module:mod_include

La directive XBitHack permet de contrôler l'interprétation des documents html standards. Elle n'affecte que les fichiers dont le type MIME est text/html. XBitHack peut prendre les valeurs suivantes :

off
Aucun traitement particulier pour les fichiers exécutables.
on
Tout fichier text/html dont le bit d'exécution est positionné pour le propriétaire sera traité en tant que document html interprété par le serveur.
full
Identique à on, avec test du bit d'exécution pour le groupe. Si ce dernier est positionné, la date de dernière modification du fichier renvoyé est définie à la date de dernière modification du fichier. Dans le cas contraire, aucune date de dernière modification n'est renvoyée. Le positionnement de ce bit permet aux clients et aux mandataires de gérer la mise en cache du résultat de la requête.

Note

Il est recommandé de n'utiliser l'option full que dans le cas où vous êtes certain que le bit d'exécution du groupe est non positionné pour les scripts SSI qui pourraient effectuer l'#include d'un programme CGI ou bien produire des sorties différentes à chaque accès (ou seraient susceptibles d'être modifiées au cours des requêtes ultérieures).

Lorsqu'elle est définie à on, la directive SSILastModified l'emporte sur la directive XBitHack.