rebuild

[apache] / 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 original client IP address for the connection
with the useragent 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 useragent which initiated the
    request as the originating useragent as identified by httpd for the
    purposes of authorization and logging, even where that useragent is
    behind a load balancer, front end server, or proxy server.</p>

    <p>The module overrides the client IP address for the connection
    with the useragent IP address reported in the request header configured
    with the <directive module="mod_remoteip">RemoteIPHeader</directive> directive.</p>

    <p>Additionally, this module implements the server side of
    HAProxy's
    <a href="http://blog.haproxy.com/haproxy/proxy-protocol/">PROXY Protocol</a> when
    using the <directive module="mod_remoteip">RemoteIPProxyProtocol</directive>
    directive.</p>

    <p>Once replaced as instructed, this overridden useragent IP address is
    then used for the <module>mod_authz_host</module>
    <directive module="mod_authz_core" name="Require">Require ip</directive>
    feature, is reported by <module>mod_status</module>, and is recorded by
    <module>mod_log_config</module> <code>%a</code> and <module>core</module>
    <code>%a</code> format strings. The underlying client IP of the connection
    is available in the <code>%{c}a</code> format string.</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 useragent to impersonate another
    useragent.</note>
</summary>

<seealso><module>mod_authz_host</module></seealso>
<seealso><module>mod_status</module></seealso>
<seealso><module>mod_log_config</module></seealso>
<seealso><a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol Spec</a></seealso>

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

    <p>Apache by default identifies the useragent with the connection's
    client_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 overrides the client IP of the connection with the
    advertised useragent IP as provided by a proxy or load balancer, for
    the duration of the request. A load balancer might establish a long
    lived keepalive connection with the server, and each request will
    have the correct useragent IP, even though the underlying client IP
    address of the load balancer remains unchanged.</p>

    <p>When multiple, comma delimited useragent IP addresses are listed in the
    header value, they are processed in Right-to-Left order.  Processing
    halts when a given useragent IP address is not trusted to present the
    preceding 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 overriding the client 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 module="mod_remoteip">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 module="mod_remoteip">RemoteIPInternalProxy</directive>
    internal (intranet) proxies are registered.</note>

</section>

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

<usage>
    <p>The <directive module="mod_remoteip">RemoteIPHeader</directive> directive triggers
    <module>mod_remoteip</module> to treat the value of the specified
    <var>header-field</var> header as the useragent IP address, or list
    of intermediate useragent IP addresses, subject to further configuration
    of the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> and
    <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directives.</p>

    <note type="warning"> Unless these other directives are used, <module>mod_remoteip</module> 
    will trust all hosts presenting a non internal address in the 
    <directive module="mod_remoteip">RemoteIPHeader</directive> header value.
    </note>

    <example><title>Internal (Load Balancer) Example</title>
    <highlight language="config">
        RemoteIPHeader X-Client-IP
        </highlight>
    </example>

    <example><title>Proxy Example</title>
    <highlight language="config">
        RemoteIPHeader X-Forwarded-For
        </highlight>
    </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 module="mod_remoteip">RemoteIPInternalProxy</directive> directive adds one
    or more addresses (or address blocks) to trust as presenting a valid
    RemoteIPHeader value of the useragent IP.  Unlike the
    <directive module="mod_remoteip">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>
    <highlight language="config">
RemoteIPHeader X-Client-IP
RemoteIPInternalProxy 10.0.2.0/24
RemoteIPInternalProxy gateway.localdomain
        </highlight>
    </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 module="mod_remoteip">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 useragent 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 module="mod_remoteip">RemoteIPInternalProxy</directive> directive.</p>

    <example><title>Internal (Load Balancer) Example</title>
        <highlight language="config">
RemoteIPHeader X-Client-IP
RemoteIPInternalProxyList conf/trusted-proxies.lst
        </highlight>
    </example>

    <example><title>conf/trusted-proxies.lst contents</title>
    <pre>
# Our internally trusted proxies;
10.0.2.0/24         #Everyone in the testing group
gateway.localdomain #The front end balancer
</pre>
    </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 module="mod_remoteip">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 useragent
    IP of the request. Note that intermediate
    <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> addresses are recorded in
    this header, while any intermediate
    <directive module="mod_remoteip">RemoteIPInternalProxy</directive> addresses are discarded.</p>

    <example><title>Example</title>
    <highlight language="config">
RemoteIPHeader X-Forwarded-For
RemoteIPProxiesHeader X-Forwarded-By
    </highlight>
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPProxyProtocol</name>
<description>Enable, optionally enable or disable the PROXY protocol handling</description>
<syntax>RemoteIPProxyProtocol On|Optional|Off</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>RemoteIPProxyProtocol</directive> enables or 
    disables the reading and handling of the PROXY protocol connection header.
    If enabled with the <code>On</code> flag, the upstream client <em>must</em>
    send the header every time it opens a connection or the connection will
    be aborted. If enabled with the <code>Optional</code> flag, the upstream
    client <em>may</em> send the header.</p>

    <p>While this directive may be specified in any virtual host, it is
    important to understand that because the PROXY protocol is connection
    based and protocol agnostic, the enabling and disabling is actually based
    on ip-address and port. This means that if you have multiple name-based
    virtual hosts for the same host and port, and you enable it any one of
    them, then it is enabled for all them (with that host and port). It also
    means that if you attempt to enable the PROXY protocol in one and disable
    in the other, that won't work; in such a case the last one wins and a
    notice will be logged indicating which setting was being overridden.</p>

    <note type="hint">When multiple virtual hosts on the same IP and port are
    configured with a combination of <code>On</code> and <code>Optional</code>
    flags, connections will not be aborted if the header is not sent.
    Instead, enforcement will happen after the request is read so virtual
    hosts configured with <code>On</code> will return a 400 Bad Request.
    Virtual hosts configured with <code>Optional</code> will continue as
    usual but without replacing the client IP information</note>
    
    <highlight language="config">
Listen 80
&lt;VirtualHost *:80&gt;
    ServerName www.example.com
    RemoteIPProxyProtocol Optional

    #Requests to this virtual host may optionally not have
    # a PROXY protocol header provided
&lt;/VirtualHost&gt;

&lt;VirtualHost *:80&gt;
    ServerName www.example.com
    RemoteIPProxyProtocol On

    #Requests to this virtual host must have a PROXY protocol
    # header provided. If it is missing, a 400 will result
&lt;/VirtualHost&gt;

Listen 8080
&lt;VirtualHost *:8080&gt;
    ServerName www.example.com
    RemoteIPProxyProtocol On

    #Requests to this virtual host must have a PROXY protocol
    # header provided. If it is missing, the connection will
    # be aborted
&lt;/VirtualHost&gt;
    </highlight>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>RemoteIPTrustedProxy</name>
<description>Restrict client 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 module="mod_remoteip">RemoteIPTrustedProxy</directive> 
    directive restricts which peer IP addresses (or address blocks) will be
    trusted to present  a valid RemoteIPHeader value of the useragent IP.</p>
  
    <p> Unlike the <directive module="mod_remoteip">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 useragent IP, and are left in the
    <directive module="mod_remoteip">RemoteIPHeader</directive> header's value.</p>

    <note type="warning">By default, <module>mod_remoteip</module> will trust 
    all hosts presenting a non internal address in the 
    <directive module="mod_remoteip">RemoteIPHeader</directive> header value.
    </note>

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

<directivesynopsis>
<name>RemoteIPTrustedProxyList</name>
<description>Restrict client 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 module="mod_remoteip">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 useragent 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 module="mod_remoteip">RemoteIPTrustedProxy</directive> directive.</p>

    <example><title>Trusted (Load Balancer) Example</title>
    <highlight language="config">
RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxyList conf/trusted-proxies.lst
        </highlight>
    </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>