From 8c8f815c1b77ea8339f1e5b54fa408f1676aa40f Mon Sep 17 00:00:00 2001 From: Graham Leggett Date: Wed, 30 Nov 2011 20:28:25 +0000 Subject: [PATCH] Clarify the peer IP of the connection and the client IP of the request within the docs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1208753 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/expr.xml | 2 +- docs/manual/mod/core.xml | 4 +- docs/manual/mod/mod_log_config.xml | 6 +-- docs/manual/mod/mod_remoteip.xml | 63 ++++++++++++++++-------------- 4 files changed, 40 insertions(+), 35 deletions(-) diff --git a/docs/manual/expr.xml b/docs/manual/expr.xml index 417f793522..9b18d7faf7 100644 --- a/docs/manual/expr.xml +++ b/docs/manual/expr.xml @@ -238,7 +238,7 @@ listfunction ::= listfuncname "(" word ")" The error log id of the connection (see ErrorLogFormat) CONN_REMOTE_ADDR - The raw IP address of the remote host (see the + The peer IP address of the connection (see the mod_remoteip module) diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index 203c1cb0c8..1486adef82 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -1375,10 +1375,10 @@ in case of an error The percent sign %a - Remote IP-address and port + Client IP address and port of the request %{c}a - Actual remote IP-address and port (see the + Underlying peer IP address and port of the connection (see the mod_remoteip module) %A diff --git a/docs/manual/mod/mod_log_config.xml b/docs/manual/mod/mod_log_config.xml index 907bfda4a2..85ee5c89aa 100644 --- a/docs/manual/mod/mod_log_config.xml +++ b/docs/manual/mod/mod_log_config.xml @@ -71,11 +71,11 @@ The percent sign. %a - Remote IP-address. + Client IP address and port of the request. %{c}a - Actual remote IP-address and port (see the - mod_remoteip module) + Underlying peer IP address and port of the connection (see the + mod_remoteip module). %A Local IP-address. diff --git a/docs/manual/mod/mod_remoteip.xml b/docs/manual/mod/mod_remoteip.xml index 547542c748..14ad97ed33 100644 --- a/docs/manual/mod/mod_remoteip.xml +++ b/docs/manual/mod/mod_remoteip.xml @@ -23,9 +23,9 @@ mod_remoteip -Replaces the apparent client remote IP address for the request -with the IP address list presented by a proxies or a load balancer via the -request headers. +Replaces the original peer IP address for the connection +with the client IP address list presented by a proxies or a load balancer +via the request headers. Base @@ -33,22 +33,22 @@ request headers. remoteip_module -

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 +

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

-

The module overrides the apparent remote (client) IP for - the request with the IP address reported in the request header - configured with the RemoteIPHeader directive.

+

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

-

Once replaced as instructed, this apparent IP address is then used - for the mod_authz_host - Require ip feature, - is reported by mod_status, and is recorded by +

Once replaced as instructed, this overridden client 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 original remote IP of the connection is - available in the %{c}a format string.

+ %a format strings. The underlying peer 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 @@ -61,23 +61,27 @@ request headers.
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.

+

Apache by default identifies the client with the connection's + peer_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.

+

mod_remoteip overrides the peer IP of the connection with the + advertised client 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 client IP, even though the underlying peer IP + address of the load balancer remains unchanged.

-

When multiple, comma delimited remote IP addresses are listed in the +

When multiple, comma delimited client 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 + halts when a given client 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 replacing the remote_ip, the module stores the list of intermediate +

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 @@ -181,9 +185,10 @@ request headers.

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 + all of the intermediate client IP addresses trusted to resolve the client + IP of the request. Note that intermediate + RemoteIPTrustedProxy addresses are recorded in + this header, while any intermediate RemoteIPInternalProxy addresses are discarded.

Example @@ -206,7 +211,7 @@ request headers. 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 + 2000::/3 block) are not trusted as the client IP, and are left in the RemoteIPHeader header's value.

Trusted (Load Balancer) Example -- 2.40.0