From: William A. Rowe Jr Date: Thu, 23 Apr 2009 04:07:04 +0000 (+0000) Subject: Introduce new documentation of mod_remoteip X-Git-Tag: 2.3.3~705 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7e794c8a052507f2937384a7109c3f2be2167a42;p=thirdparty%2Fapache%2Fhttpd.git Introduce new documentation of mod_remoteip git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@767781 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_remoteip.xml b/docs/manual/mod/mod_remoteip.xml new file mode 100644 index 00000000000..c50629f0ffd --- /dev/null +++ b/docs/manual/mod/mod_remoteip.xml @@ -0,0 +1,254 @@ + + + + + + + + + +mod_remoteip +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. + + +Base +mod_remoteip.c +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 + 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. + + +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. Processessing + halts when the 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 +Declare the header field which should be parsed for client IP addresses +RemoteIPHeader header-field +server configvirtual host + + +

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 +Declare client intranet IP addresses trusted to present the RemoteIPHeader value +RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ... +server configvirtual host + + +

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 +Declare client intranet IP addresses trusted to present the RemoteIPHeader value +RemoteIPInternalProxyList filename +server configvirtual host + + +

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 seperated 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 +Declare the header field which will record all intermediate IP addresses +RemoteIPProxiesHeader HeaderFieldName +server configvirtual host + + +

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 +Declare client intranet IP addresses trusted to present the RemoteIPHeader value +RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ... +server configvirtual host + + +

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 +Declare client intranet IP addresses trusted to present the RemoteIPHeader value +RemoteIPTrustedProxyList filename +server configvirtual host + + +

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 + + + + + + diff --git a/docs/manual/mod/mod_remoteip.xml.meta b/docs/manual/mod/mod_remoteip.xml.meta new file mode 100644 index 00000000000..0bfcf1e3be6 --- /dev/null +++ b/docs/manual/mod/mod_remoteip.xml.meta @@ -0,0 +1,12 @@ + + + + + mod_remoteip + /mod/ + .. + + + en + +