mirror of
https://github.com/apache/httpd.git
synced 2025-08-10 02:56:11 +00:00
178449b8cc
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1806985 13f79535-47bb-0310-9956-ffa450edef68
359 lines
16 KiB
XML
359 lines
16 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_remoteip.xml.meta">
|
|
|
|
<name>mod_remoteip</name>
|
|
<description>Replaces the original client IP address for the connection
|
|
with the useragent IP address list presented by a proxies or a load balancer
|
|
via the request headers.
|
|
</description>
|
|
|
|
<status>Base</status>
|
|
<sourcefile>mod_remoteip.c</sourcefile>
|
|
<identifier>remoteip_module</identifier>
|
|
|
|
<summary>
|
|
<p>This module is used to treat the useragent which initiated the
|
|
request as the originating useragent as identified by httpd for the
|
|
purposes of authorization and logging, even where that useragent is
|
|
behind a load balancer, front end server, or proxy server.</p>
|
|
|
|
<p>The module overrides the client IP address for the connection
|
|
with the useragent IP address reported in the request header configured
|
|
with the <directive module="mod_remoteip">RemoteIPHeader</directive> directive.</p>
|
|
|
|
<p>Additionally, this module implements the server side of
|
|
HAProxy's
|
|
<a href="http://blog.haproxy.com/haproxy/proxy-protocol/">PROXY Protocol</a> when
|
|
using the <directive module="mod_remoteip">RemoteIPProxyProtocol</directive>
|
|
directive.</p>
|
|
|
|
<p>Once replaced as instructed, this overridden useragent IP address is
|
|
then used for the <module>mod_authz_host</module>
|
|
<directive module="mod_authz_core" name="Require">Require ip</directive>
|
|
feature, is reported by <module>mod_status</module>, and is recorded by
|
|
<module>mod_log_config</module> <code>%a</code> and <module>core</module>
|
|
<code>%a</code> format strings. The underlying client IP of the connection
|
|
is available in the <code>%{c}a</code> format string.</p>
|
|
|
|
<note type="warning">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 useragent to impersonate another
|
|
useragent.</note>
|
|
</summary>
|
|
|
|
<seealso><module>mod_authz_host</module></seealso>
|
|
<seealso><module>mod_status</module></seealso>
|
|
<seealso><module>mod_log_config</module></seealso>
|
|
<seealso><a href="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">Proxy Protocol Spec</a></seealso>
|
|
|
|
<section id="processing"><title>Remote IP Processing</title>
|
|
|
|
<p>Apache by default identifies the useragent with the connection's
|
|
client_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.</p>
|
|
|
|
<p>mod_remoteip overrides the client IP of the connection with the
|
|
advertised useragent 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 useragent IP, even though the underlying client IP
|
|
address of the load balancer remains unchanged.</p>
|
|
|
|
<p>When multiple, comma delimited useragent IP addresses are listed in the
|
|
header value, they are processed in Right-to-Left order. Processing
|
|
halts when a given useragent 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.</p>
|
|
|
|
<p>In overriding the client IP, the module stores the list of intermediate
|
|
hosts in a remoteip-proxy-ip-list note, which <module>mod_log_config</module>
|
|
can record using the <code>%{remoteip-proxy-ip-list}n</code> 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
|
|
<directive module="mod_remoteip">RemoteIPProxiesHeader</directive>.</p>
|
|
|
|
<note><title>IPv4-over-IPv6 Mapped Addresses</title>
|
|
As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
|
|
in their IPv4 representation.</note>
|
|
|
|
<note><title>Internal (Private) Addresses</title>
|
|
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 <directive module="mod_remoteip">RemoteIPInternalProxy</directive>
|
|
internal (intranet) proxies are registered.</note>
|
|
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPHeader</name>
|
|
<description>Declare the header field which should be parsed for useragent IP addresses</description>
|
|
<syntax>RemoteIPHeader <var>header-field</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPHeader</directive> directive triggers
|
|
<module>mod_remoteip</module> to treat the value of the specified
|
|
<var>header-field</var> header as the useragent IP address, or list
|
|
of intermediate useragent IP addresses, subject to further configuration
|
|
of the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> and
|
|
<directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directives.</p>
|
|
|
|
<note type="warning"> Unless these other directives are used, <module>mod_remoteip</module>
|
|
will trust all hosts presenting a non internal address in the
|
|
<directive module="mod_remoteip">RemoteIPHeader</directive> header value.
|
|
</note>
|
|
|
|
<example><title>Internal (Load Balancer) Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Client-IP
|
|
</highlight>
|
|
</example>
|
|
|
|
<example><title>Proxy Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Forwarded-For
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPInternalProxy</name>
|
|
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
|
|
<syntax>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPInternalProxy</directive> directive adds one
|
|
or more addresses (or address blocks) to trust as presenting a valid
|
|
RemoteIPHeader value of the useragent IP. Unlike the
|
|
<directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directive, any IP address
|
|
presented in this header, including private intranet addresses, are
|
|
trusted when passed from these proxies.</p>
|
|
|
|
<example><title>Internal (Load Balancer) Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Client-IP
|
|
RemoteIPInternalProxy 10.0.2.0/24
|
|
RemoteIPInternalProxy gateway.localdomain
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPInternalProxyList</name>
|
|
<description>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</description>
|
|
<syntax>RemoteIPInternalProxyList <var>filename</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPInternalProxyList</directive> 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 useragent IP.</p>
|
|
|
|
<p>The '<code>#</code>' hash character designates a comment line, otherwise
|
|
each whitespace or newline separated entry is processed identically to
|
|
the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> directive.</p>
|
|
|
|
<example><title>Internal (Load Balancer) Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Client-IP
|
|
RemoteIPInternalProxyList conf/trusted-proxies.lst
|
|
</highlight>
|
|
</example>
|
|
|
|
<example><title>conf/trusted-proxies.lst contents</title>
|
|
<pre>
|
|
# Our internally trusted proxies;
|
|
10.0.2.0/24 #Everyone in the testing group
|
|
gateway.localdomain #The front end balancer
|
|
</pre>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPProxiesHeader</name>
|
|
<description>Declare the header field which will record all intermediate IP addresses</description>
|
|
<syntax>RemoteIPProxiesHeader <var>HeaderFieldName</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPProxiesHeader</directive> directive specifies
|
|
a header into which <module>mod_remoteip</module> will collect a list of
|
|
all of the intermediate client IP addresses trusted to resolve the useragent
|
|
IP of the request. Note that intermediate
|
|
<directive module="mod_remoteip">RemoteIPTrustedProxy</directive> addresses are recorded in
|
|
this header, while any intermediate
|
|
<directive module="mod_remoteip">RemoteIPInternalProxy</directive> addresses are discarded.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Forwarded-For
|
|
RemoteIPProxiesHeader X-Forwarded-By
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPProxyProtocol</name>
|
|
<description>Enable or disable PROXY protocol handling</description>
|
|
<syntax>RemoteIPProxyProtocol On|Off</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>RemoteIPProxyProtocol is only available in httpd 2.4.28 and newer</compatibility>
|
|
|
|
<usage>
|
|
<p>The <directive>RemoteIPProxyProtocol</directive> directive enables or
|
|
disables the reading and handling of the PROXY protocol connection header.
|
|
If enabled with the <code>On</code> flag, the upstream client <em>must</em>
|
|
send the header every time it opens a connection or the connection will
|
|
be aborted unless it is in the list of disabled hosts provided by the
|
|
<directive module="mod_remoteip">RemoteIPProxyProtocolExceptions</directive>
|
|
directive.</p>
|
|
|
|
<p>While this directive may be specified in any virtual host, it is
|
|
important to understand that because the PROXY protocol is connection
|
|
based and protocol agnostic, the enabling and disabling is actually based
|
|
on IP address and port. This means that if you have multiple name-based
|
|
virtual hosts for the same host and port, and you enable it for any one of
|
|
them, then it is enabled for all of them (with that host and port). It also
|
|
means that if you attempt to enable the PROXY protocol in one and disable
|
|
in the other, that won't work; in such a case, the last one wins and a
|
|
notice will be logged indicating which setting was being overridden.</p>
|
|
|
|
<highlight language="config">
|
|
Listen 80
|
|
<VirtualHost *:80>
|
|
ServerName www.example.com
|
|
RemoteIPProxyProtocol On
|
|
|
|
#Requests to this virtual host must have a PROXY protocol
|
|
# header provided. If it is missing, the connection will
|
|
# be aborted
|
|
</VirtualHost>
|
|
|
|
Listen 8080
|
|
<VirtualHost *:8080>
|
|
ServerName www.example.com
|
|
RemoteIPProxyProtocol On
|
|
RemoteIPProxyProtocolExceptions 127.0.0.1 10.0.0.0/8
|
|
|
|
#Requests to this virtual host must have a PROXY protocol
|
|
# header provided. If it is missing, the connection will
|
|
# be aborted except when coming from localhost or the
|
|
# 10.x.x.x RFC1918 range
|
|
</VirtualHost>
|
|
</highlight>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPProxyProtocolExceptions</name>
|
|
<description>Disable processing of PROXY header for certain hosts or networks</description>
|
|
<syntax>RemoteIPProxyProtocolExceptions host|range [host|range] [host|range]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>RemoteIPProxyProtocolExceptions is only available in httpd 2.4.28 and newer</compatibility>
|
|
|
|
<usage>
|
|
<p>The <directive>RemoteIPProxyProtocol</directive> directive enables or
|
|
disables the reading and handling of the PROXY protocol connection header.
|
|
Sometimes it is desirable to require clients to provide the PROXY header, but
|
|
permit other clients to connect without it. This directive allows a server
|
|
administrator to configure a single host or CIDR range of hosts that may do
|
|
so.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPTrustedProxy</name>
|
|
<description>Restrict client IP addresses trusted to present the RemoteIPHeader value</description>
|
|
<syntax>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPTrustedProxy</directive>
|
|
directive restricts which peer IP addresses (or address blocks) will be
|
|
trusted to present a valid RemoteIPHeader value of the useragent IP.</p>
|
|
|
|
<p> Unlike the <directive module="mod_remoteip">RemoteIPInternalProxy</directive> 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 useragent IP, and are left in the
|
|
<directive module="mod_remoteip">RemoteIPHeader</directive> header's value.</p>
|
|
|
|
<note type="warning">By default, <module>mod_remoteip</module> will trust
|
|
all hosts presenting a non internal address in the
|
|
<directive module="mod_remoteip">RemoteIPHeader</directive> header value.
|
|
</note>
|
|
|
|
<example><title>Trusted (Load Balancer) Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Forwarded-For
|
|
RemoteIPTrustedProxy 10.0.2.16/28
|
|
RemoteIPTrustedProxy proxy.example.com
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RemoteIPTrustedProxyList</name>
|
|
<description>Restrict client IP addresses trusted to present the RemoteIPHeader value</description>
|
|
<syntax>RemoteIPTrustedProxyList <var>filename</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_remoteip">RemoteIPTrustedProxyList</directive> 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 useragent IP.</p>
|
|
|
|
<p>The '<code>#</code>' hash character designates a comment line, otherwise
|
|
each whitespace or newline separated entry is processed identically to
|
|
the <directive module="mod_remoteip">RemoteIPTrustedProxy</directive> directive.</p>
|
|
|
|
<example><title>Trusted (Load Balancer) Example</title>
|
|
<highlight language="config">
|
|
RemoteIPHeader X-Forwarded-For
|
|
RemoteIPTrustedProxyList conf/trusted-proxies.lst
|
|
</highlight>
|
|
</example>
|
|
|
|
<example><title>conf/trusted-proxies.lst contents</title>
|
|
# Identified external proxies;<br/>
|
|
192.0.2.16/28 #wap phone group of proxies<br/>
|
|
proxy.isp.example.com #some well known ISP
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
|
|
</modulesynopsis>
|