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 ║ ╚══════════════════════════════════════╝
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)
- sbbs/+/node/+/input - keyboard input to inject into connected-node
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
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
Fields are tab-delimited and begin with a date/time stamp in ISO-8601 format.