mod_headers Personnalisation des en-têtes de requêtes et de réponses HTTP Extension mod_headers.c headers_module

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.
Chronologie du traitement

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".

Traitement précoce et traitement tardif

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.

Exemples
  1. Copie tous les en-têtes de requête qui commencent par "TS" vers les en-têtes de la réponse : Header echo ^TS
  2. Ajoute à la réponse un en-tête, 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
  3. Dit Bonjour à Joe 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."
  4. Ajoute l'en-tê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
  5. Permet à DAV de fonctionner avec Apache sur SSL (voir la description du problème) en remplaçant https: par http: dans l'en-tête Destination : RequestHeader edit Destination ^https: http: early
  6. Définit la valeur d'un même en-tête sous de multiples conditions non exclusives, mais ne duplique pas une valeur déjà définie dans l'en-tête qui en résulte. Si toutes les conditions suivantes sont satisfaites pour une requête (en d'autres termes, si les trois variables d'environnement 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
  7. Définit un cookie de test si et seulement si le client n'envoie pas de cookie Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
  8. Ajoute un en-tête de mise en cache pour les réponses avec un code d'état HTTP de 200 Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"
RequestHeader Configure les en-têtes d'une requête HTTP RequestHeader add|append|edit|edit*|merge|set|setifempty|unset en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]] server configvirtual host directory.htaccess FileInfo 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
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.

 Header Configure les en-têtes d'une réponse HTTP Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]] server configvirtual host directory.htaccess FileInfo 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. La situation où vous devez spécifier always dépend des différentes actions ci-dessous.

Avertissement

Etudiez avec attention la différence entre always et onsuccess pour chaque action décrite ci-dessous car le comportement induit n'est pas trivial et est souvent source de confusion. Lorsqu'il est conseillé de répéter les conditions, vous pouvez expérimenter chacune d'entre elles et utiliser celle qui vous paraît la plus efficace pour correspondre à l'en-tête préexistant.
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.

Choix de la condition : spécifiez la condition always si vous souhaitez que l'en-tête soit aussi ajouté aux réponses de type non-2xx (comme les redirections ou les erreurs).

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.

Choix de la condition : si l'en-tête préexistant auquel vous voulez ajouter une valeur a été ajouté par ce module, vous devez spécifier la même condition que celle utilisée à l'origine. Dans le cas contraire, vous devez déterminer expérimentalement si always doit être spécifié car vous ne pouvez pas savoir de manière sure dans quelle table interne la valeur existante est présente.

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.

Choix de la condition : spécifiez la condition always si vous souhaitez que l'en-tête soit aussi ajouté aux réponses de type non-2xx (comme les redirections ou les erreurs).

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.

Choix de la condition : en fonction de l'origine de l'en-tête à éditer, vous pourrez être amenés à répéter votre directive edit/edit* avec les deux conditions always et onsuccess. Autrement, vous pouvez déterminer expérimentalement si une condition always est nécessaire.

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 sans guillemets.

Choix de la condition : si l'en-tête préexistant auquel vous voulez ajouter une valeur a été ajouté par ce module, vous devez spécifier la même condition que celle utilisée à l'origine. Dans le cas contraire, vous devez déterminer expérimentalement si always est nécessaire.

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 formatée.

Choix de la condition : si l'en-tête à définir a été ajouté par ce module, vous devez spécifier la même condition que celle utilisée à l'origine. Dans le cas contraire, vous devez déterminer expérimentalement si always est nécessaire.

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

Choix de la condition : si l'en-tête à définir a été ajouté par ce module, vous devez spécifier la même condition que celle utilisée à l'origine. Dans le cas contraire, vous devez déterminer expérimentalement si always est nécessaire.

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.

Choix de la condition : répétez cette directive avec les deux conditions always et onsuccess pour être sur que l'en-tête soit bien supprimé, ou déterminez expérimentalement si always est nécessaire.

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.

Choix de la condition : si l'en-tête cible a été ajouté par ce module, vous devez spécifier la même condition que celle utilisée à l'origine. Dans le cas contraire, vous devez déterminer expérimentalement si always est nécessaire.

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 :

FormatDescription
%% 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é.
Note

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.

 Note à propos des valeurs des expressions

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> :

  • Le point de départ de la syntaxe est 'string' au lieu de 'expr'.
  • Les appels de fonction utilisent la syntaxe %{funcname:arg} au lieu de funcname(arg).
  • Les fonctions multi-arguments ne sont pas encore disponibles depuis le point de départ 'string'.
  • Il faut mettre entre guillemets l'ensemble du paramètre, comme dans l'exemple suivant : Header set foo-checksum "expr=%{md5:foo}"

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.