| name | mqtt |
| description | Use when working with Synchronet's MQTT integration — discovering whether MQTT is enabled (the `[MQTT]` section of `ctrl/main.ini`, **not** `sbbs.ini`), reading broker address/port/credentials/TLS settings, connecting with `mosquitto_sub`/`mosquitto_pub` (anonymous, user+pass, or one of four TLS modes: CA, mTLS, PSK, SBBS-internal-CA), or interacting with the topic tree for **monitoring** (server/node status, node-output spying, `action/#`, retained `login_attempts/<IP>` and `max_concurrent/<IP>`, log streams `…/log[/<N>]`) or **controlling** the BBS (production-impacting topics that recycle/pause/resume servers, clear failed-login lists, set node flags, inject input or messages into a node — plus the local-filesystem equivalents in `ctrl/`). Trigger on "is MQTT enabled", "what's the broker address", "subscribe to all sbbs logs", "pause/recycle via MQTT", "inject a message into node N", "clear failed-login for an IP", or "spy on a node remotely". |
Synchronet MQTT — monitor and control
Reference (authoritative):
MQTT in Synchronet is two-way. Most use cases are read-only monitoring, but the same broker also carries control-plane topics that recycle servers, pause/resume listeners, clear filter lists, set node flags, and inject input. Read the Control plane — production-impacting operations section before publishing anything.
Step 1 — discover whether MQTT is enabled and how to connect
The [MQTT] section lives in ctrl/main.ini, not ctrl/sbbs.ini. (This trips a lot of people; the rest of Synchronet's server/daemon config is in sbbs.ini, but MQTT belongs to BBS-level system settings in main.ini.) Read it:
grep -A 20 '^\[MQTT\]' <sbbs>/ctrl/main.ini
Keys (defaults shown; full source of truth is scfglib1.c::read_main_cfg):
| Key | Default | Meaning |
|---|
Enabled | false | master switch; if false, no topics are published or accepted |
InternalBroker | false | if true, Synchronet runs its own embedded broker (no external mosquitto needed); otherwise connect to the address below |
Broker_addr | 127.0.0.1 | IPv4/IPv6/hostname of the MQTT broker |
Broker_port | 1883 (IPPORT_MQTT) | broker TCP port (typically 1883 plain, 8883 TLS) |
Username | empty | MQTT username; empty = anonymous |
Password | empty | MQTT password; plain text in the file — restrict file permissions |
Keepalive | 60 (seconds; range 5–INT_MAX) | client keepalive interval |
Protocol_version | 4 (range 3–5; 3=v3.1, 4=v3.1.1, 5=v5) | MQTT protocol version. v5 unlocks per-message user properties (Synchronet uses these for log-level tagging on …/log without level suffix). |
Publish_QOS | 0 (range 0–2) | QoS for messages Synchronet publishes |
Subscribe_QOS | 2 (range 0–2) | QoS for subscriptions Synchronet places |
LogLevel | Info | minimum severity of console lines republished to MQTT |
Verbose | true | publish per-node status, per-server status, and full log streams. false reduces to terminal status only. (Mirrors SCFG's "Publish Verbosity = High" vs "Low".) |
TLS_mode | 0 (disabled) | see TLS table below |
TLS_cafile | empty | path to a CA cert/bundle (used by modes 1, 2) |
TLS_certfile | empty | path to client certificate (mode 2) |
TLS_keyfile | empty | path to client private key (mode 2) |
TLS_keypass | empty | passphrase for the client key, if encrypted |
TLS_psk | empty | pre-shared key, hex-encoded (mode 3) |
TLS_identity | empty | PSK identity string (mode 3) |
TLS_mode enumeration (from mqtt.h):
| Value | Name | What it means | What you need |
|---|
0 | MQTT_TLS_DISABLED | plain TCP | nothing |
1 | MQTT_TLS_CA | TLS, broker cert verified against a CA bundle | TLS_cafile |
2 | MQTT_TLS_CERT | mTLS — client also presents a cert | TLS_cafile, TLS_certfile, TLS_keyfile (+ TLS_keypass if encrypted) |
3 | MQTT_TLS_PSK | pre-shared-key TLS | TLS_psk (hex), TLS_identity |
4 | MQTT_TLS_SBBS | use Synchronet's own internal CA and the BBS's web/server cert | nothing extra; the BBS handles it |
Security note: ctrl/main.ini contains Password= and possibly TLS_keypass= in plain text. The default install on a typical Linux host is world-readable; tighten with chmod 600 ctrl/main.ini (and chown to the BBS user) if your threat model includes other local users.
Step 2 — connect with mosquitto_sub / mosquitto_pub
Once you know broker/port/auth/TLS from main.ini, plain-TCP (TLS_mode=0) anonymous:
mosquitto_sub -h <broker> -p <port> -v -t 'sbbs/#'
With username/password:
mosquitto_sub -h <broker> -p <port> -u <user> -P <pass> -v -t 'sbbs/#'
With TLS mode 1 (CA-verified broker, anonymous):
mosquitto_sub -h <broker> -p <port> --cafile <ca-bundle> -v -t 'sbbs/#'
With TLS mode 2 (mTLS):
mosquitto_sub -h <broker> -p <port> \
--cafile <ca> --cert <client-cert> --key <client-key> \
-v -t 'sbbs/#'
With TLS mode 3 (PSK):
mosquitto_sub -h <broker> -p <port> --psk <hex-key> --psk-identity <identity> \
-v -t 'sbbs/#'
TLS mode 4 (MQTT_TLS_SBBS) uses the BBS's own CA + cert internally — an external client (mosquitto_sub) doesn't get that bundle automatically; you'd need the broker's CA file out-of-band to verify it, or just use --insecure for quick diagnostics (skips hostname verification — fine for a local test broker, not for production).
MQTT protocol version — mosquitto_sub/-pub default to v3.1.1 (4). Match the broker's expectation; for v5 add -V 5. Note that the level-as-user-property convention on Synchronet's bare …/log topics only works on v5.
Native access from Synchronet JavaScript (the MQTT object)
mosquitto_sub/-pub are right for shell diagnostics, but inside Synchronet
(a JS module, service, or a chat-bot tool) use the built-in MQTT object —
it reads the broker address / port / credentials / TLS straight from the
[MQTT] section of main.ini, so there are no hardcoded broker details or
secrets in your script, and it speaks the same config the BBS itself uses.
if (!system.mqtt_enabled)
return;
var mqtt = new MQTT;
if (!mqtt.connect()) {
log(LOG_WARNING, "MQTT connect failed: " + mqtt.error_str);
return;
}
mqtt.subscribe("sbbs/" + system.qwk_id + "/host/+/server/+");
var msg;
while ((msg = mqtt.read(1000, true)) !== false) {
print(msg.topic + " => " + msg.data);
}
Key members (the object extends Socket, so socket props apply too):
| Member | Purpose |
|---|
system.mqtt_enabled | bool — is MQTT configured/on? Gate every MQTT path on this. |
system.qwk_id | the <BBSID> for building topics ("sbbs/" + system.qwk_id + …) |
new MQTT / mqtt.connect() | connect using main.ini's broker/auth/TLS (no args) |
mqtt.subscribe(topic [,qos]) / mqtt.subscribe_qos | subscribe (wildcards + / # allowed) |
mqtt.read(timeout_ms, object) | next message; object=true → {topic,data}, else raw; returns false on timeout |
mqtt.publish(retain, qos, topic, data) | publish (see control-plane warnings before using) |
mqtt.broker_addr / broker_port / username / password | the resolved connection settings (defaults from main.ini) |
mqtt.error / error_str / library | last-call result + library name/version |
Stock JS examples in exec/ (read these before writing your own):
mqtt_sub.js — generic subscriber (the connect/subscribe/read loop above).mqtt_pub.js — generic publisher.mqtt_spy.js — subscribe to a node's …/output and render the live screen.mqtt_stats.js — publishes system.stats to sbbs/<BBSID>/stats[/<field>].
Local object model vs. MQTT — pick the right source. For this instance's
own state, the JS object model is simpler and needs no broker: system.stats
(logons/posts/uploads today, totals), system.node_list / the Node-status
files, bbs/client in a session. Reach for MQTT specifically when you need
what the local objects cannot give you: the cross-host, whole-BBS live
picture (every member host's server states and client counts under one BBSID),
or a push stream of action/# events. Don't round-trip through the broker for a
number system.stats already has.
Read-only unless you mean it. Everything under Control plane
(recycle, pause, node/+/input, node/+/intr, …) is a publish() away. A
tool exposed to untrusted callers (an IRC bot, a public command) must
subscribe only and never publish to a control topic. Treat MQTT data as
read-only situational awareness there.
Topic hierarchy at a glance
All topics start with sbbs/<BBSID> where <BBSID> is the QWK BBS ID (SCFG → Message Options). Under that:
sbbs/<BBSID> ← BBS name (retained payload)
sbbs/<BBSID>/node ← total node count
sbbs/<BBSID>/node/<N> ← human-readable status (verbose mode)
sbbs/<BBSID>/node/<N>/status ← tab-delimited node status fields (see exec/load/nodedefs.js)
sbbs/<BBSID>/node/<N>/terminal ← tab-delimited last-connected terminal (cols, rows, syncterm, ANSI, CP437, …)
sbbs/<BBSID>/node/<N>/output ← live terminal output (for spying)
sbbs/<BBSID>/action/<KIND>/<KEY> ← BBS-wide client actions (see Action topics below)
sbbs/<BBSID>/host/<HOSTNAME> ← public host name (retained)
sbbs/<BBSID>/host/<HOSTNAME>/login_attempts/<IP> ← retained failed-login aggregate per IP
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER> ← server status line (state + counters)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/state/<STATE> ← retained per-state flag (e.g. .../state/ready)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/served ← total clients served since start (retained)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/client ← "<N> total\t<M> max" current/limit (retained)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/client/list ← tab-delimited rows, one per connected client (retained)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/log ← console log (level in v5 user property)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/log/<N> ← console log filtered to level N
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/client/action/<KIND> ← per-server client events (connect/disconnect/update)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/error_count ← total errors since server start (retained)
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/max_concurrent/<IP> ← retained term concurrent-connection strikes
sbbs/<BBSID>/host/<HOSTNAME>/event/log[/<N>] ← event-thread log
<SERVER> is one of: term (Terminal), mail (Mail), ftp (FTP), web (Web), srvc (Services).
One BBSID spans every host. All hosts that share a QWK ID publish under the same sbbs/<BBSID> tree, each as its own host/<HOSTNAME>. So a single subscription to sbbs/<BBSID>/host/+/server/+ gives the live, cross-host state of the whole BBS (e.g. Vertrauen's vert, git, plus other member hosts) — something the in-process JS object model can't see, since it only knows its own instance. The server status line is tab-delimited: <state>\t[<cur>/<max> clients]\t<served> served\t[<n> errors].
Action topics (BBS-wide client events, non-retained)
sbbs/<BBSID>/action/hack/<METHOD> ← suspected hack attempt
sbbs/<BBSID>/action/spam/<ACTION> ← suspected SPAM
sbbs/<BBSID>/action/error/<LEVEL> ← unexpected condition
sbbs/<BBSID>/action/exec/<PROGCODE> ← external program executed
sbbs/<BBSID>/action/login/<PROTOCOL> ← successful auth
sbbs/<BBSID>/action/login_fail/<PROTOCOL> ← failed auth
These fire one message per event, not retained — a fresh subscriber sees only events from connect-time forward. Pair with the retained login_attempts/<IP> snapshot for "current state + live updates".
Server state strings
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER> carries a status string whose first field is one of:
| State | Meaning |
|---|
stopped | server not running |
initializing | starting up |
ready | accepting clients |
paused | running but rejecting new connections (see pause control) |
reloading | re-reading config |
stopping | shutting down |
disconnected | MQTT client lost the broker; published from a will-message |
Retention semantics
Most Synchronet MQTT messages are published retained. Retained messages persist on the broker until either the broker restarts (without persistence configured) or someone publishes an empty payload to the same topic to clear it. Consequence: a fresh mosquitto_sub connection replays the latest retained value of every matched topic immediately — useful for dashboards, surprising if you expect an event stream.
The non-retained topics are: action/#, node/+/output, and the various log topics (those flow live).
Control plane — production-impacting operations
Anything below this line affects users connected to the BBS in real time. Read the warnings before publishing.
Synchronet listens for control messages on the same broker. Most accept any payload (empty is fine) — they trigger a flag rather than passing data. Where payload matters it's noted.
Host-wide controls (affect every server on a host)
sbbs/<BBSID>/host/<HOSTNAME>/recycle ← restart ALL servers on that host
sbbs/<BBSID>/host/<HOSTNAME>/pause ← stop accepting new connections on ALL servers
sbbs/<BBSID>/host/<HOSTNAME>/resume ← undo pause
sbbs/<BBSID>/host/<HOSTNAME>/clear ← clear failed-login attempt list + term max-concurrent strike list
payload: empty = clear everything; "<IP>" = clear only that IP
recycle will drop in-flight connections during the restart window. pause keeps existing users connected but new logins fail until resume. Don't publish to these unless you mean it — there's no confirmation prompt.
The same effects can be triggered locally (no MQTT needed) by creating a flag file in ctrl/:
| File | Equivalent topic |
|---|
ctrl/recycle (or recycle.term, recycle.web, …) | host/+/recycle (or server/+/recycle) |
ctrl/clear (or clear.term, clear.ftp, …) | host/+/clear (or server/+/clear) |
The flag file's first line is read as an optional IP filter (for clear); empty content means "clear all". The file is removed by Synchronet once consumed.
Per-server controls
sbbs/<BBSID>/host/<HOSTNAME>/server/<SERVER>/clear ← clear that server's view of the failed-login list
(and, for term, max-concurrent strikes)
payload: empty or "<IP>"
Per-server recycle / pause / resume follow the same pattern (one server only, instead of all).
Node controls (Terminal Server)
sbbs/<BBSID>/node/<N>/input ← inject keyboard input into the connected user's session (payload = keys to send)
sbbs/<BBSID>/node/<N>/msg ← send a short text message to the node (payload = text, terminate with \n)
sbbs/<BBSID>/node/<N>/set/status ← set node status integer; "0"=waiting, "5"=offline
sbbs/<BBSID>/node/<N>/set/errors ← set error counter ("0" to clear)
sbbs/<BBSID>/node/<N>/set/misc ← set misc attribute flags; integer ("0x"-prefixed = hex)
sbbs/<BBSID>/node/<N>/set/lock ← only sysop can login; "0" to clear
sbbs/<BBSID>/node/<N>/set/intr ← interrupt (disconnect) the user; "0" to clear
sbbs/<BBSID>/node/<N>/set/down ← mark node unavailable (status = 5); "0" to clear
sbbs/<BBSID>/node/<N>/set/rerun ← reload config on next connection; "0" to clear
input is essentially remote keystrokes — anything you send is interpreted by the user's current screen as if typed. intr disconnects the user immediately. down prevents anyone from getting that node until cleared. All four affect the live user; use with care.
Safety patterns
- Subscribe before you publish. Run
mosquitto_sub -v -t 'sbbs/+/host/+/server/+/log' -t 'sbbs/+/action/#' -t 'sbbs/+/host/+/server/+' in another terminal so you can see what your control message did.
- Prefer the narrowest scope. A per-server
recycle is less disruptive than a host-wide one; a single-IP clear/<IP> is much less than a wholesale clear.
- Test with non-destructive ops first. Status snapshots (retained) and
error_count reads are free of side effects; use them to confirm the topics work before issuing a pause or intr.
- Beware retained control topics. If a sysop has accidentally retained a
pause message in the past, the next time the BBS reconnects to the broker it could replay the retained message and re-pause itself. Clear stale retained control messages by publishing an empty payload to the same topic with -r.
Recipes
"Is MQTT enabled on this host, and where's the broker?"
awk '/^\[MQTT\]/,/^\[/' <sbbs>/ctrl/main.ini
If Enabled=false (or the section is missing), no further work is possible until SCFG → Networks → MQTT is set up. If InternalBroker=true, the broker is Synchronet itself (default port Broker_port); otherwise connect to Broker_addr:Broker_port.
"Subscribe to every log line across every host on the broker."
mosquitto_sub -h <broker> -p <port> -V 5 -v \
-t 'sbbs/+/host/+/server/+/log' \
-t 'sbbs/+/host/+/event/log'
(-V 5 so you get the level user-property on the bare …/log topic.)
"What's happening across the BBS right now — actions only, terse."
mosquitto_sub -h <broker> -p <port> -v -t 'sbbs/+/action/#'
"Show the current per-IP failed-login state (retained dashboard)."
mosquitto_sub -h <broker> -p <port> -v -t 'sbbs/+/host/+/login_attempts/+'
A fresh subscriber sees every tracked IP's last-attempt payload immediately (retained replay), then updates live.
"Spy on what node 3 is sending to the user (remote screen capture)."
mosquitto_sub -h <broker> -p <port> -t 'sbbs/<BBSID>/node/3/output'
The payload is the terminal byte stream (CP437 by default, including ANSI control sequences) — pipe through a terminal-capable viewer if you want it rendered.
"Clear a single offending IP from the failed-login list, host-wide."
mosquitto_pub -h <broker> -p <port> -t 'sbbs/<BBSID>/host/<HOSTNAME>/clear' -m '203.0.113.42'
(Or, locally: echo 203.0.113.42 > <sbbs>/ctrl/clear.)
"Recycle just the web server on host X."
mosquitto_pub -h <broker> -p <port> -t 'sbbs/<BBSID>/host/<HOSTNAME>/server/web/recycle' -m ''
Verify the result by watching the matching …/server/web status topic — you should see stopping → initializing → ready within seconds.
Common mistakes
- Looking for
[MQTT] in sbbs.ini. It's in main.ini. sbbs.ini has the per-server (term/web/mail/ftp/services) settings; MQTT is a BBS-level concern and lives with the rest of the system config in main.ini.
- Forgetting
-V 5. Without it, mosquitto_sub defaults to v3.1.1 and you don't see the MQTT v5 user property carrying the log level on bare …/log topics — you'd have to subscribe to all eight …/log/<N> subtopics instead.
- Reading the password from
main.ini and pasting it into a shell history. Use -P "$(awk -F= '/^[[:space:]]*Password=/{print $2}' <sbbs>/ctrl/main.ini)" or set MOSQUITTO_PWD and read with -P "$MOSQUITTO_PWD". Better still, configure a dedicated read-only MQTT user for diagnostics.
- Treating action topics as retained. They aren't — a fresh subscriber sees only new events. For pre-connect state, use the retained
login_attempts/<IP> and max_concurrent/<IP> topics in parallel.
- Publishing to a control topic without
-r '' cleanup. If you publish a one-shot control with -r set (retained), Synchronet may re-consume it on reconnect; clear by publishing an empty retained payload to the same topic afterwards.
- Subscribing to
node/+/output and dumping straight to a terminal. The payload contains ANSI CSI sequences that may reposition your cursor, clear your screen, change colours, etc. Pipe to a file or a controlled viewer for analysis.
- Forgetting
Verbose=true. In false/"Low" mode, per-server status and full log streams are suppressed; you'll only see terminal node status. Bump it in SCFG → Networks → MQTT → Publish Verbosity if you need the rest.
- Sending a
node/+/msg without a trailing newline. Per the wiki, the message payload must end with \n to be delivered cleanly; use -m $'<text>\n' in bash.
- Using TLS mode 4 (
MQTT_TLS_SBBS) without the BBS's CA out-of-band. That mode uses Synchronet's internal CA and the BBS's own cert; an external client can't validate it without the CA file. For local diagnostics use --insecure; for production, distribute the CA properly or use TLS mode 1.
Cross-references
- For the file/console log streams (per-category files in
data/, syslog/journalctl on *nix, the WS*.LOG sbbsctrl-on-Windows trap, and the ip.can field format) — see the logs skill.
- For low-level config parsing in
scfglib1.c (the source of truth for the [MQTT] defaults and ranges quoted here) — search for read_main_cfg in src/sbbs3/scfglib1.c.
- For MQTT-related JS host bindings (
MQTT object, mqtt.publish(), etc.) — see the javascript skill.
