Class RemoteIpValve
- All Implemented Interfaces:
- MBeanRegistration,- Contained,- JmxEnabled,- Lifecycle,- Valve
Tomcat port of mod_remoteip, this valve 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 valve 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 valve proceeds as follows:
 If the incoming request.getRemoteAddr() matches the valve'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.
| RemoteIpValve property | Description | Equivalent mod_remoteip directive | Format | Default Value | 
|---|---|---|---|---|
| remoteIpHeader | Name of the Http Header read by this valve 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 ::1 are allowed. | 
| proxiesHeader | Name of the http header created by this valve to hold the list of proxies that have been processed in the
 incoming remoteIpHeader | proxiesHeader | 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 valve 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 | 
This Valve may be attached to any Container, depending on the granularity of the filtering you wish to perform.
 Regular expression vs. IP address blocks: mod_remoteip allows to use address blocks
 (e.g. 192.168/16) to configure RemoteIPInternalProxy and RemoteIPTrustedProxy
 ; as Tomcat doesn't have a library similar to apr_ipsubnet_test,
 RemoteIpValve uses regular expression to configure internalProxies and
 trustedProxies in the same fashion as RequestFilterValve does.
 
Sample with internal proxies
RemoteIpValve configuration:
 <Valve
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10|192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   proxiesHeader="x-forwarded-by"
   protocolHeader="x-forwarded-proto"
   />
 | property | Value Before RemoteIpValve | Value After RemoteIpValve | 
|---|---|---|
| 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 | 
 Note : 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
RemoteIpValve configuration:
 <Valve
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10|192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   proxiesHeader="x-forwarded-by"
   trustedProxies="proxy1|proxy2"
   />
 | property | Value Before RemoteIpValve | Value After RemoteIpValve | 
|---|---|---|
| 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
RemoteIpValve configuration:
 <Valve
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10|192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   proxiesHeader="x-forwarded-by"
   trustedProxies="proxy1|proxy2"
   />
 | property | Value Before RemoteIpValve | Value After RemoteIpValve | 
|---|---|---|
| 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
RemoteIpValve configuration:
 <Valve
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10|192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   proxiesHeader="x-forwarded-by"
   trustedProxies="proxy1|proxy2"
   />
 | property | Value Before RemoteIpValve | Value After RemoteIpValve | 
|---|---|---|
| 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.
 
- 
Nested Class SummaryNested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
- 
Field SummaryFields inherited from class org.apache.catalina.valves.ValveBaseasyncSupported, container, containerLog, next, smFields inherited from interface org.apache.catalina.LifecycleAFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionprotected static String[]commaDelimitedListToStringArray(String commaDelimitedStrings) Convert a given comma delimited String into an array of StringObtain the name of the HTTP header used to override the value returned byRequest.getServerName()and (optionally depending on {linkisChangeLocalName()Request.getLocalName().intintObtain the name of the HTTP header used to override the value returned byRequest.getServerPort()and (optionally depending on {linkisChangeLocalPort()Request.getLocalPort().booleanvoidPerform request processing as required by this Valve.booleanbooleanvoidsetChangeLocalName(boolean changeLocalName) voidsetChangeLocalPort(boolean changeLocalPort) voidsetHostHeader(String hostHeader) Set the name of the HTTP header used to override the value returned byRequest.getServerName()and (optionally depending on {linkisChangeLocalName()Request.getLocalName().voidsetHttpServerPort(int httpServerPort) Server Port value if theprotocolHeaderis notnulland does not indicate HTTPvoidsetHttpsServerPort(int httpsServerPort) Server Port value if theprotocolHeaderindicates HTTPSvoidsetInternalProxies(String internalProxies) Regular expression that defines the internal proxies.voidsetPortHeader(String portHeader) Set the name of the HTTP header used to override the value returned byRequest.getServerPort()and (optionally depending on {linkisChangeLocalPort()Request.getLocalPort().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 SSL.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 valve 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 org.apache.catalina.valves.ValveBasebackgroundProcess, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, startInternal, stopInternal, toStringMethods inherited from class org.apache.catalina.util.LifecycleMBeanBasedestroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregisterMethods inherited from class org.apache.catalina.util.LifecycleBaseaddLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
- 
Constructor Details- 
RemoteIpValvepublic RemoteIpValve()Default constructor that ensuresValveBase(boolean)is called withtrue.
 
- 
- 
Method Details- 
commaDelimitedListToStringArrayConvert a given comma delimited String into an array of String- Parameters:
- commaDelimitedStrings- The string to convert
- Returns:
- array of String (non null)
 
- 
getHostHeaderObtain the name of the HTTP header used to override the value returned byRequest.getServerName()and (optionally depending on {linkisChangeLocalName()Request.getLocalName().- Returns:
- The HTTP header name
 
- 
setHostHeaderSet the name of the HTTP header used to override the value returned byRequest.getServerName()and (optionally depending on {linkisChangeLocalName()Request.getLocalName().- Parameters:
- hostHeader- The HTTP header name
 
- 
isChangeLocalNamepublic boolean isChangeLocalName()
- 
setChangeLocalNamepublic void setChangeLocalName(boolean changeLocalName) 
- 
getHttpServerPortpublic int getHttpServerPort()
- 
getHttpsServerPortpublic int getHttpsServerPort()
- 
getPortHeaderObtain the name of the HTTP header used to override the value returned byRequest.getServerPort()and (optionally depending on {linkisChangeLocalPort()Request.getLocalPort().- Returns:
- The HTTP header name
 
- 
setPortHeaderSet the name of the HTTP header used to override the value returned byRequest.getServerPort()and (optionally depending on {linkisChangeLocalPort()Request.getLocalPort().- Parameters:
- portHeader- The HTTP header name
 
- 
isChangeLocalPortpublic boolean isChangeLocalPort()
- 
setChangeLocalPortpublic void setChangeLocalPort(boolean changeLocalPort) 
- 
getInternalProxies- Returns:
- Regular expression that defines the internal proxies
- See Also:
 
- 
getProtocolHeader- Returns:
- the protocol header (e.g. "X-Forwarded-Proto")
- See Also:
 
- 
getProtocolHeaderHttpsValue- Returns:
- the value of the protocol header for incoming https request (e.g. "https")
- See Also:
 
- 
getProxiesHeader- Returns:
- the proxies header name (e.g. "X-Forwarded-By")
- See Also:
 
- 
getRemoteIpHeader- Returns:
- the remote IP header name (e.g. "X-Forwarded-For")
- See Also:
 
- 
getRequestAttributesEnabledpublic boolean getRequestAttributesEnabled()- Returns:
- trueif the attributes will be logged, otherwise- false
- See Also:
 
- 
getTrustedProxies- Returns:
- Regular expression that defines the trusted proxies
- See Also:
 
- 
invokeDescription copied from interface:ValvePerform request processing as required by this Valve. An individual Valve MAY perform the following actions, in the specified order: - Examine and/or modify the properties of the specified Request and Response.
- Examine the properties of the specified Request, completely generate the corresponding Response, and return control to the caller.
- Examine the properties of the specified Request and Response, wrap either or both of these objects to supplement their functionality, and pass them on.
- If the corresponding Response was not generated (and control was not
     returned, call the next Valve in the pipeline (if there is one) by
     executing getNext().invoke().
- Examine, but not modify, the properties of the resulting Response (which was created by a subsequently invoked Valve or Container).
 A Valve MUST NOT do any of the following things: - Change request properties that have already been used to direct the flow of processing control for this request (for instance, trying to change the virtual host to which a Request should be sent from a pipeline attached to a Host or Context in the standard implementation).
- Create a completed Response AND pass this Request and Response on to the next Valve in the pipeline.
- Consume bytes from the input stream associated with the Request, unless it is completely generating the response, or wrapping the request before passing it on.
- Modify the HTTP headers included with the Response after the
     getNext().invoke()method has returned.
- Perform any actions on the output stream associated with the
     specified Response after the getNext().invoke()method has returned.
 - Parameters:
- request- The servlet request to be processed
- response- The servlet response to be created
- Throws:
- IOException- if an input/output error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
- ServletException- if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
 
- 
setHttpServerPortpublic void setHttpServerPort(int httpServerPort) Server Port value if the protocolHeaderis notnulland does not indicate HTTPDefault value : 80 - Parameters:
- httpServerPort- The server port
 
- 
setHttpsServerPortpublic void setHttpsServerPort(int httpsServerPort) Server Port value if the protocolHeaderindicates HTTPSDefault value : 443 - Parameters:
- httpsServerPort- The server port
 
- 
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 proxy regular expression
 
- 
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 SSL. Default value : https- Parameters:
- protocolHeaderHttpsValue- The header name
 
- 
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 valve set request attributes for IP address, Hostname, protocol and port used for the request? This are typically used in conjunction with theAccessLogwhich 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 regular expression
 
 
-