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 sbbs/BBS-ID where 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.

Under the 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 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
• sbbs/+/node/+/laston - tab-delimited details of user to last logoff this 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
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

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).

Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic of sbbs/BBS-ID/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

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/#

Additionally, the most recent hack-attempt, SPAM-attempt, or error message is logged to the following BBS-wide topic:

• sbbs/+/hack
• sbbs/+/spam
• sbbs/+/error

• ref index
• Monitoring