Class RemoteIpFilter
- java.lang.Object
-
- jakarta.servlet.GenericFilter
-
- org.apache.catalina.filters.RemoteIpFilter
-
- All Implemented Interfaces:
Filter,FilterConfig,Serializable
public class RemoteIpFilter extends GenericFilter
Servlet filter to integrate "X-Forwarded-For" and "X-Forwarded-Proto" HTTP headers.
Most of the design of this Servlet Filter is a port of mod_remoteip, this servlet filter replaces the apparent client remote IP address and hostname for the request with the IP address list presented by a proxy or a load balancer via a request headers (e.g. "X-Forwarded-For").
Another feature of this servlet filter is to replace the apparent scheme (http/https) and server port with the scheme presented by a proxy or a load balancer via a request header (e.g. "X-Forwarded-Proto").
This servlet filter proceeds as follows:
If the incoming
request.getRemoteAddr()matches the servlet filter's list of internal or trusted proxies:- Loop on the comma delimited list of IPs and hostnames passed by the preceding load balancer or proxy in the given
request's Http header named
$remoteIpHeader(default valuex-forwarded-for). Values are processed in right-to-left order. - For each ip/host of the list:
- if it matches the internal proxies list, the ip/host is swallowed
- if it matches the trusted proxies list, the ip/host is added to the created proxies header
- otherwise, the ip/host is declared to be the remote ip and looping is stopped.
- If the request http header named
$protocolHeader(default valueX-Forwarded-Proto) consists only of forwards that matchprotocolHeaderHttpsValueconfiguration parameter (defaulthttps) thenrequest.isSecure = true,request.scheme = httpsandrequest.serverPort = 443. Note that 443 can be overwritten with the$httpsServerPortconfiguration parameter. - Mark the request with the attribute
Globals.REQUEST_FORWARDED_ATTRIBUTEand valueBoolean.TRUEto indicate that this request has been forwarded by one or more proxies.
Configuration parameters XForwardedFilter property Description Equivalent mod_remoteip directive Format Default Value remoteIpHeader Name of the Http Header read by this servlet filter that holds the list of traversed IP addresses starting from the requesting client RemoteIPHeader Compliant http header name x-forwarded-for internalProxies Regular expression that matches the IP addresses of internal proxies. If they appear in the remoteIpHeadervalue, they will be trusted and will not appear in theproxiesHeadervalueRemoteIPInternalProxy Regular expression (in the syntax supported by java.util.regex)10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}| 169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}| 100\.6[4-9]{1}\.\d{1,3}\.\d{1,3}|100\.[7-9]{1}\d{1}\.\d{1,3}\.\d{1,3}| 100\.1[0-1]{1}\d{1}\.\d{1,3}\.\d{1,3}|100\.12[0-7]{1}\.\d{1,3}\.\d{1,3}| 172\.1[6-9]{1}\.\d{1,3}\.\d{1,3}|172\.2[0-9]{1}\.\d{1,3}\.\d{1,3}| 172\.3[0-1]{1}\.\d{1,3}\.\d{1,3}| 0:0:0:0:0:0:0:1|::1
By default, 10/8, 192.168/16, 169.254/16, 127/8, 100.64/10, 172.16/12, and 0:0:0:0:0:0:0:1 are allowed.proxiesHeader Name of the http header created by this servlet filter to hold the list of proxies that have been processed in the incoming remoteIpHeaderRemoteIPProxiesHeader Compliant http header name x-forwarded-by trustedProxies Regular expression that matches the IP addresses of trusted proxies. If they appear in the remoteIpHeadervalue, they will be trusted and will appear in theproxiesHeadervalueRemoteIPTrustedProxy Regular expression (in the syntax supported by java.util.regex)protocolHeader Name of the http header read by this servlet filter that holds the flag that this request N/A Compliant http header name like X-Forwarded-Proto,X-Forwarded-SslorFront-End-HttpsX-Forwarded-ProtoprotocolHeaderHttpsValue Value of the protocolHeaderto indicate that it is an Https requestN/A String like httpsorONhttpshttpServerPort Value returned by ServletRequest.getServerPort()when theprotocolHeaderindicateshttpprotocolN/A integer 80 httpsServerPort Value returned by ServletRequest.getServerPort()when theprotocolHeaderindicateshttpsprotocolN/A integer 443 enableLookups Should a DNS lookup be performed to provide a host name when calling ServletRequest.getRemoteHost()N/A boolean false Regular expression vs. IP address blocks:
mod_remoteipallows to use address blocks (e.g.192.168/16) to configureRemoteIPInternalProxyandRemoteIPTrustedProxy; as the JVM doesn't have a library similar to apr_ipsubnet_test, we rely on regular expressions.
Sample with internal proxies
XForwardedFilter configuration:
<filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>internalProxies</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> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>
Note :Request Values property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, 192.168.0.10 null request.header['x-forwarded-by'] null null request.header['x-forwarded-proto'] https https request.scheme http https request.secure false true request.serverPort 80 443 x-forwarded-byheader is null because only internal proxies as been traversed by the request.x-forwarded-byis null because all the proxies are trusted or internal.
Sample with trusted proxies
RemoteIpFilter configuration:
<filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>internalProxies</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> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>Request Values property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2 null request.header['x-forwarded-by'] null proxy1, proxy2 Note :
proxy1andproxy2are both trusted proxies that come inx-forwarded-forheader, they both are migrated inx-forwarded-byheader.x-forwarded-byis null because all the proxies are trusted or internal.
Sample with internal and trusted proxies
RemoteIpFilter configuration:
<filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>internalProxies</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> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>Request Values property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2, 192.168.0.10 null request.header['x-forwarded-by'] null proxy1, proxy2 Note :
proxy1andproxy2are both trusted proxies that come inx-forwarded-forheader, they both are migrated inx-forwarded-byheader. As192.168.0.10is an internal proxy, it does not appear inx-forwarded-by.x-forwarded-byis null because all the proxies are trusted or internal.
Sample with an untrusted proxy
RemoteIpFilter configuration:
<filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>internalProxies</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> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>Request Values property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 untrusted-proxy request.header['x-forwarded-for'] 140.211.11.130, untrusted-proxy, proxy1 140.211.11.130 request.header['x-forwarded-by'] null proxy1 Note :
x-forwarded-byholds the trusted proxyproxy1.x-forwarded-byholds140.211.11.130becauseuntrusted-proxyis not trusted and thus, we cannot trust thatuntrusted-proxyis the actual remote ip.request.remoteAddrisuntrusted-proxythat is an IP verified byproxy1.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classRemoteIpFilter.XForwardedRequest
-
Field Summary
Fields Modifier and Type Field Description protected static StringCHANGE_LOCAL_NAME_PARAMETERprotected static StringCHANGE_LOCAL_PORT_PARAMETERprotected static StringENABLE_LOOKUPS_PARAMETERprotected static StringHOST_HEADER_PARAMETERprotected static StringHTTP_SERVER_PORT_PARAMETERprotected static StringHTTPS_SERVER_PORT_PARAMETERprotected static StringINTERNAL_PROXIES_PARAMETERprotected static StringPORT_HEADER_PARAMETERprotected static StringPROTOCOL_HEADER_HTTPS_VALUE_PARAMETERprotected static StringPROTOCOL_HEADER_PARAMETERprotected static StringPROXIES_HEADER_PARAMETERprotected static StringREMOTE_IP_HEADER_PARAMETERprotected static StringManagersmprotected static StringTRUSTED_PROXIES_PARAMETER
-
Constructor Summary
Constructors Constructor Description RemoteIpFilter()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected static String[]commaDelimitedListToStringArray(String commaDelimitedStrings)Convert a given comma delimited list of regular expressions into an array of StringvoiddoFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)voiddoFilter(ServletRequest request, ServletResponse response, FilterChain chain)Wrap the incomingrequestin aRemoteIpFilter.XForwardedRequestif the http headerx-forwarded-foris not empty.booleangetEnableLookups()intgetHttpsServerPort()PatterngetInternalProxies()StringgetPortHeader()StringgetProtocolHeader()StringgetProtocolHeaderHttpsValue()StringgetProxiesHeader()StringgetRemoteIpHeader()booleangetRequestAttributesEnabled()PatterngetTrustedProxies()voidinit()Convenience method for sub-classes to save them having to callsuper.init(config).booleanisChangeLocalName()booleanisChangeLocalPort()protected static StringlistToCommaDelimitedString(List<String> stringList)Deprecated.Unused.voidsetChangeLocalName(boolean changeLocalName)Iftrue, the return values for bothServletRequest.getLocalName()andServletRequest.getServerName()will be modified by this Filter rather than justServletRequest.getServerName().voidsetChangeLocalPort(boolean changeLocalPort)Iftrue, the return values for bothServletRequest.getLocalPort()andServletRequest.getServerPort()will be modified by this Filter rather than justServletRequest.getServerPort().voidsetEnableLookups(boolean enableLookups)voidsetHostHeader(String hostHeader)Header that holds the incoming host, usually namedX-Forwarded-Host.voidsetHttpServerPort(int httpServerPort)Server Port value if theprotocolHeaderindicates HTTP (i.e.voidsetHttpsServerPort(int httpsServerPort)Server Port value if theprotocolHeaderindicates HTTPSvoidsetInternalProxies(String internalProxies)Regular expression that defines the internal proxies.voidsetPortHeader(String portHeader)Header that holds the incoming port, usually namedX-Forwarded-Port.voidsetProtocolHeader(String protocolHeader)Header that holds the incoming protocol, usually namedX-Forwarded-Proto.voidsetProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)Case insensitive value of the protocol header to indicate that the incoming http request uses HTTPS.voidsetProxiesHeader(String proxiesHeader)The proxiesHeader directive specifies a header into which mod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the actual remote IP.voidsetRemoteIpHeader(String remoteIpHeader)Name of the http header from which the remote ip is extracted.voidsetRequestAttributesEnabled(boolean requestAttributesEnabled)Should this filter set request attributes for IP address, Hostname, protocol and port used for the request?voidsetTrustedProxies(String trustedProxies)Regular expression defining proxies that are trusted when they appear in theremoteIpHeaderheader.-
Methods inherited from class jakarta.servlet.GenericFilter
getFilterConfig, getFilterName, getInitParameter, getInitParameterNames, getServletContext, init
-
-
-
-
Field Detail
-
HTTP_SERVER_PORT_PARAMETER
protected static final String HTTP_SERVER_PORT_PARAMETER
- See Also:
- Constant Field Values
-
HTTPS_SERVER_PORT_PARAMETER
protected static final String HTTPS_SERVER_PORT_PARAMETER
- See Also:
- Constant Field Values
-
INTERNAL_PROXIES_PARAMETER
protected static final String INTERNAL_PROXIES_PARAMETER
- See Also:
- Constant Field Values
-
sm
protected static final StringManager sm
-
PROTOCOL_HEADER_PARAMETER
protected static final String PROTOCOL_HEADER_PARAMETER
- See Also:
- Constant Field Values
-
PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER
protected static final String PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER
- See Also:
- Constant Field Values
-
HOST_HEADER_PARAMETER
protected static final String HOST_HEADER_PARAMETER
- See Also:
- Constant Field Values
-
PORT_HEADER_PARAMETER
protected static final String PORT_HEADER_PARAMETER
- See Also:
- Constant Field Values
-
CHANGE_LOCAL_NAME_PARAMETER
protected static final String CHANGE_LOCAL_NAME_PARAMETER
- See Also:
- Constant Field Values
-
CHANGE_LOCAL_PORT_PARAMETER
protected static final String CHANGE_LOCAL_PORT_PARAMETER
- See Also:
- Constant Field Values
-
PROXIES_HEADER_PARAMETER
protected static final String PROXIES_HEADER_PARAMETER
- See Also:
- Constant Field Values
-
REMOTE_IP_HEADER_PARAMETER
protected static final String REMOTE_IP_HEADER_PARAMETER
- See Also:
- Constant Field Values
-
TRUSTED_PROXIES_PARAMETER
protected static final String TRUSTED_PROXIES_PARAMETER
- See Also:
- Constant Field Values
-
ENABLE_LOOKUPS_PARAMETER
protected static final String ENABLE_LOOKUPS_PARAMETER
- See Also:
- Constant Field Values
-
-
Method Detail
-
commaDelimitedListToStringArray
protected static String[] commaDelimitedListToStringArray(String commaDelimitedStrings)
Convert a given comma delimited list of regular expressions into an array of String- Parameters:
commaDelimitedStrings- The string to split- Returns:
- array of patterns (non
null)
-
listToCommaDelimitedString
@Deprecated protected static String listToCommaDelimitedString(List<String> stringList)
Deprecated.Unused. Will be removed in Tomcat 11 onwardsConvert a list of strings in a comma delimited string.- Parameters:
stringList- List of strings- Returns:
- concatenated string
-
doFilter
public void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException
- Throws:
IOExceptionServletException
-
doFilter
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException
Wrap the incomingrequestin aRemoteIpFilter.XForwardedRequestif the http headerx-forwarded-foris not empty. ThedoFiltermethod of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain. The FilterChain passed in to this method allows the Filter to pass on the request and response to the next entity in the chain.A typical implementation of this method would follow the following pattern:-
1. Examine the request
2. Optionally wrap the request object with a custom implementation to filter content or headers for input filtering
3. Optionally wrap the response object with a custom implementation to filter content or headers for output filtering
4. a) Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()),
4. b) or not pass on the request/response pair to the next entity in the filter chain to block the request processing
5. Directly set headers on the response after invocation of the next entity in the filter chain.- Parameters:
request- The request to processresponse- The response associated with the requestchain- Provides access to the next filter in the chain for this filter to pass the request and response to for further processing- Throws:
IOException- if an I/O error occurs during this filter's processing of the requestServletException- if the processing fails for any other reason
-
isChangeLocalName
public boolean isChangeLocalName()
-
isChangeLocalPort
public boolean isChangeLocalPort()
-
getHttpsServerPort
public int getHttpsServerPort()
-
getInternalProxies
public Pattern getInternalProxies()
-
getProtocolHeader
public String getProtocolHeader()
-
getPortHeader
public String getPortHeader()
-
getProtocolHeaderHttpsValue
public String getProtocolHeaderHttpsValue()
-
getProxiesHeader
public String getProxiesHeader()
-
getRemoteIpHeader
public String getRemoteIpHeader()
-
getRequestAttributesEnabled
public boolean getRequestAttributesEnabled()
- Returns:
trueif the attributes will be logged, otherwisefalse- See Also:
setRequestAttributesEnabled(boolean)
-
getTrustedProxies
public Pattern getTrustedProxies()
-
getEnableLookups
public boolean getEnableLookups()
-
init
public void init() throws ServletExceptionDescription copied from class:jakarta.servlet.GenericFilterConvenience method for sub-classes to save them having to callsuper.init(config). This is a NO-OP by default.- Overrides:
initin classGenericFilter- Throws:
ServletException- If an exception occurs that interrupts the Filter's normal operation
-
setChangeLocalName
public void setChangeLocalName(boolean changeLocalName)
If
true, the return values for bothServletRequest.getLocalName()andServletRequest.getServerName()will be modified by this Filter rather than justServletRequest.getServerName().Default value :
false- Parameters:
changeLocalName- The new flag value
-
setChangeLocalPort
public void setChangeLocalPort(boolean changeLocalPort)
If
true, the return values for bothServletRequest.getLocalPort()andServletRequest.getServerPort()will be modified by this Filter rather than justServletRequest.getServerPort().Default value :
false- Parameters:
changeLocalPort- The new flag value
-
setHttpServerPort
public void setHttpServerPort(int httpServerPort)
Server Port value if the
protocolHeaderindicates HTTP (i.e.protocolHeaderis not null and has a value different ofprotocolHeaderHttpsValue).Default value : 80
- Parameters:
httpServerPort- The server port to use
-
setHttpsServerPort
public void setHttpsServerPort(int httpsServerPort)
Server Port value if the
protocolHeaderindicates HTTPSDefault value : 443
- Parameters:
httpsServerPort- The server port to use
-
setInternalProxies
public void setInternalProxies(String internalProxies)
Regular expression that defines the internal proxies.
Default value : 10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254.\d{1,3}.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1
- Parameters:
internalProxies- The regexp
-
setHostHeader
public void setHostHeader(String hostHeader)
Header that holds the incoming host, usually named
X-Forwarded-Host.Default value :
null- Parameters:
hostHeader- The header name
-
setPortHeader
public void setPortHeader(String portHeader)
Header that holds the incoming port, usually named
X-Forwarded-Port. Ifnull,httpServerPortorhttpsServerPortwill be used.Default value :
null- Parameters:
portHeader- The header name
-
setProtocolHeader
public void setProtocolHeader(String protocolHeader)
Header that holds the incoming protocol, usually named
X-Forwarded-Proto. Ifnull, request.scheme and request.secure will not be modified.Default value :
X-Forwarded-Proto- Parameters:
protocolHeader- The header name
-
setProtocolHeaderHttpsValue
public void setProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)
Case insensitive value of the protocol header to indicate that the incoming http request uses HTTPS.
Default value :
https- Parameters:
protocolHeaderHttpsValue- The header value
-
setProxiesHeader
public void setProxiesHeader(String proxiesHeader)
The proxiesHeader directive specifies a header into which mod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the actual remote IP. Note that intermediate RemoteIPTrustedProxy addresses are recorded in this header, while any intermediate RemoteIPInternalProxy addresses are discarded.
Name of the http header that holds the list of trusted proxies that has been traversed by the http request.
The value of this header can be comma delimited.
Default value :
X-Forwarded-By- Parameters:
proxiesHeader- The header name
-
setRemoteIpHeader
public void setRemoteIpHeader(String remoteIpHeader)
Name of the http header from which the remote ip is extracted.
The value of this header can be comma delimited.
Default value :
X-Forwarded-For- Parameters:
remoteIpHeader- The header name
-
setRequestAttributesEnabled
public void setRequestAttributesEnabled(boolean requestAttributesEnabled)
Should this filter set request attributes for IP address, Hostname, protocol and port used for the request? This are typically used in conjunction with anAccessLogwhich will otherwise log the original values. Default istrue. The attributes set are:- org.apache.catalina.AccessLog.RemoteAddr
- org.apache.catalina.AccessLog.RemoteHost
- org.apache.catalina.AccessLog.Protocol
- org.apache.catalina.AccessLog.ServerPort
- org.apache.tomcat.remoteAddr
- Parameters:
requestAttributesEnabled-truecauses the attributes to be set,falsedisables the setting of the attributes.
-
setTrustedProxies
public void setTrustedProxies(String trustedProxies)
Regular expression defining proxies that are trusted when they appear in the
remoteIpHeaderheader.Default value : empty list, no external proxy is trusted.
- Parameters:
trustedProxies- The trusted proxies regexp
-
setEnableLookups
public void setEnableLookups(boolean enableLookups)
-
-