Author: markt
Date: Wed Apr 14 23:17:26 2010
New Revision: 934239
URL: http://svn.apache.org/viewvc?rev=934239&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=49024
Enhance the RemoteIpFilter docs
Patch provided by Cyrille Le Clerc
Modified:
tomcat/trunk/webapps/docs/config/filter.xml
Modified: tomcat/trunk/webapps/docs/config/filter.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/filter.xml?rev=934239&r1=934238&r2=934239&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/filter.xml (original)
+++ tomcat/trunk/webapps/docs/config/filter.xml Wed Apr 14 23:17:26 2010
@@ -226,6 +226,296 @@
</subsection>
+ <subsection name="Basic configuration to handle 'x-forwarded-for'">
+ <p>
+ The filter will process the <tt>x-forwarded-for</tt> http header.
+ </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>RemoteIpFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ </filter-mapping>
+ </source>
+ </subsection>
+
+ <subsection name="Basic configuration to handle 'x-forwarded-for'
and 'x-forwarded-proto'">
+
+ <p>
+ The filter will process <tt>x-forwarded-for</tt> and
+ <tt>x-forwarded-proto</tt> http headers. Expected value for the
+ <tt>x-forwarded-proto</tt> header in case of SSL connections is
+ <tt>https</tt> (case insensitive). </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ <init-param>
+ <param-name>protocolHeader</param-name>
+ <param-value>x-forwarded-proto</param-value>
+ </init-param>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>RemoteIpFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ </filter-mapping>
+ </source>
+ </subsection>
+
+ <subsection name="Advanced configuration with internal proxies">
+ <p>RemoteIpFilter configuration: </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ <init-param>
+ <param-name>allowedInternalProxies</param-name>
+ <param-value>192\.168\.0\.10,
192\.168\.0\.11</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPHeader</param-name>
+ <param-value>x-forwarded-for</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPProxiesHeader</param-name>
+ <param-value>x-forwarded-by</param-value>
+ </init-param>
+ <init-param>
+ <param-name>protocolHeader</param-name>
+ <param-value>x-forwarded-proto</param-value>
+ </init-param>
+ </filter>
+ </source>
+ <p>Request values:
+ <table border="1" cellpadding="5">
+ <tr>
+ <th bgcolor="#023264"><font color="#ffffff">Property</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value Before
RemoteIpFilter</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value After
RemoteIpFilter</font></th>
+ </tr>
+ <tr>
+ <td> request.remoteAddr </td>
+ <td> 192.168.0.10 </td>
+ <td> 140.211.11.130 </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-for'<tt>]</tt>
</td>
+ <td> 140.211.11.130, 192.168.0.10 </td>
+ <td> null </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-by'<tt>]</tt> </td>
+ <td> null </td>
+ <td> null </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-proto'<tt>]</tt>
</td>
+ <td> https </td>
+ <td> https </td>
+ </tr>
+ <tr>
+ <td> request.scheme </td>
+ <td> http </td>
+ <td> https </td>
+ </tr>
+ <tr>
+ <td> request.secure </td>
+ <td> false </td>
+ <td> true </td>
+ </tr>
+ <tr>
+ <td> request.serverPort </td>
+ <td> 80 </td>
+ <td> 443 </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ Note : <tt>x-forwarded-by</tt> header is <tt>null</tt> because only
+ internal proxies has been traversed by the request.
+ <tt>x-forwarded-for</tt> is <tt>null</tt> because all the proxies are
+ trusted or internal.
+ </p>
+ </subsection>
+
+
+ <subsection name="Advanced configuration with trusted proxies">
+ <p>RemoteIpFilter configuration: </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ <init-param>
+ <param-name>allowedInternalProxies</param-name>
+ <param-value>192\.168\.0\.10,
192\.168\.0\.11</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPHeader</param-name>
+ <param-value>x-forwarded-for</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPProxiesHeader</param-name>
+ <param-value>x-forwarded-by</param-value>
+ </init-param>
+ <init-param>
+ <param-name>trustedProxies</param-name>
+ <param-value>proxy1, proxy2</param-value>
+ </init-param>
+ </filter>
+ </source>
+ <p>Request values: <table border="1" cellpadding="5">
+ <tr>
+ <th bgcolor="#023264"><font color="#ffffff">Property</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value Before
RemoteIpFilter</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value After
RemoteIpFilter</font></th>
+ </tr>
+ <tr>
+ <td> request.remoteAddr </td>
+ <td> 192.168.0.10 </td>
+ <td> 140.211.11.130 </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-for'<tt>]</tt>
</td>
+ <td> 140.211.11.130, proxy1, proxy2 </td>
+ <td> null </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-by'<tt>]</tt> </td>
+ <td> null </td>
+ <td> proxy1, proxy2 </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ Note : <tt>proxy1</tt> and <tt>proxy2</tt> are both trusted proxies that
+ come in <tt>x-forwarded-for</tt> header, they both are migrated in
+ <tt>x-forwarded-by</tt> header. <tt>x-forwarded-for</tt> is <tt>null</tt>
+ because all the proxies are trusted or internal.
+ </p>
+ </subsection>
+
+ <subsection name="Advanced configuration with internal and trusted proxies">
+ <p>RemoteIpFilter configuration: </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ <init-param>
+ <param-name>allowedInternalProxies</param-name>
+ <param-value>192\.168\.0\.10,
192\.168\.0\.11</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPHeader</param-name>
+ <param-value>x-forwarded-for</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPProxiesHeader</param-name>
+ <param-value>x-forwarded-by</param-value>
+ </init-param>
+ <init-param>
+ <param-name>trustedProxies</param-name>
+ <param-value>proxy1, proxy2</param-value>
+ </init-param>
+ </filter>
+ </source>
+ <p>Request values: <table border="1" cellpadding="5">
+ <tr>
+ <th bgcolor="#023264"><font color="#ffffff">Property</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value Before
RemoteIpFilter</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value After
RemoteIpFilter</font></th>
+ </tr>
+ <tr>
+ <td> request.remoteAddr </td>
+ <td> 192.168.0.10 </td>
+ <td> 140.211.11.130 </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-for'<tt>]</tt>
</td>
+ <td> 140.211.11.130, proxy1, proxy2, 192.168.0.10 </td>
+ <td> null </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-by'<tt>]</tt> </td>
+ <td> null </td>
+ <td> proxy1, proxy2 </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ Note : <tt>proxy1</tt> and <tt>proxy2</tt> are both trusted proxies that
+ come in <tt>x-forwarded-for</tt> header, they both are migrated in
+ <tt>x-forwarded-by</tt> header. As <tt>192.168.0.10</tt> is an internal
+ proxy, it does not appear in <tt>x-forwarded-by</tt>.
+ <tt>x-forwarded-for</tt> is <tt>null</tt> because all the proxies are
+ trusted or internal.
+ </p>
+ </subsection>
+
+ <subsection name="Advanced configuration with an untrusted proxy">
+
+ <p>RemoteIpFilter configuration: </p>
+ <source>
+ <filter>
+ <filter-name>RemoteIpFilter</filter-name>
+
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
+ <init-param>
+ <param-name>allowedInternalProxies</param-name>
+ <param-value>192\.168\.0\.10,
192\.168\.0\.11</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPHeader</param-name>
+ <param-value>x-forwarded-for</param-value>
+ </init-param>
+ <init-param>
+ <param-name>remoteIPProxiesHeader</param-name>
+ <param-value>x-forwarded-by</param-value>
+ </init-param>
+ <init-param>
+ <param-name>trustedProxies</param-name>
+ <param-value>proxy1, proxy2</param-value>
+ </init-param>
+ </filter>
+ </source>
+ <p>Request values: <table border="1" cellpadding="5">
+ <tr>
+ <th bgcolor="#023264"><font color="#ffffff">Property</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value Before
RemoteIpFilter</font></th>
+ <th bgcolor="#023264"><font color="#ffffff">Value After
RemoteIpFilter</font></th>
+ </tr>
+ <tr>
+ <td> request.remoteAddr </td>
+ <td> 192.168.0.10 </td>
+ <td> untrusted-proxy </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-for'<tt>]</tt>
</td>
+ <td> 140.211.11.130, untrusted-proxy, proxy1 </td>
+ <td> 140.211.11.130 </td>
+ </tr>
+ <tr>
+ <td> request.header<tt>[</tt>'x-forwarded-by'<tt>]</tt> </td>
+ <td> null </td>
+ <td> proxy1 </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ Note : <tt>x-forwarded-by</tt> holds the trusted proxy <tt>proxy1</tt>.
+ <tt>x-forwarded-by</tt> holds <tt>140.211.11.130</tt> because
+ <tt>untrusted-proxy</tt> is not trusted and thus, we can not trust that
+ <tt>untrusted-proxy</tt> is the actual remote ip.
+ <tt>request.remoteAddr</tt> is <tt>untrusted-proxy</tt> that is an IP
+ verified by <tt>proxy1</tt>.
+ </p>
+ </subsection>
+
<subsection name="Initialisation parameters">
<p>The <strong>Remote IP Filter</strong> supports the
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
