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, and a configurable number of
preforked sockets processes that own the network connections and TLS.
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`
* `/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/mqttd.conf /etc/examples/
doas install -d -o _mqttd -g _mqttd -m 700 /var/db/mqttd
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 processes (see ROADMAP.md)
Author
------
[Tracey Emery](https://github.com/basepr1me/)
See the [License](LICENSE.md) file for more information.