Tree


LICENSE.mdcommits | blame
Makefilecommits | blame
README.mdcommits | blame
ROADMAP.mdcommits | blame
mqttctl/
mqttd/

README.md

mqttd for OpenBSD
=================

mqttd is a privilege separated MQTT broker for OpenBSD. It speaks MQTT
3.1, 3.1.1 and 5.0 over TCP and TLS and implements QoS 0, 1 and 2,
retained messages, will messages with delay, persistent sessions with
offline queues, session and message expiry, topic aliases, subscription
identifiers, shared subscriptions, bridging to other brokers, Sparkplug
Aware behaviour and topic ACLs with password, certificate or external
authentication.

The daemon is split into a privileged parent, a control process, a single
broker process holding all protocol state, a listen process that accepts
connections and a configurable number of sockets workers that run TLS and
framing for the connections handed to them.
The layout and plumbing come from the thingsd proxy daemon.

Prerequisites
-------------

* OpenBSD 7.7 or higher (uses the current imsg API)

Files
-----

* `/usr/local/sbin/mqttd`
* `/usr/local/man/man8/mqttd.8`
* `/etc/examples/mqttd.conf`
* `/usr/local/man/man5/mqttd.conf.5`
* `/etc/rc.d/mqttd`
* `/etc/login.conf.d/mqttd`
* `/usr/local/sbin/mqttctl`
* `/usr/local/man/man8/mqttctl.8`

Usage
-----

Compile and install.

		make
		doas make install
		doas groupadd _mqttd
		doas useradd -d /var/empty -L daemon -g _mqttd -s /sbin/nologin _mqttd
		doas cp mqttd/examples/etc/rc.d/mqttd /etc/rc.d/
		doas cp mqttd/examples/etc/login.conf.d/mqttd /etc/login.conf.d/
		doas cp mqttd/examples/etc/mqttd.conf /etc/examples/
		doas install -d -o _mqttd -g _mqttd -m 700 /var/db/mqttd

The login class sets the open file limit every process runs with; each
client connection costs one descriptor in one sockets worker, so the
daemon carries about `workers` times that limit in connections. Size
the class for the fleet and raise `kern.maxfiles` to match.

Create password hashes with `encrypt -b 10`, write `/etc/mqttd.conf`
according to `man mqttd.conf`, then `rcctl enable mqttd` and
`rcctl start mqttd`. Run `mqttd -d` to stay in the foreground, and
`mqttd -n` to check the configuration.

Inspect the broker with `mqttctl show broker`, `mqttctl show clients`,
`mqttctl show subscriptions` and `mqttctl show retained`.

The optional external authenticator example lives in
`mqttd/examples/auth/mqttd-auth.pl`; install it somewhere like
`/usr/local/libexec/` and point `auth exec` at it.

Listeners speak plain MQTT, MQTT over TLS, MQTT over WebSocket (with or
without TLS), accept PROXY protocol headers from a load balancer, or sit
on a unix socket.

A `snowflake` block sinks topics straight into a Snowflake table through
the SQL REST API with key-pair authentication, with local queueing and
at-least-once delivery; see `mqttd.conf(5)`.

Not yet implemented
-------------------

* adding or removing bridges without a restart
* fan-out offload to the sockets workers, only if benchmarks show the
  broker bound on per-recipient encoding (see ROADMAP.md)

Author
------

[Tracey Emery](https://github.com/basepr1me/)

See the [License](LICENSE.md) file for more information.