mod_remoteip.html.en revision e487d6c09669296f94a5190cc34586a98e624a00
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster This file is generated from xml source: DO NOT EDIT
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<title>mod_remoteip - Apache HTTP Server</title>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<script src="/style/scripts/prettify.js" type="text/javascript">
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<link href="/images/favicon.ico" rel="shortcut icon" /></head>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<p class="apache">Apache HTTP Server Version 2.5</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<div id="preamble"><h1>Apache Module mod_remoteip</h1>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper<p><span>Available Languages: </span><a href="/en/mod/mod_remoteip.html" title="English"> en </a> |
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<a href="/fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Replaces the original client IP address for the connection
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterwith the useragent IP address list presented by a proxies or a load balancer
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fostervia the request headers.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>remoteip_module</td></tr>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_remoteip.c</td></tr></table>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>This module is used to treat the useragent which initiated the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster request as the originating useragent as identified by httpd for the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster purposes of authorization and logging, even where that useragent is
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster behind a load balancer, front end server, or proxy server.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>The module overrides the client IP address for the connection
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster with the useragent IP address reported in the request header configured
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster with the <code class="directive">RemoteIPHeader</code> directive.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Once replaced as instructed, this overridden useragent IP address is
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster then used for the <code class="module"><a href="/mod/mod_authz_host.html">mod_authz_host</a></code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <code class="directive"><a href="/mod/mod_authz_host.html#require ip"><Require ip></a></code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster feature, is reported by <code class="module"><a href="/mod/mod_status.html">mod_status</a></code>, and is recorded by
74dca04245920444925c2544c591c3da5dad607eAndrew Forrest <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code> <code>%a</code> and <code class="module"><a href="/mod/core.html">core</a></code>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper <code>%a</code> format strings. The underlying client IP of the connection
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper is available in the <code>%{c}a</code> format string.</p>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper <div class="warning">It is critical to only enable this behavior from
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper intermediate hosts (proxies, etc) which are trusted by this server, since
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper it is trivial for the remote useragent to impersonate another
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper useragent.</div>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper<div id="quickview"><h3 class="directives">Directives</h3>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper<li><img alt="" src="/images/down.gif" /> <a href="#remoteipheader">RemoteIPHeader</a></li>
be56b0499bf4793872f73b8042ffacb3cf7e575eMark de Reeper<li><img alt="" src="/images/down.gif" /> <a href="#remoteipinternalproxy">RemoteIPInternalProxy</a></li>
74dca04245920444925c2544c591c3da5dad607eAndrew Forrest<li><img alt="" src="/images/down.gif" /> <a href="#remoteipinternalproxylist">RemoteIPInternalProxyList</a></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<li><img alt="" src="/images/down.gif" /> <a href="#remoteipproxiesheader">RemoteIPProxiesHeader</a></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<li><img alt="" src="/images/down.gif" /> <a href="#remoteiptrustedproxy">RemoteIPTrustedProxy</a></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<li><img alt="" src="/images/down.gif" /> <a href="#remoteiptrustedproxylist">RemoteIPTrustedProxyList</a></li>
74dca04245920444925c2544c591c3da5dad607eAndrew Forrest<li><img alt="" src="/images/down.gif" /> <a href="#processing">Remote IP Processing</a></li>
74dca04245920444925c2544c591c3da5dad607eAndrew Forrest<li><code class="module"><a href="/mod/mod_authz_host.html">mod_authz_host</a></code></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<li><code class="module"><a href="/mod/mod_status.html">mod_status</a></code></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<li><code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code></li>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<h2><a name="processing" id="processing">Remote IP Processing</a></h2>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Apache by default identifies the useragent with the connection's
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster client_ip value, and the connection remote_host and remote_logname are
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster derived from this value. These fields play a role in authentication,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster authorization and logging and other purposes by other loadable
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster modules.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>mod_remoteip overrides the client IP of the connection with the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster advertised useragent IP as provided by a proxy or load balancer, for
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster the duration of the request. A load balancer might establish a long
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster lived keepalive connection with the server, and each request will
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster have the correct useragent IP, even though the underlying client IP
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster address of the load balancer remains unchanged.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>When multiple, comma delimited useragent IP addresses are listed in the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster header value, they are processed in Right-to-Left order. Processing
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster halts when a given useragent IP address is not trusted to present the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster preceding IP address. The header field is updated to this remaining
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster list of unconfirmed IP addresses, or if all IP addresses were trusted,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster this header is removed from the request altogether.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>In overriding the client IP, the module stores the list of intermediate
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster hosts in a remoteip-proxy-ip-list note, which <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster If the administrator needs to store this as an additional header, this
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster same value can also be recording as a header using the directive
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <code class="directive">RemoteIPProxiesHeader</code>.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <div class="note"><h3>IPv4-over-IPv6 Mapped Addresses</h3>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster in their IPv4 representation.</div>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <div class="note"><h3>Internal (Private) Addresses</h3>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
<div class="directive-section"><h2><a name="RemoteIPHeader" id="RemoteIPHeader">RemoteIPHeader</a> <a name="remoteipheader" id="remoteipheader">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare the header field which should be parsed for useragent IP addresses</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPHeader <var>header-field</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<code class="module"><a href="/mod/mod_remoteip.html">mod_remoteip</a></code> to treat the value of the specified
other directives are used, <code class="module"><a href="/mod/mod_remoteip.html">mod_remoteip</a></code> will trust all
<div class="directive-section"><h2><a name="RemoteIPInternalProxy" id="RemoteIPInternalProxy">RemoteIPInternalProxy</a> <a name="remoteipinternalproxy" id="remoteipinternalproxy">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
RemoteIPTrustedProxy gateway.localdomain
<div class="directive-section"><h2><a name="RemoteIPInternalProxyList" id="RemoteIPInternalProxyList">RemoteIPInternalProxyList</a> <a name="remoteipinternalproxylist" id="remoteipinternalproxylist">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPInternalProxyList <var>filename</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
gateway.localdomain #The front end balancer
<div class="directive-section"><h2><a name="RemoteIPProxiesHeader" id="RemoteIPProxiesHeader">RemoteIPProxiesHeader</a> <a name="remoteipproxiesheader" id="remoteipproxiesheader">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare the header field which will record all intermediate IP addresses</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPProxiesHeader <var>HeaderFieldName</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
a header into which <code class="module"><a href="/mod/mod_remoteip.html">mod_remoteip</a></code> will collect a list of
<div class="directive-section"><h2><a name="RemoteIPTrustedProxy" id="RemoteIPTrustedProxy">RemoteIPTrustedProxy</a> <a name="remoteiptrustedproxy" id="remoteiptrustedproxy">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
RemoteIPTrustedProxy proxy.example.com
<div class="directive-section"><h2><a name="RemoteIPTrustedProxyList" id="RemoteIPTrustedProxyList">RemoteIPTrustedProxyList</a> <a name="remoteiptrustedproxylist" id="remoteiptrustedproxylist">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RemoteIPTrustedProxyList <var>filename</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
proxy.isp.example.com #some well known ISP
<p><span>Available Languages: </span><a href="/en/mod/mod_remoteip.html" title="English"> en </a> |
<a href="/fr/mod/mod_remoteip.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript">