bcb4e51a409d94ae670de96afb8483a4f7855294Stephan Bosch<?xml version="1.0"?>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<modulesynopsis metafile="mod_remoteip.xml.meta">

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<name>mod_remoteip</name>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<description>Replaces the original peer IP address for the connection

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomiwith the client IP address list presented by a proxies or a load balancer

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomivia the request headers.

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen</description>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<status>Base</status>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen<sourcefile>mod_remoteip.c</sourcefile>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen<identifier>remoteip_module</identifier>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<summary>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi <p>This module is used to treat the client which initiated the

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen request as the originating client as identified by httpd for the

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen purposes of authorization and logging, even where that client is

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

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen

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

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen with the client IP address reported in the request header configured

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen with the <directive>RemoteIPHeader</directive> directive.</p>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen

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

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen then used for the <module>mod_authz_host</module>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen <directive module="mod_authz_host" type="section">Require ip</directive>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen feature, is reported by <module>mod_status</module>, and is recorded by

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen <module>mod_log_config</module> <code>%a</code> and <module>core</module>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen <code>%a</code> format strings. The underlying peer IP of the connection

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen is available in the <code>%{c}a</code> format string.</p>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen

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

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen intermediate hosts (proxies, etc) which are trusted by this server, since

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen it is trivial for the remote client to impersonate another client.</note>

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen</summary>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen<seealso><module>mod_authz_host</module></seealso>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<seealso><module>mod_status</module></seealso>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi<seealso><module>mod_log_config</module></seealso>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

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

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

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

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi peer_ip value, and the connection remote_host and remote_logname are

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi derived from this value. These fields play a role in authentication,

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi authorization and logging and other purposes by other loadable

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi modules.</p>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi <p>mod_remoteip overrides the peer IP of the connection with the

6ce52edd3de46bdf565ee71f6112a9e7a6090031Timo Sirainen advertised client IP as provided by a proxy or load balancer, for

6ce52edd3de46bdf565ee71f6112a9e7a6090031Timo Sirainen the duration of the request. A load balancer might establish a long

6ce52edd3de46bdf565ee71f6112a9e7a6090031Timo Sirainen lived keepalive connection with the server, and each request will

6ce52edd3de46bdf565ee71f6112a9e7a6090031Timo Sirainen have the correct client IP, even though the underlying peer IP

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

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

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

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

987c15a5980f53225e60f79325c14cb2acddaabbTimo Sirainen halts when a given client IP address is not trusted to present the

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi preceding IP address. The header field is updated to this remaining

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi list of unconfirmed IP addresses, or if all IP addresses were trusted,

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi this header is removed from the request altogether.</p>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi <p>In overriding the client IP, the module stores the list of intermediate

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi hosts in a remoteip-proxy-ip-list note, which <module>mod_log_config</module>

26e7bc65f13482709c0f6216650582e7705eeeffAki Tuomi 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>