<-
Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

Module Apache mod_headers

Langues Disponibles:  en  |  fr  |  ja  |  ko 

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

Sommaire

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.

Directives

Sujets

top

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

top

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

top

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

Header Directive

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 du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride: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. En d�pit du nom, la valeur par d�faut de onsuccess ne limite pas une action aux r�ponses avec un code d'�tat de 2xx. Les en-t�tes d�finis sous cette condition sont encore utilis�s quand par exemple une requ�te est mandat�e ou g�n�r�e par un programme CGI avec succ�s, et ceci m�me dans le cas o� ils ont g�n�r� un code d'�chec.

Lorsque votre action est une fonction agissant sur un en-t�te existant, vous pourrez �tre amen� � sp�cifier une condition always, en fonction de la table interne dans laquelle l'en-t�te original a �t� d�fini. La table qui correspond � always est utilis�e pour les r�ponses d'erreur g�n�r�es localement ainsi que pour les r�ponses qui ont abouti. 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 :

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

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.

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.

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.

top

RequestHeader 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 du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride: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
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.

Langues Disponibles:  en  |  fr  |  ja  |  ko 

top

Commentaires

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.