sftpgo/docs/rate-limiting.md
Nicola Murino 78233ff9a3
web UI/REST API: add password reset
In order to reset the password from the admin/client user interface,
an SMTP configuration must be added and the user/admin must have an email
address.
You can prohibit the reset functionality on a per-user basis by using a
specific restriction.

Fixes #597
2021-11-13 13:25:43 +01:00

3 KiB

Rate limiting

Rate limiting allows to control the number of requests going to the SFTPGo services.

SFTPGo implements a token bucket initially full and refilled at the configured rate. The burst configuration parameter defines the size of the bucket. The rate is defined by dividing average by period, so for a rate below 1 req/s, one needs to define a period larger than a second.

Requests that exceed the configured limit will be delayed or denied if they exceed the maximum delay time.

SFTPGo allows to define per-protocol rate limiters so you can have different configurations for different protocols.

The supported protocols are:

  • SSH, includes SFTP and SSH commands
  • FTP, includes FTP, FTPES, FTPS
  • DAV, WebDAV
  • HTTP, REST API and web admin

You can also define two types of rate limiters:

  • global, it is independent from the source host and therefore define an aggregate limit for the configured protocol/s
  • per-host, this type of rate limiter can be connected to the built-in defender and generate score_limit_exceeded events and thus hosts that repeatedly exceed the configured limit can be automatically blocked

If you configure a per-host rate limiter, SFTPGo will keep a rate limiter in memory for each host that connects to the service, you can limit the memory usage using the entries_soft_limit and entries_hard_limit configuration keys.

For each rate limiter you can exclude a list of IP addresses and IP ranges by defining an allow_list. The allow list supports IPv4/IPv6 address and CIDR networks, for example:

...
"allow_list": [
  "192.0.2.1",
  "192.168.1.0/24",
  "2001:db8::68",
  "2001:db8:1234::/48"
],
...

You can defines how many rate limiters as you want, but keep in mind that if you defines multiple rate limiters each request will be checked against all the configured limiters and so it can potentially be delayed multiple times. Let's clarify with an example, here is a configuration that defines a global rate limiter and a per-host rate limiter for the FTP protocol:

"rate_limiters": [
    {
      "average": 100,
      "period": 1000,
      "burst": 1,
      "type": 1,
      "protocols": [
        "SSH",
        "FTP",
        "DAV",
        "HTTP"
      ],
      "generate_defender_events": false,
      "entries_soft_limit": 100,
      "entries_hard_limit": 150
    },
    {
      "average": 10,
      "period": 1000,
      "burst": 1,
      "type": 2,
      "protocols": [
        "FTP"
      ],
      "allow_list": [],
      "generate_defender_events": true,
      "entries_soft_limit": 100,
      "entries_hard_limit": 150
    }
]

we have a global rate limiter that limit the aggregate rate for the all the services to 100 req/s and an additional rate limiter that limits the FTP protocol to 10 req/s per host. With this configuration, when a client connects via FTP it will be limited first by the global rate limiter and then by the per host rate limiter. Clients connecting via SFTP/WebDAV will be checked only against the global rate limiter.