Skip to content

Packaged Plugins¤

With the aMQTT plugins framework, one can add additional functionality without having to rewrite core logic in the broker or client. Plugins can be loaded and configured using the plugins section of the config file (or parameter passed to the class).

Broker¤

By default, EventLoggerPlugin, PacketLoggerPlugin, AnonymousAuthPlugin and BrokerSysPlugin are activated and configured for the broker:

---
listeners:
  default:
    type: tcp
    bind: 0.0.0.0:1883
plugins:
  amqtt.plugins.logging_amqtt.EventLoggerPlugin:
  amqtt.plugins.logging_amqtt.PacketLoggerPlugin:
  amqtt.plugins.authentication.AnonymousAuthPlugin:
    allow_anonymous: true
  amqtt.plugins.sys.broker.BrokerSysPlugin:
    sys_interval: 20
Loading plugins from EntryPoints in pyproject.toml has been deprecated (v0.11.2).

Previously, all plugins were loaded from EntryPoints:

[project.entry-points."amqtt.broker.plugins"]
event_logger_plugin = "amqtt.plugins.logging_amqtt:EventLoggerPlugin"
packet_logger_plugin = "amqtt.plugins.logging_amqtt:PacketLoggerPlugin"
auth_anonymous = "amqtt.plugins.authentication:AnonymousAuthPlugin"
auth_file = "amqtt.plugins.authentication:FileAuthPlugin"
topic_taboo = "amqtt.plugins.topic_checking:TopicTabooPlugin"
topic_acl = "amqtt.plugins.topic_checking:TopicAccessControlListPlugin"
broker_sys = "amqtt.plugins.sys.broker:BrokerSysPlugin"

But the previous default config only caused 4 plugins to be active:

---
listeners:
  default:
    type: tcp
    bind: 0.0.0.0:1883
sys_interval: 20
auth:
  plugins:
    - auth_anonymous
  allow-anonymous: true
topic-check:
  enabled: False

Client¤

By default, the PacketLoggerPlugin is activated and configured for the client:

---
keep_alive: 10
ping_delay: 1
default_qos: 0
default_retain: false
auto_reconnect: true
cleansession: true
reconnect_max_interval: 10
reconnect_retries: 2
connection:
  uri: "mqtt://127.0.0.1"
plugins:
  amqtt.plugins.logging_amqtt.PacketLoggerPlugin:

Plugins¤

Anonymous (Auth Plugin)¤

amqtt.plugins.authentication.AnonymousAuthPlugin

Authentication plugin allowing anonymous access.

Config dataclass ¤

Configuration for AnonymousAuthPlugin.

allow_anonymous class-attribute instance-attribute ¤
allow_anonymous: bool = field(default=True)

Allow all anonymous authentication (even with no username).

Danger

even if allow_anonymous is set to false, the plugin will still allow access if a username is provided by the client

EntryPoint-style configuration is deprecated (v0.11.2). 
auth:
  plugins:
    - auth_anonymous
  allow-anonymous: true # if false, providing a username will allow access

Password File (Auth Plugin)¤

amqtt.plugins.authentication.FileAuthPlugin

Authentication plugin based on a file-stored user database.

Config dataclass ¤

Configuration for FileAuthPlugin.

password_file class-attribute instance-attribute ¤
password_file: str | Path | None = None

Path to file with username:password pairs, one per line. All passwords are encoded using sha-512.

EntryPoint-style configuration is deprecated (v0.11.2). 
auth:
  plugins:
    - auth_file
  password-file: /path/to/password_file

File Format

The file includes username:password pairs, one per line.

The password should be encoded using argon2:

import sys
from getpass import getpass
from argon2 import PasswordHasher

passwd = input() if not sys.stdin.isatty() else getpass()
password_hasher = PasswordHasher()
print(password_hasher.hash(passwd))
sha512 hashing is deprecated, replaced by argon2 (v0.12.0)

Due to the removal of Python's standard library crypt module in Python 3.13 and the no-longer-supported passlib library, sha512_crypt is deprecated in favor of argon2 hashing.

Deprecation includes verifying of existing sha512 but will also generate a warning. The password file will not be updated with a newly hashed version. Password files should be re-generated with argon2 or bcrypt (see script example above).

Taboo (Topic Plugin)¤

amqtt.plugins.topic_checking.TopicTabooPlugin

Prevents using topics named: prohibited, top-secret, and data/classified

Configuration

plugins:
  amqtt.plugins.topic_checking.TopicTabooPlugin:
EntryPoint-style configuration is deprecated (v0.11.2). 
topic-check:
  enabled: true
  plugins:
    - topic_taboo

ACL (Topic Plugin)¤

amqtt.plugins.topic_checking.TopicAccessControlListPlugin

Configuration

Each acl category are a list a key-value pair, where:

<username>:["<topic1>", "<topic2>", ...] (string, list[string]): username of the client followed by a list of allowed topics (wildcards are supported: #, +).

# and $SYS topics

Per the MQTT 3.1.1 spec 4.7.2, a single # will not allow access to $ broker topics; need to additionally specify $SYS/# to allow a client full access subscribe & receive.

Also MQTT spec prevents clients from publishing to topics starting with $; these will be ignored.

If set to None, no restrictions are placed on client subscriptions (legacy behavior). An empty list will block clients from using any topics.

  • subscribe-acl (mapping): determines subscription access.

  • acl (mapping): Deprecated and replaced by subscribe-acl (v0.11.2).

  • publish-acl (mapping): determines publish access.

  • receive-acl (mapping): determines if a message can be sent to a client.

    Reserved usernames

    • The username admin is allowed access to all topics.
    • The username anonymous will control allowed topics, if using the auth_anonymous plugin.
plugins:
  amqtt.plugins.topic_checking.TopicAccessControlListPlugin:
    acl:
      - username: ["list", "of", "allowed", "topics", "for", "subscribing"]
      - .
    publish_acl:
      - username: ["list", "of", "allowed", "topics", "for", "publishing"]
      - .
EntryPoint-style configuration is deprecated (v0.11.2). 
topic-check:
  enabled: true
  plugins:
    - topic_acl
  publish-acl:
    - username: ["list", "of", "allowed", "topics", "for", "publishing"]
    - .
  acl:
    - username: ["list", "of", "allowed", "topics", "for", "subscribing"]
    - .

$SYS topics¤

amqtt.plugins.sys.broker.BrokerSysPlugin

Publishes, on a periodic basis, statistics about the broker

Optional dependency required for BrokerSysPlugin" (v0.12.0).

In a future major release, psutil will become an optional dependency. " "If your application relies on the BrokerSysPlugin, please add amqtt[dollarsys] " "to your project's dependency configurations.",

Configuration

  • sys_interval - int, seconds between updates (default: 20)
plugins:
  amqtt.plugins.sys.broker.BrokerSysPlugin:
    sys_interval: 20  # int, seconds between updates

Supported Topics

  • $SYS/broker/version (string)
  • $SYS/broker/load/bytes/received (int)
  • $SYS/broker/load/bytes/sent (int)
  • $SYS/broker/messages/received (int)
  • $SYS/broker/messages/sent (int)
  • $SYS/broker/time (int, current time in epoch seconds)
  • $SYS/broker/uptime (int, seconds since broker start)
  • $SYS/broker/uptime/formatted (string, start time of broker in UTC)
  • $SYS/broker/clients/connected (int, number of currently connected clients)
  • $SYS/broker/clients/disconnected (int, number of clients that have disconnected)
  • $SYS/broker/clients/maximum (int, maximum number of clients connected)
  • $SYS/broker/clients/total (int)
  • $SYS/broker/messages/inflight (int)
  • $SYS/broker/messages/inflight/in (int)
  • $SYS/broker/messages/inflight/out (int)
  • $SYS/broker/messages/inflight/stored (int)
  • $SYS/broker/messages/publish/received (int)
  • $SYS/broker/messages/publish/sent (int)
  • $SYS/broker/messages/retained/count (int)
  • $SYS/broker/messages/subscriptions/count (int)
  • $SYS/broker/heap/size (float, MB)
  • $SYS/broker/heap/maximum (float, MB)
  • $SYS/broker/cpu/percent (float, %)
  • $SYS/broker/cpu/maximum (float, %)

Event Logger¤

amqtt.plugins.logging_amqtt.EventLoggerPlugin

This plugin issues log messages when broker and mqtt events are triggered:

  • info level messages for client connected and client disconnected
  • debug level for all others
plugins:
  amqtt.plugins.logging_amqtt.EventLoggerPlugin:

Packet Logger¤

amqtt.plugins.logging_amqtt.PacketLoggerPlugin

This plugin issues debug-level messages for mqtt events: on_mqtt_packet_sent and on_mqtt_packet_received.

plugins:
  amqtt.plugins.logging_amqtt.PacketLoggerPlugin: