Module Apache mod_headers

Directive Header

Cette directive permet de remplacer, fusionner, ou supprimer des en-têtes de réponse HTTP. L'en-tête est modifié juste après que le gestionnaire de contenu et les filtres en sortie ne s'exécutent, ce qui permet la modification des en-têtes sortants.

L'argument optionnel condition permet de déterminer sur quelle table interne d'en-têtes de réponses cette directive va opérer : onsuccess (valeur par défaut, peut être omis) ou always. A la différence de ceux de la première table, les en-têtes de la seconde sont ajoutés à la réponse même en cas d'erreur et sont conservés au fil des redirections internes (par exemple les gestionnaires ErrorDocument). Notez aussi que la répétition de cette directive avec les deux conditions peut être pertinente dans certains scénarios, car always n'englobe pas onsuccess en ce qui concerne les en-têtes existants :

• Vous ajoutez un en-tête à une réponse générée localement et échouée (non-2xx), une redirection par exemple, et dans ce cas, seule la table correspondant à always est utilisée dans la réponse définitive.
• Vous modifiez ou supprimez un en-tête généré par un script CGI ou par mod_proxy_fcgi, auquel cas, les en-têtes des scripts CGI sont dans la table correspondant à always et non dans la table par défaut.
• Vous modifiez ou supprimez un en-tête généré par tel ou tel composant du serveur, mais cet en-tête n'est pas trouvé par la condition par défaut onsuccess.

Comme il n'y a pas de liste unique "normalisée" d'en-têtes, la manière dont httpd stocke en interne les en-têtes des réponses HTTP est à l'origine de la fonctionnalité que constitue la différence entre onsuccess et always. Si vous ne gardez pas à l'esprit le concept ci-après lors de l'écriture de votre configuration, certaines réponses HTTP pourront contenir des en-têtes dupliqués (ce qui pourra dérouter les utilisateurs ou même parfois les clients HTTP). Supposons par exemple que votre configuration comporte un mandataire PHP simple avec mod_proxy_fcgi et que votre script PHP d'arrière-plan ajoute l'en-tête X-Foo: bar à chaque réponse HTTP. Comme décrit plus haut, mod_proxy_fcgi utilise la table always pour stocker les en-têtes, et une configuration comme la suivante n'aboutira pas au résultat attendu car l'en-tête sera dupliqué avec les deux valeurs :

# la valeur de X-Foo est définie dans la table d'en-têtes 'onsuccess'
Header set X-Foo: baz

Plusieurs modèles de configuration permettent de contourner ce problème, comme celui-ci :

# 'onsuccess' peut être omis car il s'agit de la valeur par défaut
Header onsuccess unset X-Foo
Header always set X-Foo "baz"

Outre le paramètre condition décrit ci-dessus, vous pouvez limiter une action en fonction de codes d'état HTTP, par exemple pour les requêtes mandatées ou générées par un programme CGI. Voir l'exemple qui utilise %{REQUEST_STATUS} dans la section ci-dessus.

L'action que cette directive provoque est déterminée par le premier argument (ou par le second argument si une condition est spécifiée). Il peut prendre une des valeurs suivantes :

add

L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs) en-têtes possèdant le même nom et donc induire des conséquences imprévues ; en général, il est préférable d'utiliser set, append ou merge.

append

La valeur d'en-tête est ajoutée à tout en-tête existant de même nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête.

echo

Les en-têtes de la requête possédant le nom spécifié sont recopiés vers les en-têtes de la réponse. en-tête peut être une expression rationnelle, et valeur ne doit pas être présent.

edit

edit*

Si l'en-tête existe, sa valeur est modifiée en fonction d'une expression rationnelle de type recherche/remplacement. L'argument valeur est une expression rationnelle, et l'argument remplacement une chaîne de caractères de remplacement qui peut contenir des références arrières ou des spécificateurs de format. La forme edit n'effectuera une recherche/remplacement qu'une seule fois dans la valeur de l'en-tête, alors que la forme edit* en effectuera autant que le nombre d'apparition de la chaîne à remplacer.

merge

La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf si elle apparaît déjà dans la liste des valeurs préexistantes de l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête. Les valeurs sont comparées en tenant compte de la casse, et après le traitement de tous les spécificateurs de format. Une valeur entourée de guillemets est considérée comme différente de la même valeur mais sans guillemets.

set

L'en-tête est défini, remplaçant tout en-tête préexistant avec le même nom. L'argument valeur peut être une chaîne de formatage.

setifempty

L'en-tête est défini, mais seulement s'il n'existe aucun en-tête avec le même nom.

L'en-tête Content-Type est un cas particulier car il est possible que sa valeur ait été déterminée mais que l'en-tête ne soit pas présent dans la réponse lorsque setifempty est évalué. Dans ce cas, il est préférable d'utiliser set comme dans l'exemple suivant :

Header set Content-Type "text/plain" "expr=-z %{CONTENT_TYPE}"

unset

L'en-tête est supprimé s'il existe. Si plusieurs en-têtes possèdent le même nom, ils seront tous supprimés. L'argument value ne doit pas apparaître.

note

La valeur de l'en-tête considéré est copiée dans une note interne dont le nom est spécifié via l'argument valeur. Ceci permet de journaliser la valeur d'un en-tête envoyé par un programme CGI ou une ressource mandatée, même s'il est prévu de l'effacer.
Disponible à partir de la version 2.4.7 du serveur HTTP Apache.

Cet argument est suivi d'un nom d'en-tête qui peut se terminer par un caractère ':', mais ce n'est pas obligatoire. La casse est ignorée avec set, append, merge, add, unset et edit. Le nom d'en-tête est sensible à la casse pour echo et peut être une expression rationnelle.

Avec set, append, merge et add, une valeur est spécifiée comme argument suivant. Si valeur contient des espaces, elle doit être entourée de guillemets. valeur peut être une chaîne de caractères, une chaîne contenant des spécificateurs de format propres à mod_headers (et des caractères littéraux), ou une expression ap_expr préfixée par expr=.

valeur supporte les spécificateurs de format suivants :

editnécessite les deux arguments valeur, qui est une expression rationnelle, et une chaîne additionnelle remplacement. Depuis la version 2.4.7, la chaîne de remplacement peut aussi contenir des spécificateurs de format.

La directive Header peut être suivie d'un argument additionnel qui peut prendre les valeurs suivantes :

early

Spécifie traitement préalable.

env=[!]variable

La directive est appliquée si et seulement si la variable d'environnement variable existe. Un ! devant variable inverse le test, et la directive ne s'appliquera alors que si variable n'est pas définie.

expr=expression

La directive s'applique si et seulement si expression est évaluée à true. Vous trouverez plus de détails à propos de la syntaxe et de l'évaluation des expressions dans la documentation ap_expr.

         # Cet exemple retarde l'évaluation de la clause de condition par
	 # rapport à <If>
         Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

Excepté le cas du mode précoce, les directives Header sont traitées juste avant l'envoi de la réponse sur le réseau. Cela signifie qu'il est possible de définir et/ou modifier la plupart des en-têtes, à l'exception de certains en-têtes qui sont ajoutés par le filtre d'en-tête HTTP. Avant la version 2.2.12, il n'était pas possible de modifier l'en-tête Content-Type avec cette directive.

Directive RequestHeader

Cette directive permet de remplacer, fusionner, modifier ou supprimer des en-têtes de requête HTTP. L'en-tête est modifié juste avant que le gestionnaire de contenu ne s'exécute, ce qui permet la modification des en-têtes entrants. L'action effectuée est déterminée par le premier argument. Ce dernier accepte les valeurs suivantes :

add

L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs) en-têtes possèdant le même nom et donc induire des conséquences imprévues ; en général, il est préférable d'utiliser set, append ou merge.

append

La valeur d'en-tête est ajoutée à tout en-tête existant de même nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête.

edit

edit*

Si l'en-tête existe, sa valeur est modifiée en fonction d'une expression rationnelle de type recherche/remplacement. L'argument valeur est une expression rationnelle, et l'argument remplacement une chaîne de caractères de remplacement qui peut contenir des références arrières ou des spécificateurs de format. Avec edit, la chaîne de l'en-tête correspondant au modèle ne sera recherchée et remplacée qu'une seule fois, alors qu'avec edit*, elle le sera pour chacune de ses instances si elle apparaît plusieurs fois.

merge

La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf si elle apparaît déjà dans la liste des valeurs préexistantes de l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête. Les valeurs sont comparées en tenant compte de la casse, et après le traitement de tous les spécificateurs de format. Une valeur entourée de guillemets est considérée comme différente de la même valeur mais sans guillemets.

set

L'en-tête est défini, remplaçant tout en-tête préexistant avec le même nom.

setifempty

L'en-tête est défini, mais seulement s'il n'existe aucun en-tête avec le même nom.
Disponible depuis la version 2.4.7 du serveur HTTP Apache.

unset

L'en-tête est supprimé s'il existe. Si plusieurs en-têtes possèdent le même nom, ils seront tous supprimés. L'argument value ne doit pas apparaître.

Cet argument est suivi d'un nom d'en-tête qui peut se terminer par un caractère ':', mais ce n'est pas obligatoire. La casse est ignorée. Avec set, append, merge et add, une valeur est fournie en troisième argument. Si une valeur contient des espaces, elle doit être entourée de guillemets. Avec unset, aucune valeur ne doit apparaître. valeur peut être une chaîne de caractères, une chaîne contenant des spécificateurs de format, ou une combinaison des deux. Les spécificateurs de format supportés sont les mêmes que ceux de la directive Header, à laquelle vous pouvez vous reporter pour plus de détails. Avec edit, les deux arguments valeur et remplacement sont obligatoires, et correspondent respectivement à une expression rationnelle et à une chaîne de remplacement.

La directive RequestHeader peut être suivie d'un argument supplémentaire, qui pourra prendre les valeurs suivantes :

early

Spécifie traitement préalable.

env=[!]variable

La directive est appliquée si et seulement si la variable d'environnement variable existe. Un ! devant variable inverse le test, et la directive ne s'appliquera alors que si variable n'est pas définie.

expr=expression

La directive s'applique si et seulement si expression est évaluée à true. Vous trouverez plus de détails à propos de la syntaxe et de l'évaluation des expressions dans la documentation ap_expr.

Excepté le cas du mode précoce, la directive RequestHeader est traitée juste avant la prise en compte de la requête par son gestionnaire, au cours de la phase de vérification. Ceci permet la modification des en-têtes générés par le navigateur, ou par les filtres en entrée d'Apache.