Differences

This shows you the differences between two versions of the page.

--- ref:mqtt [2023/01/04 16:23] – Update the hosts section digital man
+++ ref:mqtt [2024/07/11 18:37] (current) – [Servers] Add server/+/highwater topic digital man
@@ Line 1: / Line 1: @@
-====== Synchronet MQTT Topic Naming and Payload Scheme ======
+====== MQTT Topic Naming and Payload Scheme ======
 Synchronet v3.20 can publish and subscribe to message "topics" on a configured MQTT [[http://mosquitto.org/|broker]].
+As enabled and configured in [[util:SCFG]]->Networks->MQTT:
 <code>
@@ Line 22: / Line 24: @@
 </code>
-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:
+===== Retention =====
-  * sbbs/VERT = Vertrauen
+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.
-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.
+===== Topics =====
+Synchronet MQTT message topics start with ''**sbbs/BBSID**'' where ''BBSID'' is the System's BBS ID (for QWK Packets) as configured in [[util: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 nodes
+  * ''sbbs/BBSID/**host**'' - Server hosts
+  * ''sbbs/BBSID/**action**'' - Client actions (events)
+{{:ref:mqtt_explorer_top-level_example.png?700}}
+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 =====
-BBS terminal server nodes can be monitored and controlled via MQTT.
+The BBS's [[server:terminal]] server nodes (servicing terminal connections via Telnet, SSH, RLogin, Raw TCP) 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:
+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/+/nodes = 4
+  sbbs/MYBBS/node = 4 total
-In "High" Publish Verbosity mode, human-readable node status messages are published directly to ''nodes/+'' topics. For example:
+In "High" Publish Verbosity mode, human-readable node status messages are published directly to ''node/+'' topics. For example:
-  * sbbs/+/nodes/1 Bubbaboy at external program menu via telnet
+  sbbs/MYBBS/node/1 = Bubbaboy at external program menu via telnet
-  * sbbs/+/nodes/2 At login prompt via telnet
+  sbbs/MYBBS/node/2 = At login prompt via telnet
-  * sbbs/+/nodes/3 At login prompt via telnet
+  sbbs/MYBBS/node/3 = At login prompt via telnet
-  * sbbs/+/nodes/4 Waiting for connection
+  sbbs/MYBBS/node/4 = Waiting for connection
-Sub-topics of each nodes/+ topic include:
+Sub-topics of each ''node/+'' topic include:
-  * sbbs/+/nodes/+/**status** - tab-delimited node status fields
+  * sbbs/+/node/+/**status** - tab-delimited node status values (see ''[[dir:load]]/nodedefs.js'' for details)
-  * sbbs/+/nodes/+/**terminal** - tab-delimited current (or last) connected-terminal definition
+  * sbbs/+/node/+/**terminal** - tab-delimited current (or last) connected-terminal definition
-  * sbbs/+/nodes/+/**output** - live output to connected-terminal (for spying)
+  * sbbs/+/node/+/**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
+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/+/**msg** - send a short text message to the node (message should be terminated with a newline character)
+  * 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 (publish "0" to clear this flag)
+  * sbbs/+/node/+/**set/intr** - interrupt (disconnect) a user's session (publish "0" to clear this flag)
+  * sbbs/+/node/+/**set/down** - make the node not available for connections (status = 5) (publish "0" to clear this flag)
+  * sbbs/+/node/+/**set/rerun** - have the node reload its configuration upon next connection (publish "0" to clear this flag)
 ===== 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///BBS-ID///" topic. For example:
+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/+/myWindowsPC
+  sbbs/MYBBS/host/MYCOMPUTER
-  * sbbs/+/rpi
+  sbbs/MYBBS/host/rPi
-  * sbbs/+/ubuntu
+  sbbs/MYBBS/host/ubuntu
-The public host name (configured in ''[[dir:ctrl]]/[[config:sbbs.ini]]'') is published to this topic level (not a leaf). For example:
+The public host name (configured in ''[[dir:ctrl]]/[[config:sbbs.ini]]'') of the host is published to this topic level (not a leaf). For example:
-  * sbbs/VERT/vert = vert.synchro.net
+  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).
+^ 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. |
 ===== Servers =====
-Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic:
+Each Synchronet instance (host) contains the following servers, each represented by its own sub-topic of ''sbbs/BBSID/host/hostname/server'':
-  * sbbs/+/+/term - Terminal Server
+  * sbbs/+/host/+/server/**term** - Terminal Server
-  * sbbs/+/+/mail - Mail Server
+  * sbbs/+/host/+/server/**mail** - Mail Server
-  * sbbs/+/+/ftp - FTP Server
+  * sbbs/+/host/+/server/**ftp** - FTP Server
-  * sbbs/+/+/web - Web Server
+  * sbbs/+/host/+/server/**web** - Web Server
-  * sbbs/+/+/srvc - Services
+  * sbbs/+/host/+/server/**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
+  sbbs/MYBBS/host/MYCOMPUTER/server/term = ready   1/5 clients     223 served
-The server status is more verbose (contains more details) when "High" Public Verbosity is enabled.
+The //state// (first field of status) for each server is one of:
+  * stopped
+  * initializing
+  * ready
+  * paused
+  * reloading
+  * stopping
+  * disconnected
-Additionally, timed events run by the Terminal Server are represented in the //host///**event/** sub-topic.
+The server status contains more details/statistics and is published more often when "High" MQTT->Publish Verbosity is enabled in [[util:SCFG]].
-Publishing any message to the **recycle** sub-topic of any server topic will initiate a recycling of that server.
+^ 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. |
 Each server topic has the following sub-topics for status reporting:
-  * //server///**version**
+  * sbbs/+/host/+/server/+/**version** - name, version/revision, and build date/time/tool of server
-  * //server///**state** - current state of the server (0-5 = Stopped, Initializing, Ready, Reloading, Stopping, Disconnected)
+  * sbbs/+/host/+/server/+/**state/#** - server state change events
-  * //server///**max_clients** - maximum number of concurrent clients supported by this server
+  * sbbs/+/host/+/server/+/**client** - current count of connected clients and maximum number of concurrent clients supported by this server
-  * //server///**served** - total clients served since server was started
+  * sbbs/+/host/+/server/+/**client/list** - tab-delimited details of all connected clients, one client per line
-  * //server///**error** - last logged error message
+  * sbbs/+/host/+/server/+/**client/action/#** - client actions (e.g. connect, disconnect)
-  * //server///**error_count** - total errors logged since server was started
+  * sbbs/+/host/+/server/+/**served** - total clients served since server was started
-  * //server///**client_count** - current count of connected clients
+  * sbbs/+/host/+/server/+/**highwater** - highest concurrent client count since server was started
-  * //server///**client_list** - tab-delimited details of all connected clients, one client per line
+  * sbbs/+/host/+/server/+/**error_count** - total errors logged since server was started
-==== Log ====
+==== 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.
+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**
+  * sbbs/+/host/+/server/+/**log**
-  * //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.
+===== 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:
+  * sbbs/+/**exec** - send the internal code of the timed event to execute (case-insensitive)
+  * sbbs/+/**call** - send the QWK-ID of the QWKnet node to force a call-out to (case-insensitive)
 ===== See Also =====
   * [[:ref:|ref index]]
+  * [[:monitor:|Monitoring]]
-{{tag>}}
+{{tag>mqtt}}

Trace:

Differences

Navigation

Search

Toolbox