Class RemoteIpFilter
- All Implemented Interfaces:
- Filter,- FilterConfig,- Serializable
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.
| 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 theproxiesHeadervalue | RemoteIPInternalProxy | 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 remoteIpHeader | RemoteIPProxiesHeader | 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 theproxiesHeadervalue | RemoteIPTrustedProxy | 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-Https | X-Forwarded-Proto | 
| protocolHeaderHttpsValue | Value of the protocolHeaderto indicate that it is an Https request | N/A | String like httpsorON | https | 
| httpServerPort | Value returned by ServletRequest.getServerPort()when theprotocolHeaderindicateshttpprotocol | N/A | integer | 80 | 
| httpsServerPort | Value returned by ServletRequest.getServerPort()when theprotocolHeaderindicateshttpsprotocol | N/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_remoteip allows to use address blocks
 (e.g. 192.168/16) to configure RemoteIPInternalProxy and RemoteIPTrustedProxy
 ; 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>
 | 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-by header is null because only internal proxies as been traversed by the request.
 x-forwarded-by is 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>
 | 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 : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for
 header, they both are migrated in x-forwarded-by header. x-forwarded-by is 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>
 | 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 : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for
 header, they both are migrated in x-forwarded-by header. As 192.168.0.10 is an internal
 proxy, it does not appear in x-forwarded-by. x-forwarded-by is 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>
 | 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-by holds the trusted proxy proxy1. x-forwarded-by holds
 140.211.11.130 because untrusted-proxy is not trusted and thus, we cannot trust that
 untrusted-proxy is the actual remote ip. request.remoteAddr is untrusted-proxy
 that is an IP verified by proxy1.
 
- See Also:
- 
Nested Class SummaryNested Classes
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final Stringprotected static final StringManagerprotected static final String
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionprotected 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.booleanintbooleanvoidinit()Convenience method for sub-classes to save them having to callsuper.init(config).booleanbooleanprotected 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.GenericFiltergetFilterConfig, getFilterName, getInitParameter, getInitParameterNames, getServletContext, init
- 
Field Details- 
HTTP_SERVER_PORT_PARAMETER- See Also:
 
- 
HTTPS_SERVER_PORT_PARAMETER- See Also:
 
- 
INTERNAL_PROXIES_PARAMETER- See Also:
 
- 
sm
- 
PROTOCOL_HEADER_PARAMETER- See Also:
 
- 
PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER- See Also:
 
- 
HOST_HEADER_PARAMETER- See Also:
 
- 
PORT_HEADER_PARAMETER- See Also:
 
- 
CHANGE_LOCAL_NAME_PARAMETER- See Also:
 
- 
CHANGE_LOCAL_PORT_PARAMETER- See Also:
 
- 
PROXIES_HEADER_PARAMETER- See Also:
 
- 
REMOTE_IP_HEADER_PARAMETER- See Also:
 
- 
TRUSTED_PROXIES_PARAMETER- See Also:
 
- 
ENABLE_LOOKUPS_PARAMETER- See Also:
 
 
- 
- 
Constructor Details- 
RemoteIpFilterpublic RemoteIpFilter()
 
- 
- 
Method Details- 
commaDelimitedListToStringArrayConvert 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)
 
- 
listToCommaDelimitedStringDeprecated.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
 
- 
doFilterpublic void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException - Throws:
- IOException
- ServletException
 
- 
doFilterpublic 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 process
- response- The response associated with the request
- chain- 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 request
- ServletException- if the processing fails for any other reason
 
- 
isChangeLocalNamepublic boolean isChangeLocalName()
- 
isChangeLocalPortpublic boolean isChangeLocalPort()
- 
getHttpsServerPortpublic int getHttpsServerPort()
- 
getInternalProxies
- 
getProtocolHeader
- 
getPortHeader
- 
getProtocolHeaderHttpsValue
- 
getProxiesHeader
- 
getRemoteIpHeader
- 
getRequestAttributesEnabledpublic boolean getRequestAttributesEnabled()- Returns:
- trueif the attributes will be logged, otherwise- false
- See Also:
 
- 
getTrustedProxies
- 
getEnableLookupspublic boolean getEnableLookups()
- 
initDescription 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 class- GenericFilter
- Throws:
- ServletException- If an exception occurs that interrupts the Filter's normal operation
 
- 
setChangeLocalNamepublic 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
 
- 
setChangeLocalPortpublic 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
 
- 
setHttpServerPortpublic 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
 
- 
setHttpsServerPortpublic void setHttpsServerPort(int httpsServerPort) Server Port value if the protocolHeaderindicates HTTPSDefault value : 443 - Parameters:
- httpsServerPort- The server port to use
 
- 
setInternalProxiesRegular 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
 
- 
setHostHeaderHeader that holds the incoming host, usually named X-Forwarded-Host.Default value : null- Parameters:
- hostHeader- The header name
 
- 
setPortHeaderHeader that holds the incoming port, usually named X-Forwarded-Port. Ifnull,httpServerPortorhttpsServerPortwill be used.Default value : null- Parameters:
- portHeader- The header name
 
- 
setProtocolHeaderHeader 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
 
- 
setProtocolHeaderHttpsValueCase insensitive value of the protocol header to indicate that the incoming http request uses HTTPS. Default value : https- Parameters:
- protocolHeaderHttpsValue- The header value
 
- 
setProxiesHeaderThe 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
 
- 
setRemoteIpHeaderName 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
 
- 
setRequestAttributesEnabledpublic 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.
 
- 
setTrustedProxiesRegular 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
 
- 
setEnableLookupspublic void setEnableLookups(boolean enableLookups) 
 
-