1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1794142 -->
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_remoteip.xml.meta">
27 <name>mod_remoteip</name>
28 <description>Remplace l'adresse IP du client
29 pour la requête par l'adresse IP présentée par un mandataire ou un
30 répartiteur de charge via les en-têtes de la requête.
34 <sourcefile>mod_remoteip.c</sourcefile>
35 <identifier>remoteip_module</identifier>
38 <p>Ce module permet de traiter le client qui a initié la
39 requête en tant que client original du point de vue de httpd à
40 des fins d'autorisation et de connexion, même si ce client se
41 trouve derrière un répartiteur de charge, un serveur frontal, ou un
42 serveur mandataire.</p>
44 <p>Le module remplace l'adresse IP du client
45 pour la connexion par l'adresse IP indiquée dans
46 l'en-tête de requête configuré via la directive
47 <directive module="mod_remoteip">RemoteIPHeader</directive>.</p>
49 <p>En outre, ce module implémente la partie serveur du <a
50 href="http://blog.haproxy.com/haproxy/proxy-protocol/">protocole PROXY</a>
51 de HAProxy lorsqu'on utilise la directive <directive
52 module="mod_remoteip">RemoteIPProxyProtocol</directive>.</p>
54 <p>Une fois sa valeur modifiée comme indiqué, cette adresse IP client est
55 utilisée pour la fonctionnalité <directive
56 module="mod_authz_host" name="Require">Require ip</directive> de
57 <module>mod_authz_host</module> ; elle est aussi affichée par
58 <module>mod_status</module>, et enregistrée via les chaînes de formatage
59 <code>%a</code> des modules <module>mod_log_config</module> et <module>core</module>.
60 L'adresse IP client sous-jacente de la connexion est enregistrée via la chaîne de
61 formatage <code>%{c}a</code>.
64 <note type="warning">Il est essentiel de n'activer cette
65 fonctionnalité que pour les requêtes en provenance des serveurs
66 intermédiaires (mandataires, etc...) auxquels le serveur peut faire
67 confiance, car il est trivial pour le client distant d'usurper
68 l'identité d'un autre client.</note>
71 <seealso><module>mod_authz_host</module></seealso>
72 <seealso><module>mod_status</module></seealso>
73 <seealso><module>mod_log_config</module></seealso>
74 <seealso><a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol Spec</a></seealso>
76 <section id="processing"><title>Traitement des adresses distantes</title>
78 <p>Par défaut, Apache identifie le client via la valeur client_ip de la
79 connexion, et de cette valeur découlent les valeurs remote_host et
80 remote_logname de la connexion. Ces champs jouent un rôle
81 dans l'authentification, l'autorisation et la journalisation, ainsi que
82 dans d'autres traitements effectués par d'autres modules
85 <p>mod_remoteip remplace l'adresse IP client de la connexion par l'adresse IP client
86 indiquée par exemple par un mandataire ou un répartiteur de charge
87 pour toute la durée de la requête. Un répartiteur de charge pourra ainsi
88 établir une connexion keepalive de longue durée avec le serveur, chaque
89 requête conservant alors l'adresse IP client correcte bien que l'adresse IP
90 client sous-jacente du répartiteur de charge reste inchangée.</p>
92 <p>Lorsque la valeur de l'en-tête comporte plusieurs adresses IP
93 client séparées par des virgules, celles-ci sont traitées de la
94 droite vers la gauche. Le traitement s'arrête lorsque l'adresse IP
95 client courante n'est pas digne de confiance pour présenter
96 l'adresse IP précédente. Le champ d'en-tête est alors mis à jour de
97 façon à ne contenir que cette liste d'adresses non confirmées, ou
98 bien, si toutes les adresses IP sont dignes de confiance, cet
99 en-tête est tout bonnement supprimé de la requête.</p>
101 <p>Lors du remplacement de l'adresse IP client, le module stocke
102 la liste des hôtes intermédiaires dans un mémo
103 remoteip-proxy-ip-list, que l'on peut faire enregistrer par
104 <module>mod_log_config</module> en utilisant le symbole de format
105 <code>%{remoteip-proxy-ip-list}n</code>. Si l'administrateur doit
106 stocker ceci dans un en-tête additionnel, la même valeur peut aussi
107 être enregistrée sous la forme d'un en-tête en utilisant la
108 directive <directive module="mod_remoteip">RemoteIPProxiesHeader</directive>.</p>
110 <note><title>Adresses IPv4 converties au format IPv6</title>
111 Avec httpd, d'une manière générale, toute adresse IPv4 convertie au
112 format IPv6 est enregistrée sous sa forme IPv4.</note>
114 <note><title>Adresses internes (privées)</title>
115 Tous les blocs d'adresses internes 10/8, 172.16/12, 192.168/16,
116 169.254/16 and 127/8 (ainsi que les adresses IPv6 en dehors du bloc
117 public 2000::/3 block) ne sont évaluées par mod_remoteip que lorsque
118 des mandataires internes (intranet)
119 <directive module="mod_remoteip">RemoteIPInternalProxy</directive> sont enregistrés.</note>
124 <name>RemoteIPHeader</name>
125 <description>Définit le champ d'en-tête qui contiendra les adresses IP
126 du client</description>
127 <syntax>RemoteIPHeader <var>en-tête</var></syntax>
128 <contextlist><context>server config</context><context>virtual host</context></contextlist>
131 <p>La directive <directive module="mod_remoteip">RemoteIPHeader</directive> indique à
132 <module>mod_remoteip</module> de traiter la valeur de
133 l'<var>en-tête</var> spécifié comme l'adresse IP du client, ou comme
134 une liste d'adresses IP clients intermédiaires, en fonction de la
135 configuration des directives
136 <directive module="mod_remoteip">RemoteIPInternalProxy</directive> et
137 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>.</p>
139 <note type="warning">Si ces deux dernières
140 directives ne sont pas utilisées, <module>mod_remoteip</module>
141 traitera tout hôte présentant une adresse non interne
142 dans l'en-tête <directive
143 module="mod_remoteip">RemoteIPHeader</directive> comme hôte de
146 <example><title>Exemple à usage interne (répartiteur de
148 <highlight language="config">
149 RemoteIPHeader X-Client-IP
153 <example><title>Exemple dans le cas d'un mandataire</title>
154 <highlight language="config">
155 RemoteIPHeader X-Forwarded-For
162 <name>RemoteIPInternalProxy</name>
163 <description>Déclare les adresses IP intranet clients comme dignes de
164 confiance pour présenter la valeur RemoteIPHeader</description>
165 <syntax>RemoteIPInternalProxy
166 <var>ip-mandataire</var>|<var>ip-mandataire/sous-réseau</var>|<var>nom-hôte</var> ...</syntax>
167 <contextlist><context>server config</context><context>virtual host</context></contextlist>
170 <p>La directive <directive module="mod_remoteip">RemoteIPInternalProxy</directive> permet
171 d'ajouter une ou plusieurs adresses (ou blocs d'adresses) auxquelles
172 on peut faire confiance pour présenter une valeur RemoteIPHeader
173 valide de l'adresse IP du client. A la différence de la directive
174 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>, toute adresse IP
175 présentée dans cet en-tête, y comprises les adresses intranet
176 privées, sont considérées comme dignes de confiance lorsqu'elles
177 sont indiquées par ces mandataires.</p>
179 <example><title>Exemple à usage interne (répartiteur de
181 <highlight language="config">
182 RemoteIPHeader X-Client-IP
183 RemoteIPInternalProxy 10.0.2.0/24
184 RemoteIPInternalProxy gateway.localdomain
191 <name>RemoteIPInternalProxyList</name>
192 <description>Déclare les adresses IP intranet clients comme dignes de
193 confiance pour présenter la valeur RemoteIPHeader</description>
194 <syntax>RemoteIPInternalProxyList <var>nom-fichier</var></syntax>
195 <contextlist><context>server config</context><context>virtual host</context></contextlist>
198 <p>La directive <directive module="mod_remoteip">RemoteIPInternalProxyList</directive>
199 permet de spécifier un fichier parcouru au démarrage du serveur pour
200 construire une liste d'adresses (ou blocs d'adresses), auxquelles
201 on peut faire confiance pour présenter une valeur RemoteIPHeader
202 valide de l'adresse IP du client.</p>
204 <p>Le caractère '<code>#</code>' indique une ligne de commentaires,
205 sinon, toutes les lignes séparées par un caractère <code>nouvelle
207 tous les éléments d'une ligne séparés par un espace sont traités de
208 la même façon qu'avec la directive
209 <directive module="mod_remoteip">RemoteIPInternalProxy</directive>.</p>
211 <example><title>Exemple à usage interne (répartiteur de
213 <highlight language="config">
214 RemoteIPHeader X-Client-IP
215 RemoteIPInternalProxyList conf/trusted-proxies.lst
219 <example><title>contenu de conf/mandataires-de-confiance.lst</title>
221 # Nos mandataires internes de confiance
222 10.0.2.0/24 # Tout le monde dans le groupe de test
223 passerelle.domaine-local # Le frontal répartiteur de charge
230 <name>RemoteIPProxiesHeader</name>
231 <description>Déclare le champ d'en-tête qui contiendra toutes les
232 adresses IP intermédiaires</description>
233 <syntax>RemoteIPProxiesHeader <var>Nom_en-tête</var></syntax>
234 <contextlist><context>server config</context><context>virtual host</context></contextlist>
237 <p>La directive <directive module="mod_remoteip">RemoteIPProxiesHeader</directive> permet
238 de spécifier l'en-tête dans lequel <module>mod_remoteip</module> va
239 collecter une liste de toutes les adresses IP clients intermédiaires
240 auxquelles on pourra faire confiance pour résoudre l'adresse IP
241 client de la requête. Notez que les adresses intermédiaires
242 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> sont enregistrées dans
243 cet en-tête, alors que toute adresse intermédiaire
244 <directive module="mod_remoteip">RemoteIPInternalProxy</directive> est omise.</p>
246 <example><title>Exemple</title>
247 <highlight language="config">
248 RemoteIPHeader X-Forwarded-For
249 RemoteIPProxiesHeader X-Forwarded-By
256 <name>RemoteIPProxyProtocol</name>
257 <description>Active ou désactive la gestion du protocole PROXY</description>
258 <syntax>RemoteIPProxyProtocol On|Off</syntax>
259 <contextlist><context>server config</context><context>virtual host</context>
261 <compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache</compatibility>
264 <p>La directive <directive>RemoteIPProxyProtocol</directive> permet
265 d'activer ou de désactiver la prise en compte et la gestion de l'en-tête de
266 connexion du protocole PROXY. Si elle est définie à <code>On</code>, la
267 demande du client <em>doit</em> envoyer l'en-tête approprié pour chaque
268 nouvelle connexion, sinon cette dernière sera fermée à moins qu'il ne fasse
269 partie de la liste, définie via la directive <directive
270 module="mod_remoteip">RemoteIPProxyProtocolDisableHosts</directive>, des
271 hôtes pour lesquels le protocole PROXY est désactivé.</p>
273 <p>Bien que cette directive peut être définie au niveau de n'importe quel
274 serveur virtuel, il est important de garder à l'esprit que, étant donné que
275 le protocole PROXY est basé sur la connexion et agnostique quant au
276 protocle, son activation/désactivation est basée sur le couple adresse
277 IP/port. Cela signifie que si plusieurs serveurs virtuels à base de nom sont
278 configurés avec le même couple adresse IP/port, et si vous activez le
279 protocole PROXY pour l'un d'entre eux, il le sera aussi pour tous les autres
280 (avec le même couple adresse IP/port). Cela signifie aussi que si vous
281 tentez d'activer le protocole PROXY pour un serveur virtuel et de le
282 désactiver pour un autre, cela ne marchera pas ; dans ce dernier cas, la
283 dernière directive l'emporte sur les autres et une notification sera
284 enregistrée dans le journal pour indiquer les réglages qui ont été annulés.</p>
286 <highlight language="config">
288 <VirtualHost *:80>
289 ServerName www.example.com
290 RemoteIPProxyProtocol On
292 #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
293 #protocole PROXY. Si ce n'est pas le cas, la connexion sera fermée.
297 <VirtualHost *:8080>
298 ServerName www.example.com
299 RemoteIPProxyProtocol On
300 RemoteIPProxyProtocolExceptions 127.0.0.1 10.0.0.0/8
302 #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
303 #protocole PROXY. Si ce n'est pas le cas, la connexion sera fermée à moins
304 que sa source ne soit localhost ou la gamme d'adresses RFC1918 10.x.x.x
311 <name>RemoteIPProxyProtocolExceptions</name>
312 <description>Désactive la prise en compte de l'en-tête PROXY pour certains hôtes
313 ou réseaux</description>
314 <syntax>RemoteIPProxyProtocolExceptions host|range [host|range] [host|range]</syntax>
315 <contextlist><context>server config</context><context>virtual host</context>
317 <compatibility>RemoteIPProxyProtocolExceptions est disponible à partir de la
318 version 2.4.26 du serveur HTTP Apache</compatibility>
321 <p>La directive <directive>RemoteIPProxyProtocol</directive> permet de
322 contrôler la prise en compte de l'en-tête de connexion du protocole PROXY.
323 Il est parfois souhaitable d'exiger pour certains clients la
324 présence de l'en-tête PROXY, mais aussi de permettre aux autres clients de
325 se connecter sans ce dernier. Cette directive permet à l'administrateur du
326 serveur d'autoriser cette possibilité à un hôte isolé ou à une gamme d'hôtes
332 <name>RemoteIPTrustedProxy</name>
333 <description>Restreint les adresses IP clients dignes de
334 confiance pour présenter la valeur RemoteIPHeader</description>
335 <syntax>RemoteIPTrustedProxy
336 <var>ip-mandataire</var>|<var>ip-mandataire/sous-réseau</var>|<var>nom-hôte</var> ...</syntax>
337 <contextlist><context>server config</context><context>virtual host</context></contextlist>
340 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> permet
341 de définir quelles adresses IP (ou blocs d'adresses) seront
342 considérées comme de confiance pour présenter une valeur RemoteIPHeader
343 valide de l'adresse IP du client.</p>
345 <p>A la différence de la directive
346 <directive module="mod_remoteip">RemoteIPInternalProxy</directive>, toutes les adresses IP
347 intranet ou privées indiquées par de tels mandataires, y compris les
348 blocs d'adresses 10/8, 172.16/12, 192.168/16, 169.254/16 et 127/8
349 (ou située en dehors du bloc IPv6 public 2000::/3), ne sont pas
350 dignes de confiance en tant qu'adresses IP clientes, et se situent
351 à gauche dans le contenu de l'en-tête
352 <directive module="mod_remoteip">RemoteIPHeader</directive>.</p>
354 <note type="warning">Par défaut, <module>mod_remoteip</module>
355 considérera comme de confiance tout hôte présentant une adresse non
356 interne dans l'en-tête <directive
357 module="mod_remoteip">RemoteIPHeader</directive>.
360 <example><title>Exemple d'adresse de confiance (répartiteur de
362 <highlight language="config">
363 RemoteIPHeader X-Forwarded-For
364 RemoteIPTrustedProxy 10.0.2.16/28
365 RemoteIPTrustedProxy proxy.example.com
372 <name>RemoteIPTrustedProxyList</name>
373 <description>Restreint les adresses IP clients dignes de
374 confiance pour présenter la valeur RemoteIPHeader</description>
375 <syntax>RemoteIPTrustedProxyList <var>nom-fichier</var></syntax>
376 <contextlist><context>server config</context><context>virtual host</context></contextlist>
379 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxyList</directive>
380 permet de spécifier un fichier parcouru au démarrage du serveur pour
381 construire une liste d'adresses (ou blocs d'adresses), auxquelles
382 on peut faire confiance pour présenter une valeur RemoteIPHeader
383 valide de l'adresse IP du client.</p>
385 <p>Le caractère '<code>#</code>' indique une ligne de commentaires,
386 sinon, toutes les lignes séparées par un caractère nouvelle ligne ou
387 tous les éléments d'une ligne séparés par un espace sont traités de
388 la même façon qu'avec la directive
389 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>.</p>
391 <example><title>Exemple d'adresse de confiance (répartiteur de
393 <highlight language="config">
394 RemoteIPHeader X-Forwarded-For
395 RemoteIPTrustedProxyList conf/trusted-proxies.lst
399 <example><title>conf/mandataires-de-confiance.lst contents</title>
400 # Mandataires externes identifiés<br/>
401 192.0.2.16/28 #groupe wap phone de mandataires<br/>
402 proxy.isp.example.com #un FAI bien connu