Summary

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.

The module overrides the client IP address for the connection
with the useragent IP address reported in the request header configured
with the RemoteIPHeader directive.

Once replaced as instructed, this overridden useragent IP address is
then used for the mod_authz_host<Require ip>
feature, is reported by mod_status, and is recorded by
mod_log_config%a and core%a format strings. The underlying client IP of the connection
is available in the %{c}a format string.

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.

Topics

See also

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.

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.

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.

In overriding the client IP, the module stores the list of intermediate
hosts in a remoteip-proxy-ip-list note, which mod_log_config
can record using the %{remoteip-proxy-ip-list}n 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
RemoteIPProxiesHeader.

IPv4-over-IPv6 Mapped Addresses

As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
in their IPv4 representation.

Internal (Private) Addresses

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 RemoteIPInternalProxy
internal (intranet) proxies are registered.

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

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

The RemoteIPProxiesHeader directive specifies
a header into which mod_remoteip will collect a list of
all of the intermediate client IP addresses trusted to resolve the useragent
IP of the request. Note that intermediate
RemoteIPTrustedProxy addresses are recorded in
this header, while any intermediate
RemoteIPInternalProxy addresses are discarded.

The RemoteIPTrustedProxy directive adds one
or more addresses (or address blocks) to trust as presenting a valid
RemoteIPHeader value of the useragent IP. Unlike the
RemoteIPInternalProxy 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
RemoteIPHeader header's value.

conf/trusted-proxies.lst contents

Notice:This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.