<?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 apparent client remote IP address 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 overrides the apparent remote (client) IP 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 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 original remote 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 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.</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

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 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>