Synchronet 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 Synchronet BBS QWK-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). For example:

• sbbs/VERT = Vertrauen

All MQTT messages published by Synchronet contain just plain text (US-ASCII characters), the one exception being nodes/+/output topics that include terminal control characters/sequences. Numeric values, unless otherwise are specified, are represented in US-ASCII decimal characters.

BBS terminal server nodes can be monitored and controlled via MQTT.

Under the sbbs/BBS-ID/nodes hierarchy, you'll find a sub-topic for each BBS node, with the total node count published to the nodes topic, for example:

• sbbs/+/nodes = 4

In “High” Publish Verbosity mode, human-readable node status messages are published directly to nodes/+ topics. For example:

• sbbs/+/nodes/1 Bubbaboy at external program menu via telnet
• sbbs/+/nodes/2 At login prompt via telnet
• sbbs/+/nodes/3 At login prompt via telnet
• sbbs/+/nodes/4 Waiting for connection

Sub-topics of each nodes/+ topic include:

• sbbs/+/nodes/+/status - tab-delimited node status fields
• sbbs/+/nodes/+/terminal - tab-delimited current (or last) connected-terminal definition
• sbbs/+/nodes/+/output - live output to connected-terminal (for spying)
• sbbs/+/nodes/+/input - keyboard input to inject into connected-node
• sbbs/+/nodes/+/laston - tab-delimited details of user to last logoff this node

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/” topic. For example:

• sbbs/+/myWindowsPC
• sbbs/+/rpi
• sbbs/+/ubuntu

The public host name (configured in ctrl/sbbs.ini) is published to this topic level (not a leaf). For example:

• sbbs/VERT/vert = vert.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:

• sbbs/+/+/term - Terminal Server
• sbbs/+/+/mail - Mail Server
• sbbs/+/+/ftp - FTP Server
• sbbs/+/+/web - Web Server
• sbbs/+/+/srvc - Services

The status of each server is published to its server topic, for example:

• sbbs/VERT/vert/term = 2 ready 1/5 clients 223 served

The server status is more verbose (contains more details) when “High” Public Verbosity is enabled.

Additionally, timed events run by the Terminal Server are represented in the host/event/ sub-topic.

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:

• server/version
• server/state - current state of the server (0-5 = Stopped, Initializing, Ready, Reloading, Stopping, Disconnected)
• server/max_clients - maximum number of concurrent clients supported by this server
• server/served - total clients served since server was started
• server/error - last logged error message
• server/error_count - total errors logged since server was started
• server/client_count - current count of connected clients
• 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).

• server/log
• server/log/#

• ref index