1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>mod_remoteip - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.3</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_remoteip</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/mod_remoteip.html" title="English"> en </a> |
25 <a href="../fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Replaces the apparent client remote IP address and hostname
28 for the request with the IP address list presented by a proxies or a load
29 balancer via the request headers.
31 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
32 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>remoteip_module</td></tr>
33 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_remoteip.c</td></tr></table>
36 <p>This module is used to treat the remote host which initiated the
37 request as the originating remote host as identified by httpd for the
38 purposes of authorization and logging, even where that remote host is
39 behind a load balancer, front end server, or proxy server.</p>
41 <p>The module replaces the apparent remote (client) IP/hostname for
42 the request with the IP address reported in the request header
43 configured with the <code class="directive">RemoteIPHeader</code> directive.</p>
45 <p>Once replaced as instructed, this apparent IP address is then used
46 for <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code> features
47 <code class="directive"><a href="../mod/mod_authz_host.html#require host"><Require host></a></code>
48 and <code class="directive"><a href="../mod/mod_authz_host.html#require ip"><Require ip></a></code>,
49 is reported by <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>, and is recorded by
50 <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> <code>%a</code> and <code>%h</code>
51 directives. It also determines the machine probed for an inetd
52 identity by <code class="module"><a href="../mod/mod_ident.html">mod_ident</a></code> based on the
53 <code class="directive"><a href="../mod/mod_ident.html#identitycheck">IdentityCheck</a></code> configuration.</p>
55 <div class="warning">It is critical to only enable this behavior from
57 intermediate hosts (proxies, etc) which are trusted by this server, since
58 it is trivial for the remote client to impersonate another client.</div>
60 <div id="quickview"><h3 class="directives">Directives</h3>
62 <li><img alt="" src="../images/down.gif" /> <a href="#remoteipheader">RemoteIPHeader</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#remoteipinternalproxy">RemoteIPInternalProxy</a></li>
64 <li><img alt="" src="../images/down.gif" /> <a href="#remoteipinternalproxylist">RemoteIPInternalProxyList</a></li>
65 <li><img alt="" src="../images/down.gif" /> <a href="#remoteipproxiesheader">RemoteIPProxiesHeader</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#remoteiptrustedproxy">RemoteIPTrustedProxy</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#remoteiptrustedproxylist">RemoteIPTrustedProxyList</a></li>
71 <li><img alt="" src="../images/down.gif" /> <a href="#processing">Remote IP Processing</a></li>
72 </ul><h3>See also</h3>
74 <li><code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></li>
75 <li><code class="module"><a href="../mod/mod_status.html">mod_status</a></code></li>
76 <li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
77 <li><code class="module"><a href="../mod/mod_ident.html">mod_ident</a></code></li>
79 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
81 <h2><a name="processing" id="processing">Remote IP Processing</a></h2>
83 <p>Apache identifies the client with the connection's remote_ip value,
84 and the connection remote_host and remote_logname are derived from this
85 value. These fields play a role in authentication, authorization and
86 logging and other purposes by other loadable modules.</p>
88 <p>mod_remoteip replaces the true remote_ip with the advertised remote_ip as
89 provided by a proxy, for every evaluation of the client that occurs in the
90 server, and resets the remote_host and remote_logname values to trigger a
91 fresh dns or ident query of the remote IP address.</p>
93 <p>When multiple, comma delimited remote IP addresses are listed in the
94 header value, they are processed in Right-to-Left order. Processing
95 halts when a given remote IP address is not trusted to present the
96 preceeding IP address. The header field is updated to this remaining
97 list of unconfirmed IP addresses, or if all IP addresses were trusted,
98 this header is removed from the request altogether.</p>
100 <p>In replacing the remote_ip, the module stores the list of intermediate
101 hosts in a remoteip-proxy-ip-list note, which <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>
102 can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
103 If the administrator needs to store this as an additional header, this
104 same value can also be recording as a header using the directive
105 <code class="directive">RemoteIPProxiesHeader</code>.</p>
107 <div class="note"><h3>IPv4-over-IPv6 Mapped Addresses</h3>
108 As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
109 in their IPv4 representation.</div>
111 <div class="note"><h3>Internal (Private) Addresses</h3>
112 All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
113 blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
114 evaluated by mod_remoteip when <code class="directive">RemoteIPInternalProxy</code>
115 internal (intranet) proxies are registered.</div>
118 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
119 <div class="directive-section"><h2><a name="RemoteIPHeader" id="RemoteIPHeader">RemoteIPHeader</a> <a name="remoteipheader" id="remoteipheader">Directive</a></h2>
120 <table class="directive">
121 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare the header field which should be parsed for client IP addresses</td></tr>
122 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPHeader <var>header-field</var></code></td></tr>
123 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
124 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
125 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
127 <p>The <code class="directive">RemoteIPHeader</code> directive triggers
128 <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> to treat the value of the specified
129 <var>header-field</var> header as the client IP address, or list
130 of intermediate client IP addresses, subject to further configuration
131 of the <code class="directive">RemoteIPInternalProxy</code> and
132 <code class="directive">RemoteIPTrustedProxy</code> directives. Unless these
133 other directives are used, <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> will trust all
134 hosts presenting a <code class="directive">RemoteIPHeader</code> IP value.</p>
136 <div class="example"><h3>Internal (Load Balancer) Example</h3><p><code>
137 RemoteIPHeader X-Client-IP
140 <div class="example"><h3>Proxy Example</h3><p><code>
141 RemoteIPHeader X-Forwarded-For
145 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
146 <div class="directive-section"><h2><a name="RemoteIPInternalProxy" id="RemoteIPInternalProxy">RemoteIPInternalProxy</a> <a name="remoteipinternalproxy" id="remoteipinternalproxy">Directive</a></h2>
147 <table class="directive">
148 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
149 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</code></td></tr>
150 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
151 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
152 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
154 <p>The <code class="directive">RemoteIPInternalProxy</code> directive adds one
155 or more addresses (or address blocks) to trust as presenting a valid
156 RemoteIPHeader value of the client IP. Unlike the
157 <code class="directive">RemoteIPTrustedProxy</code> directive, any IP address
158 presented in this header, including private intranet addresses, are
159 trusted when passed from these proxies.</p>
161 <div class="example"><h3>Internal (Load Balancer) Example</h3><p><code>
162 RemoteIPHeader X-Client-IP<br />
163 RemoteIPTrustedProxy 10.0.2.0/24<br />
164 RemoteIPTrustedProxy gateway.localdomain
168 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
169 <div class="directive-section"><h2><a name="RemoteIPInternalProxyList" id="RemoteIPInternalProxyList">RemoteIPInternalProxyList</a> <a name="remoteipinternalproxylist" id="remoteipinternalproxylist">Directive</a></h2>
170 <table class="directive">
171 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
172 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPInternalProxyList <var>filename</var></code></td></tr>
173 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
174 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
175 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
177 <p>The <code class="directive">RemoteIPInternalProxyList</code> directive specifies
178 a file parsed at startup, and builds a list of addresses (or address blocks)
179 to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
181 <p>The '<code>#</code>' hash character designates a comment line, otherwise
182 each whitespace or newline separated entry is processed identically to
183 the <code class="directive">RemoteIPInternalProxy</code> directive.</p>
185 <div class="example"><h3>Internal (Load Balancer) Example</h3><p><code>
186 RemoteIPHeader X-Client-IP<br />
187 RemoteIPTrustedProxyList conf/trusted-proxies.lst
190 <div class="example"><h3>conf/trusted-proxies.lst contents</h3><p><code>
191 # Our internally trusted proxies;<br />
192 10.0.2.0/24 #Everyone in the testing group<br />
193 gateway.localdomain #The front end balancer
197 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
198 <div class="directive-section"><h2><a name="RemoteIPProxiesHeader" id="RemoteIPProxiesHeader">RemoteIPProxiesHeader</a> <a name="remoteipproxiesheader" id="remoteipproxiesheader">Directive</a></h2>
199 <table class="directive">
200 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare the header field which will record all intermediate IP addresses</td></tr>
201 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPProxiesHeader <var>HeaderFieldName</var></code></td></tr>
202 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
203 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
204 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
206 <p>The <code class="directive">RemoteIPProxiesHeader</code> directive specifies
207 a header into which <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> will collect a list of
208 all of the intermediate client IP addresses trusted to resolve the actual
209 remote IP. Note that intermediate <code class="directive">RemoteIPTrustedProxy</code>
210 addresses are recorded in this header, while any intermediate
211 <code class="directive">RemoteIPInternalProxy</code> addresses are discarded.</p>
213 <div class="example"><h3>Example</h3><p><code>
214 RemoteIPHeader X-Forwarded-For<br />
215 RemoteIPProxiesHeader X-Forwarded-By
219 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
220 <div class="directive-section"><h2><a name="RemoteIPTrustedProxy" id="RemoteIPTrustedProxy">RemoteIPTrustedProxy</a> <a name="remoteiptrustedproxy" id="remoteiptrustedproxy">Directive</a></h2>
221 <table class="directive">
222 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
223 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</code></td></tr>
224 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
225 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
226 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
228 <p>The <code class="directive">RemoteIPTrustedProxy</code> directive adds one
229 or more addresses (or address blocks) to trust as presenting a valid
230 RemoteIPHeader value of the client IP. Unlike the
231 <code class="directive">RemoteIPInternalProxy</code> directive, any intranet
232 or private IP address reported by such proxies, including the 10/8, 172.16/12,
233 192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public
234 2000::/3 block) are not trusted as the remote IP, and are left in the
235 <code class="directive">RemoteIPHeader</code> header's value.</p>
237 <div class="example"><h3>Trusted (Load Balancer) Example</h3><p><code>
238 RemoteIPHeader X-Forwarded-For<br />
239 RemoteIPTrustedProxy 10.0.2.16/28<br />
240 RemoteIPTrustedProxy proxy.example.com
244 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
245 <div class="directive-section"><h2><a name="RemoteIPTrustedProxyList" id="RemoteIPTrustedProxyList">RemoteIPTrustedProxyList</a> <a name="remoteiptrustedproxylist" id="remoteiptrustedproxylist">Directive</a></h2>
246 <table class="directive">
247 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
248 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPTrustedProxyList <var>filename</var></code></td></tr>
249 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
250 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
251 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
253 <p>The <code class="directive">RemoteIPTrustedProxyList</code> directive specifies
254 a file parsed at startup, and builds a list of addresses (or address blocks)
255 to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
257 <p>The '<code>#</code>' hash character designates a comment line, otherwise
258 each whitespace or newline seperated entry is processed identically to
259 the <code class="directive">RemoteIPTrustedProxy</code> directive.</p>
261 <div class="example"><h3>Trusted (Load Balancer) Example</h3><p><code>
262 RemoteIPHeader X-Forwarded-For<br />
263 RemoteIPTrustedProxyList conf/trusted-proxies.lst
266 <div class="example"><h3>conf/trusted-proxies.lst contents</h3><p><code>
267 # Identified external proxies;<br />
268 192.0.2.16/28 #wap phone group of proxies<br />
269 proxy.isp.example.com #some well known ISP
274 <div class="bottomlang">
275 <p><span>Available Languages: </span><a href="../en/mod/mod_remoteip.html" title="English"> en </a> |
276 <a href="../fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
277 </div><div id="footer">
278 <p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
279 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>