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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener with the <directive module="mod_remoteip">RemoteIPHeader</directive> directive.</p>
c41be3600a58bd39a76d1215abcdbbd8e9b1c356minfrin <p>Once replaced as instructed, this overridden useragent IP address is
a6fc6b44b7f8ad7390864b3555341d3abf867f7end <directive module="mod_authz_core" name="Require">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">RemoteIPProxiesHeader</directive>.</p>
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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener evaluated by mod_remoteip when <directive module="mod_remoteip">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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener of the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> and
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directives. Unless these
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe other directives are used, <module>mod_remoteip</module> will trust all
a9b189b5bcf33767c7c29d3682e7452a7f847430covener hosts presenting a <directive module="mod_remoteip">RemoteIPHeader</directive> IP value.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Internal (Load Balancer) Example</title>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Client-IP
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe RemoteIPHeader X-Forwarded-For
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">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>
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPHeader X-Client-IP
70d39834fda98ce22bd29dc44c5fae5c9abe3a06humbedoohRemoteIPInternalProxy gateway.localdomain
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> directive.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Internal (Load Balancer) Example</title>
70d39834fda98ce22bd29dc44c5fae5c9abe3a06humbedoohRemoteIPHeader X-Client-IP
70d39834fda98ce22bd29dc44c5fae5c9abe3a06humbedooh </highlight>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>conf/trusted-proxies.lst contents</title>
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh# Our internally trusted proxies;
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohgateway.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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> addresses are recorded in
2d391792b33e3c27e070739f74d74989c77fea8eminfrin this header, while any intermediate
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">RemoteIPInternalProxy</directive> addresses are discarded.</p>
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPHeader X-Forwarded-For
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPProxiesHeader X-Forwarded-By
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <directive module="mod_remoteip">RemoteIPHeader</directive> header's value.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Trusted (Load Balancer) Example</title>
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPHeader X-Forwarded-For
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPTrustedProxy proxy.example.com
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
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>
a9b189b5bcf33767c7c29d3682e7452a7f847430covener <p>The <directive module="mod_remoteip">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
a9b189b5bcf33767c7c29d3682e7452a7f847430covener the <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directive.</p>
07ab4965db0651f28c3c8d13534003c8f6760fd5wrowe <example><title>Trusted (Load Balancer) Example</title>
3a257106808eabaefbb483bdc6273e7af062ead8humbedoohRemoteIPHeader X-Forwarded-For
3a257106808eabaefbb483bdc6273e7af062ead8humbedooh </highlight>
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>