Serveur HTTP Apache Version 2.5
Description: | Personnalisation des en-têtes de requêtes et de réponses HTTP |
---|---|
Statut: | Extension |
Identificateur de Module: | headers_module |
Fichier Source: | mod_headers.c |
Ce module fournit des directives permettant de contrôler et modifier les en-têtes de requêtes et de réponses HTTP. Les en-têtes peuvent être fusionnés, remplacés ou supprimés.
Les directives fournies par mod_headers
peuvent
s'insérer presque partout dans la configuration du serveur, et on
peut limiter leur portée en les plaçant dans des sections de configuration.
La chronologie du traitement est importante et est affectée par l'ordre d'apparition des directives dans le fichier de configuration et par leur placement dans les sections de configuration. Ainsi, ces deux directives ont un effet différent si leur ordre est inversé :
RequestHeader append MirrorID "mirror 12" RequestHeader unset MirrorID
Dans cet ordre, l'en-tête MirrorID
n'est pas défini.
Si l'ordre des directives était inversé, l'en-tête
MirrorID
serait défini à "mirror 12".
mod_headers
peut agir soir précocement, soit
tardivement au niveau de la requête. Le mode normal est le mode
tardif, lorsque les en-têtes de requête sont définis, immédiatement
avant l'exécution du générateur de contenu, et pour les en-têtes de
réponse, juste au moment où la réponse est envoyée sur le réseau.
Utilisez toujours le mode tardif sur un serveur en production.
Le mode précoce a été conçu à des fins d'aide aux tests et au
débogage pour les développeurs. Les directives définies en utilisant
le mot-clé early
sont censées agir au tout début du
traitement de la requête. Cela signifie que l'on peut les utiliser
pour simuler différentes requêtes et définir des situations de test,
tout en gardant à l'esprit que les en-têtes peuvent être modifiés à
tout moment par d'autres modules avant que le réponse ne soit
générée.
Comme les directives précoces sont traitées avant que le
chemin de la requête ne soit parcouru, les en-têtes
précoces ne peuvent être définis que dans un contexte de serveur
principal ou de serveur virtuel. Les directives précoces ne peuvent
pas dépendre d'un chemin de requête, si bien qu'elles échoueront
dans des contextes tels que <Directory>
ou <Location>
.
Header echo ^TS
mon-en-tête
, qui
contient un horodatage permettant de déterminer le moment où la
requête a été reçue, et le temps qui s'est écoulé jusqu'à ce que
la requête ait commencé à être servie. Cet en-tête peut être
utilisé par le client pour estimer la charge du serveur ou
isoler les goulets d'étranglement entre le client et le
serveur.
Header set mon-en-tête "%D %t"
le résultat est l'ajout à la réponse d'un en-tête du type :
mon-en-tête: D=3775428 t=991424704447256
Header set mon-en-tête "Bonjour Joe. Il a fallu %D microsecondes \
à Apache pour servir cette requête."
le résultat est l'ajout à la réponse d'un en-tête du type :
Header set MyHeader "Bonjour Joe. Il a fallu D=3775428 microsecondes à Apache pour servir cette requête."
mon-en-tête
à la réponse si et
seulement si l'en-tête mon-en-tête-requête
est
présent dans la requête. Ceci peut s'avérer utile pour générer
des en-têtes de réponse "à la tête du client". Notez que cet
exemple nécessite les services du module
mod_setenvif
.
SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
Si l'en-tête mon-en-tête-requête: mavaleur
est
présent dans la requête HTTP, la réponse contiendra un en-tête
du type :
mon-en-tête: D=3775428 t=991424704447256 montexte
RequestHeader edit Destination ^https: http: early
CGI
,
NO_CACHE
et NO_STORE
existent pour la
requête) :
Header merge Cache-Control no-cache env=CGI Header merge Cache-Control no-cache env=NO_CACHE Header merge Cache-Control no-store env=NO_STORE
alors, la réponse contiendra l'en-tête suivant :
Cache-Control: no-cache, no-store
Si append
avait été utilisé à la place de
merge
, la réponse aurait contenu l'en-tête suivant
:
Cache-Control: no-cache, no-cache, no-store
Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"
Description: | Configure les en-têtes d'une réponse HTTP |
---|---|
Syntaxe: | Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note
en-tête [[expr=]valeur
[remplacement]
[early|env=[!]variable|expr=expression]]
|
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess |
Surcharges autorisées: | FileInfo |
Statut: | Extension |
Module: | mod_headers |
Compatibilité: | SetIfEmpty est disponible depuis la version 2.4.7 du serveur HTTP Apache ; le paramètre expr=valeur a été introduit avec la version 2.4.10 |
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 :
always
est utilisée dans la réponse
définitive.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.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 :
Vous devez lire la différence, décrite plus haut, entre les listes
d'en-têtes always
et onsuccess
avant de lire
la liste d'actions ci-dessous car cet important concept s'applique
encore ici. En fait, chaque action fonctionne telle qu'elle est décrite
mais seulement pour la liste d'en-têtes cible.
add
set
, append
ou merge
.append
echo
edit
edit*
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
set
setifempty
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
note
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 :
Format | Description |
---|---|
%% |
Le caractère pourcentage |
%t |
Le moment de réception de la requête en temps
universel coordonné depuis le temps epoch (Jan. 1, 1970) et
exprimé en microsecondes. La valeur est précédée de
t= . |
%D |
Le temps écoulé entre la réception de la requête et l'envoi
des en-têtes sur le réseau. Il s'agit de la durée de traitement
de la requête. La valeur est précédée de D= . La
valeur est exprimée en microsecondes. |
%l |
La charge moyenne courante du serveur proprement dit. Ce
sont les valeurs obtenues par getloadavg() qui
représentent la charge moyenne courante, sur 5 minutes et sur 15
minutes. Chaque valeur est précédée de l= et
séparée de la suivante par un / .Disponible depuis la version 2.4.4 du serveur HTTP Apache. |
%i |
Le pourcentage courant de httpd au repos (de 0 à 100)
en se basant sur le nombre de processus et threads disponibles.
La valeur est précédée de i= .Disponible depuis la version 2.4.4 du serveur HTTP Apache. |
%b |
Le pourcentage courant de httpd utilisé (de 0 à 100)
en se basant sur le nombre de processus et threads disponibles.
La valeur est précédée de b= .Disponible depuis la version 2.4.4 du serveur HTTP Apache. |
%{NOM_VARIABLE}e |
Le contenu de la variable
d'environnement NOM_VARIABLE . |
%{NOM_VARIABLE}s |
Le contenu de la variable
d'environnement SSL NOM_VARIABLE , si
mod_ssl est activé. |
Le spécificateur de format %s
est disponible
depuis la version 2.1 d'Apache ; il peut être utilisé à la place
de %e
pour éviter de devoir spécifier
SSLOptions +StdEnvVars
. Cependant, si
SSLOptions +StdEnvVars
doit tout de même être
spécifié pour une raison quelconque, %e
sera plus
efficace que %s
.
Lorsque le paramètre valeur utilise l'interpréteur ap_expr, certaines syntaxes d'expressions seront différentes des exemples qui évaluent des expressions booléennes telles que <If> :
Header set foo-checksum "expr=%{md5:foo}"
edit
né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
env=[!]variable
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
# 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.
Description: | Configure les en-têtes d'une requête HTTP |
---|---|
Syntaxe: | RequestHeader add|append|edit|edit*|merge|set|setifempty|unset
en-tête [[expr=]valeur
[remplacement]
[early|env=[!]variable|expr=expression]]
|
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess |
Surcharges autorisées: | FileInfo |
Statut: | Extension |
Module: | mod_headers |
Compatibilité: | SetIfEmpty est disponible depuis la version 2.4.7 du serveur HTTP Apache ; le paramètre expr=valeur a été introduit avec la version 2.4.10 |
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
set
, append
ou merge
.append
edit
edit*
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
set
setifempty
unset
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
env=[!]variable
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
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.