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: 1789800:1789811 (outdated) -->
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 RemoteIPProxyProtocolDisableHosts 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>RemoteIPProxyProtocolDisableHosts</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>RemoteIPProxyProtocolDisableHosts host|range [host|range] [host|range]</syntax>
315 <contextlist><context>server config</context><context>virtual host</context>
317 <compatibility>RemoteIPProxyProtocolDisableHosts 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
327 au format CIDR. Elle est en général utilisée dans le cadre du monitoring du
328 trafic vers un serveur virtuel à destination du serveur situé derrière le
329 répartiteur de charge.</p>
334 <name>RemoteIPTrustedProxy</name>
335 <description>Restreint les adresses IP clients dignes de
336 confiance pour présenter la valeur RemoteIPHeader</description>
337 <syntax>RemoteIPTrustedProxy
338 <var>ip-mandataire</var>|<var>ip-mandataire/sous-réseau</var>|<var>nom-hôte</var> ...</syntax>
339 <contextlist><context>server config</context><context>virtual host</context></contextlist>
342 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> permet
343 de définir quelles adresses IP (ou blocs d'adresses) seront
344 considérées comme de confiance pour présenter une valeur RemoteIPHeader
345 valide de l'adresse IP du client.</p>
347 <p>A la différence de la directive
348 <directive module="mod_remoteip">RemoteIPInternalProxy</directive>, toutes les adresses IP
349 intranet ou privées indiquées par de tels mandataires, y compris les
350 blocs d'adresses 10/8, 172.16/12, 192.168/16, 169.254/16 et 127/8
351 (ou située en dehors du bloc IPv6 public 2000::/3), ne sont pas
352 dignes de confiance en tant qu'adresses IP clientes, et se situent
353 à gauche dans le contenu de l'en-tête
354 <directive module="mod_remoteip">RemoteIPHeader</directive>.</p>
356 <note type="warning">Par défaut, <module>mod_remoteip</module>
357 considérera comme de confiance tout hôte présentant une adresse non
358 interne dans l'en-tête <directive
359 module="mod_remoteip">RemoteIPHeader</directive>.
362 <example><title>Exemple d'adresse de confiance (répartiteur de
364 <highlight language="config">
365 RemoteIPHeader X-Forwarded-For
366 RemoteIPTrustedProxy 10.0.2.16/28
367 RemoteIPTrustedProxy proxy.example.com
374 <name>RemoteIPTrustedProxyList</name>
375 <description>Restreint les adresses IP clients dignes de
376 confiance pour présenter la valeur RemoteIPHeader</description>
377 <syntax>RemoteIPTrustedProxyList <var>nom-fichier</var></syntax>
378 <contextlist><context>server config</context><context>virtual host</context></contextlist>
381 <p>La directive <directive module="mod_remoteip">RemoteIPTrustedProxyList</directive>
382 permet de spécifier un fichier parcouru au démarrage du serveur pour
383 construire une liste d'adresses (ou blocs d'adresses), auxquelles
384 on peut faire confiance pour présenter une valeur RemoteIPHeader
385 valide de l'adresse IP du client.</p>
387 <p>Le caractère '<code>#</code>' indique une ligne de commentaires,
388 sinon, toutes les lignes séparées par un caractère nouvelle ligne ou
389 tous les éléments d'une ligne séparés par un espace sont traités de
390 la même façon qu'avec la directive
391 <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>.</p>
393 <example><title>Exemple d'adresse de confiance (répartiteur de
395 <highlight language="config">
396 RemoteIPHeader X-Forwarded-For
397 RemoteIPTrustedProxyList conf/trusted-proxies.lst
401 <example><title>conf/mandataires-de-confiance.lst contents</title>
402 # Mandataires externes identifiés<br/>
403 192.0.2.16/28 #groupe wap phone de mandataires<br/>
404 proxy.isp.example.com #un FAI bien connu