Table of Contents

Monitoring and Control via MQTT

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:

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:

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:

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.

Host sub-topic Description
recycle Publishing any message to the recycle sub-topic of any host topic will initiate a recycling of that host's servers (all of them).
pause Publishing any message to the pause sub-topic of any host topic will initiate pause that host's servers (all of them), preventing the acceptance of any new incoming client connections.
resume Publishing any message to the resume sub-topic of any host topic will un-pause that host's servers (all of them), that we previously paused via the pause topic.
clear Publishing to the clear sub-topic of any host topic clears the failed-login attempt list (host-shared across all of that host's servers) and that host's terminal server's max-concurrent-connection strike list. Payload may be empty (clear everything) or a numeric IPv4/IPv6 address (clear only entries for that IP). The same effect can be triggered locally by creating ctrl/clear (or ctrl/clear.term, ctrl/clear.ftp, etc.) optionally containing an IP address as its first line.

Servers

Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic of sbbs/BBSID/host/hostname/server:

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

sbbs/MYBBS/host/MYCOMPUTER/server/term = ready   1/5 clients     223 served

The state (first field of status) for each server is one of:

The server status contains more details/statistics and is published more often when “High” MQTT->Publish Verbosity is enabled in SCFG.

Server sub-topic Description
recycle Publishing any message to the recycle sub-topic of any server topic will initiate a recycling of that server.
pause Publishing any message to the pause sub-topic of any server topic will prevent that server from accepting any new incoming client connections.
resume Publishing any message to the resume sub-topic of any server topic will un-pause that server, returning to the “ready” state, accepting incoming client connections.
clear Publishing to the clear sub-topic of any server topic clears that server's view of the failed-login attempt list (and, for the terminal server, its max-concurrent-connection strike list). Payload may be empty (clear all) or a numeric IPv4/IPv6 address (clear only that IP).

Each server topic has the following sub-topics for status reporting:

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

Login Attempts

Synchronet maintains two per-IP lists for surveilling unsuccessful logins and connection-limit hits, both published as retained MQTT messages so subscribers see live state immediately on connect.

Failed Login Attempts

Each source IP with one or more unsuccessful login attempts to any of the BBS's protocol servers (terminal/FTP/mail/services/web) is published as a retained message at:

Fields are tab-delimited:

For example: 

sbbs/VERT/host/vert/login_attempts/27.79.1.152 = 20260502T141018-0700	20260502T141023-0700	2	0	SSH	ftp

The plaintext password (kept internally for sysop inspection on the running host) is not published, since MQTT publishes may be visible to off-host subscribers.

Entries are removed (an empty retained payload is published, which the broker treats as a delete of the retained topic) when:

The list is shared across all of a host's servers, so failed FTP, mail, web, and services attempts share the same login_attempts/IP topic; the protocol of the latest attempt is recorded in the payload.

This topic is complementary to the per-event action/login_fail topic, not a replacement. login_fail is an event stream: one message fires for each individual failed authentication, and the broker keeps no record after delivery. login_attempts/IP is the aggregated retained state: one message per IP, overwritten on each new attempt, deleted on success or sysop clear. A subscriber to login_fail sees every attempt as it happens but knows nothing on first connect; a subscriber to login_attempts/+ sees the current per-IP state of every tracked IP immediately (via retained-message replay) and updates as state changes. Use login_fail for a live feed or alerting, login_attempts/+ for a “current bad-IP state” dashboard or to enumerate the IPs your tooling can pass to clear.

Max-Concurrent-Connection Strikes

The Terminal Server tracks each source IP that hits the maximum concurrent connections without login limit (configured in SCFG->Servers->Terminal Server). The current strike count for each tracked IP is published as a retained message at:

The payload is the bare decimal strike count.

Entries are removed when:

Actions

Client actions are published to the following BBS-wide topics:

Fields are tab-delimited and begin with a date/time stamp in ISO-8601 format.

Triggers

The Terminal Server's event thread can be instructed to executed Timed Events or initiate QWKnet call-outs by posting a message to the following topics:

See Also