Apache Module mod_remoteip

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 theRemoteIPHeader directive.

Additionally, this module implements the server side of HAProxy'sPROXY Protocol when using theRemoteIPProxyProtocol directive.

Once replaced as instructed, this overridden useragent IP address is then used for themod_authz_hostRequire ip feature, is reported bymod_status, and is recorded bymod_log_config%a andcore%a format strings. The underlying client IP of the connection is available in the%{c}a format string.

Topics

• Remote IP Processing

Directives

• RemoteIPHeader
• RemoteIPInternalProxy
• RemoteIPInternalProxyList
• RemoteIPProxiesHeader
• RemoteIPProxyProtocol
• RemoteIPProxyProtocolExceptions
• RemoteIPTrustedProxy
• RemoteIPTrustedProxyList

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug

See also

• mod_authz_host
• mod_status
• mod_log_config
• Proxy Protocol Spec
• Comments

Remote IP Processing

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, whichmod_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 directiveRemoteIPProxiesHeader.

RemoteIPHeaderDirective

TheRemoteIPHeader directive triggersmod_remoteip to treat the value of the specifiedheader-field header as the useragent IP address, or list of intermediate useragent IP addresses, subject to further configuration of theRemoteIPInternalProxy andRemoteIPTrustedProxy directives. Unless these other directives are used,mod_remoteip will trust all hosts presenting aRemoteIPHeader IP value.

RemoteIPHeader X-Client-IP

RemoteIPHeader X-Forwarded-For

RemoteIPInternalProxyDirective

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

RemoteIPHeader X-Client-IPRemoteIPInternalProxy 10.0.2.0/24RemoteIPInternalProxy gateway.localdomain

RemoteIPInternalProxyListDirective

TheRemoteIPInternalProxyList 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 theRemoteIPInternalProxy directive.

RemoteIPHeader X-Client-IPRemoteIPInternalProxyList conf/trusted-proxies.lst

# Our internally trusted proxies;10.0.2.0/24         #Everyone in the testing groupgateway.localdomain #The front end balancer

RemoteIPProxiesHeaderDirective

TheRemoteIPProxiesHeader directive specifies a header into whichmod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the useragent IP of the request. Note that intermediateRemoteIPTrustedProxy addresses are recorded in this header, while any intermediateRemoteIPInternalProxy addresses are discarded.

RemoteIPHeader X-Forwarded-ForRemoteIPProxiesHeader X-Forwarded-By

RemoteIPProxyProtocolDirective

TheRemoteIPProxyProtocol directive enables or disables the reading and handling of the PROXY protocol connection header. If enabled with theOn flag, the upstream clientmust send the header every time it opens a connection or the connection will be aborted unless it is in the list of disabled hosts provided by theRemoteIPProxyProtocolExceptions directive.

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 for any one of them, then it is enabled for all of 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.

Listen 80<VirtualHost *:80>    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>Listen 8080<VirtualHost *:8080>    ServerName www.example.com    RemoteIPProxyProtocol On    RemoteIPProxyProtocolExceptions 127.0.0.1 10.0.0.0/8    #Requests to this virtual host must have a PROXY protocol    # header provided. If it is missing, the connection will    # be aborted except when coming from localhost or the    # 10.x.x.x RFC1918 range</VirtualHost>

RemoteIPProxyProtocolExceptionsDirective

TheRemoteIPProxyProtocol directive enables or disables the reading and handling of the PROXY protocol connection header. Sometimes it is desirable to require clients to provide the PROXY header, but permit other clients to connect without it. This directive allows a server administrator to configure a single host or CIDR range of hosts that may do so. This is generally useful for monitoring and administrative traffic to a virtual host direct to the server behind the upstream load balancer.

RemoteIPTrustedProxyDirective

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

RemoteIPHeader X-Forwarded-ForRemoteIPTrustedProxy 10.0.2.16/28RemoteIPTrustedProxy proxy.example.com

RemoteIPTrustedProxyListDirective

TheRemoteIPTrustedProxyList 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 theRemoteIPTrustedProxy directive.

RemoteIPHeader X-Forwarded-ForRemoteIPTrustedProxyList conf/trusted-proxies.lst