Rate Limiting

info

This feature is only available with the dynamic-security feature

Concept Overview

Rate Limiting controls the volume of MQTT messages a client can send or receive over a specific period. It is designed to prevent system overload by throttling excessive message traffic.

The message flow can be restricted independently for incoming traffic (messages sent by the client to the broker) and outgoing traffic (messages sent from the broker to the client). These limits can be enforced globally via the broker's mosquitto.conf file, or assigned to specific client roles using the Dynamic Security plugin.

The rate limit does not simply apply to the set ACLs, but to the complete traffic a client generates, with a limiting role attached. If multiple roles are assigned, competing limits will lead to the lower limit being enforced. If no limit is configured (-1), the limit of the other role will be used for the client traffic rate limiting.

Configuration Options

When configuring rate limits via the plugin, you can define the following options. Both incoming and outgoing traffic can be configured independently of one another.

Option / Parameter	Description	Default Value	Allowed Values
rolename	(Required) The name of the specific client role to attach the limits to. Any client with this role will have the rates enforced on it.	-	String
incoming_rate_limit	(Optional) The maximum number of incoming messages permitted. A value of 0 means the rate is completely unlimited.	-1 (No limit)	Integer
outgoing_rate_limit	(Optional) The maximum number of outgoing messages permitted. A value of 0 means the rate is completely unlimited.	-1 (No limit)	Integer
incoming_time_frame	(Optional) The duration of the incoming time window. This must consist of a positive integer followed by a time unit character (e.g., "1s" for one second, "1d" for one day).	"0s" (Not configured)	Numbers with time units. Supported units: s,h,d,w,m,y (second, hour, day, week, month, year)
outgoing_time_frame	(Optional) The duration of the outgoing time window (e.g., "1s", "1h"). This only has an effect if a corresponding rate limit is configured.	"0s" (Not configured)	Numbers with time units. Supported units: s,h,d,w,m,y (second, hour, day, week, month, year)

Dynamic Security API

To apply these configuration options to a specific role, you send a JSON payload to the Dynamic Security plugin API. (Note: If you are unfamiliar with this API, please refer to the main API documentation). As shown in the table above, only the command and rolename fields are strictly required. All rate and time frame parameters are optional. This allows you to perform partial updates. For example, you can modify the incoming_rate_limit while leaving the existing outgoing rate limits completely unchanged.

Example

{
  "commands": [
    {
      "command": "setRolePublishRateLimit",
      "rolename": "sensor_device",
      "incoming_rate_limit": 10,
      "outgoing_rate_limit": 0,
      "incoming_time_frame": "1s",
    }
  ]
}

Explanation

In the command payload above:

• command: Name of the rate limiting set in place.
• rolename: Targets the specific role named sensor_device.
• incoming_rate_limit & incoming_time_frame: Restricts clients with this role to sending a maximum of 10 messages every 1 second.
• outgoing_rate_limit: Set to 0, meaning the broker can send an unlimited number of messages to clients with this role.
• outgoing_time_frame: Because this was intentionally omitted from the payload, any existing outgoing time frame configuration for this role remains unchanged.