Apache HTTP Server Version 2.3

Apache > HTTP Server > Documentation > Version 2.3 > Modules

# Apache Module mod_remoteip

Available Languages: en | fr

Description: | Replaces the apparent client remote IP address and hostname for the request with the 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

### Summary

This module is used to treat the remote host which initiated the request as the originating remote host as identified by httpd for the purposes of authorization and logging, even where that remote host is behind a load balancer, front end server, or proxy server.

The module replaces the apparent remote (client) IP/hostname for the request with the IP address reported in the request header configured with the `RemoteIPHeader` directive.

Once replaced as instructed, this apparent IP address is then used for `mod_authz_host` features `<Require host>` and `<Require ip>`, is reported by `mod_status`, and is recorded by `mod_log_config` `%a` and `%h` directives. It also determines the machine probed for an inetd identity by `mod_ident` based on the `IdentityCheck` configuration.

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 client to impersonate another client.

### Directives

### Topics

- Remote IP Processing

### See also

- `mod_authz_host`
- `mod_status`
- `mod_log_config`
- `mod_ident`

## Remote IP Processing

Apache identifies the client with the connection's remote_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 replaces the true remote_ip with the advertised remote_ip as provided by a proxy, for every evaluation of the client that occurs in the server, and resets the remote_host and remote_logname values to trigger a fresh dns or ident query of the remote IP address.

When multiple, comma delimited remote IP addresses are listed in the header value, they are processed in Right-to-Left order. Processing halts when a given remote IP address is not trusted to present the preceeding 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 replacing the remote_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.

## RemoteIPHeader Directive

Description: | Declare the header field which should be parsed for client 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 client IP address, or list of intermediate client 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.

### Internal (Load Balancer) Example

`RemoteIPHeader X-Client-IP`

### Proxy Example

`RemoteIPHeader X-Forwarded-For`

## RemoteIPInternalProxy Directive

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 client IP. Unlike the `RemoteIPTrustedProxy` directive, any IP address presented in this header, including private intranet addresses, are trusted when passed from these proxies.

### Internal (Load Balancer) Example

`RemoteIPHeader X-Client-IP
RemoteIPTrustedProxy 10.0.2.0/24
RemoteIPTrustedProxy gateway.localdomain`

## RemoteIPInternalProxyList Directive

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 client IP.

The '`#`' hash character designates a comment line, otherwise each whitespace or newline separated entry is processed identically to the `RemoteIPInternalProxy` directive.

### Internal (Load Balancer) Example

`RemoteIPHeader X-Client-IP
RemoteIPTrustedProxyList conf/trusted-proxies.lst`

### 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 Directive

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 actual remote IP. Note that intermediate `RemoteIPTrustedProxy` addresses are recorded in this header, while any intermediate `RemoteIPInternalProxy` addresses are discarded.

### Example

`RemoteIPHeader X-Forwarded-For
RemoteIPProxiesHeader X-Forwarded-By`

## RemoteIPTrustedProxy Directive

Description: | Declare client intranet 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 adds one or more addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the client 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 remote IP, and are left in the `RemoteIPHeader` header's value.

### Trusted (Load Balancer) Example

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

## RemoteIPTrustedProxyList Directive

Description: | Declare client intranet 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 client IP.

The '`#`' hash character designates a comment line, otherwise each whitespace or newline seperated entry is processed identically to the `RemoteIPTrustedProxy` directive.

### Trusted (Load Balancer) Example

`RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxyList conf/trusted-proxies.lst`

### 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`

Available Languages: en | fr