granicus.if.org Git - apache/blob - docs/manual/mod/mod_remoteip.html.en

   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
   7       -->
   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>
  13 <body>
  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="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_remoteip</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_remoteip.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  26 </div>
  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.
  30 </td></tr>
  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>
  34 <h3>Summary</h3>
  35
  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>
  40
  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>
  44
  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">&lt;Require host&gt;</a></code>
  48     and <code class="directive"><a href="../mod/mod_authz_host.html#require ip">&lt;Require ip&gt;</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>
  54
  55     <div class="warning">It is critical to only enable this behavior from
  56
  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>
  59 </div>
  60 <div id="quickview"><h3 class="directives">Directives</h3>
  61 <ul id="toc">
  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>
  68 </ul>
  69 <h3>Topics</h3>
  70 <ul id="topics">
  71 <li><img alt="" src="../images/down.gif" /> <a href="#processing">Remote IP Processing</a></li>
  72 </ul><h3>See also</h3>
  73 <ul class="seealso">
  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>
  78 </ul></div>
  79 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  80 <div class="section">
  81 <h2><a name="processing" id="processing">Remote IP Processing</a></h2>
  82
  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>
  87
  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>
  92
  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>
  99
 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>
 106
 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>
 110
 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>
 116
 117 </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>
 126 </table>
 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>
 135
 136     <div class="example"><h3>Internal (Load Balancer) Example</h3><p><code>
 137         RemoteIPHeader X-Client-IP
 138     </code></p></div>
 139
 140     <div class="example"><h3>Proxy Example</h3><p><code>
 141         RemoteIPHeader X-Forwarded-For
 142     </code></p></div>
 143
 144 </div>
 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>
 153 </table>
 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>
 160
 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
 165     </code></p></div>
 166
 167 </div>
 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>
 176 </table>
 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>
 180
 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>
 184
 185     <div class="example"><h3>Internal (Load Balancer) Example</h3><p><code>
 186         RemoteIPHeader X-Client-IP<br />
 187         RemoteIPTrustedProxyList conf/trusted-proxies.lst
 188     </code></p></div>
 189
 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
 194     </code></p></div>
 195
 196 </div>
 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>
 205 </table>
 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>
 212
 213     <div class="example"><h3>Example</h3><p><code>
 214         RemoteIPHeader X-Forwarded-For<br />
 215         RemoteIPProxiesHeader X-Forwarded-By
 216     </code></p></div>
 217
 218 </div>
 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>
 227 </table>
 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>
 236
 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
 241     </code></p></div>
 242
 243 </div>
 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>
 252 </table>
 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>
 256
 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>
 260
 261     <div class="example"><h3>Trusted (Load Balancer) Example</h3><p><code>
 262         RemoteIPHeader X-Forwarded-For<br />
 263         RemoteIPTrustedProxyList conf/trusted-proxies.lst
 264     </code></p></div>
 265
 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
 270     </code></p></div>
 271
 272 </div>
 273 </div>
 274 <div class="bottomlang">
 275 <p><span>Available Languages: </span><a href="../en/mod/mod_remoteip.html" title="English">&nbsp;en&nbsp;</a> |
 276 <a href="../fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 277 </div><div id="footer">
 278 <p class="apache">Copyright 2011 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>
 280 </body></html>