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

MQTT5 经纪人 (EMQX)

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

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

注意

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

版本

此组件具有以下版本：

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

Type

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

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

操作系统

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

Linux
Windows

要求

此组件具有以下要求：

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

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

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

依赖项

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

2.0.2

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

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

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 broker (EMQX) 组件，则必须更新配置文件。版本 1 配置文件不适用于版本 2。

emqxConfig

（可选）要使用的EMQXMQTT代理配置。您可以在此组件中设置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 核心设备上，您可以指定在没有 root 或管理员权限的情况下运行EMQXMQTT代理。如果将此选项设置为 false，则运行此组件的系统用户必须是 docker 组的成员。

默认值：true

startupTimeoutSeconds

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

默认值：90

ipcTimeoutSeconds

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

默认值：5

crtLogLevel

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

默认为EMQXMQTT代理日志级别（log.levelinemqx）。

restartIdentifier

（可选）配置此选项以重新启动EMQXMQTT代理。当此配置值更改时，此组件会重新启动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

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

该对象包含以下信息：

listener.ssl.external

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

注意

如果您指定不同的端口，并且使用MQTT网桥组件将MQTT消息中继到其他代理，则必须使用 MQTT bridge 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

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

默认值：90

ipcTimeoutSeconds

默认值：5

crtLogLevel

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

默认为EMQXMQTT代理日志级别（log.levelinemqx）。

restartIdentifier

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

dockerOptions

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


"-p 1883:1883"

mergeConfigurationFiles

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

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


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

除了支持的配置文件外，Greengrass 还支持用于配置调用的 Greengrass 身份验证插件的文件。EMQX EMQX 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替换为 Amazon 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.2	错误修复和改进修复了在客户端设备身份验证组件准备就绪之前EMQX启动的问题。
2.0.1	对客户端设备身份验证版本 2.5.0 发行版进行了版本更新。
2.0.0	此版本的 MQTT 5 broker (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 遥测发射器

MQTT5 经纪人 (EMQX)

注意

主题

版本

Type

操作系统

要求

依赖项

配置

重要

注意

例 示例：默认配置

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

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

例 示例：调整经MQTT纪商的日志级别

例 示例：启用EMQX控制面板

注意

注意

例 示例：配置合并更新