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

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_remoteip.xml.meta">
  24
  25 <name>mod_remoteip</name>
  26 <description>Replaces the apparent client remote IP address and hostname
  27 for the request with the IP address list presented by a proxies or a load
  28 balancer via the request headers.
  29 </description>
  30
  31 <status>Base</status>
  32 <sourcefile>mod_remoteip.c</sourcefile>
  33 <identifier>remoteip_module</identifier>
  34
  35 <summary>
  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 <directive>RemoteIPHeader</directive> directive.</p>
  44
  45     <p>Once replaced as instructed, this apparent IP address is then used
  46     for <module>mod_authz_host</module> features
  47     <directive module="mod_authz_host" type="section">Require host</directive>
  48     and <directive module="mod_authz_host" type="section">Require ip</directive>,
  49     is reported by <module>mod_status</module>, and is recorded by
  50     <module>mod_log_config</module> <code>%a</code> and <code>%h</code>
  51     directives.  It also determines the machine probed for an inetd
  52     identity by <module>mod_ident</module> based on the
  53     <directive module="mod_ident">IdentityCheck</directive> configuration.</p>
  54
  55     <note type="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.</note>
  59 </summary>
  60
  61 <seealso><module>mod_authz_host</module></seealso>
  62 <seealso><module>mod_status</module></seealso>
  63 <seealso><module>mod_log_config</module></seealso>
  64 <seealso><module>mod_ident</module></seealso>
  65
  66 <section id="processing"><title>Remote IP Processing</title>
  67
  68     <p>Apache identifies the client with the connection's remote_ip value,
  69     and the connection remote_host and remote_logname are derived from this
  70     value.  These fields play a role in authentication, authorization and
  71     logging and other purposes by other loadable modules.</p>
  72
  73     <p>mod_remoteip replaces the true remote_ip with the advertised remote_ip as
  74     provided by a proxy, for every evaluation of the client that occurs in the
  75     server, and resets the remote_host and remote_logname values to trigger a
  76     fresh dns or ident query of the remote IP address.</p>
  77
  78     <p>When multiple, comma delimited remote IP addresses are listed in the
  79     header value, they are processed in Right-to-Left order.  Processing
  80     halts when a given remote IP address is not trusted to present the
  81     preceeding IP address.  The header field is updated to this remaining
  82     list of unconfirmed IP addresses, or if all IP addresses were trusted,
  83     this header is removed from the request altogether.</p>
  84
  85     <p>In replacing the remote_ip, the module stores the list of intermediate
  86     hosts in a remoteip-proxy-ip-list note, which <module>mod_log_config</module>
  87     can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
  88     If the administrator needs to store this as an additional header, this
  89     same value can also be recording as a header using the directive
  90     <directive>RemoteIPProxiesHeader</directive>.</p>
  91
  92     <note><title>IPv4-over-IPv6 Mapped Addresses</title>
  93     As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
  94     in their IPv4 representation.</note>
  95
  96     <note><title>Internal (Private) Addresses</title>
  97     All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
  98     blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
  99     evaluated by mod_remoteip when <directive>RemoteIPInternalProxy</directive>
 100     internal (intranet) proxies are registered.</note>
 101
 102 </section>
 103
 104 <directivesynopsis>
 105 <name>RemoteIPHeader</name>
 106 <description>Declare the header field which should be parsed for client IP addresses</description>
 107 <syntax>RemoteIPHeader <var>header-field</var></syntax>
 108 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 109
 110 <usage>
 111     <p>The <directive>RemoteIPHeader</directive> directive triggers
 112     <module>mod_remoteip</module> to treat the value of the specified
 113     <var>header-field</var> header as the client IP address, or list
 114     of intermediate client IP addresses, subject to further configuration
 115     of the <directive>RemoteIPInternalProxy</directive> and
 116     <directive>RemoteIPTrustedProxy</directive> directives.  Unless these
 117     other directives are used, <module>mod_remoteip</module> will trust all
 118     hosts presenting a <directive>RemoteIPHeader</directive> IP value.</p>
 119
 120     <example><title>Internal (Load Balancer) Example</title>
 121         RemoteIPHeader X-Client-IP
 122     </example>
 123
 124     <example><title>Proxy Example</title>
 125         RemoteIPHeader X-Forwarded-For
 126     </example>
 127 </usage>
 128 </directivesynopsis>
 129
 130 <directivesynopsis>
 131 <name>RemoteIPInternalProxy</name>
 132 <description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
 133 <syntax>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
 134 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 135
 136 <usage>
 137     <p>The <directive>RemoteIPInternalProxy</directive> directive adds one
 138     or more addresses (or address blocks) to trust as presenting a valid
 139     RemoteIPHeader value of the client IP.  Unlike the
 140     <directive>RemoteIPTrustedProxy</directive> directive, any IP address
 141     presented in this header, including private intranet addresses, are
 142     trusted when passed from these proxies.</p>
 143
 144     <example><title>Internal (Load Balancer) Example</title>
 145         RemoteIPHeader X-Client-IP<br/>
 146         RemoteIPTrustedProxy 10.0.2.0/24<br/>
 147         RemoteIPTrustedProxy gateway.localdomain
 148     </example>
 149 </usage>
 150 </directivesynopsis>
 151
 152 <directivesynopsis>
 153 <name>RemoteIPInternalProxyList</name>
 154 <description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
 155 <syntax>RemoteIPInternalProxyList <var>filename</var></syntax>
 156 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 157
 158 <usage>
 159     <p>The <directive>RemoteIPInternalProxyList</directive> directive specifies
 160     a file parsed at startup, and builds a list of addresses (or address blocks)
 161     to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
 162
 163     <p>The '<code>#</code>' hash character designates a comment line, otherwise
 164     each whitespace or newline separated entry is processed identically to
 165     the <directive>RemoteIPInternalProxy</directive> directive.</p>
 166
 167     <example><title>Internal (Load Balancer) Example</title>
 168         RemoteIPHeader X-Client-IP<br/>
 169         RemoteIPTrustedProxyList conf/trusted-proxies.lst
 170     </example>
 171
 172     <example><title>conf/trusted-proxies.lst contents</title>
 173          # Our internally trusted proxies;<br/>
 174          10.0.2.0/24         #Everyone in the testing group<br/>
 175          gateway.localdomain #The front end balancer
 176     </example>
 177 </usage>
 178 </directivesynopsis>
 179
 180 <directivesynopsis>
 181 <name>RemoteIPProxiesHeader</name>
 182 <description>Declare the header field which will record all intermediate IP addresses</description>
 183 <syntax>RemoteIPProxiesHeader <var>HeaderFieldName</var></syntax>
 184 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 185
 186 <usage>
 187     <p>The <directive>RemoteIPProxiesHeader</directive> directive specifies
 188     a header into which <module>mod_remoteip</module> will collect a list of
 189     all of the intermediate client IP addresses trusted to resolve the actual
 190     remote IP.  Note that intermediate <directive>RemoteIPTrustedProxy</directive>
 191     addresses are recorded in this header, while any intermediate
 192     <directive>RemoteIPInternalProxy</directive> addresses are discarded.</p>
 193
 194     <example><title>Example</title>
 195         RemoteIPHeader X-Forwarded-For<br/>
 196         RemoteIPProxiesHeader X-Forwarded-By
 197     </example>
 198 </usage>
 199 </directivesynopsis>
 200
 201 <directivesynopsis>
 202 <name>RemoteIPTrustedProxy</name>
 203 <description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
 204 <syntax>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
 205 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 206
 207 <usage>
 208     <p>The <directive>RemoteIPTrustedProxy</directive> directive adds one
 209     or more addresses (or address blocks) to trust as presenting a valid
 210     RemoteIPHeader value of the client IP.  Unlike the
 211     <directive>RemoteIPInternalProxy</directive> directive, any intranet
 212     or private IP address reported by such proxies, including the 10/8, 172.16/12,
 213     192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public
 214     2000::/3 block) are not trusted as the remote IP, and are left in the
 215     <directive>RemoteIPHeader</directive> header's value.</p>
 216
 217     <example><title>Trusted (Load Balancer) Example</title>
 218         RemoteIPHeader X-Forwarded-For<br/>
 219         RemoteIPTrustedProxy 10.0.2.16/28<br/>
 220         RemoteIPTrustedProxy proxy.example.com
 221     </example>
 222 </usage>
 223 </directivesynopsis>
 224
 225 <directivesynopsis>
 226 <name>RemoteIPTrustedProxyList</name>
 227 <description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
 228 <syntax>RemoteIPTrustedProxyList <var>filename</var></syntax>
 229 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 230
 231 <usage>
 232     <p>The <directive>RemoteIPTrustedProxyList</directive> directive specifies
 233     a file parsed at startup, and builds a list of addresses (or address blocks)
 234     to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
 235
 236     <p>The '<code>#</code>' hash character designates a comment line, otherwise
 237     each whitespace or newline seperated entry is processed identically to
 238     the <directive>RemoteIPTrustedProxy</directive> directive.</p>
 239
 240     <example><title>Trusted (Load Balancer) Example</title>
 241         RemoteIPHeader X-Forwarded-For<br/>
 242         RemoteIPTrustedProxyList conf/trusted-proxies.lst
 243     </example>
 244
 245     <example><title>conf/trusted-proxies.lst contents</title>
 246        # Identified external proxies;<br/>
 247        192.0.2.16/28         #wap phone group of proxies<br/>
 248        proxy.isp.example.com #some well known ISP
 249     </example>
 250 </usage>
 251 </directivesynopsis>
 252
 253
 254 </modulesynopsis>