1 <?xml version="1.0" encoding="ISO-8859-1" ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.fr.xsl"?>
4 <!-- English Revision: 1673563 -->
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 <manualpage metafile="env.xml.meta">
27 <title>Apache et les variables d'environnement</title>
30 <p>Deux types de variables d'environnement affectent le serveur
33 <p>Le premier type correspond aux variables d'environnement
34 contrôlées par le système d'exploitation sous-jacent et définies
35 avant le démarrage du serveur. Leurs valeurs peuvent être utilisées
36 directement dans les fichiers de configuration, et peuvent
37 éventuellement être transmises aux scripts CGI et SSI via la
38 directive PassEnv.</p>
40 <p>Le second type correspond aux variables nommées appelées aussi
41 <em>variables d'environnement</em> dans lesquelles le serveur HTTP
42 Apache stocke des informations via un mécanisme spécial. Ces
43 informations peuvent servir à contrôler diverses opérations comme
44 l'enregistrement des traces ou le contrôle d'accès. On utilise aussi ces
45 variables dans le mécanisme de communication avec les programmes externes
46 comme les scripts CGI. Ce document présente différentes méthodes pour
47 manipuler et utiliser ces variables.</p>
49 <p>Bien que ces variables soient référencées comme <em>variables
50 d'environnement</em>, il ne faut pas les confondre avec les variables
51 d'environnement contrôlées par le système d'exploitation sous-jacent.
52 En fait, ces variables sont stockées et manipulées dans une structure
53 interne à Apache. Elles ne deviennent de véritables variables
54 d'environnement du système d'exploitation que lorsqu'elles sont mises à la
55 disposition de scripts CGI et de scripts inclus côté serveur (SSI). Si vous
56 souhaitez manipuler l'environnement du système d'exploitation sous lequel
57 le serveur s'exécute, vous devez utiliser les mécanismes standards de
58 manipulation de l'environnement fournis par l'interpréteur de commandes
59 (shell) de votre système d'exploitation.</p>
62 <section id="setting">
63 <title>Définition des variables d'environnement</title>
66 <module>mod_cache</module>
67 <module>mod_env</module>
68 <module>mod_rewrite</module>
69 <module>mod_setenvif</module>
70 <module>mod_unique_id</module>
73 <directive module="mod_setenvif">BrowserMatch</directive>
74 <directive module="mod_setenvif">BrowserMatchNoCase</directive>
75 <directive module="mod_env">PassEnv</directive>
76 <directive module="mod_rewrite">RewriteRule</directive>
77 <directive module="mod_env">SetEnv</directive>
78 <directive module="mod_setenvif">SetEnvIf</directive>
79 <directive module="mod_setenvif">SetEnvIfNoCase</directive>
80 <directive module="mod_env">UnsetEnv</directive>
84 <section id="basic-manipulation">
85 <title>Manipulations de base de l'environnement</title>
87 <p>La méthode la plus élémentaire pour définir une variable
88 d'environnement au niveau d'Apache consiste à utiliser la directive
89 inconditionnelle <directive module="mod_env"
90 >SetEnv</directive>. Les variables peuvent aussi être transmises depuis
91 l'environnement du shell à partir duquel le serveur a été démarré en
92 utilisant la directive
93 <directive module="mod_env">PassEnv</directive>.</p>
96 <section id="conditional">
97 <title>Définitions conditionnelles en fonction des requêtes</title>
99 <p>Pour plus de souplesse, les directives fournies par le module
100 <module>mod_setenvif</module> permettent de définir les
101 variables d'environnement en tenant compte des caractéristiques
102 de chaque requête. Par exemple, une
103 variable pourrait n'être définie que lorsqu'un navigateur spécifique
104 (User-Agent) a généré la requête, ou seulement quand un en-tête
105 Referer particulier est présent. La directive
106 <directive module="mod_rewrite">RewriteRule</directive> du module
107 <module>mod_rewrite</module> qui utilise l'option
108 <code>[E=...]</code> pour définir
109 les variables d'environnement apporte encore plus de souplesse.</p>
112 <section id="unique-identifiers">
113 <title>Identifiants uniques</title>
115 <p>Finalement, le module <module>mod_unique_id</module> définit la variable
116 d'environnement <code>UNIQUE_ID</code> pour chaque requête à une valeur
117 qui est garantie unique parmi "toutes" les requêtes sous des
118 conditions très spécifiques.</p>
121 <section id="standard-cgi">
122 <title>Variables CGI standards</title>
124 <p>En plus de l'ensemble des variables d'environnement internes à la
125 configuration d'Apache et de celles transmises depuis le shell,
126 les scripts CGI et les pages SSI
127 se voient affectés un ensemble de variables
128 d'environnement contenant des méta-informations à propos de la requête
129 comme préconisé dans la
130 <a href="http://www.ietf.org/rfc/rfc3875">spécification
131 sur les CGIs</a>.</p>
134 <section id="caveats">
135 <title>Quelques mises en garde</title>
138 <li>Les directives de manipulation de l'environnement ne permettent
139 pas de supplanter ou modifier les variables CGI standards.</li>
141 <li>Lorsqu'on utilise <program>suexec</program> pour exécuter des
142 scripts CGI, l'environnement est nettoyé et réduit à un ensemble de
143 variables <em>sûres</em> avant l'exécution du script. La liste des
144 variables <em>sûres</em> est définie à la compilation dans
145 <code>suexec.c</code>.</li>
147 <li>Pour des raisons de portabilité, les noms des variables
148 d'environnement ne peuvent contenir que des lettres, des chiffres, et
149 le caractère "sousligné". En outre, le premier caractère ne doit pas
150 être un chiffre. Les caractères qui ne satisfont pas à ces conditions
151 seront remplacés par un caractère "sousligné" quand ils seront
152 transmis aux scripts CGI et aux pages SSI.</li>
154 <li>Les contenus d'en-têtes HTTP transmis aux scripts de type
155 CGI ou autre via des variables d'environnement constituent un
156 cas particulier (voir plus loin). Leur nom est converti en
157 majuscules et seuls les tirets sont remplacés par des
158 caractères '_' ("souligné") ; si le format du nom de l'en-tête
159 n'est pas valide, celui-ci est ignoré. Voir <a
160 href="#fixheader">plus loin</a> pour une solution de
161 contournement du problème.</li>
163 <li>La directive <directive
164 module="mod_env">SetEnv</directive> s'exécute assez tard au
165 cours du traitement de la requête, ce qui signifie que des
166 directives telles que <directive
167 module="mod_setenvif">SetEnvIf</directive> et <directive
168 module="mod_rewrite">RewriteCond</directive> ne verront pas
169 les variables qu'elle aura définies.</li>
171 <li>Lorsque le serveur cherche un chemin via une <glossary
172 ref="subrequest">sous-requête</glossary> interne (par exemple la
173 recherche d'un <directive
174 module="mod_dir">DirectoryIndex</directive>), ou lorsqu'il génère un
175 listing du contenu d'un répertoire via le module
176 <module>mod_autoindex</module>, la sous-requête n'hérite pas des
177 variables d'environnement spécifiques à la requête. En outre, à cause
178 des phases de l'API auxquelles <module>mod_setenvif</module> prend
179 part, les directives <directive
180 module="mod_setenvif">SetEnvIf</directive> ne sont pas évaluées
181 séparément dans la sous-requête.</li>
186 <title>Utilisation des variables d'environnement</title>
190 <module>mod_authz_host</module>
191 <module>mod_cgi</module>
192 <module>mod_ext_filter</module>
193 <module>mod_headers</module>
194 <module>mod_include</module>
195 <module>mod_log_config</module>
196 <module>mod_rewrite</module>
199 <directive module="mod_authz_core">Require</directive>
200 <directive module="mod_log_config">CustomLog</directive>
201 <directive module="mod_access_compat">Deny</directive>
202 <directive module="mod_ext_filter">ExtFilterDefine</directive>
203 <directive module="mod_headers">Header</directive>
204 <directive module="mod_log_config">LogFormat</directive>
205 <directive module="mod_rewrite">RewriteCond</directive>
206 <directive module="mod_rewrite">RewriteRule</directive>
210 <section id="cgi-scripts">
211 <title>Scripts CGI</title>
213 <p>La communication d'informations aux scripts CGI constitue une des
214 principales utilisations des variables d'environnement. Comme indiqué
215 plus haut, l'environnement transmis aux scripts CGI comprend des
216 méta-informations standards à propos de la requête, en plus des
217 variables définies dans la configuration d'Apache. Pour plus de
218 détails, se référer au
219 <a href="howto/cgi.html">tutoriel CGI</a>.</p>
222 <section id="ssi-pages">
223 <title>Pages SSI</title>
225 <p>Les documents inclus côté serveur (SSI) traités par le filtre
226 <code>INCLUDES</code> du module <module>mod_include</module>,
228 variables d'environnement à l'aide de l'élément <code>echo</code>,
229 et peuvent utiliser des variables d'environnement dans les éléments
230 de contrôle de flux pour rendre certaines parties d'une page
231 conditionnelles en fonction des caractéristiques de la requête.
232 Apache fournit aussi les variables d'environnement CGI standards
234 comme indiqué plus haut. Pour plus de détails, se référer au
235 <a href="howto/ssi.html">tutoriel SSI</a>.</p>
238 <section id="access-control">
239 <title>Contrôle d'accès</title>
241 <p>L'accès au serveur peut être contrôlé en fonction de la valeur de
242 variables d'environnement à l'aide des directives
243 <code>allow from env=</code> et <code>deny from env=</code>.
244 En association avec la directive
245 <directive module="mod_setenvif">SetEnvIf</directive>, ceci confère une
246 grande souplesse au contrôle d'accès au serveur en fonction des
247 caractéristiques du client. Par exemple, vous pouvez utiliser ces
248 directives pour interdire l'accès depuis un navigateur particulier
253 <section id="logging">
254 <title>Enregistrement conditionnel des traces</title>
256 <p>Les variables d'environnement peuvent être enregistrées dans le
257 fichier de log des accès à l'aide de l'option <code>%e</code> de la
258 directive <directive module="mod_log_config">LogFormat</directive>.
259 En outre, la décision de tracer ou non les requêtes peut être prise
260 en fonction de l'état de variables d'environnement en utilisant la
261 forme conditionnelle de la directive
262 <directive module="mod_log_config">CustomLog</directive>. En
263 association avec la directive <directive module="mod_setenvif"
264 >SetEnvIf</directive>, ceci confère une grande souplesse au contrôle
265 du traçage des requêtes. Par exemple, vous pouvez choisir de ne pas
266 tracer les requêtes pour des noms de fichiers se terminant par
267 <code>gif</code>, ou encore de ne tracer que les requêtes des clients
268 n'appartenant pas à votre sous-réseau.</p>
271 <section id="response-headers">
272 <title>En-têtes de réponse conditionnels</title>
274 <p>La directive <directive module="mod_headers">Header</directive>
275 peut se baser sur la présence ou l'absence d'une variable
276 d'environnement pour décider si un certain en-tête HTTP sera placé
277 dans la réponse au client. Ceci permet, par exemple, de n'envoyer un
278 certain en-tête de réponse que si un en-tête correspondant est présent
279 dans la requête du client.</p>
283 <section id="external-filter">
284 <title>Activation de filtres externes</title>
286 <p>Les filtres externes configurés par le module
287 <module>mod_ext_filter</module> à l'aide de la directive <directive
288 module="mod_ext_filter">ExtFilterDefine</directive> peuvent être
289 activés de manière conditionnelle en fonction d'une variable
290 d'environnement à l'aide des options
291 <code>disableenv=</code> et <code>enableenv=</code>.</p>
294 <section id="url-rewriting">
295 <title>Réécriture d'URL</title>
297 <p>La forme <code>%{ENV:<em>variable</em>}</code> de
298 <em>TestString</em> dans la
299 directive <directive module="mod_rewrite">RewriteCond</directive>
300 permet au moteur de réécriture du module
301 <module>mod_rewrite</module> de prendre des
302 décisions conditionnées par des variables d'environnement.
303 Notez que les variables accessibles dans
304 <module>mod_rewrite</module> sans le préfixe
305 <code>ENV:</code> ne sont pas de véritables variables
306 d'environnement. Ce sont plutôt des variables spécifiques à
307 <module>mod_rewrite</module>
308 qui ne sont pas accessibles pour les autres modules.</p>
312 <section id="special">
313 <title>Variables d'environnement à usage spécial</title>
315 <p>Des problèmes d'interopérabilité ont conduit à l'introduction de
316 mécanismes permettant de modifier le comportement d'Apache lorsqu'il
317 dialogue avec certains clients. Afin de rendre ces mécanismes aussi
318 souples que possible, ils sont invoqués en définissant des variables
319 d'environnement, en général à l'aide de la directive
320 <directive module="mod_setenvif">BrowserMatch</directive>, bien que les
321 directives <directive module="mod_env">SetEnv</directive> et
322 <directive module="mod_env">PassEnv</directive> puissent aussi être
323 utilisées, par exemple.</p>
325 <section id="downgrade">
326 <title>downgrade-1.0</title>
328 <p>Ceci force le traitement d'une requête comme une requête HTTP/1.0
329 même si elle a été rédigée dans un langage plus récent.</p>
332 <section id="force-gzip">
333 <title>force-gzip</title>
334 <p>Si le filtre <code>DEFLATE</code> est activé, cette variable
335 d'environnement ignorera les réglages accept-encoding de votre
336 navigateur et enverra une sortie compressée inconditionnellement.</p>
338 <section id="force-no-vary">
339 <title>force-no-vary</title>
341 <p>Cette variable entraîne la suppression de tout champ
342 <code>Vary</code> des en-têtes de la réponse avant que cette dernière
343 soit renvoyée au client. Certains clients n'interprètent pas ce champ
344 correctement, et la définition de cette variable permet de contourner
345 ce problème, mais implique aussi la définition de
346 <strong>force-response-1.0</strong>.</p>
349 <section id="force-response">
350 <title>force-response-1.0</title>
352 <p>Cette variable force une réponse en langage HTTP/1.0 aux clients
353 qui envoient des requêtes dans le même langage. Elle fut implémentée à
354 l'origine suite à des problèmes avec les mandataires d'AOL. Certains
355 clients en langage HTTP/1.0 ne réagissent pas correctement face à une
356 réponse en langage HTTP/1.1, et cette variable peut être utilisée pour
357 assurer l'interopérabilité avec eux.</p>
361 <section id="gzip-only-text-html">
362 <title>gzip-only-text/html</title>
364 <p>Positionnée à "1", cette variable désactive le filtre en sortie
365 <code>DEFLATE</code> fourni par le module <module>mod_deflate</module> pour les
366 types de contenu autres que <code>text/html</code>. Si vous préférez
367 utiliser des fichiers compressés statiquement,
368 <module>mod_negotiation</module> évalue aussi la variable (non
369 seulement pour gzip, mais aussi pour tous les encodages autres que
373 <section id="no-gzip"><title>no-gzip</title>
375 <p>Quand cette variable est définie, le filtre <code>DEFLATE</code> du
376 module <module>mod_deflate</module> est désactivé, et
377 <module>mod_negotiation</module> refusera de délivrer des ressources
382 <section id="no-cache"><title>no-cache</title>
383 <p><em>Disponible dans les versions 2.2.12 et ultérieures d'Apache</em></p>
385 <p>Lorsque cette variable est définie,
386 <module>mod_cache</module> ne sauvegardera pas de réponse
387 susceptible d'être mise en cache. Cette variable d'environnement
388 n'a aucune incidence sur le fait qu'une réponse déjà enregistrée
389 dans la cache soit utilisée ou non pour la requête courante.</p>
393 <section id="nokeepalive">
394 <title>nokeepalive</title>
396 <p>Quand cette variable est définie, la directive
397 <directive module="core">KeepAlive</directive> est désactivée.</p>
401 <section id="prefer-language"><title>prefer-language</title>
403 <p>Cette variable modifie le comportement du module
404 <module>mod_negotiation</module>. Si elle contient un symbole de
405 langage (tel que <code>en</code>, <code>ja</code>
406 ou <code>x-klingon</code>), <module>mod_negotiation</module> essaie de
407 délivrer une variante dans ce langage. S'il n'existe pas de telle
408 variante, le processus normal de
409 <a href="content-negotiation.html">négociation</a> s'applique.</p>
413 <section id="redirect-carefully">
414 <title>redirect-carefully</title>
416 <p>Cette variable force le serveur à être plus prudent lors de l'envoi
417 d'une redirection au client. Elle est en général utilisée quand un
418 client présente un problème connu avec les redirections. Elle fut
419 implémentée à l'origine suite a un problème rencontré avec le logiciel
420 WebFolders de Microsoft qui ne gère pas correctement les redirections
421 vers des ressources de type répertoire via des méthodes DAV.</p>
425 <section id="suppress-error-charset">
426 <title>suppress-error-charset</title>
428 <p><em>Disponible dans les versions postérieures à 2.0.54</em></p>
430 <p>Quand Apache génère une redirection en réponse à une requête client,
431 la réponse inclut un texte destiné à être affiché au cas où le client ne
432 suivrait pas, ou ne pourrait pas suivre automatiquement la redirection.
433 Habituellement, Apache marque ce texte en accord avec le jeu de caractères
434 qu'il utilise, à savoir ISO-8859-1.</p>
435 <p> Cependant, si la redirection fait référence à une page qui utilise un
436 jeu de caractères différent, certaines versions de navigateurs obsolètes
437 essaieront d'utiliser le jeu de caractères du texte de la redirection
438 plutôt que celui de la page réelle.
439 Ceci peut entraîner, par exemple, un rendu incorrect du Grec.</p>
440 <p>Si cette variable d'environnement est définie, Apache omettra le jeu de
441 caractères pour le texte de la redirection, et les navigateurs obsolètes
442 précités utiliseront correctement celui de la page de destination.</p>
444 <note type="warning">
445 <title>Note concernant la sécurité</title>
447 <p>L'envoi de pages d'erreur sans spécifier un jeu de caractères peut
448 conduire à des attaques de type "cross-site-scripting" pour les
449 navigateurs qui ne respectent pas la spécification HTTP/1.1 (MSIE) et
450 tentent de déduire le jeu de caractères à partir du contenu. De tels
451 navigateurs peuvent être facilement trompés et utiliser le jeu de
452 caractères UTF-7 ; les contenus des données en entrée de type UTF-7
453 (comme les URI de requête) ne seront alors plus protégés par les
454 mécanismes d'échappement usuels conçus pour prévenir les attaques
455 de type "cross-site-scripting".</p>
460 <section id="proxy"><title>force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked,
461 proxy-sendcl, proxy-chain-auth, proxy-interim-response, proxy-initial-not-pooled</title>
463 <p>Ces directives modifient le comportement protocolaire du module
464 <module>mod_proxy</module>. Voir la documentation sur
465 <module>mod_proxy</module> et <module>mod_proxy_http</module> pour plus de détails.</p>
470 <section id="examples">
471 <title>Exemples</title>
473 <section id="fixheader">
474 <title>Transmission du contenu d'en-têtes non valides aux scripts
477 <p>Avec la version 2.4, Apache est plus strict avec la conversion
478 des en-têtes HTTP en variables d'environnement dans
479 <module>mod_cgi</module> et d'autres modules : dans les versions
480 précédentes, tout caractère invalide dans les noms d'en-têtes
481 était tout simplement remplacé par un caractère '_', ce qui
482 pouvait exposer à des attaques de type cross-site-scripting via
483 injection d'en-têtes (voir <a
484 href="http://events.ccc.de/congress/2007/Fahrplan/events/2212.en.html">Bogues
485 du Web inhabituelles</a>, planche 19/20).</p>
487 <p>Si vous devez supporter un client qui envoie des en-têtes non
488 conformes et si ceux-ci ne peuvent pas être corrigés, il existe
489 une solution de contournement simple mettant en jeu les modules
490 <module>mod_setenvif</module> et <module>mod_headers</module>,
491 et permettant de prendre en compte ces en-têtes :</p>
493 <highlight language="config">
494 # L'exemple suivant montre comment prendre en compte un en-tête<br />
495 # Accept_Encoding non conforme envoyé par un client.
497 SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1
498 RequestHeader set Accept-Encoding %{fix_accept_encoding}e env=fix_accept_encoding
503 <section id="misbehaving">
504 <title>Modification du comportement protocolaire face à des clients
505 réagissant de manière non conforme</title>
507 <p>Les versions antérieures recommandaient l'ajout de ces lignes dans
508 httpd.conf pour tenir compte de problèmes connus avec certains clients.
509 Comme les clients concernés sont maintenant très peu utilisés, cet
510 ajout n'est pratiquement plus nécessaire.</p>
511 <highlight language="config">
513 # The following directives modify normal HTTP response behavior.
514 # The first directive disables keepalive for Netscape 2.x and browsers that
515 # spoof it. There are known problems with these browser implementations.
516 # The second directive is for Microsoft Internet Explorer 4.0b2
517 # which has a broken HTTP/1.1 implementation and does not properly
518 # support keepalive when it is used on 301 or 302 (redirect) responses.
520 BrowserMatch "Mozilla/2" nokeepalive
521 BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
524 # The following directive disables HTTP/1.1 responses to browsers which
525 # are in violation of the HTTP/1.0 spec by not being able to grok a
526 # basic 1.1 response.
528 BrowserMatch "RealPlayer 4\.0" force-response-1.0
529 BrowserMatch "Java/1\.0" force-response-1.0
530 BrowserMatch "JDK/1\.0" force-response-1.0
534 <section id="no-img-log">
535 <title>Ne pas tracer les requêtes pour des images dans le fichier de
536 trace des accès</title>
538 <p>Dans cet exemple, les requêtes pour des images n'apparaissent pas
539 dans le fichier de trace des accès. Il peut être facilement adapté pour
540 empêcher le traçage de répertoires particuliers, ou de requêtes
541 en provenance de certains hôtes.</p>
542 <highlight language="config">
543 SetEnvIf Request_URI \.gif image-request
544 SetEnvIf Request_URI \.jpg image-request
545 SetEnvIf Request_URI \.png image-request
546 CustomLog logs/access_log common env=!image-request
550 <section id="image-theft">
551 <title>Prévention du "Vol d'image"</title>
553 <p>Cet exemple montre comment empêcher les utilisateurs ne faisant pas
554 partie de votre serveur d'utiliser des images de votre serveur comme
555 images en ligne dans leurs pages. Cette configuration n'est pas
556 recommandée, mais elle peut fonctionner dans des circonstances bien
557 définies. Nous supposons que toutes vos images sont enregistrées dans
558 un répertoire nommé <code>/web/images</code>.</p>
559 <highlight language="config">
560 SetEnvIf Referer "^http://www\.example\.com/" local_referal
561 # Autorise les navigateurs qui n'envoient aucune information de Referer
562 SetEnvIf Referer "^$" local_referal
563 <Directory "/web/images">
564 Require env local_referal
568 <p>Pour plus d'informations sur cette technique, voir le tutoriel sur
570 "<a href="http://www.serverwatch.com/tutorials/article.php/1132731"
571 >Keeping Your Images from Adorning Other Sites</a>".</p>
projects / apache / blob