mod_remoteip.xml revision 4e4a8d70e659908065730286e022078b2d906550
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.
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin<description>Replaces the original client IP address for the connection
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrinwith the useragent IP address list presented by a proxies or a load balancer
2d391792b33e3c27e070739f74d74989c77fea8eminfrinvia the request headers.
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe</description>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>This module is used to treat the useragent which initiated the
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin request as the originating useragent as identified by httpd for the
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin purposes of authorization and logging, even where that useragent is
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe behind a load balancer, front end server, or proxy server.</p>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>The module overrides the client IP address for the connection
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin with the useragent IP address reported in the request header configured
2d391792b33e3c27e070739f74d74989c77fea8eminfrin with the <directive>RemoteIPHeader</directive> directive.</p>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>Once replaced as instructed, this overridden useragent IP address is
2d391792b33e3c27e070739f74d74989c77fea8eminfrin <directive module="mod_authz_host" type="section">Require ip</directive>
2d391792b33e3c27e070739f74d74989c77fea8eminfrin feature, is reported by <module>mod_status</module>, and is recorded by
2a781ea98a32c069ae57a89566ee9628e19a2ec2minfrin <module>mod_log_config</module> <code>%a</code> and <module>core</module>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <code>%a</code> format strings. The underlying client IP of the connection
2d391792b33e3c27e070739f74d74989c77fea8eminfrin is available in the <code>%{c}a</code> format string.</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
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin it is trivial for the remote useragent to impersonate another
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin useragent.</note>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<section id="processing"><title>Remote IP Processing</title>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>Apache by default identifies the useragent with the connection's
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin client_ip value, and the connection remote_host and remote_logname are
2d391792b33e3c27e070739f74d74989c77fea8eminfrin derived from this value. These fields play a role in authentication,
2d391792b33e3c27e070739f74d74989c77fea8eminfrin authorization and logging and other purposes by other loadable
2d391792b33e3c27e070739f74d74989c77fea8eminfrin modules.</p>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>mod_remoteip overrides the client IP of the connection with the
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin advertised useragent IP as provided by a proxy or load balancer, for
2d391792b33e3c27e070739f74d74989c77fea8eminfrin the duration of the request. A load balancer might establish a long
2d391792b33e3c27e070739f74d74989c77fea8eminfrin lived keepalive connection with the server, and each request will
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin have the correct useragent IP, even though the underlying client IP
2d391792b33e3c27e070739f74d74989c77fea8eminfrin address of the load balancer remains unchanged.</p>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>When multiple, comma delimited useragent IP addresses are listed in the
a018efc9e8a265809cf699c801f4a6844368c63algentis header value, they are processed in Right-to-Left order. Processing
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin halts when a given useragent IP address is not trusted to present the
2a781ea98a32c069ae57a89566ee9628e19a2ec2minfrin preceding 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>
2d391792b33e3c27e070739f74d74989c77fea8eminfrin <p>In overriding the client 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>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim internal (intranet) proxies are registered.</note>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<directivesynopsis>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin<description>Declare the header field which should be parsed for useragent IP addresses</description>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<syntax>RemoteIPHeader <var>header-field</var></syntax>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe<contextlist><context>server config</context><context>virtual host</context></contextlist>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>The <directive>RemoteIPHeader</directive> directive triggers
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <module>mod_remoteip</module> to treat the value of the specified
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <var>header-field</var> header as the useragent IP address, or list
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin of intermediate useragent 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
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin RemoteIPHeader value of the useragent IP. Unlike the
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <directive>RemoteIPTrustedProxy</directive> directive, any IP address
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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)
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin to trust as presenting a valid RemoteIPHeader value of the useragent IP.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The '<code>#</code>' hash character designates a comment line, otherwise
a018efc9e8a265809cf699c801f4a6844368c63algentis each whitespace or newline separated 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
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin all of the intermediate client IP addresses trusted to resolve the useragent
2d391792b33e3c27e070739f74d74989c77fea8eminfrin IP of the request. Note that intermediate
2d391792b33e3c27e070739f74d74989c77fea8eminfrin <directive>RemoteIPTrustedProxy</directive> addresses are recorded in
2d391792b33e3c27e070739f74d74989c77fea8eminfrin 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
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin RemoteIPHeader value of the useragent IP. Unlike the
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <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
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin 2000::/3 block) are not trusted as the useragent 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)
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin to trust as presenting a valid RemoteIPHeader value of the useragent IP.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <p>The '<code>#</code>' hash character designates a comment line, otherwise
4e4a8d70e659908065730286e022078b2d906550humbedooh each whitespace or newline separated 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>