This is an old revision of the document!
MQTT Topic Naming and Payload Scheme
Synchronet v3.20 can publish and subscribe to message “topics” on a configured MQTT broker.
As enabled and configured in SCFG->Networks->MQTT:
╔══════════════════════════════════════╗ ║ 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 ║ ╚══════════════════════════════════════╝
Retention
Most Synchronet MQTT messages are published with the retain flag enabled. Retained messages published before a client/subscriber connects will still be received (upon new client connection) until until the broker is restarted or the retained messages are explicitly removed from the broker.
Topics
Synchronet MQTT message topics start with sbbs/BBSID
where BBSID
is the System's BBS ID (for QWK Packets) as configured in SCFG->Message Options. 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 leaf topics are published as children of the sbbs/BBSID
topic under 3 main branches:
sbbs/BBSID/node
- BBS nodessbbs/BBSID/host
- Server hostssbbs/BBSID/action
- Client actions (events)
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.
Nodes
The BBS's terminal server nodes (servicing terminal connections via Telnet, SSH, RLogin, Raw TCP) can be monitored and controlled via MQTT.
Under the sbbs/BBSID/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
load/nodedefs.js
for details) - sbbs/+/node/+/terminal - tab-delimited current (or last) connected-terminal definition
- sbbs/+/node/+/output - live output to connected-terminal (for spying)
Example:
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
Control
Nodes can be controlled by publishing messages to the following topics:
- sbbs/+/node/+/input - keyboard input to inject into connected-node
- sbbs/+/node/+/set/status - set the node's status value (to an integer value: “0” is waiting for connection, “5” is off-line)
- sbbs/+/node/+/set/errors - set the node's error counter value (to an integer value, e.g. “0” to clear the error counter)
- sbbs/+/node/+/set/misc - set the node's miscellaneous attribute flags (to an integer value, “0x” prefix for hexadecimal values)
- sbbs/+/node/+/set/lock - only a sysop can login
- sbbs/+/node/+/set/intr - interrupt (disconnect) a user's session
- sbbs/+/node/+/set/down - make the node not available for connections (status = 5)
- sbbs/+/node/+/set/rerun - have the node reload its configuration upon next connection
Hosts
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/BBSID/host
topic. For example:
sbbs/MYBBS/host/MYCOMPUTER sbbs/MYBBS/host/rPi sbbs/MYBBS/host/ubuntu
The public host name (configured in ctrl/sbbs.ini
) of the host is published to this topic level (not a leaf). For example:
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).
Servers
Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic of sbbs/BBSID/host/hostname/server
:
- 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/+/version
- 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
Logs
Each server/+
and 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).
- sbbs/+/host/+/server/+/log
- sbbs/+/host/+/server/+/log/#
- sbbs/+/host/+/event/log
- sbbs/+/host/+/event/log/#
Actions
Client actions are published to the following BBS-wide topics:
- sbbs/+/action/hack/METHOD - suspected hack attempt
- sbbs/+/action/spam/ACTION - suspected SPAM received
- sbbs/+/action/error/LEVEL - unexpected condition
- sbbs/+/action/exec/PROGCODE - external program executed
- sbbs/+/action/login/PROTOCOL - successful user authentication
- sbbs/+/action/login_fail/PROTOCOL - unsuccessful user authentication
- sbbs/+/action/logout/PROTOCOL - user logged-out
- sbbs/+/action/download/DIRCODE - file downloaded
- sbbs/+/action/upload/DIRCODE - file uploaded
- sbbs/+/action/post/SUBCODE - message posted
- sbbs/+/action/newuser/PROTOCOL - new user created
- sbbs/+/action/page/node/NODE_NUM - sysop paged for chat
Fields are tab-delimited and begin with a date/time stamp in ISO-8601 format.