ratelimit Object

Added in version 8.2602.0.

The ratelimit object allows defining named rate limit policies that can be reused across multiple inputs. This is particularly useful for applying a consistent policy to a group of listeners or for managing rate limits centrally.

Parameters

name

type	required	default
string	yes	none

The name of the rate limit policy. This name is used to reference the policy from input modules (e.g., via RateLimit.Name="policyName").

interval

type	required	default
integer	no	0

The interval (in seconds) for the rate limit. Messages exceeding the burst limit within this interval are dropped. A value of 0 disables rate limiting.

burst

type	required	default
integer	no	10000

The maximum number of messages allowed within the interval.

severity

type	required	default
severity	no	0

Only messages with a syslog severity numerically greater than or equal to this threshold are subject to rate limiting. Lower numeric severities remain unlimited.

This is useful when a shared policy should throttle verbose traffic such as info or debug while leaving more urgent messages untouched. Modules that derive severity from input metadata, such as imjournal, can use the same shared policy without a module-specific severity knob.

policyWatch

type	required	default
boolean	no	off

Enable automatic reload of configured external policy files when they change. When watch support is available, rsyslog monitors the configured policy and perSourcePolicy files and reloads them after the debounce interval. When watch support is unavailable in the current build or runtime environment, rsyslog logs a warning and continues with HUP-only reload behavior.

policyWatchDebounce

type	required	default
time interval	no	5s

Quiet period applied to policyWatch reloads. Each new file event resets the timer, so rapid updates are coalesced into one reload. Supported suffixes are ms, s, m, and h. Bare numbers are interpreted as seconds.

perSource

type	required	default
boolean	no	off

Enable per-source rate limiting using an external YAML policy.

perSourcePolicy

type	required	default
string	no	none

Path to the YAML file that defines per-source limits. Required when perSource is on. The YAML file must define a default block with max and window values and may optionally include overrides keyed by exact sender values.

default:
  max: 1000
  window: 10s
overrides:
  - key: "db01.corp.local"
    max: 5000
    window: 10s

perSourceKeyTpl

type	required	default
string	no	RSYSLOG_PerSourceKey

Template that computes the per-source key. The default template is equivalent to %hostname%.

perSourceMaxStates

type	required	default
integer	no	10000

Upper bound on the number of tracked sender keys for per-source limits. When the cap is reached, least-recently-used sender state is evicted.

perSourceTopN

type	required	default
integer	no	10

Number of per-source drop counters to expose in statistics output (top-N by drops).

Example

# Define a strict rate limit for public facing ports
ratelimit(name="strict" interval="1" burst="50")

# Rate-limit only lower-priority journal traffic
ratelimit(name="journal_lowprio"
          interval="600"
          burst="20000"
          severity="info")

# Define a watched YAML policy for automatic reload
ratelimit(name="watched"
          policy="/etc/rsyslog/ratelimit.yaml"
          policyWatch="on"
          policyWatchDebounce="500ms")

# Define per-source policy for TCP inputs
ratelimit(name="per_source"
          perSource="on"
          perSourcePolicy="/etc/rsyslog/imtcp-ratelimits.yaml"
          perSourceKeyTpl="PerSourceKey")

# Apply it to a TCP listener
input(type="imtcp" port="10514" rateLimit.Name="strict")

# Apply it to a Plain TCP listener
input(type="imptcp" port="10515" rateLimit.Name="strict")

# Apply per-source limits to a TCP listener
input(type="imtcp" port="10516" rateLimit.Name="per_source")

# Apply a severity-aware shared policy to the journal reader
module(load="imjournal" rateLimit.Name="journal_lowprio")

Per-source key examples

# Key by IP address
template(name="PerSourceIP" type="string" string="%fromhost-ip%")
ratelimit(name="per_source_ip"
          perSource="on"
          perSourcePolicy="/etc/rsyslog/imtcp-ratelimits.yaml"
          perSourceKeyTpl="PerSourceIP")
input(type="imtcp" port="514" rateLimit.Name="per_source_ip")

# Key by hostname (default)
template(name="PerSourceHost" type="string" string="%hostname%")
ratelimit(name="per_source_host"
          perSource="on"
          perSourcePolicy="/etc/rsyslog/imtcp-ratelimits.yaml"
          perSourceKeyTpl="PerSourceHost")
input(type="imtcp" port="514" rateLimit.Name="per_source_host")

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project