Apache HTTP Server Version 2.5
Apache HTTP Server Version 2.5
| 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. |
|---|---|
| Status: | Base |
| Module Identifier: | remoteip_module |
| Source File: | mod_remoteip.c |
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.
Additionally, this module implements the server side of
HAProxy's
PROXY Protocol when
using the RemoteIPProxyProtocol
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.
RemoteIPHeader RemoteIPInternalProxy RemoteIPInternalProxyList RemoteIPProxiesHeader RemoteIPProxyProtocol RemoteIPTrustedProxy RemoteIPTrustedProxyList
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.
RemoteIPInternalProxy
internal (intranet) proxies are registered.| Description: | Declare the header field which should be parsed for useragent IP addresses |
|---|---|
| Syntax: | RemoteIPHeader header-field |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
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.
mod_remoteip
will trust all hosts presenting a non internal address in the
RemoteIPHeader header value.
RemoteIPHeader X-Client-IP
RemoteIPHeader X-Forwarded-For
| Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value |
|---|---|
| Syntax: | RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ... |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
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.
RemoteIPHeader X-Client-IP RemoteIPInternalProxy 10.0.2.0/24 RemoteIPInternalProxy gateway.localdomain
| Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value |
|---|---|
| Syntax: | RemoteIPInternalProxyList filename |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
The RemoteIPInternalProxyList 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.
The '#' hash character designates a comment line, otherwise
each whitespace or newline separated entry is processed identically to
the RemoteIPInternalProxy directive.
RemoteIPHeader X-Client-IP RemoteIPInternalProxyList conf/trusted-proxies.lst
# Our internally trusted proxies; 10.0.2.0/24 #Everyone in the testing group gateway.localdomain #The front end balancer
| Description: | Declare the header field which will record all intermediate IP addresses |
|---|---|
| Syntax: | RemoteIPProxiesHeader HeaderFieldName |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
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.
RemoteIPHeader X-Forwarded-For RemoteIPProxiesHeader X-Forwarded-By
| Description: | Enable, optionally enable or disable the PROXY protocol handling |
|---|---|
| Syntax: | RemoteIPProxyProtocol On|Optional|Off |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
The RemoteIPProxyProtocol enables or
disables the reading and handling of the PROXY protocol connection header.
If enabled with the On flag, the upstream client must
send the header every time it opens a connection or the connection will
be aborted. If enabled with the Optional flag, the upstream
client may send the header.
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.
On and Optional
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 On will return a 400 Bad Request.
Virtual hosts configured with Optional will continue as
usual but without replacing the client IP informationListen 80
<VirtualHost *:80>
ServerName www.example.com
RemoteIPProxyProtocol Optional
#Requests to this virtual host may optionally not have
# a PROXY protocol header provided
</VirtualHost>
<VirtualHost *:80>
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
</VirtualHost>
Listen 8080
<VirtualHost *:8080>
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
</VirtualHost>
| Description: | Restrict client IP addresses trusted to present the RemoteIPHeader value |
|---|---|
| Syntax: | RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ... |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
The RemoteIPTrustedProxy
directive restricts which peer IP addresses (or address blocks) will be
trusted to present 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.
mod_remoteip will trust
all hosts presenting a non internal address in the
RemoteIPHeader header value.
RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxy 10.0.2.16/28 RemoteIPTrustedProxy proxy.example.com
| Description: | Restrict client IP addresses trusted to present the RemoteIPHeader value |
|---|---|
| Syntax: | RemoteIPTrustedProxyList filename |
| Context: | server config, virtual host |
| Status: | Base |
| Module: | mod_remoteip |
The RemoteIPTrustedProxyList 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.
The '#' hash character designates a comment line, otherwise
each whitespace or newline separated entry is processed identically to
the RemoteIPTrustedProxy directive.
RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxyList conf/trusted-proxies.lst
# Identified external proxies;
192.0.2.16/28 #wap phone group of proxies
proxy.isp.example.com #some well known ISP