2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision : 1331006 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_headers.xml.meta">
27 <name>mod_headers</name>
28 <description>Personnalisation des en-têtes de requêtes et de réponses
30 <status>Extension</status>
31 <sourcefile>mod_headers.c</sourcefile>
32 <identifier>headers_module</identifier>
35 <p>Ce module fournit des directives permettant de contrôler et
36 modifier les en-têtes de requêtes et de réponses HTTP. Les en-têtes
37 peuvent être fusionnés, remplacés ou supprimés.</p>
40 <section id="order"><title>Chronologie du traitement</title>
42 <p>Les directives fournies par <module>mod_headers</module> peuvent
43 s'insérer presque partout dans la configuration du serveur, et on
44 peut limiter leur portée en les plaçant dans des <a
45 href="../sections.html">sections de configuration</a>.</p>
47 <p>La chronologie du traitement est importante et est affectée par
48 l'ordre d'apparition des directives dans le fichier de configuration
49 et par leur placement dans les <a
50 href="../sections.html#mergin">sections de configuration</a>. Ainsi,
51 ces deux directives ont un effet différent si leur ordre est inversé
54 <highlight language="config">
55 RequestHeader append MirrorID "mirror 12"
56 RequestHeader unset MirrorID
59 <p>Dans cet ordre, l'en-tête <code>MirrorID</code> n'est pas défini.
60 Si l'ordre des directives était inversé, l'en-tête
61 <code>MirrorID</code> serait défini à "mirror 12".</p>
64 <section id="early"><title>Traitement précoce et traitement
66 <p><module>mod_headers</module> peut agir soir précocement, soit
67 tardivement au niveau de la requête. Le mode normal est le mode
68 tardif, lorsque les en-têtes de <em>requête</em> sont définis, immédiatement
69 avant l'exécution du générateur de contenu, et pour les en-têtes de
70 <em>réponse</em>, juste au moment où la réponse est envoyée sur le réseau.
71 Utilisez toujours le mode tardif sur un serveur en production.</p>
73 <p>Le mode précoce a été conçu à des fins d'aide aux tests et au
74 débogage pour les développeurs. Les directives définies en utilisant
75 le mot-clé <code>early</code> sont censées agir au tout début du
76 traitement de la requête. Cela signifie que l'on peut les utiliser
77 pour simuler différentes requêtes et définir des situations de test,
78 tout en gardant à l'esprit que les en-têtes peuvent être modifiés à
79 tout moment par d'autres modules avant que le réponse ne soit
80 générée.</p>
82 <p>Comme les directives précoces sont traitées avant que le
83 chemin de la requête ne soit parcouru, les en-têtes
84 précoces ne peuvent être définis que dans un contexte de serveur
85 principal ou de serveur virtuel. Les directives précoces ne peuvent
86 pas dépendre d'un chemin de requête, si bien qu'elles échoueront
87 dans des contextes tels que <code><Directory></code> ou
88 <code><Location></code>.</p>
91 <section id="examples"><title>Exemples</title>
95 Copie tous les en-têtes de requête qui commencent par "TS" vers
96 les en-têtes de la réponse :
98 <highlight language="config">
104 Ajoute à la réponse un en-tête, <code>mon-en-tête</code>, qui
105 contient un horodatage permettant de déterminer le moment où la
106 requête a été reçue, et le temps qui s'est écoulé jusqu'à ce que
107 la requête ait commencé à être servie. Cet en-tête peut être
108 utilisé par le client pour estimer la charge du serveur ou
109 isoler les goulets d'étranglement entre le client et le
112 <highlight language="config">
113 Header set mon-en-tête "%D %t"
116 <p>le résultat est l'ajout à la réponse d'un en-tête du type :</p>
119 mon-en-tête: D=3775428 t=991424704447256
124 Dit Bonjour à Joe
127 Header set mon-en-tête "Bonjour Joe. Il a fallu %D microsecondes \<br />
128 à Apache pour servir cette requête."
131 <p>le résultat est l'ajout à la réponse d'un en-tête du type :</p>
133 <highlight language="config">
134 Header set MyHeader "Bonjour Joe. Il a fallu D=3775428 microsecondes à Apache
135 pour servir cette requête."
140 Ajoute l'en-tête <code>mon-en-tête</code> à la réponse si et
141 seulement si l'en-tête <code>mon-en-tête-requête</code> est
142 présent dans la requête. Ceci peut s'avérer utile pour générer
143 des en-têtes de réponse "à la tête du client". Notez que cet
144 exemple nécessite les services du module
145 <module>mod_setenvif</module>.
147 <highlight language="config">
148 SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
149 Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
152 <p>Si l'en-tête <code>mon-en-tête-requête: mavaleur</code> est
153 présent dans la requête HTTP, la réponse contiendra un en-tête
157 mon-en-tête: D=3775428 t=991424704447256 montexte
162 Permet à DAV de fonctionner avec Apache sur SSL (voir la <a
163 href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">description
164 du problème</a>) en remplaçant <var>https:</var> par
165 <var>http:</var> dans l'en-tête <var>Destination</var> :
167 <highlight language="config">
168 RequestHeader edit Destination ^https: http: early
173 Définit la valeur d'un même en-tête sous de multiples conditions
174 non exclusives, mais ne duplique pas une valeur déjà définie
175 dans l'en-tête qui en résulte. Si toutes les conditions
176 suivantes sont satisfaites pour une requête (en d'autres termes,
177 si les trois variables d'environnement <code>CGI</code>,
178 <code>NO_CACHE</code> et <code>NO_STORE</code> existent pour la
181 <highlight language="config">
182 Header merge Cache-Control no-cache env=CGI
183 Header merge Cache-Control no-cache env=NO_CACHE
184 Header merge Cache-Control no-store env=NO_STORE
187 <p>alors, la réponse contiendra l'en-tête suivant :</p>
190 Cache-Control: no-cache, no-store
193 <p>Si <code>append</code> avait été utilisé à la place de
194 <code>merge</code>, la réponse aurait contenu l'en-tête suivant
198 Cache-Control: no-cache, no-cache, no-store
202 Définit un cookie de test si et seulement si le client n'envoie
204 <highlight language="config">
205 Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
212 <name>RequestHeader</name>
213 <description>Configure les en-têtes d'une requête HTTP</description>
214 <syntax>RequestHeader add|append|edit|edit*|merge|set|unset <var>en-tête</var>
215 [<var>valeur</var>] [<var>remplacement</var>] [early|env=[!]<var>variable</var>]</syntax>
216 <contextlist><context>server config</context><context>virtual host</context>
217 <context>directory</context><context>.htaccess</context></contextlist>
218 <override>FileInfo</override>
221 <p>Cette directive permet de remplacer, fusionner, modifier ou
222 supprimer des en-têtes de requête HTTP. L'en-tête est modifié juste
223 avant que le gestionnaire de contenu ne s'exécute, ce qui permet la
224 modification des en-têtes entrants. L'action effectuée est
225 déterminée par le premier argument. Ce dernier accepte les valeurs
230 <dt><code>add</code></dt>
231 <dd>L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il
232 existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs)
233 en-têtes possèdant le même nom et donc induire des conséquences
234 imprévues ; en général, il est préférable d'utiliser
235 <code>set</code>, <code>append</code> ou <code>merge</code>.</dd>
237 <dt><code>append</code></dt>
238 <dd>La valeur d'en-tête est ajoutée à tout en-tête existant de même
239 nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée
240 de celles qui sont déjà présentes par une virgule. Il s'agit de la
241 méthode HTTP standard permettant d'affecter plusieurs valeurs à un
244 <dt><code>edit*</code></dt>
245 <dd>Si l'en-tête existe, sa valeur est modifiée en fonction d'une
246 <glossary ref="regex">expression rationnelle</glossary> de type
247 recherche/remplacement. L'argument <var>valeur</var> est une
248 <glossary ref="regex">expression rationnelle</glossary>, et
249 l'argument <var>remplacement</var> une chaîne de caractères de
250 remplacement qui peut contenir des références arrières. Avec
251 <code>edit</code>, la chaîne de l'en-tête correspondant au modèle ne
252 sera recherchée et remplacée qu'une seule fois, alors qu'avec
253 <code>edit*</code>, elle le sera pour chacune de ses instances si
254 elle apparaît plusieurs fois.</dd>
256 <dt><code>merge</code></dt>
257 <dd>La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf
258 si elle apparaît déjà dans la liste des valeurs préexistantes de
259 l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est
260 ainsi ajoutée, elle est séparée de celles qui sont déjà présentes
261 par une virgule. Il s'agit de la méthode HTTP standard permettant
262 d'affecter plusieurs valeurs à un en-tête. Les valeurs sont
263 comparées en tenant compte de la casse, et après le traitement de
264 tous les spécificateurs de format. Une valeur entourée de guillemets
265 est considérée comme différente de la même valeur mais sans
268 <dt><code>set</code></dt>
269 <dd>L'en-tête est défini, remplaçant tout en-tête préexistant avec
270 le même nom.</dd>
272 <dt><code>unset</code></dt>
273 <dd>L'en-tête est supprimé s'il existe. Si plusieurs en-têtes
274 possèdent le même nom, ils seront tous supprimés. L'argument
275 <var>value</var> ne doit pas apparaître.</dd>
278 <p>Cet argument est suivi d'un nom d'en-tête qui peut se terminer
279 par un caractère ':', mais ce n'est pas obligatoire. La casse est
280 ignorée. Avec <code>set</code>, <code>append</code>,
281 <code>merge</code> et <code>add</code>, une <var>valeur</var> est
282 fournie en troisième argument. Si une <var>valeur</var> contient des
283 espaces, elle doit être entourée de guillemets. Avec
284 <code>unset</code>, aucune <var>valeur</var> ne doit apparaître.
285 <var>valeur</var> peut être une chaîne de caractères, une chaîne
286 contenant des spécificateurs de format, ou une combinaison des deux.
287 Les spécificateurs de format supportés sont les mêmes que ceux de la
288 directive <directive module="mod_headers">Header</directive>, à
289 laquelle vous pouvez vous reporter pour plus de détails. Avec
290 <code>edit</code>, les deux arguments <var>valeur</var> et
291 <var>remplacement</var> sont obligatoires, et correspondent
292 respectivement à une <glossary ref="regex">expression
293 rationnelle</glossary> et à une chaîne de remplacement.</p>
295 <p>La directive <directive>RequestHeader</directive> peut être
296 suivie d'un argument supplémentaire, qui pourra prendre les valeurs
299 <dt><code>early</code></dt>
300 <dd>Spécifie <a href="#early">traitement préalable</a>.</dd>
301 <dt><code>env=[!]<var>variable</var></code></dt>
302 <dd>La directive est appliquée si et seulement si la <a
303 href="../env.html">variable d'environnement</a>
304 <code>variable</code> existe. Un <code>!</code> devant
305 <code>variable</code> inverse le test, et la directive ne
306 s'appliquera alors que si <code>variable</code> n'est pas définie.</dd>
307 <dt><code>expr=<var>expression</var></code></dt>
308 <dd>La directive s'applique si et seulement si <var>expression</var>
309 est évaluée à true. Vous trouverez plus de détails à propos de la
310 syntaxe et de l'évaluation des expressions dans la documentation <a
311 href="../expr.html">ap_expr</a>.</dd>
314 <p>Excepté le cas du mode <a href="#early">précoce</a>, la directive
315 <directive>RequestHeader</directive> est traitée juste avant la
316 prise en compte de la requête par son gestionnaire, au cours de la
317 phase de vérification. Ceci permet la modification des en-têtes
318 générés par le navigateur, ou par les filtres en entrée
325 <description>Configure les en-têtes d'une réponse HTTP</description>
326 <syntax>Header [<var>condition</var>] add|append|echo|edit|merge|set|unset
327 <var>en-tête</var> [<var>valeur</var>] [early|env=[!]<var>variable</var>]</syntax>
328 <contextlist><context>server config</context><context>virtual host</context>
329 <context>directory</context><context>.htaccess</context></contextlist>
330 <override>FileInfo</override>
331 <compatibility>La condition par défaut est temporairement passée
332 à "always" dans les version 2.3.9 et 2.3.10</compatibility>
335 <p>Cette directive permet de remplacer, fusionner, ou
336 supprimer des en-têtes de réponse HTTP. L'en-tête est modifié juste
337 après que le gestionnaire de contenu et les filtres en sortie ne
338 s'exécutent, ce qui permet la modification des en-têtes
341 <p>L'argument optionnel <var>condition</var> permet de déterminer
342 sur quelle table interne d'en-têtes de réponses cette directive va
343 opérer. D'autres composants du serveur peuvent avoir stocké leurs
344 en-têtes de réponses dans la table correspondant à
345 <code>onsuccess</code> ou dans celle correspondant à
346 <code>always</code>. Dans ce contexte, "Always" fait référence au
347 choix d'envoyer les en-têtes que vous ajoutez aux réponses, qu'elle
348 soient avec succès ou échouées ; par contre, si votre action est une
349 fonction d'un en-tête existant, vous devrez lire la documentation de
350 manière plus approfondie car dans ce cas, les choses se compliquent.</p>
352 <p>Vous pouvez avoir à changer la valeur par défaut
353 <code>onsuccess</code> en <code>always</code> dans des circonstances
354 similaires à celles exposées plus loin. Notez aussi que la répétition
355 de cette directive avec les deux conditions peut être pertinente
356 dans certains scénarios, car <code>always</code> n'englobe pas
357 <code>onsuccess</code> en ce qui concerne les en-têtes existants :</p>
360 <li>Vous ajoutez un en-tête à une réponse échouée (non-2xx),
361 une redirection par exemple, et dans ce cas, seule la table
362 correspondant à <code>always</code> est utilisée dans la réponse
363 définitive.</li>
364 <li>Vous modifiez ou supprimez un en-tête généré par un script
365 CGI, et dans ce cas, les scripts CGI sont dans la table
366 correspondant à <code>always</code> et non dans la table par
368 <li>Vous modifiez ou supprimez un en-tête généré par tel ou tel
369 composant du serveur, mais cet en-tête n'est pas trouvé par la
370 condition par défaut <code>onsuccess</code>.</li>
373 <p>L'action que cette directive provoque est déterminée par le
374 premier argument (ou par le second argument si une
375 <var>condition</var> est spécifiée). Il peut prendre
376 une des valeurs suivantes :</p>
379 <dt><code>add</code></dt>
380 <dd>L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il
381 existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs)
382 en-têtes possèdant le même nom et donc induire des conséquences
383 imprévues ; en général, il est préférable d'utiliser
384 <code>set</code>, <code>append</code> ou <code>merge</code>.</dd>
386 <dt><code>append</code></dt>
387 <dd>La valeur d'en-tête est ajoutée à tout en-tête existant de même
388 nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée
389 de celles qui sont déjà présentes par une virgule. Il s'agit de la
390 méthode HTTP standard permettant d'affecter plusieurs valeurs à un
393 <dt><code>echo</code></dt>
394 <dd>Les en-têtes de la requête possédant le nom spécifié sont
395 recopiés vers les en-têtes de la réponse. <var>en-tête</var> peut
396 être une <glossary ref="regex">expression rationnelle</glossary>, et
397 <var>valeur</var> ne doit pas être présent.</dd>
399 <dt><code>edit</code></dt>
400 <dd>Si l'en-tête existe, sa valeur est modifiée en fonction d'une
401 <glossary ref="regex">expression rationnelle</glossary> de type
402 recherche/remplacement. L'argument <var>valeur</var> est une
403 <glossary ref="regex">expression rationnelle</glossary>, et
404 l'argument <var>remplacement</var> une chaîne de caractères de
405 remplacement qui peut contenir des références arrières.</dd>
407 <dt><code>merge</code></dt>
408 <dd>La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf
409 si elle apparaît déjà dans la liste des valeurs préexistantes de
410 l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est
411 ainsi ajoutée, elle est séparée de celles qui sont déjà présentes
412 par une virgule. Il s'agit de la méthode HTTP standard permettant
413 d'affecter plusieurs valeurs à un en-tête. Les valeurs sont
414 comparées en tenant compte de la casse, et après le traitement de
415 tous les spécificateurs de format. Une valeur entourée de guillemets
416 est considérée comme différente de la même valeur mais sans
419 <dt><code>set</code></dt>
420 <dd>L'en-tête est défini, remplaçant tout en-tête préexistant avec
421 le même nom. L'argument <var>valeur</var> peut être une chaîne de
424 <dt><code>unset</code></dt>
425 <dd>L'en-tête est supprimé s'il existe. Si plusieurs en-têtes
426 possèdent le même nom, ils seront tous supprimés. L'argument
427 <var>value</var> ne doit pas apparaître.</dd>
430 <p>Cet argument est suivi d'un nom d'<var>en-tête</var> qui peut se
431 terminer par un caractère ':', mais ce n'est pas obligatoire. La
432 casse est ignorée avec <code>set</code>, <code>append</code>,
433 <code>merge</code>, <code>add</code>, <code>unset</code> et
434 <code>edit</code>. Le nom d'<var>en-tête</var> est sensible à la
435 casse pour <code>echo</code> et peut être une <glossary
436 ref="regex">expression rationnelle</glossary>.</p>
438 <p>Avec <code>set</code>, <code>append</code>, <code>merge</code> et
439 <code>add</code>, une <var>valeur</var> est spécifiée comme
440 argument suivant. Si <var>valeur</var> contient des espaces, elle
441 doit être entourée de guillemets. <var>valeur</var> peut être une
442 chaîne de caractères, une chaîne contenant des spécificateurs de
443 format, ou une combinaison des deux. <var>valeur</var> supporte les
444 spécificateurs de format suivants :</p>
446 <table border="1" style="zebra">
447 <columnspec><column width=".25"/><column width=".75"/></columnspec>
448 <tr><th>Format</th><th>Description</th></tr>
449 <tr><td><code>%%</code></td>
450 <td>Le caractère pourcentage</td></tr>
452 <tr><td><code>%t</code></td>
453 <td>Le moment de réception de la requête en temps
454 universel coordonné depuis le temps epoch (Jan. 1, 1970) et
455 exprimé en microsecondes. La valeur est précédée de
456 <code>t=</code>.</td></tr>
458 <tr><td><code>%D</code></td>
459 <td>Le temps écoulé entre la réception de la requête et l'envoi
460 des en-têtes sur le réseau. Il s'agit de la durée de traitement
461 de la requête. La valeur est précédée de <code>D=</code>. La
462 valeur est exprimée en microsecondes.</td></tr>
464 <tr><td><code>%{NOM_VARIABLE}e</code></td>
465 <td>Le contenu de la <a href="../env.html">variable
466 d'environnement</a> <code>NOM_VARIABLE</code>.</td></tr>
468 <tr><td><code>%{NOM_VARIABLE}s</code></td>
469 <td>Le contenu de la <a href="../env.html">variable
470 d'environnement SSL</a> <code>NOM_VARIABLE</code>, si
471 <module>mod_ssl</module> est activé.</td></tr>
475 <note><title>Note</title>
476 <p>Le spécificateur de format <code>%s</code> est disponible
477 depuis la version 2.1 d'Apache ; il peut être utilisé à la place
478 de <code>%e</code> pour éviter de devoir spécifier
479 <code>SSLOptions +StdEnvVars</code>. Cependant, si
480 <code>SSLOptions +StdEnvVars</code> doit tout de même être
481 spécifié pour une raison quelconque, <code>%e</code> sera plus
482 efficace que <code>%s</code>.</p>
485 <p><code>edit</code>nécessite les deux arguments
486 <var>valeur</var>, qui est une <glossary ref="regex">expression
487 rationnelle</glossary>, et une chaîne additionnelle
488 <var>remplacement</var>.</p>
490 <p>La directive <directive>Header</directive> peut être suivie d'un
491 argument additionnel qui peut prendre les valeurs suivantes :</p>
494 <dt><code>early</code></dt>
495 <dd>Spécifie <a href="#early">traitement préalable</a>.</dd>
496 <dt><code>env=[!]<var>variable</var></code></dt>
497 <dd>La directive est appliquée si et seulement si la <a
498 href="../env.html">variable d'environnement</a>
499 <code>variable</code> existe. Un <code>!</code> devant
500 <code>variable</code> inverse le test, et la directive ne
501 s'appliquera alors que si <code>variable</code> n'est pas définie.</dd>
502 <dt><code>expr=<var>expression</var></code></dt>
503 <dd>La directive s'applique si et seulement si <var>expression</var>
504 est évaluée à true. Vous trouverez plus de détails à propos de la
505 syntaxe et de l'évaluation des expressions dans la documentation <a
506 href="../expr.html">ap_expr</a>.</dd>
509 <p>Excepté le cas du mode <a href="#early">précoce</a>, les
510 directives <directive>Header</directive> sont traitées juste avant
511 l'envoi de la réponse sur le réseau. Cela signifie qu'il est
512 possible de définir et/ou modifier la plupart des en-têtes, à
513 l'exception de ceux qui sont ajoutés par le filtre HTTP
514 d'en-tête, comme Content-Type.</p>
projects / apache / blob