====== MQTT ======

===== Setup =====

This is a bit of a stub for MQTT but it'll help you get going, on Ubuntu at least.

First, you'll need Synchronet v3.20a or later.

Then install the Mosquitto broker and client:

   sudo apt install mosquitto mosquitto-clients

Additionally, if you wish to use an X based mqtt client to receive messages, install libnss3 and xdg-utils

Mosquitto will install and start automatically but you won't see any messages. If you wish to see them, then stop the broker

   sudo systemctl stop mosquitto

and run it manually

   sudo mosquitto -v

To continue running as a service CTRL-C to stop mosquitto and then restart

   sudo systemctl start mosquitto

At this point you should probably rebuild sbbs so that libmosquitto will be picked up and included in libsbbs.so. You can verify this with the following command:

   bbs@bbs:/var/log/apt$ ldd /sbbs/exec/libsbbs.so|grep mosquitto
        libmosquitto.so.1 => /usr/lib/x86_64-linux-gnu/libmosquitto.so.1 (0x00007fbf8c582000)

If there is no response to the command, then a recompile is necessary.

Run [[util:SCFG]] and go to Networks->MQTT. Change the `Broker Address` and `Port` to match your installed Mosquitto broker's configuration (default 127.0.0.1 and port 1883) and set `Enabled` to `Yes`.

Now start sbbs and you should see the following lines in your log

   Dec 12 02:13:08 bbs synchronet[1188320]: #015#015Reading /sbbs/ctrl/sbbs.ini
   Dec 12 02:13:08 bbs synchronet: MQTT lib: mosquitto 1.6.9
   Dec 12 02:13:08 bbs synchronet: MQTT connecting to broker 127.0.0.1:1883

If you see a "failure: 14" message, then your broker isn't running.

At this point you should see messages from sbbs being passed into the Mosquitto broker

```
1670834270: Received PUBLISH from auto-FEB8177A-5A3E-5EE9-6AA3-9CE9BE593CA3 (d0, q0, r0, m0, 'sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log/7', ... (74 bytes))
1670834270: Received PUBLISH from auto-FEB8177A-5A3E-5EE9-6AA3-9CE9BE593CA3 (d0, q0, r0, m0, 'sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log', ... (74 bytes))
```

Now, if you want to install a GUI client to view the messages.

   wget https://www.emqx.com/en/downloads/MQTTX/v1.9.0/MQTTX_1.9.0_amd64.deb

then

   dpkg -i v1.9.0/MQTTX_1.9.0_amd64.deb

run mqttx to start the package.

Create a new connection to 127.0.0.1 port 1883 - you can keep everything else as defaults, though you may want to change the Client ID.


You should be connected to the broker. If you're not connected, click the "Connect" button. Now you can subscribe to messages.

Click "New Subscription"

Now enter the path which will be sbbs/ followed by your BBS's short name, EOTLBBS in my case. You'll find it on your logs. 

   sbbs/EOTLBBS/#

The # at the end like similar to a wildcard and will show you all the messages. 

Once they start flowing, you can narrow them down a little. Try this subscription.

sbbs/EOTLBBS/bbs.endofthelinebbs.com/client_count,sbbs/EOTLBBS/bbs.endofthelinebbs.com/socket_count,sbbs/EOTLBBS/bbs.endofthelinebbs.com/served

Replace EOTLBBS and bbs.endofthelinebbs.com accordingly with your own board's information. 

As you can see, mqtt generates a lot of messages so if you need to save bandwidth, it is best to run the broker and clients on the same server.

This is just a quick and dirty howto to get you going if you want to try out mqtt in sbbs. Feel free to edit and refine.


One more tip, if you're starting sbbs from systemd (and why wouldn't you be?) you will want to ensure mosquitto starts before sbbs. There are several ways to accomplish this. 

Changing the sbbs service file "Unit" entry for Wanted= is how I will do it, though not tested as yet).

   [Unit]
   Description=Synchronet BBS service
   Documentation=man:sbbs
   After=syslog.target network.target mosquitto.service

After making changes to your sbbs service file, Be sure to run

   sudo systemctl daemon-reload

This is a list of data points captured during a short run. Obviously if you use these, replace your BBS's system name and hostname.

<file>
sbbs/EOTLBBS/bbs.endofthelinebbs.com/client_count
sbbs/EOTLBBS/bbs.endofthelinebbs.com/client_list
sbbs/EOTLBBS/bbs.endofthelinebbs.com/served
sbbs/EOTLBBS/bbs.endofthelinebbs.com/socket_count
sbbs/EOTLBBS/bbs.endofthelinebbs.com/srvc/log
sbbs/EOTLBBS/bbs.endofthelinebbs.com/srvc/log/6
sbbs/EOTLBBS/bbs.endofthelinebbs.com/srvc/log/7
sbbs/EOTLBBS/bbs.endofthelinebbs.com/term/log
sbbs/EOTLBBS/bbs.endofthelinebbs.com/term/log/5
sbbs/EOTLBBS/bbs.endofthelinebbs.com/term/log/6
sbbs/EOTLBBS/bbs.endofthelinebbs.com/term/log/7
sbbs/EOTLBBS/bbs.endofthelinebbs.com/thread_count
sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/client_count
sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log
sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log/4
sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log/6
sbbs/EOTLBBS/bbs.endofthelinebbs.com/web/log/7
sbbs/EOTLBBS/node1/output
sbbs/EOTLBBS/node1/status
sbbs/EOTLBBS/node1/terminal
</file>

Note, the numbers at the end of the log outputs is the log level. These may be subject to change in future and may be added to or removed.

For collecting data and viewing, I highly recommend Node-Red. You can find installation instructions online and should be able to figure its usage but I highly recommend using the current node.js (Node 18 currently) and install the Dashboard module (which will not run on the Ubuntu provided version of node.js).

===== WebSockets =====

New browser-based Web Monitor and Node Spy features have been added in 3.20, which are powered by MQTT.  The first time you load either of these features you'll be prompted to provide the Hostname and WebSocket Ports for your MQTT server (these are different than the WebSocket ports used to power fTelnet).

Keep in mind that it's your web browser connecting to the MQTT server, so you need to provide a hostname that is reachable by your web browser (e.g. if your BBS is running on a VPS, then localhost won't be a good choice for the Hostname, unless you plan to remote into that VPS and launch a browser from there).

For the WebSocket ports, you'll need to update your Mosquitto server's configuration to listen on additional ports, because it doesn't do this by default.  The config file does a pretty good job of explaining this, but just to give a working example here's what my config file looks like (of course the cert paths will be different for you):

    # mqtt protocol standard port
    listener 1883
    
    # mqtt protocol ssl port
    listener 8883
    certfile C:\Retsyn\Certificates\bbs.ftelnet.ca.pem
    keyfile C:\Retsyn\Certificates\bbs.ftelnet.ca.key.pem
    
    # websocket protocol standard port
    listener 1884
    protocol websockets
    socket_domain ipv4
    
    # websocket protocol ssl port
    listener 8884
    protocol websockets
    socket_domain ipv4
    certfile C:\Retsyn\Certificates\bbs.ftelnet.ca.pem
    keyfile C:\Retsyn\Certificates\bbs.ftelnet.ca.key.pem

My understanding is that the SSL certs created by the Synchronet Let's Encrypt client can be converted to a format that is usable by Mosquitto, but I haven't investigated that because I run a separate client to handle my SSL certs.  If someone else goes through the conversion process, please add the steps/commands here!

===== Security =====

It is VERY important that you DO NOT open any of the MQTT ports to the general public.  Sensitive information may be published to some topics, and other topics allow controlling your BBS (eg downing nodes).  So please make sure your MQTT ports are behind a firewall, and if you want to make use of the Web Monitor or Node Spy features, then only IP addresses belonging to you should be allowed through.

===== See Also =====
  * [[:howto:|howto index]]
  * [[monitor:mqtt|Synchronet MQTT Topic Naming and Payload Scheme]]

{{tag>mqtt}}
