版本类型操作系统要求依赖项配置本地日志文件许可证更改日志

MQTT 5 代理（EMQX）

EMQX MQTT 代理组件 (aws.greengrass.clientdevices.mqtt.EMQX) 处理客户端设备与 Greengrass 核心设备之间的 MQTT 消息。此组件提供 EMQX MQTT 5.0 代理的修改版本。部署此 MQTT 代理，以便在客户端设备与核心设备的通信中使用 MQTT 5 功能。有关如何选择 MQTT 代理的更多信息，请参阅选择 MQTT 代理。

此代理实施 MQTT 5.0 协议。它支持会话和消息过期间隔、用户属性、共享订阅、主题别名等功能。MQTT 5 向后兼容 MQTT 3.1.1，因此，如果您运行 Moquette MQTT 3.1.1 代理，您可以将其替换为 EMQX MQTT 5 代理，并且客户端设备可以继续照常连接和运行。

注意

客户端设备是本地 IoT 设备，连接到 Greengrass 核心设备以发送 MQTT 消息和数据进行处理。有关更多信息，请参阅与本地 IoT 设备交互。

版本

此组件具有以下版本：

2.0.x
1.2.x
1.1.x
1.0.x

类型

此组件是一个通用组件 (aws.greengrass.generic)。Greengrass Nucleus 运行组件的生命周期脚本。

有关更多信息，请参阅组件类型。

操作系统

此组件可以安装在运行以下操作系统的核心设备上：

Linux
Windows

要求

此组件具有以下要求：

核心设备必须能够接受 MQTT 代理运行端口的连接。默认情况下，此组件在端口 8883 运行 MQTT 代理。配置此组件时，您可以指定其他端口。

如果您指定其它端口，并且使用 MQTT 网桥组件将 MQTT 消息中继到其它代理，您必须使用 MQTT 网桥 v2.1.0 或更高版本。将其配置为使用 MQTT 代理运行的端口。

如果您指定其它端口，并使用 IP 检测器组件管理 MQTT 代理端点，则必须使用 IP 检测器 v2.1.0 或更高版本。将其配置为报告 MQTT 代理运行的端口。
在 Linux 核心设备上，在核心设备上安装并配置 Docker：
- Greengrass 核心设备上安装的 Docker Engine 1.9.1 或更高版本。版本 20.10 是经验证可与 AWS IoT Greengrass Core 软件配合使用的最新版本。在部署运行 Docker 容器的组件之前，必须直接在核心设备上安装 Docker。
- 在部署此组件之前，Docker 进程守护程序已启动并在核心设备上运行。
- 运行此组件的系统用户必须具有根权限或管理员权限。或者，您可以以 docker 组中系统用户的身份运行此组件，并将此组件的 requiresPrivileges 选项配置为 false，以在没有权限的情况下运行 EQMX MQTT 代理。
支持在 VPC 中运行 EMQX MQTT 网桥组件。
armv7 平台不支持 EMQX MQTT 代理组件。

依赖项

在您部署组件时，AWS IoT Greengrass 也会部署其依赖关系的兼容版本。这意味着您必须满足组件及其所有依赖关系的要求，才能成功部署组件。本部分列出了此组件的已发布版本的依赖关系，以及定义每个依赖关系的组件版本的语义版本约束。您还可以在 AWS IoT Greengrass 控制台中查看每个组件版本的依赖关系。在组件详细信息页面上，查找依赖关系列表。

2.0.1

下表列出了此组件的版本 2.0.1 的依赖关系。

依赖关系	兼容版本	依赖关系类型
客户端设备身份验证	>=2.2.0 <2.6.0	硬性

2.0.0

下表列出了此组件版本 2.0.0 的依赖关系。

依赖关系	兼容版本	依赖关系类型
客户端设备身份验证	>=2.2.0 <2.5.0	硬性

1.2.2 – 1.2.3

下表列出了此组件的版本 1.2.2 至 1.2.3 的依赖关系。

依赖关系	兼容版本	依赖关系类型
客户端设备身份验证	>=2.2.0 <2.5.0	硬性

1.2.0 and 1.2.1

下表列出了此组件的版本 1.2.0 和 1.2.1 的依赖关系。

依赖关系	兼容版本	依赖关系类型
客户端设备身份验证	>=2.2.0 <2.4.0	硬性

1.0.0 and 1.1.0

下表列出了此组件的版本 1.0.0 和 1.1.0 的依赖关系。

依赖关系	兼容版本	依赖关系类型
客户端设备身份验证	>=2.2.0 <2.3.0	硬性

有关组件依赖关系的更多信息，请参阅组件配方参考。

配置

2.0.0 - 2.0.1

此组件提供您可以在部署组件时自定义的以下配置参数。

重要

如果您使用版本 2 的 MQTT 5 代理（EMQX）组件，则必须更新您的配置文件。版本 1 配置文件不适用于版本 2。

emqxConfig

（可选）要使用的 EMQX MQTT 代理配置。您可以在此组件中设置 EMQX 配置选项。

当您使用 EMQX 代理时，Greengrass 使用默认配置。除非您使用此字段对其进行修改，否则将使用此配置。

修改以下配置设置会导致 EMQX 代理组件重新启动。其它配置更改无需重新启动组件即可生效。

emqxConfig/cluster
emqxConfig/node
emqxConfig/rpc

注意

aws.greengrass.clientdevices.mqtt.EMQX 允许您配置对安全敏感的选项。这些包括 TLS 设置、身份验证和授权提供程序。我们推荐默认配置，使用双向 TLS 身份验证和 Greengrass 客户端设备身份验证提供程序。

例示例：默认配置

以下示例显示为 MQTT 5（EMQX）代理设置的默认值。您可以使用 emqxConfig 配置设置覆盖这些设置。


{
  "authorization": {
    "no_match": "deny",
    "sources": []
  },
  "node": {
    "cookie": "<placeholder>"
  }, 
  "listeners": {
     "ssl": {
       "default": {
         "ssl_options": {
           "keyfile": "{work:path}\\data\\key.pem",
           "certfile": "{work:path}\\data\\cert.pem",
           "cacertfile": null,
           "verify": "verify_peer",
           "versions": ["tlsv1.3", "tlsv1.2"],
           "fail_if_no_peer_cert": true
         }
       }
     },
     "tcp": {
       "default": {
         "enabled": false
       }
     },
     "ws": {
       "default": {
         "enabled": false
       }
     },
     "wss": {
       "default": {
         "enabled": false
       }
     }
  },
  "plugins": {
    "states": [{"name_vsn": "gg-1.0.0", "enable": true}],
    "install_dir": "plugins"
  }
}

authMode

（可选）为代理设置授权提供程序。可以是以下任一值：

enabled –（默认）使用 Greengrass 身份验证和授权提供程序。
bypass_on_failure – 使用 Greengrass 身份验证提供程序，如果 Greengrass 拒绝身份验证或授权，则使用 EMQX 提供程序链中剩余的任何身份验证提供程序。
bypass – 禁用 Greengrass 提供程序。身份验证和授权由 EMQX 提供程序链处理。

requiresPrivilege

（可选）在 Linux 核心设备上，您可以指定在没有根权限或管理员权限的情况下运行 EMQX MQTT 代理。如果将此选项设置为 false，则运行此组件的系统用户必须是 docker 组的成员。

默认：true

startupTimeoutSeconds

（可选）EMQX MQTT 代理启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 BROKEN。

默认：90

ipcTimeoutSeconds

（可选）组件等待 Greengrass Nucleus 响应进程间通信（IPC）请求的最长时间（以秒为单位）。如果此组件在检查客户端设备是否获得授权时报告超时错误，请增加此数字。

默认：5

crtLogLevel

（可选）AWS 通用运行时（CRT）库的日志级别。

默认为 EMQX MQTT 代理日志级别（emqx 中的 log.level）。

restartIdentifier

（可选）配置此选项可重新启动 EMQX MQTT 代理。当此配置值更改时，此组件会重新启动 MQTT 代理。您可以使用此选项强制客户端设备断开连接。

dockerOptions

（可选）仅在 Linux 操作系统上配置此选项，以便向 Docker 命令行添加参数。例如，要映射其它端口，请使用 -p Docker 参数：


"-p 1883:1883"

例示例：将 v1.x 配置文件更新为 v2.x

以下示例显示了将 v1.x 配置文件更新到 2.x 版本所需的更改。

版本 1.x 配置文件：


{
    "emqx": {
        "listener.ssl.external": "443",
        "listener.ssl.external.max_connections": "1024000",
        "listener.ssl.external.max_conn_rate": "500",
        "listener.ssl.external.rate_limit": "50KB,5s",
        "listener.ssl.external.handshake_timeout": "15s",
        "log.level": "warning"
    },
    "mergeConfigurationFiles": {
        "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
    }
}

v2 的等效配置文件：


{
    "emqxConfig": {
        "listeners": {
            "ssl": {
                "default": {
                   "bind": "8883",
                   "max_connections": "1024000",
                   "max_conn_rate": "500",
                   "handshake_timeout": "15s"
                }
            }
        },
        "log": {
            "console": {
              "enable": true,
              "level": "warning"
            }
        }
    },
    "authMode": "enabled"
}

没有与 listener.ssl.external.rate_limit 配置条目对应的内容。已删除 use_greengrass_managed_certificates 配置选项。

例示例：为代理设置新端口

以下示例将 MQTT 代理运行的端口从默认的 8883 更改为端口 1234。如果您使用的是 Linux，请包含 dockerOptions 字段。


{
  "emqxConfig": {
    "listeners": {
      "ssl": {
        "default": {
          "bind": 1234
        }
      }
    }
  },
  "dockerOptions": "-p 1234:1234"
}

例示例：调整 MQTT 代理的日志级别

以下示例将 MQTT 代理的日志级别更改为 debug。您可从以下日志级别中进行选择：

debug
info
notice
warning
error
critical
alert
emergency

默认日志级别为 warning。


{
  "emqxConfig": {
    "log": {
      "console": {
         "level": "debug"
      }
    }
  }
}

例示例：启用 EMQX 控制面板

以下示例启用 EMQX 控制面板，以便您可以监控和管理您的代理。如果您使用的是 Linux，请包含 dockerOptions 字段。


{
  "emqxConfig": {
    "dashboard": {
      "listeners": {
        "http": {
          "bind": 18083
        }
      }
    }
  },
  "dockerOptions": "-p 18083:18083"
}

1.0.0 - 1.2.2

此组件提供您可以在部署组件时自定义的以下配置参数。

emqx

（可选）要使用的 EMQX MQTT 代理配置。您可以在此组件中配置 EMQX 配置选项的子集。

该对象包含以下信息：

listener.ssl.external

（可选）MQTT 代理运行的端口。

注意

如果您指定其它端口，并且使用 MQTT 网桥组件将 MQTT 消息中继到其它代理，您必须使用 MQTT 网桥 v2.1.0 或更高版本。将其配置为使用 MQTT 代理运行的端口。

如果您指定其它端口，并使用 IP 检测器组件管理 MQTT 代理端点，则必须使用 IP 检测器 v2.1.0 或更高版本。将其配置为报告 MQTT 代理运行的端口。

默认：8883

listener.ssl.external.max_connections

（可选）MQTT 代理支持的最大并行连接数。

默认：1024000

listener.ssl.external.max_conn_rate

（可选）MQTT 代理每秒可以接收的最大新连接数。

默认：500

listener.ssl.external.rate_limit

（可选）与 MQTT 代理的所有连接的带宽限制。按以下格式指定带宽及其持续时间，用逗号 (,) 分隔：bandwidth,duration。例如，您可以指定 50KB,5s 将 MQTT 代理限制为每 5 秒 50 千字节（KB）的数据。

listener.ssl.external.handshake_timeout

（可选）MQTT 代理等待完成对新连接的身份验证的时长。

默认：15s

mqtt.max_packet_size

（可选）MQTT 消息的最大大小。

默认值：268435455（256MB 减去 1）

log.level

（可选）MQTT 代理的日志级别。从以下选项中进行选择：

debug
info
notice
warning
error
critical
alert
emergency

默认日志级别为 warning。

requiresPrivilege

默认：true

startupTimeoutSeconds

（可选）EMQX MQTT 代理启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 BROKEN。

默认：90

ipcTimeoutSeconds

默认：5

crtLogLevel

（可选）AWS 通用运行时（CRT）库的日志级别。

默认为 EMQX MQTT 代理日志级别（emqx 中的 log.level）。

restartIdentifier

（可选）配置此选项可重新启动 EMQX MQTT 代理。当此配置值更改时，此组件会重新启动 MQTT 代理。您可以使用此选项强制客户端设备断开连接。

dockerOptions

（可选）仅在 Linux 操作系统上配置此选项，以便向 Docker 命令行添加参数。例如，要映射其它端口，请使用 -p Docker 参数：


"-p 1883:1883"

mergeConfigurationFiles

（可选）配置此选项可添加或覆盖指定 EMQX 配置文件中的默认值。有关配置文件及其格式的信息，请参阅 EMQX 4.0 文档中的配置。您指定的值将附加到配置文件中。

以下示例将更新 etc/emqx.conf 文件。


"mergeConfigurationFiles": {
    "etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},

除 EMQX 支持的配置文件外，Greengrass 还支持一个文件，为 EMQX 配置 Greengrass 身份验证插件，名为 etc/plugins/aws_greengrass_emqx_auth.conf。有两个支持的选项，即 auth_mode 和 use_greengrass_managed_certificates。要使用其它身份验证提供程序，请将 auth_mode 选项设置为以下选项之一：

enabled –（默认）使用 Greengrass 身份验证和授权提供程序。
bypass_on_failure – 使用 Greengrass 身份验证提供程序，如果 Greengrass 拒绝身份验证或授权，则使用 EMQX 提供程序链中剩余的任何身份验证提供程序。
bypass – 禁用 Greengrass 提供程序。然后，身份验证和授权由 EMQX 提供程序链处理。

如果 use_greengrass_managed_certificates 为 true，则此选项表示 Greengrass 管理代理 TLS 证书。如果为 false，则表示您通过其它来源提供证书。

以下示例更新了 etc/plugins/aws_greengrass_emqx_auth.conf 配置文件中的默认值。


"mergeConfigurationFiles": {
    "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
  },

注意

aws.greengrass.clientdevices.mqtt.EMQX 允许您配置对安全敏感的选项。这些包括 TLS 设置、身份验证和授权提供程序。推荐的配置是默认配置，使用双向 TLS 身份验证和 Greengrass 客户端设备身份验证提供程序。

replaceConfigurationFiles

（可选）配置此选项可替换指定的 EMQX 配置文件。您指定的值替换整个现有配置文件。您无法在此部分中指定 etc/emqx.conf 文件。您必须使用 mergeConfigurationFile 才能修改 etc/emqx.conf。

例示例：配置合并更新

以下示例配置指定在端口 443 运行 MQTT 代理。


{
  "emqx": {
    "listener.ssl.external": "443",
    "listener.ssl.external.max_connections": "1024000",
    "listener.ssl.external.max_conn_rate": "500",
    "listener.ssl.external.rate_limit": "50KB,5s",
    "listener.ssl.external.handshake_timeout": "15s",
    "log.level": "warning"
  },
  "requiresPrivilege": "true",
  "startupTimeoutSeconds": "90",
  "ipcTimeoutSeconds": "5"
}

本地日志文件

此组件使用以下日志文件。

查看此组件的日志

在核心设备上运行以下命令以实时查看此组件的日志文件。将 /greengrass/v2 或 C:\greengrass\v2 替换为 AWS IoT Greengrass 根文件夹的路径。
Linux
```
sudo tail -f /greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
```
Windows (PowerShell)
```
Get-Content C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log -Tail 10 -Wait
```

许可证

在 Windows 操作系统上，该软件包括根据 Microsoft 软件许可条款 – Microsoft Visual Studio Community 2022 分发的代码。下载此软件，即表示您同意该代码的许可条款。

此组件在 Greengrass Core 软件许可协议下发行。

更改日志

下表介绍每个组件版本的更改。

v2.x

版本	更改
2.0.1	对客户端设备身份验证版本 2.5.0 发行版进行了版本更新。
2.0.0	此版本的 MQTT 5 代理（EMQX）需要的配置参数与版本 1.x 不同。如果您为版本 1.x 使用非默认配置，您必须为 2.x 更新组件的配置。有关更多信息，请参阅配置。新功能将 MQTT 代理升级为 EMQX 5.1.1。支持在没有重新启动组件的情况下更改代理配置。更新添加新的`emqxConfig` 配置字段，用于替换 `emqx`、`mergeConfigurationFiles` 和 `replaceConfigurationFiles` 配置字段。

版本

更改

2.0.1

对客户端设备身份验证版本 2.5.0 发行版进行了版本更新。

2.0.0

此版本的 MQTT 5 代理（EMQX）需要的配置参数与版本 1.x 不同。如果您为版本 1.x 使用非默认配置，您必须为 2.x 更新组件的配置。有关更多信息，请参阅配置。

新功能

将 MQTT 代理升级为 EMQX 5.1.1。
支持在没有重新启动组件的情况下更改代理配置。

更新

添加新的emqxConfig 配置字段，用于替换 emqx、mergeConfigurationFiles 和 replaceConfigurationFiles 配置字段。

v1.x

版本	更改
1.2.3	错误修复和改进修复了以下问题：先前通过断开连接并重新验证客户端进行身份验证后，客户端无法与 EMQX 交互。
1.2.2	对客户端设备身份验证版本 2.4.0 发行版进行了版本更新。
1.2.1	错误修复和改进修复了以下问题：如果尚不存在 Visual C++ Redistributable，则组件无法在 Windows 上启动。将 EMQX 更新至版本 4.4.14。
1.2.0	添加了对证书链的支持。
1.1.0	新功能支持 EMQX 配置，包括代理选项和插件。错误修复和改进将 EMQX 更新至版本 4.4.9。
1.0.1	修复了在 TLS 握手期间导致某些 MQTT 客户端无法连接的问题。
1.0.0	初始版本。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

MQTT 3.1.1 代理（Moquette）

Nucleus 遥测发射器

MQTT 5 代理（EMQX）

注意

主题

版本

类型

操作系统

要求

依赖项

配置

重要

注意

例 示例：默认配置

例 示例：将 v1.x 配置文件更新为 v2.x

例 示例：为代理设置新端口

例 示例：调整 MQTT 代理的日志级别

例 示例：启用 EMQX 控制面板

注意

注意

例 示例：配置合并更新