<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

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

<name>mod_remoteip</name>

<description>Replaces the original peer IP address for the connection

with the client 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 client which initiated the

request as the originating client as identified by httpd for the

purposes of authorization and logging, even where that client is

behind a load balancer, front end server, or proxy server.</p>

<p>The module overrides the peer IP address for the connection

with the client IP address reported in the request header configured

with the <directive>RemoteIPHeader</directive> directive.</p>

<p>Once replaced as instructed, this overridden client IP address is

then used for the <module>mod_authz_host</module>

<directive module="mod_authz_host" type="section">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 peer 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 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>

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

<p>Apache by default identifies the client with the connection's

peer_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 peer IP of the connection with the

advertised client 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 client IP, even though the underlying peer IP

address of the load balancer remains unchanged.</p>

<p>When multiple, comma delimited client IP addresses are listed in the

header value, they are processed in Right-to-Left order. Processing

halts when a given client 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>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 client

IP of the request. 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 client 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>