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.
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.