path: root/docs/manual/mod/mod_remoteip.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_remoteip.xml.meta">

<name>mod_remoteip</name>
<description>Replaces the apparent client remote IP address and hostname 
for the request with the IP address list presented by a proxies or a load 
balancer via the request headers.
</description>

<status>Base</status>
<sourcefile>mod_remoteip.c</sourcefile>
<identifier>remoteip_module</identifier>

<summary>
    <p>This module is used to treat the remote host which initiated the 
    request as the originating remote host as identified by httpd for the
    purposes of authorization and logging, even where that remote host is
    behind a load balancer, front end server, or proxy server.</p>

    <p>The module replaces the apparent remote (client) IP/hostname for 
    the request with the IP address reported in the request header
    configured with the <directive>RemoteIPHeader</directive> directive.</p>

    <p>Once replaced as instructed, this apparent IP address is then used
    for <module>mod_authz_host</module> features
    <directive module="mod_authz_host" type="section">Require host</directive>
    and <directive module="mod_authz_host" type="section">Require ip</directive>,
    is reported by <module>mod_status</module>, and is recorded by
    <module>mod_log_config</module> <code>%a</code> and <code>%h</code>
    directives.  It also determines the machine probed for an inetd 
    identity by <module>mod_ident</module> based on the 
    <directive module="mod_ident">IdentityCheck</directive> configuration.</p>

    <note type="warning">It is critical to only enable this behavior from

    intermediate hosts (proxies, etc) which are trusted by this server, since
    it is trivial for the remote client to impersonate another client.</note>
</summary>

<seealso><module>mod_authz_host</module></seealso>
<seealso><module>mod_status</module></seealso>
<seealso><module>mod_log_config</module></seealso>
<seealso><module>mod_ident</module></seealso>

<section id="processing"><title>Remote IP Processing</title>

    <p>Apache identifies the client with the connection's remote_ip value,
    and the connection remote_host and remote_logname are derived from this 
    value.  These fields play a role in authentication, authorization and 
    logging and other purposes by other loadable modules.</p>

    <p>mod_remoteip replaces the true remote_ip with the advertised remote_ip as
    provided by a proxy, for every evaluation of the client that occurs in the
    server, and resets the remote_host and remote_logname values to trigger a 
    fresh dns or ident query of the remote IP address.</p>

    <p>When multiple, comma delimited remote IP addresses are listed in the 
    header value, they are processed in Right-to-Left order.  Processing
    halts when a given remote IP address is not trusted to present the
    preceeding IP address.  The header field is updated to this remaining 
    list of unconfirmed IP addresses, or if all IP addresses were trusted,
    this header is removed from the request altogether.</p>

    <p>In replacing the remote_ip, the module stores the list of intermediate
    hosts in a remoteip-proxy-ip-list note, which <module>mod_log_config</module>
    can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
    If the administrator needs to store this as an additional header, this
    same value can also be recording as a header using the directive
    <directive>RemoteIPProxiesHeader</directive>.</p>

    <note><title>IPv4-over-IPv6 Mapped Addresses</title>
    As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
    in their IPv4 representation.</note>

    <note><title>Internal (Private) Addresses</title>
    All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
    blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
    evaluated by mod_remoteip when <directive>RemoteIPInternalProxy</directive>
    internal (intranet) proxies are registered.</note> 

</section>

<directivesynopsis>
<name>RemoteIPHeader</name>
<description>Declare the header field which should be parsed for client IP addresses</description>
<syntax>RemoteIPHeader <var>header-field</var></syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPHeader</directive> directive triggers 
    <module>mod_remoteip</module> to treat the value of the specified
    <var>header-field</var> header as the client IP address, or list
    of intermediate client IP addresses, subject to further configuration 
    of the <directive>RemoteIPInternalProxy</directive> and
    <directive>RemoteIPTrustedProxy</directive> directives.  Unless these
    other directives are used, <module>mod_remoteip</module> will trust all
    hosts presenting a <directive>RemoteIPHeader</directive> IP value.</p>

    <example><title>Internal (Load Balancer) Example</title>
        RemoteIPHeader X-Client-IP
    </example>

    <example><title>Proxy Example</title>
        RemoteIPHeader X-Forwarded-For
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPInternalProxy</name>
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
<syntax>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPInternalProxy</directive> directive adds one
    or more addresses (or address blocks) to trust as presenting a valid
    RemoteIPHeader value of the client IP.  Unlike the
    <directive>RemoteIPTrustedProxy</directive> directive, any IP address
    presented in this header, including private intranet addresses, are 
    trusted when passed from these proxies.</p>

    <example><title>Internal (Load Balancer) Example</title>
        RemoteIPHeader X-Client-IP<br/>
        RemoteIPTrustedProxy 10.0.2.0/24<br/>
        RemoteIPTrustedProxy gateway.localdomain
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPInternalProxyList</name>
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
<syntax>RemoteIPInternalProxyList <var>filename</var></syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPInternalProxyList</directive> directive specifies
    a file parsed at startup, and builds a list of addresses (or address blocks)
    to trust as presenting a valid RemoteIPHeader value of the client IP.</p>

    <p>The '<code>#</code>' hash character designates a comment line, otherwise
    each whitespace or newline separated entry is processed identically to
    the <directive>RemoteIPInternalProxy</directive> directive.</p>

    <example><title>Internal (Load Balancer) Example</title>
        RemoteIPHeader X-Client-IP<br/>
        RemoteIPTrustedProxyList conf/trusted-proxies.lst
    </example>

    <example><title>conf/trusted-proxies.lst contents</title>
         # Our internally trusted proxies;<br/>
         10.0.2.0/24         #Everyone in the testing group<br/>
         gateway.localdomain #The front end balancer
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPProxiesHeader</name>
<description>Declare the header field which will record all intermediate IP addresses</description>
<syntax>RemoteIPProxiesHeader <var>HeaderFieldName</var></syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPProxiesHeader</directive> directive specifies
    a header into which <module>mod_remoteip</module> will collect a list of
    all of the intermediate client IP addresses trusted to resolve the actual
    remote IP.  Note that intermediate <directive>RemoteIPTrustedProxy</directive>
    addresses are recorded in this header, while any intermediate 
    <directive>RemoteIPInternalProxy</directive> addresses are discarded.</p>

    <example><title>Example</title>
        RemoteIPHeader X-Forwarded-For<br/>
        RemoteIPProxiesHeader X-Forwarded-By
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPTrustedProxy</name>
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
<syntax>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPTrustedProxy</directive> directive adds one
    or more addresses (or address blocks) to trust as presenting a valid
    RemoteIPHeader value of the client IP.  Unlike the
    <directive>RemoteIPInternalProxy</directive> directive, any intranet 
    or private IP address reported by such proxies, including the 10/8, 172.16/12,
    192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public
    2000::/3 block) are not trusted as the remote IP, and are left in the 
    <directive>RemoteIPHeader</directive> header's value.</p>

    <example><title>Trusted (Load Balancer) Example</title>
        RemoteIPHeader X-Forwarded-For<br/>
        RemoteIPTrustedProxy 10.0.2.16/28<br/>
        RemoteIPTrustedProxy proxy.example.com
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPTrustedProxyList</name>
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
<syntax>RemoteIPTrustedProxyList <var>filename</var></syntax>
<contextlist><context>server config</context><context>virtual host</context></contextlist>

<usage>
    <p>The <directive>RemoteIPTrustedProxyList</directive> directive specifies
    a file parsed at startup, and builds a list of addresses (or address blocks)
    to trust as presenting a valid RemoteIPHeader value of the client IP.</p>

    <p>The '<code>#</code>' hash character designates a comment line, otherwise
    each whitespace or newline seperated entry is processed identically to
    the <directive>RemoteIPTrustedProxy</directive> directive.</p>

    <example><title>Trusted (Load Balancer) Example</title>
        RemoteIPHeader X-Forwarded-For<br/>
        RemoteIPTrustedProxyList conf/trusted-proxies.lst
    </example>

    <example><title>conf/trusted-proxies.lst contents</title>
       # Identified external proxies;<br/>
       192.0.2.16/28         #wap phone group of proxies<br/>
       proxy.isp.example.com #some well known ISP
    </example>
</usage>
</directivesynopsis>


</modulesynopsis>