*********
Mosquitto
*********

.. admonition:: Voorkennis

  * shell-opdrachten
  * installeren van software op Linux/Raspberry Pi

Mosquitto (https://mosquitto.org) is een open source MQTT-broker.
We beschrijven hier het installeren en configureren van Mosquitto op een Rasberry Pi of op een Linux-server "in the cloud".

Mosquitto ondersteunt naast het MQTT-protocol ook de volgende mogelijkheden:

  * gebruik van MQTT via *websockets*.
    Dit gebruiken we voor MQTTT: dit is een web-toepasssing die via websockets communiceert met een MQTT-broker.
  * statische HTTP-server.
    Via het HTTP-protocol kan Mosquitto het document (web-toepassing) bij een URL opleveren.
    Dit gebruiken we voor MQTTT en voor de IoT-knoop simulator:
    dat zijn statische web-toepassingen die geen verdere server-acties vereisen.

Installeren
===========

We geven hier de aanwijzingen voor Debian Stretch (ook van toepassing op de Raspberry Pi).
Mosquitto is voor deze distributie een standaard-pakket, je installeert dit met:

.. code-block:: shell

  $ sudo apt-get update
  $ sudo apt-get install mosquitto mosquitto-clients


Als je zeker wilt zijn van de nieuwste versie van mosquitto, dan kun je de aanwijzingen gebruiken van
https://theembeddedlab.com/tutorials/install-mosquitto-on-a-raspberry-pi/

Mosquitto-server
================

In de meeste gevallen gebruik je mosquitto als een "service" (ook wel daemon genoemd):
dit betekent dat de mosquitto-broker opgestart wordt bij het opstarten van het systeem.
De normale Debian-installatie installeert de mosquitto-broker als service.

Met de volgende opdrachten kun je de broker starten, stoppen of herstarten.

.. code-block:: shell

  $ sudo service mosquitto start
  $ sudo service mosquitto stop
  $ sudo service mosquitto restart

Testen
======

Je kunt testen of de broker werkt, via de client-opdrachten ``mosquitto_pub`` en ``mosquitto_sub``:

Open een nieuw shell-venster, en geef daarin de opdracht:

.. code-block:: shell

  $ mosquitto_sub -t "mytopic"

Deze opdracht blijft actief totdat je deze afbreekt (met ^C).

Geef *in een ander shell-venster* de opdracht:

.. code-block:: shell

  $ mosquitto_pub -t "mytopic" -m "Hello World"

Je ziet nu dit bericht verschijnen in het ``mosquitto_sub`` shell-venster.

Configureren
============

De mosquitto-configuratie is beschreven in het bestand ``mosquitto.conf``.
Je vind dit bestand waarschijnlijk in ``/etc/mosquitto`` of ``/usr/local/etc/mosquitto``.
De handleiding: https://mosquitto.org/man/mosquitto-conf-5.html geeft een beschrijving van de configuratie-parameters.

We gebruiken hier een eenvoudige configuratie, met twee soorten listeners
en een eenvoudige username/password-authenticatie.

Als je de configuratie veranderd hebt moet je de mosquitto-service herstarten (zie hierboven).

Listeners
---------

We gebruiken twee soorten *listeners*: clients via het MQTT-protocol (port 1883),
en clients via de HTTP/websockets protocollen (port 1884).
De username/password-combinaties zijn beschreven in de password-file ``/etc/mosquitto/passwd``.
Het wachtwoord wordt gecodereerd opgeslagen.
Je beheert deze password-file met behulp van ``mosquitto_passwd`` (https://mosquitto.org/man/mosquitto_passwd-1.html).

.. code-block:: none

  listener 1883
  allow_anonymous false
  password_file /etc/mosquitto/passwd
  listener 1884
  protocol websockets
  http_dir /var/mosquitto/http

Opmerking: voor een echte beveiliging is het nodig om ook beveiligde verbindingen te gebruiken.

MQTT-bridge
===========

Je kunt een lokale MQTT-broker gebruiken als *bridge* naar een publieke MQTT-broker.

.. todo::

  * MQTT: beveiliging met TLS etc. verder uitwerken.
  * MQTT broker als bridge naar een publieke broker
  * MQTT performance-testing
  * MQTT-paho in combinatie met mosquitto?

Links
=====

* https://mosquitto.org
* https://mosquitto.org/download/

  * RaspBian: *Mosquitto is available through the main repository.*
  * https://mosquitto.org/blog/2013/01/mosquitto-debian-repository/

* https://mosquitto.org/man/mosquitto-conf-5.html
* https://www.cloudmqtt.com/docs-bridge.html
* https://www.cloudmqtt.com/