Module mod_remoteip
Module mod_remoteip supports directives for the IBM® HTTP Server for i Web server.
Summary
The module mod_remoteip is used to treat the useragent which initiated the request as the originating useragent as identified by HTTP server for the purposes of authorization and logging, even where that useragent is behind a load balancer, front end server, or proxy server.
The module mod_remoteip 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, 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.
Remote IP Processing
HTTP server 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.
Directives
RemoteIPHeader
| Module: mod_remoteip | |
| Syntax: RemoteIPHeader header-field | |
| Default: none | |
| Context: server config, virtual host | |
| Override: none | |
| Origin: Apache | |
| Examples: RemoteIPHeader X-Client-IP | |
| Examples: RemoteIPHeader X-Forwarded-For |
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.
- Example 1
#Internal (Load Balancer) RemoteIPHeader X-Client-IP
- Example 2
#Proxy RemoteIPHeader X-Forwarded-For
RemoteIPInternalProxy
| Module: mod_remoteip | |
| Syntax: RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ... | |
| Default: none | |
| Context: Server config, virtual host | |
| Override: none | |
| Origin: Apache | |
| Examples: RemoteIPInternalProxy 10.0.2.0/24 |
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.
- Example:
#Internal (Load Balancer) RemoteIPHeader X-Client-IP RemoteIPInternalProxy 10.0.2.0/24 RemoteIPInternalProxy gateway.localdomain
RemoteIPInternalProxyList
| Module: mod_remoteip | |
| Syntax: RemoteIPInternalProxyList filename | |
| Default: none | |
| Context: Server config, virtual host | |
| Override: none | |
| Origin: Apache | |
| Examples: RemoteIPInternalProxyList conf/trusted-proxies.lst |
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.
- Example:
#Internal (Load Balancer) RemoteIPHeader X-Client-IP RemoteIPInternalProxyList conf/trusted-proxies.lstExample of conf/trusted-proxies.lst contents
# Our internally trusted proxies; 10.0.2.0/24 #Everyone in the testing group gateway.localdomain #The front end balancer
RemoteIPProxiesHeader
| Module: mod_remoteip | |
| Syntax: RemoteIPProxiesHeader HeaderFiledName | |
| Default: none | |
| Context: server config, virtual host | |
| Override: none | |
| Origin: Apache | |
Examples:
|
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.
RemoteIPTrustedProxy
| Module: mod_remoteip | |
| Syntax: RemoteIPProxiesHeader HeaderFiledName | |
| Default: none | |
| Context: server config, virtual host | |
| Override: none | |
| Origin: Apache | |
| Examples: RemoteIPTrustedProxy 10.0.2.16/28 | |
| Examples: RemoteIPTrustedProxy proxy.example.com |
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.
- Example:
#Trusted (Load Balancer) RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxy 10.0.2.16/28 RemoteIPTrustedProxy proxy.example.com
RemoteIPTrustedProxyList
| Module: mod_remoteip | |
| Syntax: RemoteIPTrustedProxyList filename | |
| Default: none | |
| Context: server config, virtual host | |
| Override: none | |
| Origin: Apache | |
| Examples: RemoteIPTrustedProxyList conf/trusted-proxies.lst |
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.
- Example:
#Trusted(Load Balancer) RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxyList conf/trusted-proxies.lstExample of conf/trusted-proxies.lst contents
# Identified external proxies; 192.0.2.16/28 #wap phone group of proxies proxy.isp.example.com #some well known ISP