DoSFilter (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

org.eclipse.jetty.servlets

## Class DoSFilter

- java.lang.Object
- - org.eclipse.jetty.servlets.DoSFilter

- All Implemented Interfaces:
    javax.servlet.Filter
  Direct Known Subclasses:
    CloseableDoSFilter

      public class DoSFilter
      extends Object
      implements javax.servlet.Filter

  Denial of Service filter

  This filter is based on the `QoSFilter`. it is useful for limiting exposure to abuse from request flooding, whether malicious, or as a result of a misconfigured client.

  The filter keeps track of the number of requests from a connection per second. If a limit is exceeded, the request is either rejected, delayed, or throttled.

  When a request is throttled, it is placed in a priority queue. Priority is given first to authenticated users and users with an HttpSession, then connections which can be identified by their IP addresses. Connections with no way to identify them are given lowest priority.

  The `extractUserId(ServletRequest request)` function should be implemented, in order to uniquely identify authenticated users.

  The following init parameters control the behavior of the filter:

  maxRequestsPerSec
    the maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
  delayMs
    is the delay given to all requests over the rate limit, before they are considered at all. -1 means just reject request, 0 means no delay, otherwise it is the delay.
  maxWaitMs
    how long to blocking wait for the throttle semaphore.
  throttledRequests
    is the number of requests over the rate limit able to be considered at once.
  throttleMs
    how long to async wait for semaphore.
  maxRequestMs
    how long to allow this request to run.
  maxIdleTrackerMs
    how long to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it
  insertHeaders
    if true , insert the DoSFilter headers into the response. Defaults to true.
  trackSessions
    if true, usage rate is tracked by session if a session exists. Defaults to true.
  remotePort
    if true and session tracking is not used, then rate is tracked by IP+port (effectively connection). Defaults to false.
  ipWhitelist
    a comma-separated list of IP addresses that will not be rate limited
  managedAttr
    if set to true, then this servlet is set as a `ServletContext` attribute with the filter name as the attribute name. This allows context external mechanism (eg JMX via `ContextHandler.MANAGED_ATTRIBUTES`) to manage the configuration of the filter.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `_delayMs`
    `protected boolean` | `_insertHeaders`
    `protected ContinuationListener[]` | `_listener`
    `protected long` | `_maxIdleTrackerMs`
    `protected long` | `_maxRequestMs`
    `protected int` | `_maxRequestsPerSec`
    `protected long` | `_maxWaitMs`
    `protected String` | `_name`
    `protected Semaphore` | `_passes`
    `protected Queue<Continuation>[]` | `_queue`
    `protected ConcurrentHashMap<String,org.eclipse.jetty.servlets.DoSFilter.RateTracker>` | `_rateTrackers`
    `protected boolean` | `_remotePort`
    `protected int` | `_throttledRequests`
    `protected long` | `_throttleMs`
    `protected boolean` | `_trackSessions`
    `protected String` | `_whitelistStr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DoSFilter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `closeConnection(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Thread thread)` Takes drastic measures to return this response and stop this thread.
    `void` | `destroy()`
    `void` | `doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain filterchain)`
    `protected void` | `doFilterChain(javax.servlet.FilterChain chain, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
    `protected String` | `extractUserId(javax.servlet.ServletRequest request)` Returns the user id, used to track this connection.
    `long` | `getDelayMs()` Get delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
    `long` | `getMaxIdleTrackerMs()` Get maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
    `protected int` | `getMaxPriority()`
    `long` | `getMaxRequestMs()` Get maximum amount of time (in milliseconds) to allow the request to process.
    `int` | `getMaxRequestsPerSec()` Get maximum number of requests from a connection per second.
    `long` | `getMaxWaitMs()` Get maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
    `protected int` | `getPriority(javax.servlet.ServletRequest request, org.eclipse.jetty.servlets.DoSFilter.RateTracker tracker)` Get priority for this request, based on user type
    `org.eclipse.jetty.servlets.DoSFilter.RateTracker` | `getRateTracker(javax.servlet.ServletRequest request)` Return a request rate tracker associated with this connection; keeps track of this connection's request rate.
    `int` | `getThrottledRequests()` Get number of requests over the rate limit able to be considered at once.
    `long` | `getThrottleMs()` Get amount of time (in milliseconds) to async wait for semaphore.
    `String` | `getWhitelist()` Get a list of IP addresses that will not be rate limited.
    `void` | `init(javax.servlet.FilterConfig filterConfig)`
    `protected void` | `initWhitelist()` Initialize the IP address whitelist
    `boolean` | `isInsertHeaders()` Check flag to insert the DoSFilter headers into the response.
    `boolean` | `isRemotePort()` Get flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
    `boolean` | `isTrackSessions()` Get flag to have usage rate tracked by session if a session exists.
    `void` | `setDelayMs(long value)` Set delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
    `void` | `setInsertHeaders(boolean value)` Set flag to insert the DoSFilter headers into the response.
    `void` | `setMaxIdleTrackerMs(long value)` Set maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
    `void` | `setMaxRequestMs(long value)` Set maximum amount of time (in milliseconds) to allow the request to process.
    `void` | `setMaxRequestsPerSec(int value)` Get maximum number of requests from a connection per second.
    `void` | `setMaxWaitMs(long value)` Set maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
    `void` | `setRemotePort(boolean value)` Set flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
    `void` | `setThrottledRequests(int value)` Set number of requests over the rate limit able to be considered at once.
    `void` | `setThrottleMs(long value)` Set amount of time (in milliseconds) to async wait for semaphore.
    `void` | `setTrackSessions(boolean value)` Set flag to have usage rate tracked by session if a session exists.
    `void` | `setWhitelist(String value)` Set a list of IP addresses that will not be rate limited.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### _name

          protected String _name

    - #### _delayMs

          protected long _delayMs

    - #### _throttleMs

          protected long _throttleMs

    - #### _maxWaitMs

          protected long _maxWaitMs

    - #### _maxRequestMs

          protected long _maxRequestMs

    - #### _maxIdleTrackerMs

          protected long _maxIdleTrackerMs

    - #### _insertHeaders

          protected boolean _insertHeaders

    - #### _trackSessions

          protected boolean _trackSessions

    - #### _remotePort

          protected boolean _remotePort

    - #### _throttledRequests

          protected int _throttledRequests

    - #### _passes

          protected Semaphore _passes

    - #### _queue

          protected Queue<Continuation>[] _queue

    - #### _listener

          protected ContinuationListener[] _listener

    - #### _maxRequestsPerSec

          protected int _maxRequestsPerSec

    - #### _rateTrackers

          protected final ConcurrentHashMap<String,org.eclipse.jetty.servlets.DoSFilter.RateTracker> _rateTrackers

    - #### _whitelistStr

          protected String _whitelistStr

  - ### Constructor Detail

    - #### DoSFilter

          public DoSFilter()

  - ### Method Detail

    - #### init

          public void init(javax.servlet.FilterConfig filterConfig)

      Specified by:
        `init` in interface `javax.servlet.Filter`

    - #### doFilter

          public void doFilter(javax.servlet.ServletRequest request,
                      javax.servlet.ServletResponse response,
                      javax.servlet.FilterChain filterchain)
                        throws IOException,
                               javax.servlet.ServletException

      Specified by:
        `doFilter` in interface `javax.servlet.Filter`
      Throws:
        `IOException`
        `javax.servlet.ServletException`

    - #### doFilterChain

          protected void doFilterChain(javax.servlet.FilterChain chain,
                           javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)
                                throws IOException,
                                       javax.servlet.ServletException

      Parameters:
        `chain` -
        `request` -
        `response` -
      Throws:
        `IOException`
        `javax.servlet.ServletException`

    - #### closeConnection

          protected void closeConnection(javax.servlet.http.HttpServletRequest request,
                             javax.servlet.http.HttpServletResponse response,
                             Thread thread)

      Takes drastic measures to return this response and stop this thread. Due to the way the connection is interrupted, may return mixed up headers.
      Parameters:
        `request` - current request
        `response` - current response, which must be stopped
        `thread` - the handling thread

    - #### getPriority

          protected int getPriority(javax.servlet.ServletRequest request,
                        org.eclipse.jetty.servlets.DoSFilter.RateTracker tracker)

      Get priority for this request, based on user type
      Parameters:
        `request` -
        `tracker` -
      Returns:
        priority

    - #### getMaxPriority

          protected int getMaxPriority()

      Returns:
        the maximum priority that we can assign to a request

    - #### getRateTracker

          public org.eclipse.jetty.servlets.DoSFilter.RateTracker getRateTracker(javax.servlet.ServletRequest request)

      Return a request rate tracker associated with this connection; keeps track of this connection's request rate. If this is not the first request from this connection, return the existing object with the stored stats. If it is the first request, then create a new request tracker. Assumes that each connection has an identifying characteristic, and goes through them in order, taking the first that matches: user id (logged in), session id, client IP address. Unidentifiable connections are lumped into one. When a session expires, its rate tracker is automatically deleted.
      Parameters:
        `request` -
      Returns:
        the request rate tracker for the current connection

    - #### destroy

          public void destroy()

      Specified by:
        `destroy` in interface `javax.servlet.Filter`

    - #### extractUserId

          protected String extractUserId(javax.servlet.ServletRequest request)

      Returns the user id, used to track this connection. This SHOULD be overridden by subclasses.
      Parameters:
        `request` -
      Returns:
        a unique user id, if logged in; otherwise null.

    - #### initWhitelist

          protected void initWhitelist()

      Initialize the IP address whitelist

    - #### getMaxRequestsPerSec

          public int getMaxRequestsPerSec()

      Get maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
      Returns:
        maximum number of requests

    - #### setMaxRequestsPerSec

          public void setMaxRequestsPerSec(int value)

      Get maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
      Parameters:
        `value` - maximum number of requests

    - #### getDelayMs

          public long getDelayMs()

      Get delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.

    - #### setDelayMs

          public void setDelayMs(long value)

      Set delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
      Parameters:
        `value` - delay (in milliseconds), 0 - no delay, -1 - reject request

    - #### getMaxWaitMs

          public long getMaxWaitMs()

      Get maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
      Returns:
        maximum wait time

    - #### setMaxWaitMs

          public void setMaxWaitMs(long value)

      Set maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
      Parameters:
        `value` - maximum wait time

    - #### getThrottledRequests

          public int getThrottledRequests()

      Get number of requests over the rate limit able to be considered at once.
      Returns:
        number of requests

    - #### setThrottledRequests

          public void setThrottledRequests(int value)

      Set number of requests over the rate limit able to be considered at once.
      Parameters:
        `value` - number of requests

    - #### getThrottleMs

          public long getThrottleMs()

      Get amount of time (in milliseconds) to async wait for semaphore.
      Returns:
        wait time

    - #### setThrottleMs

          public void setThrottleMs(long value)

      Set amount of time (in milliseconds) to async wait for semaphore.
      Parameters:
        `value` - wait time

    - #### getMaxRequestMs

          public long getMaxRequestMs()

      Get maximum amount of time (in milliseconds) to allow the request to process.
      Returns:
        maximum processing time

    - #### setMaxRequestMs

          public void setMaxRequestMs(long value)

      Set maximum amount of time (in milliseconds) to allow the request to process.
      Parameters:
        `value` - maximum processing time

    - #### getMaxIdleTrackerMs

          public long getMaxIdleTrackerMs()

      Get maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
      Returns:
        maximum tracking time

    - #### setMaxIdleTrackerMs

          public void setMaxIdleTrackerMs(long value)

      Set maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
      Parameters:
        `value` - maximum tracking time

    - #### isInsertHeaders

          public boolean isInsertHeaders()

      Check flag to insert the DoSFilter headers into the response.
      Returns:
        value of the flag

    - #### setInsertHeaders

          public void setInsertHeaders(boolean value)

      Set flag to insert the DoSFilter headers into the response.
      Parameters:
        `value` - value of the flag

    - #### isTrackSessions

          public boolean isTrackSessions()

      Get flag to have usage rate tracked by session if a session exists.
      Returns:
        value of the flag

    - #### setTrackSessions

          public void setTrackSessions(boolean value)

      Set flag to have usage rate tracked by session if a session exists.
      Parameters:
        `value` - value of the flag

    - #### isRemotePort

          public boolean isRemotePort()

      Get flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
      Returns:
        value of the flag

    - #### setRemotePort

          public void setRemotePort(boolean value)

      Set flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
      Parameters:
        `value` - value of the flag

    - #### getWhitelist

          public String getWhitelist()

      Get a list of IP addresses that will not be rate limited.
      Returns:
        comma-separated whitelist

    - #### setWhitelist

          public void setWhitelist(String value)

      Set a list of IP addresses that will not be rate limited.
      Parameters:
        `value` - comma-separated whitelist

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.