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 : 810187 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
7 <!-- $LastChangedRevision: 2009061101 $ -->
10 Licensed to the Apache Software Foundation (ASF) under one or more
11 contributor license agreements. See the NOTICE file distributed with
12 this work for additional information regarding copyright ownership.
13 The ASF licenses this file to You under the Apache License, Version 2.0
14 (the "License"); you may not use this file except in compliance with
15 the License. You may obtain a copy of the License at
17 http://www.apache.org/licenses/LICENSE-2.0
19 Unless required by applicable law or agreed to in writing, software
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
26 <manualpage metafile="env.xml.meta">
28 <title>Apache et les variables d'environnement</title>
31 <p>Deux types de variables d'environnement affectent le serveur
34 <p>Le premier type correspond aux variables d'environnement
35 contrôlées par le système d'exploitation sous-jacent et définies
36 avant le démarrage du serveur. Leurs valeurs peuvent être utilisées
37 directement dans les fichiers de configuration, et peuvent
38 éventuellement être transmises aux scripts CGI et SSI via la
39 directive PassEnv.</p>
41 <p>Le second type correspond aux variables nommées appelées aussi
42 <em>variables d'environnement</em> dans lesquelles le serveur HTTP
43 Apache stocke des informations via un mécanisme spécial. Ces
44 informations peuvent servir à contrôler diverses opérations comme
45 l'enregistrement des traces ou le contrôle d'accès. On utilise aussi ces
46 variables dans le mécanisme de communication avec les programmes externes
47 comme les scripts CGI. Ce document présente différentes méthodes pour
48 manipuler et utiliser ces variables.</p>
50 <p>Bien que ces variables soient référencées comme <em>variables
51 d'environnement</em>, il ne faut pas les confondre avec les variables
52 d'environnement contrôlées par le système d'exploitation sous-jacent.
53 En fait, ces variables sont stockées et manipulées dans une structure
54 interne à Apache. Elles ne deviennent de véritables variables
55 d'environnement du système d'exploitation que lorsqu'elles sont mises à la
56 disposition de scripts CGI et de scripts inclus côté serveur (SSI). Si vous
57 souhaitez manipuler l'environnement du système d'exploitation sous lequel
58 le serveur s'exécute, vous devez utiliser les mécanismes standards de
59 manipulation de l'environnement fournis par l'interpréteur de commandes
60 (shell) de votre système d'exploitation.</p>
63 <section id="setting">
64 <title>Définition des variables d'environnement</title>
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.w3.org/CGI/">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>La directive <directive
155 module="mod_env">SetEnv</directive> s'exécute assez tard au
156 cours du traitement de la requête, ce qui signifie que des
157 directives telles que <directive
158 module="mod_setenvif">SetEnvIf</directive> et <directive
159 module="mod_rewrite">RewriteCond</directive> ne verront pas
160 les variables qu'elle aura définies.</li>
165 <title>Utilisation des variables d'environnement</title>
169 <module>mod_authz_host</module>
170 <module>mod_cgi</module>
171 <module>mod_ext_filter</module>
172 <module>mod_headers</module>
173 <module>mod_include</module>
174 <module>mod_log_config</module>
175 <module>mod_rewrite</module>
178 <directive module="mod_authz_host">Allow</directive>
179 <directive module="mod_log_config">CustomLog</directive>
180 <directive module="mod_authz_host">Deny</directive>
181 <directive module="mod_ext_filter">ExtFilterDefine</directive>
182 <directive module="mod_headers">Header</directive>
183 <directive module="mod_log_config">LogFormat</directive>
184 <directive module="mod_rewrite">RewriteCond</directive>
185 <directive module="mod_rewrite">RewriteRule</directive>
189 <section id="cgi-scripts">
190 <title>Scripts CGI</title>
192 <p>La communication d'informations aux scripts CGI constitue une des
193 principales utilisations des variables d'environnement. Comme indiqué
194 plus haut, l'environnement transmis aux scripts CGI comprend des
195 méta-informations standards à propos de la requête, en plus des
196 variables définies dans la configuration d'Apache. Pour plus de
197 détails, se référer au
198 <a href="howto/cgi.html">tutoriel CGI</a>.</p>
201 <section id="ssi-pages">
202 <title>Pages SSI</title>
204 <p>Les documents inclus côté serveur (SSI) traités par le filtre
205 <code>INCLUDES</code> du module <module>mod_include</module>,
207 variables d'environnement à l'aide de l'élément <code>echo</code>,
208 et peuvent utiliser des variables d'environnement dans les éléments
209 de contrôle de flux pour rendre certaines parties d'une page
210 conditionnelles en fonction des caractéristiques de la requête.
211 Apache fournit aussi les variables d'environnement CGI standards
213 comme indiqué plus haut. Pour plus de détails, se référer au
214 <a href="howto/ssi.html">tutoriel SSI</a>.</p>
217 <section id="access-control">
218 <title>Contrôle d'accès</title>
220 <p>L'accès au serveur peut être contrôlé en fonction de la valeur de
221 variables d'environnement à l'aide des directives
222 <code>allow from env=</code> et <code>deny from env=</code>.
223 En association avec la directive
224 <directive module="mod_setenvif">SetEnvIf</directive>, ceci confère une
225 grande souplesse au contrôle d'accès au serveur en fonction des
226 caractéristiques du client. Par exemple, vous pouvez utiliser ces
227 directives pour interdire l'accès depuis un navigateur particulier
232 <section id="logging">
233 <title>Enregistrement conditionnel des traces</title>
235 <p>Les variables d'environnement peuvent être enregistrées dans le
236 fichier de log des accès à l'aide de l'option <code>%e</code> de la
237 directive <directive module="mod_log_config">LogFormat</directive>.
238 En outre, la décision de tracer ou non les requêtes peut être prise
239 en fonction de l'état de variables d'environnement en utilisant la
240 forme conditionnelle de la directive
241 <directive module="mod_log_config">CustomLog</directive>. En
242 association avec la directive <directive module="mod_setenvif"
243 >SetEnvIf</directive>, ceci confère une grande souplesse au contrôle
244 du traçage des requêtes. Par exemple, vous pouvez choisir de ne pas
245 tracer les requêtes pour des noms de fichiers se terminant par
246 <code>gif</code>, ou encore de ne tracer que les requêtes des clients
247 n'appartenant pas à votre sous-réseau.</p>
250 <section id="response-headers">
251 <title>En-têtes de réponse conditionnels</title>
253 <p>La directive <directive module="mod_headers">Header</directive>
254 peut se baser sur la présence ou l'absence d'une variable
255 d'environnement pour décider si un certain en-tête HTTP sera placé
256 dans la réponse au client. Ceci permet, par exemple, de n'envoyer un
257 certain en-tête de réponse que si un en-tête correspondant est présent
258 dans la requête du client.</p>
262 <section id="external-filter">
263 <title>Activation de filtres externes</title>
265 <p>Les filtres externes configurés par le module
266 <module>mod_ext_filter</module> à l'aide de la directive <directive
267 module="mod_ext_filter">ExtFilterDefine</directive> peuvent être
268 activés de manière conditionnelle en fonction d'une variable
269 d'environnement à l'aide des options
270 <code>disableenv=</code> et <code>enableenv=</code>.</p>
273 <section id="url-rewriting">
274 <title>Réécriture d'URL</title>
276 <p>La forme <code>%{ENV:<em>variable</em>}</code> de
277 <em>TestString</em> dans la
278 directive <directive module="mod_rewrite">RewriteCond</directive>
279 permet au moteur de réécriture du module
280 <module>mod_rewrite</module> de prendre des
281 décisions conditionnées par des variables d'environnement.
282 Notez que les variables accessibles dans
283 <module>mod_rewrite</module> sans le préfixe
284 <code>ENV:</code> ne sont pas de véritables variables
285 d'environnement. Ce sont plutôt des variables spécifiques à
286 <module>mod_rewrite</module>
287 qui ne sont pas accessibles pour les autres modules.</p>
291 <section id="special">
292 <title>Variables d'environnement à usage spécial</title>
294 <p>Des problèmes d'interopérabilité ont conduit à l'introduction de
295 mécanismes permettant de modifier le comportement d'Apache lorsqu'il
296 dialogue avec certains clients. Afin de rendre ces mécanismes aussi
297 souples que possible, ils sont invoqués en définissant des variables
298 d'environnement, en général à l'aide de la directive
299 <directive module="mod_setenvif">BrowserMatch</directive>, bien que les
300 directives <directive module="mod_env">SetEnv</directive> et
301 <directive module="mod_env">PassEnv</directive> puissent aussi être
302 utilisées, par exemple.</p>
304 <section id="downgrade">
305 <title>downgrade-1.0</title>
307 <p>Ceci force le traitement d'une requête comme une requête HTTP/1.0
308 même si elle a été rédigée dans un langage plus récent.</p>
311 <section id="force-gzip">
312 <title>force-gzip</title>
313 <p>Si le filtre <code>DEFLATE</code> est activé, cette variable
314 d'environnement ignorera les réglages accept-encoding de votre
315 navigateur et enverra une sortie compressée inconditionnellement.</p>
317 <section id="force-no-vary">
318 <title>force-no-vary</title>
320 <p>Cette variable entraîne la suppression de tout champ
321 <code>Vary</code> des en-têtes de la réponse avant que cette dernière
322 soit renvoyée au client. Certains clients n'interprètent pas ce champ
323 correctement, et la définition de cette variable permet de contourner
324 ce problème, mais implique aussi la définition de
325 <strong>force-response-1.0</strong>.</p>
328 <section id="force-response">
329 <title>force-response-1.0</title>
331 <p>Cette variable force une réponse en langage HTTP/1.0 aux clients
332 qui envoient des requêtes dans le même langage. Elle fut implémentée à
333 l'origine suite à des problèmes avec les mandataires d'AOL. Certains
334 clients en langage HTTP/1.0 ne réagissent pas correctement face à une
335 réponse en langage HTTP/1.1, et cette variable peut être utilisée pour
336 assurer l'interopérabilité avec eux.</p>
340 <section id="gzip-only-text-html">
341 <title>gzip-only-text/html</title>
343 <p>Positionnée à "1", cette variable désactive le filtre en sortie
344 <code>DEFLATE</code> fourni par le module <module>mod_deflate</module> pour les
345 types de contenu autres que <code>text/html</code>. Si vous préférez
346 utiliser des fichiers compressés statiquement,
347 <module>mod_negotiation</module> évalue aussi la variable (non
348 seulement pour gzip, mais aussi pour tous les encodages autres que
352 <section id="no-gzip"><title>no-gzip</title>
354 <p>Quand cette variable est définie, le filtre <code>DEFLATE</code> du
355 module <module>mod_deflate</module> est désactivé, et
356 <module>mod_negotiation</module> refusera de délivrer des ressources
361 <section id="no-cache"><title>no-cache</title>
362 <p><em>Disponible dans les versions 2.2.12 et ultérieures d'Apache</em></p>
364 <p>Lorsque cette variable est définie,
365 <module>mod_cache</module> ne sauvegardera pas de réponse
366 susceptible d'être mise en cache. Cette variable d'environnement
367 n'a aucune incidence sur le fait qu'une réponse déjà enregistrée
368 dans la cache soit utilisée ou non pour la requête courante.</p>
372 <section id="nokeepalive">
373 <title>nokeepalive</title>
375 <p>Quand cette variable est définie, la directive
376 <directive module="core">KeepAlive</directive> est désactivée.</p>
380 <section id="prefer-language"><title>prefer-language</title>
382 <p>Cette variable modifie le comportement du module
383 <module>mod_negotiation</module>. Si elle contient un symbole de
384 langage (tel que <code>en</code>, <code>ja</code>
385 ou <code>x-klingon</code>), <module>mod_negotiation</module> essaie de
386 délivrer une variante dans ce langage. S'il n'existe pas de telle
387 variante, le processus normal de
388 <a href="content-negotiation.html">négociation</a> s'applique.</p>
392 <section id="redirect-carefully">
393 <title>redirect-carefully</title>
395 <p>Cette variable force le serveur à être plus prudent lors de l'envoi
396 d'une redirection au client. Elle est en général utilisée quand un
397 client présente un problème connu avec les redirections. Elle fut
398 implémentée à l'origine suite a un problème rencontré avec le logiciel
399 WebFolders de Microsoft qui ne gère pas correctement les redirections
400 vers des ressources de type répertoire via des méthodes DAV.</p>
404 <section id="suppress-error-charset">
405 <title>suppress-error-charset</title>
407 <p><em>Disponible dans les versions postérieures à 2.0.54</em></p>
409 <p>Quand Apache génère une redirection en réponse à une requête client,
410 la réponse inclut un texte destiné à être affiché au cas où le client ne
411 suivrait pas, ou ne pourrait pas suivre automatiquement la redirection.
412 Habituellement, Apache marque ce texte en accord avec le jeu de caractères
413 qu'il utilise, à savoir ISO-8859-1.</p>
414 <p> Cependant, si la redirection fait référence à une page qui utilise un
415 jeu de caractères différent, certaines versions de navigateurs obsolètes
416 essaieront d'utiliser le jeu de caractères du texte de la redirection
417 plutôt que celui de la page réelle.
418 Ceci peut entraîner, par exemple, un rendu incorrect du Grec.</p>
419 <p>Si cette variable d'environnement est définie, Apache omettra le jeu de
420 caractères pour le texte de la redirection, et les navigateurs obsolètes
421 précités utiliseront correctement celui de la page de destination.</p>
423 <note type="warning">
424 <title>Note concernant la sécurité</title>
426 <p>L'envoi de pages d'erreur sans spécifier un jeu de caractères peut
427 conduire à des attaques de type "cross-site-scripting" pour les
428 navigateurs qui ne respectent pas la spécification HTTP/1.1 (MSIE) et
429 tentent de déduire le jeu de caractères à partir du contenu. De tels
430 navigateurs peuvent être facilement trompés et utiliser le jeu de
431 caractères UTF-7 ; les contenus des données en entrée de type UTF-7
432 (comme les URI de requête) ne seront alors plus protégés par les
433 mécanismes d'échappement usuels conçus pour prévenir les attaques
434 de type "cross-site-scripting".</p>
439 <section id="proxy"><title>force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked,
440 proxy-sendcl, proxy-chain-auth, proxy-interim-response, proxy-initial-not-pooled</title>
442 <p>Ces directives modifient le comportement protocolaire du module
443 <module>mod_proxy</module>. Voir la documentation sur
444 <module>mod_proxy</module> et <module>mod_proxy_http</module> pour plus de détails.</p>
449 <section id="examples">
450 <title>Exemples</title>
452 <section id="misbehaving">
453 <title>Modification du comportement protocolaire face à des clients
454 réagissant de manière non conforme</title>
456 <p>Les versions antérieures recommandaient l'ajout de ces lignes dans
457 httpd.conf pour tenir compte de problèmes connus avec certains clients.
458 Comme les clients concernés sont maintenant très peu utilisés, cet
459 ajout n'est pratiquement plus nécessaire.</p>
462 # The following directives modify normal HTTP response behavior.
463 # The first directive disables keepalive for Netscape 2.x and browsers that
464 # spoof it. There are known problems with these browser implementations.
465 # The second directive is for Microsoft Internet Explorer 4.0b2
466 # which has a broken HTTP/1.1 implementation and does not properly
467 # support keepalive when it is used on 301 or 302 (redirect) responses.
469 BrowserMatch "Mozilla/2" nokeepalive
470 BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
473 # The following directive disables HTTP/1.1 responses to browsers which
474 # are in violation of the HTTP/1.0 spec by not being able to grok a
475 # basic 1.1 response.
477 BrowserMatch "RealPlayer 4\.0" force-response-1.0
478 BrowserMatch "Java/1\.0" force-response-1.0
479 BrowserMatch "JDK/1\.0" force-response-1.0</pre></example>
482 <section id="no-img-log">
483 <title>Ne pas tracer les requêtes pour des images dans le fichier de
484 trace des accès</title>
486 <p>Dans cet exemple, les requêtes pour des images n'apparaissent pas
487 dans le fichier de trace des accès. Il peut être facilement adapté pour
488 empêcher le traçage de répertoires particuliers, ou de requêtes
489 en provenance de certains hôtes.</p>
491 SetEnvIf Request_URI \.gif image-request<br />
492 SetEnvIf Request_URI \.jpg image-request<br />
493 SetEnvIf Request_URI \.png image-request<br />
494 CustomLog logs/access_log common env=!image-request
498 <section id="image-theft">
499 <title>Prévention du "Vol d'image"</title>
501 <p>Cet exemple montre comment empêcher les utilisateurs ne faisant pas
502 partie de votre serveur d'utiliser des images de votre serveur comme
503 images en ligne dans leurs pages. Cette configuration n'est pas
504 recommandée, mais elle peut fonctionner dans des circonstances bien
505 définies. Nous supposons que toutes vos images sont enregistrées dans
506 un répertoire nommé <code>/web/images</code>.</p>
508 SetEnvIf Referer "^http://www\.example\.com/" local_referal
509 # Allow browsers that do not send Referer info
510 SetEnvIf Referer "^$" local_referal
511 <Directory /web/images>
513 Order Deny,Allow<br />
515 Allow from env=local_referal
520 <p>Pour plus d'informations sur cette technique, voir le tutoriel sur
522 "<a href="http://www.serverwatch.com/tutorials/article.php/1132731"
523 >Keeping Your Images from Adorning Other Sites</a>".</p>
projects / apache / blob