版本 Type 作業系統要求相依性組態本機記錄檔授權變更記錄

MQTT 5 經紀商

EMQX MQTT 代理組件（aws.greengrass.clientdevices.mqtt.EMQX）處理客戶端設備和 Greengrass 核心設備之間的 MQTT 消息。此元件提供 EMQX MQ TT 5.0 代理程式的修改版本。部署此 MQTT 代理程式，以便在用戶端裝置與核心裝置之間的通訊中使用 MQTT 5 功能。如需如何選擇 MQTT 代理程式的詳細資訊，請參閱。選擇一個 MQTT 經紀商

此代理程式會實作 MQTT 5.0 通訊協定。它包括對工作階段和訊息到期間隔、使用者屬性、共用訂閱、主題別名等的支援。MQTT 5 與 MQTT 3.1.1 向後兼容，因此，如果您運行 Moquette MQTT 3.1.1 代理商，則可以將其替換為 EMQX MQTT 5 代理商，並且客戶端設備可以繼續連接並像往常一樣運行。

注意

用戶端裝置是連線到 Greengrass 核心裝置以傳送 MQTT 訊息和資料進行處理的本機 IoT 裝置。如需詳細資訊，請參閱與本機 IoT 裝置互動。

版本

此元件具有下列版本：

2.0.x
1.2.x
1.x
1.0.x

Type

此元件是一般元件 (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：
- 碼頭引擎 1.9.1 或更高版本安裝在 Greengrass 核心設備上。版本 20.10 是經過驗證可與 AWS IoT Greengrass 核心軟件配合使用的最新版本。在部署執行 Docker 容器的元件之前，您必須直接在核心裝置上安裝 Docker。
- 在您部署此元件之前，Docker 精靈會在核心裝置上啟動並執行。
- 執行此元件的系統使用者必須具有 root 或管理員權限。或者，您可以在docker群組中以系統使用者的身分執行此元件，並將false此元件的requiresPrivileges選項設定為在沒有權限的情況下執行 EQMX MQTT 代理程式。
支援 EMQX MQTT 代理程式元件在 VPC 中執行。
平台上不支援 EMQX MQTT 代理程式元件。armv7

相依性

部署元件時， AWS IoT Greengrass 也會部署其相依性的相容版本。這表示您必須符合元件及其所有相依性的需求，才能成功部署元件。本節列出此元件之已發行版本的相依性，以及定義每個相依性之元件版本的語意版本條件約束。您也可以在AWS IoT Greengrass 主控台中檢視元件每個版本的相依性。在元件詳細資料頁面上，尋找 [相依性] 清單。

相依性	兼容版本	相依性類型
用戶端裝置驗證	>=2.2.0	硬式

相依性	兼容版本	相依性類型
用戶端裝置驗證	>=2.2.0	硬式

相依性	兼容版本	相依性類型
用戶端裝置驗證	>=2.2.0	硬式

相依性	兼容版本	相依性類型
用戶端裝置驗證	>=2.2.0	硬式

相依性	兼容版本	相依性類型
用戶端裝置驗證	>=2.2.0	硬式

如需有關元件相依性的詳細資訊，請參閱元件方案參考。

組態

2.0.0 - 2.0.1

此元件提供下列組態參數，您可以在部署元件時自訂這些參數。

重要

如果您使用 MQTT 5 代理程式 (EMQX) 元件的第 2 版，則必須更新您的組態檔案。版本 1 設定檔不適用於版本 2。

EMQX 配置

(選擇性) 要使用的 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 核心裝置上，您可以指定在沒有 root 權限或系統管理員權限的情況下執行 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定每 5 秒將 MQTT 代理程式限制為 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 稱為一個文件。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"
}

本機記錄檔

此元件會使用下列記錄檔。

若要檢視此元件的記錄

在核心裝置上執行下列命令，即時檢視此元件的記錄檔。以 AWS IoT Greengrass 根資料夾的路徑取代/greengrass/v2或 C:\greengrass\v2。
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 視覺工作室社區 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。啟用 Broker 組態變更，而不必重新啟動元件。更新新增取代`emqx`、`mergeConfigurationFiles`和`emqxConfig`組態欄位的新`replaceConfigurationFiles`組態欄位。

版本

變更

2.0.1

版本更新了客戶端設備身份驗證版本 2.5.0 版本。

2.0.0

此版本的 MQTT 5 代理程式 (EMQX) 預期的組態參數與版本 1.x 不同。如果您對 1.x 版使用非預設組態，則必須更新元件的 2.x 組態。如需詳細資訊，請參閱組態。

新功能

將 MQTT 代理程式升級至 EMQX 5.1.1。
啟用 Broker 組態變更，而不必重新啟動元件。

更新

新增取代emqx、mergeConfigurationFiles和emqxConfig組態欄位的新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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

MQTT 3.1.1 經紀商 (平均)

原子核遙測發射器