mod_remoteip.xml revision 07ab4965db0651f28c3c8d13534003c8f6760fd5
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<!-- $LastChangedRevision$ -->
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe Licensed to the Apache Software Foundation (ASF) under one or more
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe contributor license agreements. See the NOTICE file distributed with
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe this work for additional information regarding copyright ownership.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe The ASF licenses this file to You under the Apache License, Version 2.0
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe (the "License"); you may not use this file except in compliance with
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe the License. You may obtain a copy of the License at
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe Unless required by applicable law or agreed to in writing, software
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe distributed under the License is distributed on an "AS IS" BASIS,
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe See the License for the specific language governing permissions and
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe limitations under the License.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Replaces the apparent client remote IP address and hostname
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowefor the request with the IP address list presented by a proxies or a load
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowebalancer via the request headers.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>This module is used to treat the remote host which initiated the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe request as the originating remote host as identified by httpd for the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe purposes of authorization and logging, even where that remote host is
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe behind a load balancer, front end server, or proxy server.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The module replaces the apparent remote (client) IP/hostname for
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe the request with the IP address reported in the request header
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe configured with the <directive>RemoteIPHeader</directive> directive.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>Once replaced as instructed, this apparent IP address is then used
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive module="mod_authz_host" type="section">Require host</directive>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe and <directive module="mod_authz_host" type="section">Require ip</directive>,
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe is reported by <module>mod_status</module>, and is recorded by
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <module>mod_log_config</module> <code>%a</code> and <code>%h</code>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe directives. It also determines the machine probed for an inetd
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive module="mod_ident">IdentityCheck</directive> configuration.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <note type="warning">It is critical to only enable this behavior from
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe intermediate hosts (proxies, etc) which are trusted by this server, since
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe it is trivial for the remote client to impersonate another client.</note>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<section id="processing"><title>Remote IP Processing</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>Apache identifies the client with the connection's remote_ip value,
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe and the connection remote_host and remote_logname are derived from this
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe value. These fields play a role in authentication, authorization and
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe logging and other purposes by other loadable modules.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>mod_remoteip replaces the true remote_ip with the advertised remote_ip as
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe provided by a proxy, for every evaluation of the client that occurs in the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe server, and resets the remote_host and remote_logname values to trigger a
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe fresh dns or ident query of the remote IP address.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>When multiple, comma delimited remote IP addresses are listed in the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe header value, they are processed in Right-to-Left order. Processessing
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe halts when the a given remote IP address is not trusted to present the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe preceeding IP address. The header field is updated to this remaining
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe list of unconfirmed IP addresses, or if all IP addresses were trusted,
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe this header is removed from the request altogether.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>In replacing the remote_ip, the module stores the list of intermediate
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe hosts in a remoteip-proxy-ip-list note, which <module>mod_log_config</module>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe If the administrator needs to store this as an additional header, this
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe same value can also be recording as a header using the directive
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe in their IPv4 representation.</note>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe evaluated by mod_remoteip when <directive>RemoteIPInternalProxy</directive>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe internal (intranet) proxies are registered.</note>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare the header field which should be parsed for client IP addresses</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPHeader <var>header-field</var></syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPHeader</directive> directive triggers
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <module>mod_remoteip</module> to treat the value of the specified
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <var>header-field</var> header as the client IP address, or list
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe of intermediate client IP addresses, subject to further configuration
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe of the <directive>RemoteIPInternalProxy</directive> and
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPTrustedProxy</directive> directives. Unless these
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe other directives are used, <module>mod_remoteip</module> will trust all
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe hosts presenting a <directive>RemoteIPHeader</directive> IP value.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Internal (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Client-IP
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Forwarded-For
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPInternalProxy</directive> directive adds one
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe or more addresses (or address blocks) to trust as presenting a valid
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader value of the client IP. Unlike the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPTrustedProxy</directive> directive, any IP address
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe presented in this header, including private intranet addresses, are
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe trusted when passed from these proxies.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Internal (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Client-IP<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPTrustedProxy gateway.localdomain
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPInternalProxyList <var>filename</var></syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPInternalProxyList</directive> directive specifies
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe a file parsed at startup, and builds a list of addresses (or address blocks)
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The '<code>#</code>' hash character designates a comment line, otherwise
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe each whitespace or newline seperated entry is processed identically to
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe the <directive>RemoteIPInternalProxy</directive> directive.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Internal (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Client-IP<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>conf/trusted-proxies.lst contents</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe # Our internally trusted proxies;<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe gateway.localdomain #The front end balancer
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare the header field which will record all intermediate IP addresses</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPProxiesHeader <var>HeaderFieldName</var></syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPProxiesHeader</directive> directive specifies
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe a header into which <module>mod_remoteip</module> will collect a list of
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe all of the intermediate client IP addresses trusted to resolve the actual
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe remote IP. Note that intermediate <directive>RemoteIPTrustedProxy</directive>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe addresses are recorded in this header, while any intermediate
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPInternalProxy</directive> addresses are discarded.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Forwarded-For<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPProxiesHeader X-Forwarded-By
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPTrustedProxy</directive> directive adds one
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe or more addresses (or address blocks) to trust as presenting a valid
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader value of the client IP. Unlike the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPInternalProxy</directive> directive, any intranet
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe or private IP address reported by such proxies, including the 10/8, 172.16/12,
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe 192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe 2000::/3 block) are not trusted as the remote IP, and are left in the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPHeader</directive> header's value.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Trusted (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Forwarded-For<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPTrustedProxy proxy.example.com
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPTrustedProxyList <var>filename</var></syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The <directive>RemoteIPTrustedProxyList</directive> directive specifies
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe a file parsed at startup, and builds a list of addresses (or address blocks)
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe to trust as presenting a valid RemoteIPHeader value of the client IP.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The '<code>#</code>' hash character designates a comment line, otherwise
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe each whitespace or newline seperated entry is processed identically to
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe the <directive>RemoteIPTrustedProxy</directive> directive.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Trusted (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Forwarded-For<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>conf/trusted-proxies.lst contents</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe # Identified external proxies;<br/>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe proxy.isp.example.com #some well known ISP
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</directivesynopsis>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</modulesynopsis>