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: 1776624 -->
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|Optional|Off</syntax>
259 <contextlist><context>server config</context><context>virtual host</context>
263 <p>La directive <directive>RemoteIPProxyProtocol</directive> permet
264 d'activer ou de désactiver la prise en compte et la gestion de l'en-tête de
265 connexion du protocole PROXY. Si elle est définie à <code>On</code>, la
266 demande du client <em>doit</em> envoyer l'en-tête approprié pour chaque
267 nouvelle connexion, sinon cette dernière sera fermée. Si elle est définie à
268 <code>Optional</code>, la demande du client <em>peut</em> envoyer l'en-tête
269 approprié, mais ce n'est pas obligatoire.</p>
271 <p>Bien que cette directive peut être définie au niveau de n'importe quel
272 serveur virtuel, il est important de garder à l'esprit que, étant donné que
273 le protocole PROXY est basé sur la connexion et agnostique quant au
274 protocle, son activation/désactivation est basée sur le couple adresse
275 IP/port. Cela signifie que si plusieurs serveurs virtuels à base de nom sont
276 configurés avec le même couple adresse IP/port, et si vous activez le
277 protocole PROXY pour l'un d'entre eux, il le sera aussi pour tous les autres
278 (avec le même couple adresse IP/port). Cela signifie aussi que si vous
279 tentez d'activer le protocole PROXY pour un serveur virtuel et de le
280 désactiver pour un autre, cela ne marchera pas ; dans ce dernier cas, la
281 dernière directive l'emporte sur les autres et une notification sera
282 enregistrée dans le journal pour indiquer les réglages qui ont été annulés.</p>
284 <note type="hint">Lorsque plusieurs serveurs virtuels avec le même couple
285 adresse IP/port sont configurés avec une combinaison de drapeaux
286 <code>On</code> et <code>Optional</code>, les connexions ne seront pas
287 fermées si l'en-tête approprié n'est pas envoyé. L'activation interviendra
288 alors après la lecture de la requête si bien que les serveurs virtuels
289 configurés avec le drapeau <code>On</code> renverront une erreur 400 Bad
290 Request. Les serveurs virtuels configurés avec le drapeau
291 <code>Optional</code> quant à eux continueront de fonctionner de manière
292 habituelle mais sans remplacer les informations IP du client.</note>
294 <highlight language="config">
296 <VirtualHost *:80>
297 ServerName www.example.com
298 RemoteIPProxyProtocol Optional
300 #Les requêtes pour ce serveur virtuel ne doivent pas obligatoirement
301 #contenir d'en-tête du protocole PROXY
304 <VirtualHost *:80>
305 ServerName www.example.com
306 RemoteIPProxyProtocol On
308 #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
309 #protocole PROXY. Si ce n'est pas le cas, une erreur 400 sera renvoyée
313 <VirtualHost *:8080>
314 ServerName www.example.com
315 RemoteIPProxyProtocol On
317 #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
318 #protocole PROXY. Si ce n'est pas le cas, la connexion sera fermée
325 <name>RemoteIPTrustedProxy</name>
326 <description>Restreint les adresses IP clients dignes de
327 confiance pour présenter la valeur RemoteIPHeader</description>
328 <syntax>RemoteIPTrustedProxy
329 <var>ip-mandataire</var>|<var>ip-mandataire/sous-réseau</var>|<var>nom-hôte</var> ...</syntax>
330 <contextlist><context>server config</context><context>virtual host</context></contextlist>
333 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> permet
334 de définir quelles adresses IP (ou blocs d'adresses) seront
335 considérées comme de confiance pour présenter une valeur RemoteIPHeader
336 valide de l'adresse IP du client.</p>
338 <p>A la différence de la directive
339 <directive module="mod_remoteip">RemoteIPInternalProxy</directive>, toutes les adresses IP
340 intranet ou privées indiquées par de tels mandataires, y compris les
341 blocs d'adresses 10/8, 172.16/12, 192.168/16, 169.254/16 et 127/8
342 (ou située en dehors du bloc IPv6 public 2000::/3), ne sont pas
343 dignes de confiance en tant qu'adresses IP clientes, et se situent
344 à gauche dans le contenu de l'en-tête
345 <directive module="mod_remoteip">RemoteIPHeader</directive>.</p>
347 <note type="warning">Par défaut, <module>mod_remoteip</module>
348 considérera comme de confiance tout hôte présentant une adresse non
349 interne dans l'en-tête <directive
350 module="mod_remoteip">RemoteIPHeader</directive>.
353 <example><title>Exemple d'adresse de confiance (répartiteur de
355 <highlight language="config">
356 RemoteIPHeader X-Forwarded-For
357 RemoteIPTrustedProxy 10.0.2.16/28
358 RemoteIPTrustedProxy proxy.example.com
365 <name>RemoteIPTrustedProxyList</name>
366 <description>Restreint les adresses IP clients dignes de
367 confiance pour présenter la valeur RemoteIPHeader</description>
368 <syntax>RemoteIPTrustedProxyList <var>nom-fichier</var></syntax>
369 <contextlist><context>server config</context><context>virtual host</context></contextlist>
372 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxyList</directive>
373 permet de spécifier un fichier parcouru au démarrage du serveur pour
374 construire une liste d'adresses (ou blocs d'adresses), auxquelles
375 on peut faire confiance pour présenter une valeur RemoteIPHeader
376 valide de l'adresse IP du client.</p>
378 <p>Le caractère '<code>#</code>' indique une ligne de commentaires,
379 sinon, toutes les lignes séparées par un caractère nouvelle ligne ou
380 tous les éléments d'une ligne séparés par un espace sont traités de
381 la même façon qu'avec la directive
382 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>.</p>
384 <example><title>Exemple d'adresse de confiance (répartiteur de
386 <highlight language="config">
387 RemoteIPHeader X-Forwarded-For
388 RemoteIPTrustedProxyList conf/trusted-proxies.lst
392 <example><title>conf/mandataires-de-confiance.lst contents</title>
393 # Mandataires externes identifiés<br/>
394 192.0.2.16/28 #groupe wap phone de mandataires<br/>
395 proxy.isp.example.com #un FAI bien connu