Lib.rs

› 网络编程 › Zenoh
#zenoh #mqtt #pub-sub #plugin #eclipse #routes #io

zenoh-plugin-mqtt

Zenoh的MQTT插件

所有者为 Julien Enoch、OlivierHecart、Luca Cominardi、eclipse-zenoh-bot。

10个版本 ()

1.0.0-alpha.62024年8月6日
1.0.0-alpha.52024年7月26日
1.0.0-alpha.2 2024年6月21日
0.11.1 2024年6月21日
0.0.0 2022年12月7日

#333 在 网络编程

Download history 177/week @ 2024-04-29 127/week @ 2024-05-13 22/week @ 2024-05-20 141/week @ 2024-06-03 1/week @ 2024-06-10 202/week @ 2024-06-17 23/week @ 2024-06-24 88/week @ 2024-07-08 11/week @ 2024-07-15 67/week @ 2024-07-22 76/week @ 2024-07-29 100/week @ 2024-08-05

260 每月下载

EPL-2.0 OR Apache-2.0

70KB
1.5K SLoC

CI Discussion Discord License License

Eclipse Zenoh

Eclipse Zenoh：零开销的Pub/Sub、存储/查询和计算。

Zenoh（发音为/zeno/）统一了数据流动、静态数据和计算。它将传统的pub/sub与地理分布式的存储、查询和计算巧妙地结合起来，同时保持了超越任何主流堆栈的时间效率和空间效率。

请访问网站 zenoh.io 和 路线图 获取更多信息。

MQTT插件和独立zenoh-bridge-mqtt

👉 安装最新版本：见下文安装说明

👉 使用Docker镜像：见下文Docker镜像说明

👉 构建"main"分支：见下文构建说明

背景

MQTT 是一种利用代理路由消息的pub/sub协议。Eclipse Zenoh的MQTT插件充当MQTT代理，接受来自MQTT客户端（V3和V5）的连接，并将MQTT pub/sub转换为Zenoh pub/sub。即：

  • 在主题 device/123/temperature 上的MQTT发布被路由为在键表达式 device/123/temperature 上的Zenoh发布。
  • 在主题 device# 上的MQTT订阅映射到在键表达式 device/** 上的Zenoh订阅。

这允许任何MQTT系统与Zenoh进行紧密集成，同时也为MQTT系统带来了Zenoh路由基础设施的好处。一些用例示例：

  • 从设备到边缘和云的路由MQTT
  • 通过NAT穿越在互联网上桥接2个不同的MQTT系统
  • 通过Zenoh REST API进行pub/sub到MQTT
  • MQTT-ROS2（机器人）通信
  • 将MQTT发布存储在任何Zenoh存储中（RocksDB、InfluxDB、文件系统等）
  • 使用InfluxDB作为存储的MQTT记录/回放

Eclipse Zenoh的MQTT插件既可以作为动态库被Zenoh路由器（zenohd）加载，也可以作为独立的可执行文件（zenoh-bridge-mqtt）运行，它可以作为Zenoh客户端或对等节点。

配置

zenoh-bridge-mqtt可以通过传递给-c参数的JSON5文件进行配置。您可以在以下链接中查看此类配置文件的注释示例：DEFAULT_CONFIG.json5。

此配置文件中相同的"mqtt"部分也可以用于Zenoh路由器的配置文件（在其"plugins"部分）。路由器将在启动时自动尝试加载插件库（zenoh_plugin_mqtt）并应用其配置。

zenoh-bridge-mqtt还接受以下参数。如果设置，每个参数将覆盖配置文件中的类似设置

  • 与Zenoh相关的参数
    • -c, --config <FILE>：配置文件
    • -m, --mode <MODE>：Zenoh会话模式。默认：peer可能的值：peer或client。
      有关更多详细信息，请参阅zenoh文档。
    • -l, --listen <LOCATOR>：此路由器将监听传入会话的定位器。重复此选项以打开多个监听器。定位器示例：tcp/localhost:7447。
    • -e, --peer <LOCATOR>：此路由器将尝试连接到的对等节点定位器（通常是另一个网桥或Zenoh路由器）。重复此选项以连接到多个对等节点。定位器示例：tcp/<ip-address>:7447。
    • --no-multicast-scouting：禁用允许自动发现Zenoh对等节点和路由器的Zenoh侦察协议。
    • -, --id <hex_string> : Zenoh网桥必须使用的标识符（作为十六进制字符串 - 例如：0A0B23...）。警告：此标识符必须在系统中是唯一的！ 如果未设置，将使用随机UUIDv4。
    • --rest-http-port [PORT | IP:PORT] : 配置REST API的HTTP接口（默认禁用，设置此选项启用）。接受值
      • 端口号
      • 格式为<local_ip>:<port_number>的字符串（将HTTP服务器绑定到特定接口）。
  • MQTT相关参数
    • -, --port [PORT | IP:PORT] : 绑定MQTT服务器的地址。默认："0.0.0.0:1883"。接受值
      • 端口号（"0.0.0.0"将用作绑定时的IP，意味着主机的任何接口）
      • 格式为<local_ip>:<port_number>的字符串（将MQTT服务器绑定到特定接口）。
    • -, --scope <String> : 当映射到zenoh键表达式时，作为前缀添加到所有路由MQTT主题的字符串。这应用于避免当多个使用相同主题名称的MQTT系统通过Zenoh路由时发生冲突。
    • -, --allow <String> : 匹配必须通过zenoh路由的MQTT主题名称的正则表达式。默认情况下，所有主题都允许。如果同时设置了--allow和--deny，则只有匹配'allow'表达式的主题将被允许。
    • --deny <String> : 匹配不得通过zenoh路由的MQTT主题名称的正则表达式。默认情况下，不拒绝任何主题。如果同时设置了--allow和--deny，则只有匹配'allow'表达式的主题将被允许。
    • -, --generalise-pub <String> : 用于泛化Zenoh发布的声明并因此最小化发现流量的键表达式列表（可多次使用）。有关更多详细信息，请参阅此博客。
    • -r, --generalise-sub <String>：用于泛化zenoh订阅声明的键表达式列表，从而最小化发现流量（可多次使用）。请参阅这篇博客获取更多详情。
    • --tx-channel-size <无符号整数>：MQTT传输通道的大小（默认：65536）。通道从Zenoh接收消息，直到它们可以被发送到MQTT客户端。如果通道容量达到上限，新的Zenoh消息将被丢弃，直到有空间可用。
    • --dictionary-file <文件>：包含MQTT客户端用户名/密码字典的文件的路径。
    • --server-private-key <文件>：MQTT服务器的TLS私钥的路径。如果指定了私钥，还必须提供一个有效的服务器证书。
    • --server-certificate <文件>：MQTT服务器的TLS公共证书的路径。如果指定了证书，还必须提供一个有效的服务器私钥。
    • --root-ca-certificate <文件>：用于验证连接到MQTT服务器的客户端的证书授权机构的证书路径。如果指定了证书，还必须提供一个有效服务器私钥和证书。

管理空间

MQTT Zenoh网关提供了一个管理空间，允许获取其状态和配置的一些信息。此管理空间可通过任何zenoh API访问，包括您可以在启动时通过--rest-http-port参数激活的REST API。

zenoh-bridge-mqtt通过以下路径暴露此管理空间：@/service/<uuid>/mqtt（其中<uuid>是网关实例的唯一标识符）。信息随后按这些路径组织

  • @/service/<uuid>/mqtt/version：网桥版本
  • @/service/<uuid>/mqtt/config：网桥配置

使用REST API和curl命令行工具查询管理空间的示例（不要忘记使用--rest-http-port 8000参数激活REST API）

  • curl https://127.0.0.1:8000:/@/service/**

技巧：将结果通过jq命令传递，以进行JSON美化打印或转换。

MQTTS支持

Eclipse Zenoh的MQTT插件和独立网桥支持MQTTS。MQTTS可以通过两种方式配置

  • 服务器端身份验证：MQTT客户端验证服务器的TLS证书，但反之则不然。
  • 双向身份验证（mTLS）：服务器和客户端相互验证。

MQTTS可以通过配置文件配置，或者在独立网桥的情况下通过命令行参数配置。

服务器端身份验证配置

服务器端认证需要服务器端的私钥和证书。这些可以作为文件或base 64编码的字符串提供。

在配置文件中，使用文件时所需的 tls 字段是 server_private_key 和 server_certificate。使用base 64编码字符串时，所需的 tls 字段是 server_private_key_base64 和 server_certificate_base64。

一个支持服务器端认证的配置文件示例：

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

独立的桥接器（zenoh-bridge-mqtt）还允许通过命令行参数 --server-private-key 和 --server-certificate 提供所需的文件。

双向认证（mTLS）配置

为了启用双向认证，还需要提供用于验证连接到MQTT服务器的客户端的证书颁发机构的证书。这可以作为文件或base 64编码的字符串提供。

在配置文件中，使用文件时所需的 tls 字段是 root_ca_certificate。使用base 64编码字符串时，所需的 tls 字段是 root_ca_certificate_base64。

一个支持服务器端认证的配置文件示例：

{
  "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"
      }
    }
  }
}

独立的桥接器（zenoh-bridge-mqtt）还允许通过命令行参数 --root-ca-certificate 提供所需的文件。

用户名/密码认证

Eclipse Zenoh的MQTT插件和独立的桥接器支持MQTT客户端的基本用户名/密码认证。凭据通过字典文件提供，每行包含单个用户的用户名和密码，格式如下

username:password

用户名/密码认证可以通过配置文件配置，如果使用独立的桥接器，则可以通过命令行参数配置。

在配置文件中，用于配置字典文件的必需 auth 字段是 dictionary_file。

一个支持用户名/密码认证的配置文件示例：

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

独立的桥接器（zenoh-bridge-mqtt）还允许通过命令行参数 --dictionary-file 提供所需的文件。

安全考虑

用户名和密码作为MQTT CONNECT 消息的一部分发送，并以明文形式。因此，它们可能会被工具（如 Wireshark）查看。

为了防止这种情况，强烈建议与MQTTS功能一起使用此功能，以确保凭据在传输过程中被加密。

如何安装

要安装Zenoh路由器的MQTT插件或zenoh-bridge-mqtt独立可执行文件的最新版本，您可以按照以下步骤操作

手动安装（所有平台）

所有发布包可以从以下位置下载

每个子目录都有Rust目标名称。有关每个目标对应的平台，请参阅https://doc.rust-lang.net.cn/stable/rustc/platform-support.html

选择您的平台并下载

  • 插件所需的 zenoh-plugin-mqtt-<版本>-<平台>.zip 文件。
    然后将其解压缩到与 zenohd 相同的目录中，或者解压缩到插件库可以找到的任何目录（例如 /usr/lib）
  • 独立可执行文件的 zenoh-bridge-mqtt-<版本>-<平台>.zip 文件。
    然后将其解压缩到您想要的位置，并运行提取的 zenoh-bridge-mqtt 二进制文件。

Linux Debian

将Eclipse Zenoh私有仓库添加到源列表中

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

然后，可以选择以下任意一种方法：

  • 使用以下命令安装插件：sudo apt install zenoh-plugin-mqtt。
  • 使用以下命令安装独立的可执行文件：sudo apt install zenoh-bridge-mqtt。

Docker镜像

zenoh-bridge-mqtt 独立可执行文件也以Docker镜像的形式提供，适用于amd64和arm64。要获取它，请执行以下操作：

  • docker pull eclipse/zenoh-bridge-mqtt:latest 以获取最新发布版本
  • docker pull eclipse/zenoh-bridge-mqtt:main 以获取主分支版本（夜间构建）

用法：docker run --init -p 1883:1883 eclipse/zenoh-bridge-mqtt
它支持与 zenoh-bridge-mqtt 相同的命令行参数（参见上方或使用 -h 参数检查）。

如何构建它

⚠️ 警告 ⚠️：Zenoh及其生态系统正在积极开发中。当你从git构建时，请确保你也从git构建了你计划使用的任何其他Zenoh仓库（例如，绑定、插件、后端等）。可能会发生git中的某些更改与最新的打包Zenoh版本（例如，deb、docker、pip）不兼容的情况。我们在维护Zenoh项目中各个git仓库之间的兼容性方面投入了特别大的努力。

⚠️ 警告 ⚠️：由于Rust没有稳定的ABI，插件应使用与 zenohd 完全相同的Rust版本构建，并且对于 zenoh 依赖项使用相同的版本（或提交号）。否则，在 zenohd 和库之间的共享类型内存映射中的不兼容性可能导致 "SIGSEV" 崩溃。

为了构建MQTT的zenoh桥，您只需要安装 Rust。如果您已经安装了Rust工具链，请确保它已通过以下方式更新：

$ rustup update

然后，您可以在您的机器上克隆仓库

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

独立的可执行文件 zenoh-bridge-mqtt 和一个插件共享库（Linux上的 *.so，Mac OS上的 *.dylib，Windows上的 *.dll）将被生成在 target/release 子目录中，以便由zenoh路由器 zenohd 动态加载。

依赖项

~42–56MB
~1M SLoC