Broker API reference¶
The Broker
class provides a complete MQTT 3.1.1 broker implementation. This class allows Python developers to embed a MQTT broker in their own applications.
Usage example¶
The following example shows how to start a broker using the default configuration:
import logging
import anyio
import os
from moat.mqtt.broker import open_broker
async def broker_coro():
async with create_broker() as broker:
while True:
await anyio.sleep(99999)
if __name__ == '__main__':
formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
logging.basicConfig(level=logging.INFO, format=formatter)
anyio.run(broker_coro)
When executed, this script runs the broker_coro
until it completes.
broker_coro
creates a Broker
instance.
Once completed, the loop is ran forever, making this script never stop …
Reference¶
Broker API¶
Typically, you create a Broker
instance by way of async with
create_broker()
(). This context manager creates a taskgroup for the client’s housekeeping tasks to run in.
-
moat.mqtt.broker.
create_broker
()¶
If using an async context manager doesn’t fit your code, you can pass your own taskgroup
and explicitly start (and stop) the broker. However, the broker may leak some tasks, thus using create_broker()
is strongly recommended.
Broker configuration¶
~moat.mqtt.broker.create_broker accepts a config
parameter which allows to setup some behaviour and defaults settings. This argument must be a Python dictionary. For convenience, it is presented below as a YAML file [1].
listeners:
default:
max-connections: 50000
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/key
my-ws-1:
bind: 0.0.0.0:8080
type: ws
timeout-disconnect-delay: 2
auth:
plugins: ['auth.anonymous'] #List of plugins to activate for authentication among all registered plugins
allow-anonymous: true / false
password-file: "/some/passwd_file"
topic-check:
enabled: true / false # Set to False if topic filtering is not needed
plugins: ['topic_acl'] #List of plugins to activate for topic filtering among all registered plugins
acl:
# username: [list of allowed topics]
username1: ['repositories/+/master', 'calendar/#', 'data/memes'] # List of topics on which client1 can publish and subscribe
username2: ...
anonymous: [] # List of topics on which an anonymous client can publish and subscribe
The listeners
section allows to define network listeners which must be started by the Broker
. Several listeners can be setup. default
subsection defines common attributes for all listeners. Each listener can have the following settings:
bind
: IP address and port binding.max-connections
: Set maximum number of active connection for the listener.0
means no limit.type
: transport protocol type; can betcp
for classic TCP listener orws
for MQTT over websocket.ssl
enables (on
) or disable secured connection over the transport protocol.cafile
,cadata
,certfile
andkeyfile
: mandatory parameters for SSL secured connections.
The auth
section setup authentication behaviour:
plugins
: defines the list of activated plugins. Note the plugins must be defined in themoat.mqtt.broker.plugins
entry point.allow-anonymous
: used by the internalmoat.mqtt.plugins.authentication.AnonymousAuthPlugin
plugin. This parameter enables (on
) or disable anonymous connection, ie. connection without username.password-file
: used by the internalmoat.mqtt.plugins.authentication.FileAuthPlugin
plugin. This parameter gives to path of the password file to load for authenticating users.
The topic-check
section setup access control policies for publishing and subscribing to topics:
enabled
: set to true if you want to impose an access control policy. Otherwise, set it to false.plugins
: defines the list of activated plugins. Note the plugins must be defined in themoat.mqtt.broker.plugins
entry point.- additional parameters: depending on the plugin used for access control, additional parameters should be added.
- In case of
topic_acl
plugin, the Access Control List (ACL) must be defined in the parameteracl
. - For each username, a list with the allowed topics must be defined.
- If the client logs in anonymously, the
anonymous
entry within the ACL is used in order to grant/deny subscriptions.
- In case of
[1] | See PyYAML for loading YAML files as Python dict. |