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

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，因此，如果您运行 M oquette MQTT 3.1.1 代理，则可以将其替换为 EMQX MQTT 5 代理，客户端设备可以继续照常连接和运行。

注意

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

版本

此组件有以下版本：

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

类型

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

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

操作系统

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

Linux
Windows

要求

此组件具有以下要求：

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

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

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

依赖项

部署组件时， 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"
  }
}

身份验证模式

（可选）为经纪人设置授权提供商。可以是以下任一值：

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 核响应进程间通信 (IPC) 请求的最长时间（以秒为单位）。如果此组件在检查客户端设备是否获得授权时报告超时错误，请增加此数字。

默认：5

crtLogLevel

（可选） AWS 公共运行时 (CRT) 库的日志级别。

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

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（256 MB 减去 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 代理日志级别（log.level中）。emqx

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 操作系统上，该软件包括根据微软软件许可条款分发的代码——微软 Visual Studio 社区 2022。下载此软件即表示您同意该代码的许可条款。

该组件是根据 Greengrass 核心软件许可协议发布的。

更改日志

下表描述了该组件的每个版本中的更改。

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`配置字段，用于替换`emqxmergeConfigurationFiles`、和`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配置字段，用于替换emqxmergeConfigurationFiles、和replaceConfigurationFiles配置字段。

v1.x

版本	更改
1.2.3	错误修复和改进修复了先前通过断开连接并重新验证客户端进行身份验证后，客户端无法与 EMQX 交互的问题。
1.2.2	版本已针对客户端设备身份验证版本 2.4.0 版本进行了更新。
1.2.1	错误修复和改进修复了如果尚不存在 Visual C++ 可再发行版，则该组件无法在 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 控制面板

注意

注意

例 示例：配置合并更新