MQTT Topic Naming and Payload Scheme
Synchronet v3.20 can publish and subscribe to message “topics” on a configured MQTT broker.
╔══════════════════════════════════════╗ ║ Message Queue Telemetry Transport ║ ╠══════════════════════════════════════╣ ║ │Enabled Yes ║ ║ │Broker Address 192.168.1.2 ║ ║ │Broker Port 1883 ║ ║ │Username ║ ║ │Password ║ ║ │Keep-alive 60 seconds ║ ║ │Protocol Version 5 ║ ║ │Publish Verbosity High ║ ║ │Publish QOS 0: At most once ║ ║ │Subscribe QOS 2: Exactly once ║ ║ │Log Level Informational ║ ║ │TLS (encryption) Off ║ ╚══════════════════════════════════════╝
Synchronet MQTT message topics start with
BBS-ID is the BBS's QWK BBS ID. It's possible for a single MQTT broker to serve multiple Synchronet BBSes in this way. The full BBS name is published to this topic level (not a leaf topic). For example:
sbbs/MYBBS = My Brand-new BBS
All MQTT messages published by Synchronet contain just plain text (US-ASCII characters), the one exception being
sbbs/+/node/+/output topics that include terminal control characters/sequences. Numeric values, unless otherwise are specified, are represented in US-ASCII decimal characters.
The BBS's terminal server nodes (servicing terminal connections via Telnet, SSH, RLogin, Raw TCP) can be monitored and controlled via MQTT.
sbbs/BBS-ID/node hierarchy, you'll find a sub-topic for each BBS node, with the total node count published to the
node topic, for example:
sbbs/MYBBS/node = 4 total
In “High” Publish Verbosity mode, human-readable node status messages are published directly to
node/+ topics. For example:
sbbs/MYBBS/node/1 = Bubbaboy at external program menu via telnet sbbs/MYBBS/node/2 = At login prompt via telnet sbbs/MYBBS/node/3 = At login prompt via telnet sbbs/MYBBS/node/4 = Waiting for connection
Sub-topics of each
node/+ topic include:
- sbbs/+/node/+/status - tab-delimited node status values (see
- sbbs/+/node/+/terminal - tab-delimited current (or last) connected-terminal definition
- sbbs/+/node/+/output - live output to connected-terminal (for spying)
- sbbs/+/node/+/input - keyboard input to inject into connected-node
- sbbs/+/node/+/laston - tab-delimited details of user to last logoff this node
sbbs/VERT/node/1/status = 0 0 1 65535 0 0 0 7 sbbs/VERT/node/1/terminal = 80 24 syncterm ANSI CP437 6 0 2005 sbbs/VERT/node/1/laston = 1 Digital Man 00:00:10
A single Synchronet BBS can be split across multiple instances running on separate inter-networked host computers. Each host will be represented with its own sub-topic of the
sbbs/BBS-ID/host topic. For example:
sbbs/MYBBS/host/MYCOMPUTER sbbs/MYBBS/host/rPi sbbs/MYBBS/host/ubuntu
sbbs/MYBBS/host/MYCOMPUTER = mybbs.synchro.net
The control and monitoring of a specific Synchronet instance is done through this “host sub-topic” tree.
Publishing any message to the recycle sub-topic of any host topic will initiate a recycling of that host's servers (all of them).
Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic of
- sbbs/+/host/+/server/term - Terminal Server
- sbbs/+/host/+/server/mail - Mail Server
- sbbs/+/host/+/server/ftp - FTP Server
- sbbs/+/host/+/server/web - Web Server
- sbbs/+/host/+/server/srvc - Services
The status of each server is published to its server topic, for example:
sbbs/MYBBS/host/MYCOMPUTER/server/term = 2 ready 1/5 clients 223 served
The numeric state (first field of status) for each server is 0-5 corresponding with Stopped, Initializing, Ready, Reloading, Stopping, and Disconnected.
The server status contains more details/statistics and is published more often when “High” Public Verbosity is enabled.
Publishing any message to the recycle sub-topic of any server topic will initiate a recycling of that server.
Each server topic has the following sub-topics for status reporting:
- sbbs/+/host/+/server/+/max_clients - maximum number of concurrent clients supported by this server
- sbbs/+/host/+/server/+/served - total clients served since server was started
- sbbs/+/host/+/server/+/error_count - total errors logged since server was started
- sbbs/+/host/+/server/+/client_count - current count of connected clients
- sbbs/+/host/+/server/+/client_list - tab-delimited details of all connected clients, one client per line
event sub-topics has a log child topic where all messages of all log levels (severity) will be published as well as a grandchild topic for each log level (0-7, decreasing in severity) of logged messages.
Log messages published directly to the “log” topic also have a MQTT v5 user property that specifies the log level of each message (for indication / sorting by the receiving client).
Additionally, the most recent hack-attempt, SPAM-attempt, or error message is logged to the following BBS-wide topic: