Throttle (throttle) Plugin

The throttle plugin rate-limits Dovecot operations using token-bucket-style counters. Operations that match a configured event filter are counted in short and long buckets; once a bucket is full, further matching operations inside the same worker process are delayed by sleeping the worker for an amount of time proportional to how far over the bucket limit the user (or the global counter) currently is.

Counters are kept in a dedicated throttle server process, so the limits apply across all worker processes on the same host.

The short buckets are intended to be configured to throttle early and with low event counts (e.g. 30 second limit). This takes care of short bursts of activity. The long buckets are intended to prevent excessive abuse from a user over a longer time period (e.g. 1 day). They should be configured so that long bucket limits are not exceeded by regular clients.

WARNING

Throttling delays the entire worker via a synchronous sleep. The plugin requires client_limit=1 for any service into which it is loaded. If multiple clients share a worker, a sleep triggered by one user blocks every other client on that worker.

A single worker sleep is capped at 60 seconds regardless of how far over the bucket limit the counter has gone.

Throttle Types

Each throttle entry has a throttle_type:

Type	Description
global	One bucket shared by all users. Useful for protecting shared resources (e.g. limiting total deliveries per minute on a backend).
user	One bucket per username. Used to rate-limit per-user activity. The username is included in the bucket's global ID, so user buckets are isolated from each other.

Settings

throttle

Default	[None]
Value	Named List Filter

Named list filter of throttle definitions. The filter name refers to the throttle_name setting.

throttle_filter

Default	[None]
Value	string

Event filter expression matched against every emitted event. On match, the bucket is incremented and, if full, the worker is slept proportionally to the overage.

throttle_long_bucket_expire

Default	1d
Value	time

Long bucket window length. Counter resets when the wall clock crosses a multiple of this interval (fixed window, not rolling).

throttle_long_bucket_max_count

Default	[None]
Value	unsigned integer

Maximum events allowed inside one long bucket window before the worker is slept on further matches. This setting must be explicitly set to non-0 value.

throttle_name

Default	[None]
Value	string

Name of the throttle. The throttle filter name refers to this setting.

throttle_short_bucket_expire

Default	1min
Value	time

Short bucket window length. Counter resets when the wall clock crosses a multiple of this interval (fixed window, not rolling).

throttle_short_bucket_max_count

Default	[None]
Value	unsigned integer

Maximum events allowed inside one short bucket window before the worker is slept on further matches. This setting must be explicitly set to non-0 value.

throttle_socket_path

Default	throttle
Value	string

Path to the unix socket exposed by the throttle service. Relative paths are resolved against base_dir.

throttle_type

Default	user
Value	string

Scope of the throttle bucket:

Value	Description
global	One bucket shared by all users on this host.
user	One bucket per username. The username is part of the bucket's identity.

Example Configuration

Limit each user to 60 IMAP APPEND commands per minute and 10 000 per day, and globally limit LMTP deliveries to 1 000 per minute on the backend:

mail_plugins {
  throttle = yes
}

throttle imap_append_user {
  type = user
  filter = event=imap_command_finished AND cmd_name=APPEND

  short_bucket_expire = 1min
  short_bucket_max_count = 60
  long_bucket_expire = 1d
  long_bucket_max_count = 10000
}

throttle lmtp_global {
  type = global
  filter = event=lmtp_command_finished AND cmd_name=DATA

  short_bucket_expire = 1min
  short_bucket_max_count = 1000
  long_bucket_expire = 1h
  long_bucket_max_count = 50000
}

To load the plugin only into specific protocols, use a protocol filter around mail_plugins.

doveadm Commands

doveadm throttle list queries the running throttle server for current counter values.

Events

When throttling delays an event, the plugin annotates the event with a throttled field containing the sleep duration in milliseconds. This can be used in Statistics.

For IMAP commands, the cumulative sleep across all throttles that matched during the command is also recorded in the throttled_any field on the command's global event; this causes the tagged response to be prefixed with [THROTTLED].