Skip to content

Broker Configuration¤

This configuration structure is a amqtt.contexts.BrokerConfig or a python dictionary with the same structure when instantiating amqtt.broker.Broker or as a yaml formatted file passed to the amqtt script.

If not specified, the Broker() will be started with the default BrokerConfig(), as represented in yaml format:

---
listeners:
  default:
    type: tcp
    bind: 0.0.0.0:1883
timeout_disconnect_delay: 0
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

BrokerConfig dataclass ¤

Bases: Dictable

Structured configuration for a broker. Can be passed directly to amqtt.broker.Broker or created from a dictionary.

auth class-attribute instance-attribute ¤

auth: dict[str, Any] | None = None

Deprecated field used to config EntryPoint-loaded plugins. See AnonymousAuthPlugin and FileAuthPlugin for recommended configuration.

listeners class-attribute instance-attribute ¤

listeners: dict[
    Literal["default"] | str, ListenerConfig
] = {
    "default": ListenerConfig(
        type="tcp",
        bind="0.0.0.0:1883",
        max_connections=0,
        ssl=False,
        cafile=None,
        capath=None,
        cadata=None,
        certfile=None,
        keyfile=None,
        reader=None,
        writer=None,
    )
}

Network of listeners used by the services. a 'default' named listener is required; if another listener does not set a value, the 'default' settings are applied. See ListenerConfig for more information.

plugins class-attribute instance-attribute ¤

plugins: (
    dict[str, Any] | list[str | dict[str, Any]] | None
) = {
    "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
    },
}

The dictionary has a key of the dotted-module path of a class derived from BasePlugin, BaseAuthPlugin or BaseTopicPlugin; the value is a dictionary of configuration options for that plugin. See custom plugins for more information. list[str | dict[str,Any]] is deprecated but available to support legacy use cases.

session_expiry_interval class-attribute instance-attribute ¤

session_expiry_interval: int | None = None

Seconds for an inactive session to be retained.

sys_interval class-attribute instance-attribute ¤

sys_interval: int | None = None

Deprecated field to configure the BrokerSysPlugin. See BrokerSysPlugin for recommended configuration.

timeout_disconnect_delay class-attribute instance-attribute ¤

timeout_disconnect_delay: int | None = 0

Client disconnect timeout without a keep-alive.

topic_check class-attribute instance-attribute ¤

topic_check: dict[str, Any] | None = None

Deprecated field used to config EntryPoint-loaded plugins. See TopicTabooPlugin and TopicACLPlugin for recommended configuration method.

Deprecated: auth configuration settings

auth

Configuration for authentication behaviour:

  • plugins (list[string]): defines the list of plugins which are activated as authentication plugins.

Note

Plugins used here must first be defined in the amqtt.broker.plugins entry point.

Warning

If plugins is omitted from the auth section, all plugins listed in the amqtt.broker.plugins entrypoint will be enabled for authentication, including allowing anonymous login.

plugins: [] will deny connections from all clients.

  • allow-anonymous (bool): True will allow anonymous connections, used by amqtt.plugins.authentication.AnonymousAuthPlugin.

Danger

False does not disable the auth_anonymous plugin; connections will still be allowed as long as a username is provided. If security is required, do not include auth_anonymous in the plugins list.

  • password-file (string). Path to sha-512 encoded password file, used by amqtt.plugins.authentication.FileAuthPlugin.
Deprecated: sys_interval

sys_interval (int)

System status report interval in seconds, used by the amqtt.plugins.sys.broker.BrokerSysPlugin.

Deprecated: topic-check configuration settings

topic-check

Configuration for access control policies for publishing and subscribing to topics:

  • enabled (bool): Enable access control policies (true). false will allow clients to publish and subscribe to any topic.

  • plugins (list[string]): defines the list of plugins which are activated as access control plugins. Note the plugins must be defined in the amqtt.broker.plugins entry point.

  • acl (list): plugin to determine subscription access; if publish-acl is not specified, determine both publish and subscription access. The list should be 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: #, +).

    used by the amqtt.plugins.topic_acl.TopicAclPlugin

  • publish-acl (list): plugin to determine publish access. This parameter defines the list of access control rules; each item is 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: #, +).

Reserved usernames (used by the amqtt.plugins.topic_acl.TopicAclPlugin)

      - The username `admin` is allowed access to all topic.
      - The username `anonymous` will control allowed topics if using the `auth_anonymous` plugin.

ListenerConfig dataclass ¤

Bases: Dictable

Structured configuration for a broker's listeners.

bind class-attribute instance-attribute ¤

bind: str | None = '0.0.0.0:1883'

address and port for the listener to bind to

cadata class-attribute instance-attribute ¤

cadata: str | Path | None = None

Either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates.

cafile class-attribute instance-attribute ¤

cafile: str | Path | None = None

Path to a file of concatenated CA certificates in PEM format. See Certificates for more info.

capath class-attribute instance-attribute ¤

capath: str | Path | None = None

Path to a directory containing one or more CA certificates in PEM format, following the OpenSSL-specific layout.

certfile class-attribute instance-attribute ¤

certfile: str | Path | None = None

Full path to file in PEM format containing the server's certificate (as well as any number of CA certificates needed to establish the certificate's authenticity.)

keyfile class-attribute instance-attribute ¤

keyfile: str | Path | None = None

Full path to file in PEM format containing the server's private key.

max_connections class-attribute instance-attribute ¤

max_connections: int = 0

max number of connections allowed for this listener

ssl class-attribute instance-attribute ¤

ssl: bool = False

secured by ssl

type class-attribute instance-attribute ¤

type: ListenerType = TCP

Type of listener: tcp for 'mqtt' or ws for 'websocket' when specified in dictionary or yaml.'

Example¤

When a configuration is passed to the amqtt script, here is the equivalent format based on the structures above:

listeners:
    default:
        max-connections: 500
        type: tcp
    my-tcp-1:
        bind: 127.0.0.1:1883
    my-tcp-2:
        bind: 1.2.3.4:1884
        max-connections: 1000
    my-tcp-ssl-1:
        bind: 127.0.0.1:8885
        ssl: on
        cafile: /some/cafile
        capath: /some/folder
        capath: 'certificate data'
        certfile: /some/certfile
        keyfile: /some/keyfile
    my-ws-1:
        bind: 0.0.0.0:8080
        type: ws
    my-wss-1:
        bind: 0.0.0.0:9003
        type: ws
        ssl: on
        certfile: /some/certfile
        keyfile: /some/keyfile
timeout-disconnect-delay: 2
plugins:
  - amqtt.plugins.authentication.AnonymousAuthPlugin:
      allow-anonymous: true
  - amqtt.plugin.authentication.FileAuthPlugin:
      password-file: /some/password-file
  - amqtt.plugins.topic_checking.TopicAccessControlListPlugin:
      acl:
        username1: ['repositories/+/master', 'calendar/#', 'data/memes']
        username2: ['calendar/2025/#', 'data/memes']
        anonymous: ['calendar/2025/#']

This configuration file would create the following listeners:

  • my-tcp-1: an unsecured TCP listener on port 1883 allowing 500 clients connections simultaneously
  • my-tcp-2: an unsecured TCP listener on port 1884 allowing 1000 client connections
  • my-tcp-ssl-1: a secured TCP listener on port 8883 allowing 500 clients connections simultaneously
  • my-ws-1: an unsecured websocket listener on port 9001 allowing 500 clients connections simultaneously
  • my-wss-1: a secured websocket listener on port 9003 allowing 500

And enable the following topic access:

  • username1 to login and subscribe/publish to topics repositories/+/master, calendar/# and data/memes
  • username2 to login and subscribe/publish to topics calendar/2025/# and data/memes
  • any user not providing credentials (anonymous) can only subscribe/publish to calendar/2025/#