Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
ref:mqtt [2023/01/03 19:23] – updated to reflect current scheme digital manref:mqtt [2024/01/12 17:38] (current) – [Servers] Table the server sub-topics 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]]. Synchronet v3.20 can publish and subscribe to message "topics" on a configured MQTT [[http://mosquitto.org/|broker]].
-Synchronet message topics start with "sbbs///BBS-ID///" where //BBS-ID// is the Synchronet BBS QWK-ID. 
  
-All message contents contain just plain text (US-ASCII characters). Numeric values, unless otherwise are specified, are represented in US-ASCII decimal characters.+As enabled and configured in [[util:SCFG]]->Networks->MQTT: 
 + 
 +<code> 
 +╔══════════════════════════════════════╗ 
 +║   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             ║ 
 +╚══════════════════════════════════════╝ 
 +</code> 
 + 
 +===== 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 [[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 ===== ===== 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/// hierarchy, you'll find a sub-topic for each BBS node along with a total node count, 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: 
-  * node1/ +  sbbs/MYBBS/node = 4 total
-  * node2/ +
-  * node3/ +
-  * node4/ +
-  * node_count = 4+
  
-Messages are not published directly to node topics, but rather sub-topics of each node topic: +In "High" Publish Verbosity mode, human-readable node status messages are published directly to ''node/+'' topics. For example: 
-  * node#/**status** - tab-delimited node status fields + 
-  * node#/**terminal** - tab-delimited current (or last) connected-terminal definition +  sbbs/MYBBS/node/1 = Bubbaboy at external program menu via telnet 
-  * node#/**output** - live output to connected-terminal (for spying) +  sbbs/MYBBS/node/2 = At login prompt via telnet 
-  * node#/**input** - keyboard input to inject into connected-node +  sbbs/MYBBS/node/3 = At login prompt via telnet 
-  * node#/**laston** - tab-delimited details of user to last logoff this node+  sbbs/MYBBS/node/4 = Waiting for connection 
 + 
 + 
 +Sub-topics of each ''node/+'' topic include: 
 + 
 +  * sbbs/+/node/+/**status** - tab-delimited node status values (see ''[[dir: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) 
 + 
 +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 ===== ===== 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:
  
-  * myWindowsPC/ +  sbbs/MYBBS/host/MYCOMPUTER 
-  * rpi/ +  sbbs/MYBBS/host/rPi 
-  * ubuntu/+  sbbs/MYBBS/host/ubuntu 
 + 
 +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/MYBBS/host/MYCOMPUTER = mybbs.synchro.net
  
 The control and monitoring of a specific Synchronet instance is done through this "host sub-topic" tree.  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 ===== ===== 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'':
  
-  * //host///**term/** - Terminal Server +  * sbbs/+/host/+/server/**term** - Terminal Server 
-  * //host///**mail/** - Mail Server +  * sbbs/+/host/+/server/**mail** - Mail Server 
-  * //host///**ftp/** - FTP Server +  * sbbs/+/host/+/server/**ftp** - FTP Server 
-  * //host///**web/** - Web Server +  * sbbs/+/host/+/server/**web** - Web Server 
-  * //host///**srvc/** - Services+  * sbbs/+/host/+/server/**srvc** - Services
  
-Additionally, timed events run by the Terminal Server are represented in the //host///**event/** sub-topic.+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
  
-Publishing any message to the **recycle** sub-topic of any server topic will initiate a recycling of that server.+The //state// (first field of status) for each server is one of: 
 +  * stopped 
 +  * initializing 
 +  * ready 
 +  * paused 
 +  * reloading 
 +  * stopping 
 +  * disconnected 
 + 
 +The server status contains more details/statistics and is published more often when "High" MQTT->Publish Verbosity is enabled in [[util: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. |
  
 Each server topic has the following sub-topics for status reporting: 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/+/**error_count** - total errors logged since server was started
-  * //server///**client_list** - tab-delimited details of all connected clients, one client per line+
  
-==== 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). 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 ===== ===== See Also =====
   * [[:ref:|ref index]]   * [[:ref:|ref index]]
 +  * [[:monitor:|Monitoring]]
  
-{{tag>}}+{{tag>mqtt}}
  

Trace: