search

eclipse-zenoh / zenoh-plugin-mqtt

A Zenoh plug-in that allows to integrate and/or route MQTT pub/sub with Eclipse Zenoh.
Other
15 stars 13 forks source link

readme

CI Discussion Discord License License

Eclipse Zenoh

The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.

Zenoh (pronounce /zeno/) unifies data in motion, data at rest and computations. It carefully blends traditional pub/sub with geo-distributed storages, queries and computations, while retaining a level of time and space efficiency that is well beyond any of the mainstream stacks.

Check the website zenoh.io and the roadmap for more detailed information.

MQTT plugin and standalone zenoh-bridge-mqtt

:point_right: Install latest release: see below

:point_right: Docker image: see below

:point_right: Build "main" branch: see below

Background

MQTT is a pub/sub protocol leveraging a broker to route the messages between the MQTT clients. The MQTT plugin for Eclipse Zenoh acts as a MQTT broker, accepting connections from MQTT clients (V3 and V5) and translating the MQTT pub/sub into a Zenoh pub/sub. I.e.:

This allows a close intergration of any MQTT system with Zenoh, but also brings to MQTT systems the benefits of a Zenoh routing infrastructure. Some examples of use cases:

The MQTT plugin for Eclipse Zenoh is available either as a dynamic library to be loaded by the Zenoh router (zenohd), either as a standalone executable (zenoh-bridge-mqtt) that can acts as a Zenoh client or peer.

Configuration

zenoh-bridge-mqtt can be configured via a JSON5 file passed via the -cargument. You can see a commented example of such configuration file: DEFAULT_CONFIG.json5.

The "mqtt" part of this same configuration file can also be used in the configuration file for the zenoh router (within its "plugins" part). The router will automatically try to load the plugin library (zenoh_plugin_mqtt) at startup and apply its configuration.

zenoh-bridge-mqtt also accepts the following arguments. If set, each argument will override the similar setting from the configuration file:

Admin space

The zenoh bridge for MQTT exposes an administration space allowing to get some information on its status and configuration. This administration space is accessible via any zenoh API, including the REST API that you can activate at zenoh-bridge-mqtt startup using the --rest-http-port argument.

The zenoh-bridge-mqtt exposes this administration space with paths prefixed by @/service/<uuid>/mqtt (where <uuid> is the unique identifier of the bridge instance). The informations are then organized with such paths:

Example of queries on administration space using the REST API with the curl command line tool (don't forget to activate the REST API with --rest-http-port 8000 argument):

Pro tip: pipe the result into jq command for JSON pretty print or transformation.

MQTTS support

The MQTT plugin and standalone bridge for Eclipse Zenoh supports MQTTS. MQTTS can be configured in two ways:

Server side authentication configuration

Server side authentication requires both a private key and certificate for the server. These can be provided as either a file or as a base 64 encoded string.

In the configuration file, the required tls fields when using files are server_private_key and server_certificate. When using base 64 encoded strings the required tls fields are server_private_key_base64 and server_certificate_base64.

An example configuration file supporting server side authentication would be:

{
  "plugins": {
    "mqtt": {
      "tls": {
        "server_private_key": "/path/to/private-key.pem",
        "server_certificate": "/path/to/certificate.pem"
      }
    }
  }
}

The standalone bridge (zenoh-bridge-mqtt) also allows the required files to be provided through the --server-private-key and --server-certificate command line arguments.

Mutual authentication (mTLS) configuration

In order to enable mutual authentication a certificate for the certificate authority used to validate clients connecting to the MQTT server must also be provided. This can be provided as either a file or a base 64 encoded string.

In the configuration file, the required tls field when using a file is root_ca_certificate. When using base 64 encoded strings the required tls field when using a file is root_ca_certificate_base64.

An example configuration file supporting server side authentication would be:

{
  "plugins": {
    "mqtt": {
      "tls": {
        "server_private_key": "/path/to/private-key.pem",
        "server_certificate": "/path/to/certificate.pem",
        "root_ca_certificate": "/path/to/root-ca-certificate.pem"
      }
    }
  }
}

The standalone bridge (zenoh-bridge-mqtt) also allows the required file to be provided through the --root-ca-certificate command line argument.

Username/password authentication

The MQTT plugin and standalone bridge for Eclipse Zenoh supports basic username/password authentication of MQTT clients. Credentials are provided via a dictionary file with each line containing the username and password for a single user in the following format:

username:password

Username/passord authentication can be configured via the configuration file or, if using the standalone bridge, via command line arguments.

In the configuration file, the required auth field for configuring the dictionary file is dictionary_file.

An example configuration file supporting username/password authentication would be:

{
  "plugins": {
    "mqtt": {
      "auth": {
        "dictionary_file": "/path/to/dictionary-file",
      }
    }
  }
}

The standalone bridge (zenoh-bridge-mqtt) also allows the required file to be provided through the --dictionary-file command line argument.

Security considerations

Usernames and passwords are sent as part of the MQTT CONNECT message in clear text. As such, they can potentially be viewed using tools such as Wireshark.

To prevent this, it is highly recommended that this feature is used in conjunction with the MQTTS feature to ensure credentials are encrypted on the wire.

How to install it

To install the latest release of either the MQTT plugin for the Zenoh router, either the zenoh-bridge-mqtt standalone executable, you can do as follows:

Manual installation (all platforms)

All release packages can be downloaded from:

Each subdirectory has the name of the Rust target. See the platforms each target corresponds to on https://doc.rust-lang.org/stable/rustc/platform-support.html

Choose your platform and download:

Linux Debian

Add Eclipse Zenoh private repository to the sources list:

echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update

Then either:

Docker image

The zenoh-bridge-mqtt standalone executable is also available as a Docker images for both amd64 and arm64. To get it, do:

Usage: docker run --init -p 1883:1883 eclipse/zenoh-bridge-mqtt
It supports the same command line arguments than the zenoh-bridge-mqtt (see above or check with -h argument).

How to build it

:warning: WARNING :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in mantaining compatibility between the various git repositories in the Zenoh project.

:warning: WARNING :warning: : As Rust doesn't have a stable ABI, the plugins should be built with the exact same Rust version than zenohd, and using for zenoh dependency the same version (or commit number) than 'zenohd'. Otherwise, incompatibilities in memory mapping of shared types between zenohd and the library can lead to a "SIGSEV" crash.

In order to build the zenoh bridge for MQTT you only need to install Rust. If you already have the Rust toolchain installed, make sure it is up-to-date with:

$ rustup update

Then, you may clone the repository on your machine:

$ git clone https://github.com/eclipse-zenoh/zenoh-plugin-mqtt.git
$ cd zenoh-plugin-mqtt
$ cargo build --release

The standalone executable binary zenoh-bridge-mqtt and a plugin shared library (*.so on Linux, *.dylib on Mac OS, *.dll on Windows) to be dynamically loaded by the zenoh router zenohd will be generated in the target/release subdirectory.