Package org.apache.catalina.valves

Class RemoteIpValve

  • All Implemented Interfaces:
    javax.management.MBeanRegistration, Contained, JmxEnabled, Lifecycle, Valve
    public class RemoteIpValve
extends ValveBase

    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 value x-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 (e.g. x-forwarded-proto) consists only of forwards that match protocolHeaderHttpsValue configuration parameter (default https) then request.isSecure = true, request.scheme = https and request.serverPort = 443. Note that 443 can be overwritten with the $httpsServerPort configuration parameter.
    • Mark the request with the attribute Globals.REQUEST_FORWARDED_ATTRIBUTE and value Boolean.TRUE to indicate that this request has been forwarded by one or more proxies.
    Configuration parameters
    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 remoteIpHeader value, they will be trusted and will not appear in the proxiesHeader value 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}| 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, 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 remoteIpHeader value, they will be trusted and will appear in the proxiesHeader value 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-Ssl or Front-End-Https null
    protocolHeaderHttpsValue Value of the protocolHeader to indicate that it is an Https request N/A String like https or ON https
    httpServerPort Value returned by ServletRequest.getServerPort() when the protocolHeader indicates http protocol N/A integer 80
    httpsServerPort Value returned by ServletRequest.getServerPort() when the protocolHeader indicates https protocol 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" />
    Request Values
    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" />
    Request Values
    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" />
    Request Values
    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" />
    Request Values
    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.

    • Constructor Detail

      • RemoteIpValve

        public RemoteIpValve()
        Default constructor that ensures ValveBase(boolean) is called with true.

    • Method Detail

      • commaDelimitedListToStringArray

        protected static java.lang.String[] commaDelimitedListToStringArray​(java.lang.String commaDelimitedStrings)
        Convert a given comma delimited String into an array of String
        Parameters:
        commaDelimitedStrings - The string to convert
        Returns:
        array of String (non null)

      • listToCommaDelimitedString

        @Deprecated
protected static java.lang.String listToCommaDelimitedString​(java.util.List<java.lang.String> stringList)
        Deprecated.
        Unused. This will be removed in Tomcat 10.1.x onwards. Use StringUtils.join(java.util.Collection) instead
        Convert an array of strings in a comma delimited string
        Parameters:
        stringList - The string list to convert
        Returns:
        The concatenated string

      • isChangeLocalName

        public boolean isChangeLocalName()

      • setChangeLocalName

        public void setChangeLocalName​(boolean changeLocalName)

      • getHttpServerPort

        public int getHttpServerPort()

      • getHttpsServerPort

        public int getHttpsServerPort()

      • isChangeLocalPort

        public boolean isChangeLocalPort()

      • setChangeLocalPort

        public void setChangeLocalPort​(boolean changeLocalPort)

      • getInternalProxies

        public java.lang.String getInternalProxies()
        Returns:
        Regular expression that defines the internal proxies
        See Also:
        setInternalProxies(String)

      • getProtocolHeader

        public java.lang.String getProtocolHeader()
        Returns:
        the protocol header (e.g. "X-Forwarded-Proto")
        See Also:
        setProtocolHeader(String)

      • getProtocolHeaderHttpsValue

        public java.lang.String getProtocolHeaderHttpsValue()
        Returns:
        the value of the protocol header for incoming https request (e.g. "https")
        See Also:
        setProtocolHeaderHttpsValue(String)

      • getProxiesHeader

        public java.lang.String getProxiesHeader()
        Returns:
        the proxies header name (e.g. "X-Forwarded-By")
        See Also:
        setProxiesHeader(String)

      • getRemoteIpHeader

        public java.lang.String getRemoteIpHeader()
        Returns:
        the remote IP header name (e.g. "X-Forwarded-For")
        See Also:
        setRemoteIpHeader(String)

      • getRequestAttributesEnabled

        public boolean getRequestAttributesEnabled()
        Returns:
        true if the attributes will be logged, otherwise false
        See Also:
        setRequestAttributesEnabled(boolean)

      • getTrustedProxies

        public java.lang.String getTrustedProxies()
        Returns:
        Regular expression that defines the trusted proxies
        See Also:
        setTrustedProxies(String)

      • invoke

        public void invoke​(Request request,
                   Response response)
            throws java.io.IOException,
                   ServletException

        Perform 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:
        java.io.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

      • setHttpServerPort

        public void setHttpServerPort​(int httpServerPort)

        Server Port value if the protocolHeader is not null and does not indicate HTTP

        Default value : 80

        Parameters:
        httpServerPort - The server port

      • setHttpsServerPort

        public void setHttpsServerPort​(int httpsServerPort)

        Server Port value if the protocolHeader indicates HTTPS

        Default value : 443

        Parameters:
        httpsServerPort - The server port

      • setInternalProxies

        public void setInternalProxies​(java.lang.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 proxy regular expression

      • setProtocolHeader

        public void setProtocolHeader​(java.lang.String protocolHeader)

        Header that holds the incoming protocol, usually named X-Forwarded-Proto. If null, request.scheme and request.secure will not be modified.

        Default value : null

        Parameters:
        protocolHeader - The header name

      • setProtocolHeaderHttpsValue

        public void setProtocolHeaderHttpsValue​(java.lang.String protocolHeaderHttpsValue)

        Case insensitive value of the protocol header to indicate that the incoming http request uses SSL.

        Default value : https

        Parameters:
        protocolHeaderHttpsValue - The header name

      • setProxiesHeader

        public void setProxiesHeader​(java.lang.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​(java.lang.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 valve set request attributes for IP address, Hostname, protocol and port used for the request? This are typically used in conjunction with the AccessLog which will otherwise log the original values. Default is true. 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 - true causes the attributes to be set, false disables the setting of the attributes.

      • setTrustedProxies

        public void setTrustedProxies​(java.lang.String trustedProxies)

        Regular expression defining proxies that are trusted when they appear in the remoteIpHeader header.

        Default value : empty list, no external proxy is trusted.

        Parameters:
        trustedProxies - The regular expression