Both sides previous revisionPrevious revisionNext revision | Previous revision |
ref:mqtt [2022/12/13 21:44] – digital man | ref:mqtt [2024/01/12 17:38] (current) – [Servers] Table the server sub-topics digital man |
---|
====== 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 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). | 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 control and monitoring of a specific Synchronet instance is done through this "host sub-topic" tree. Synchronet instance status values are published in the following sub-topics: | 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: |
* //host///**version** | sbbs/MYBBS/host/MYCOMPUTER = mybbs.synchro.net |
* //host///**thread_count** | |
* //host///**socket_count** | |
* //host///**error_count** | |
* //host///**served** | |
* //host///**client_count** | |
* //host///**client_list** - tab-delimited details of all connected clients, one client per line | |
| |
Publishing any message to the **recycle** sub-topic of any host topic will initiate a recycling of that host's servers. | 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. | |
| |
===== 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 |
| |
Each server topic has the following sub-topics for status reporting: | The server status contains more details/statistics and is published more often when "High" MQTT->Publish Verbosity is enabled in [[util:SCFG]]. |
| |
* //server///**version** | ^ Server sub-topic ^ Description ^ |
* //server///**state** - current state of the server (0-4 = Stopped, Initializing, Ready, Reloading, Stopping) | | recycle | Publishing any message to the **recycle** sub-topic of any server topic will initiate a recycling of that server. | |
* //server///**max_clients** | | pause | Publishing any message to the **pause** sub-topic of any server topic will prevent that server from accepting any new incoming client connections. | |
* //server///**client_count** | | 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. | |
| |
Some servers also track their count of open sockets and running threads (when not 1:1 with their client_count): | Each server topic has the following sub-topics for status reporting: |
* //server///**thread_count** | |
* //server///**socket_count** | |
| |
==== Log ==== | * sbbs/+/host/+/server/+/**version** - name, version/revision, and build date/time/tool of server |
| * sbbs/+/host/+/server/+/**state/#** - server state change events |
| * sbbs/+/host/+/server/+/**client** - current count of connected clients and maximum number of concurrent clients supported by this server |
| * sbbs/+/host/+/server/+/**client/list** - tab-delimited details of all connected clients, one client per line |
| * sbbs/+/host/+/server/+/**client/action/#** - client actions (e.g. connect, disconnect) |
| * sbbs/+/host/+/server/+/**served** - total clients served since server was started |
| * sbbs/+/host/+/server/+/**error_count** - total errors logged since server was started |
| |
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. | ==== 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). | 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}} |
| |