Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Courtier MQTT 5 (EMQX)
Le composant broker EMQX MQTT (aws.greengrass.clientdevices.mqtt.EMQX) gère les messages MQTT entre les appareils clients et un périphérique principal de Greengrass. Ce composant fournit une version modifiée du broker EMQX MQTT 5.0. Déployez ce broker MQTT pour utiliser les fonctionnalités de MQTT 5 dans la communication entre les appareils clients et un périphérique principal. Pour plus d'informations sur le choix d'un courtier MQTT, consultezChoisissez un courtier MQTT.
Ce broker implémente le protocole MQTT 5.0. Il inclut la prise en charge des intervalles d'expiration des sessions et des messages, des propriétés utilisateur, des abonnements partagés, des alias de rubrique, etc. MQTT 5 est rétrocompatible avec MQTT 3.1.1, donc si vous exécutez le broker Moquette MQTT 3.1.1, vous pouvez le remplacer par le broker EMQX MQTT 5, et les appareils clients peuvent continuer à se connecter et à fonctionner comme d'habitude.
Les appareils clients sont des appareils IoT locaux qui se connectent à un appareil principal de Greengrass pour envoyer des messages MQTT et des données à traiter. Pour plus d’informations, consultez Interagissez avec les appareils IoT locaux.
Versions
Les versions de ce composant sont les suivantes :
Type
Ce composant est un composant générique (aws.greengrass.generic). Le noyau Greengrass exécute les scripts de cycle de vie du composant.
Pour plus d’informations, consultez Types de composants.
Système d’exploitation
Ce composant peut être installé sur les appareils principaux qui exécutent les systèmes d'exploitation suivants :
Prérequis
Ce composant répond aux exigences suivantes :
-
Le périphérique principal doit être capable d'accepter des connexions sur le port où fonctionne le broker MQTT. Ce composant exécute le broker MQTT sur le port 8883 par défaut. Vous pouvez spécifier un port différent lorsque vous configurez ce composant.
Si vous spécifiez un port différent et que vous utilisez le composant pont MQTT pour relayer les messages MQTT à d'autres courtiers, vous devez utiliser le pont MQTT v2.1.0 ou version ultérieure. Configurez-le pour utiliser le port sur lequel le broker MQTT fonctionne.
Si vous spécifiez un port différent et que vous utilisez le composant de détection IP pour gérer les points de terminaison du broker MQTT, vous devez utiliser le détecteur IP v2.1.0 ou version ultérieure. Configurez-le pour signaler le port sur lequel le broker MQTT fonctionne.
-
Sur les appareils principaux Linux, Docker est installé et configuré sur le périphérique principal :
-
Docker Engine 1.9.1 ou version ultérieure installé sur le périphérique principal de Greengrass. La version 20.10 est la dernière version vérifiée pour fonctionner avec le logiciel AWS IoT Greengrass Core. Vous devez installer Docker directement sur le périphérique principal avant de déployer des composants qui exécutent des conteneurs Docker.
-
Le daemon Docker a démarré et s'est exécuté sur le périphérique principal avant que vous ne déployiez ce composant.
-
L'utilisateur du système qui exécute ce composant doit disposer des autorisations root ou administrateur. Vous pouvez également exécuter ce composant en tant qu'utilisateur du système dans le docker groupe et configurer l'requiresPrivilegesoption de ce composant false pour exécuter le courtier EQMX MQTT sans privilèges.
-
Le composant broker EMQX MQTT est compatible pour s'exécuter dans un VPC.
-
Le composant broker EMQX MQTT n'est pas pris en charge sur la plateforme. armv7
Dépendances
Lorsque vous déployez un composant, il déploie AWS IoT Greengrass également des versions compatibles de ses dépendances. Cela signifie que vous devez satisfaire aux exigences relatives au composant et à toutes ses dépendances pour réussir le déploiement du composant. Cette section répertorie les dépendances des versions publiées de ce composant et les contraintes de version sémantiques qui définissent les versions des composants pour chaque dépendance. Vous pouvez également consulter les dépendances de chaque version du composant dans la AWS IoT Greengrass console. Sur la page de détails du composant, recherchez la liste des dépendances.
- 2.0.1
-
Le tableau suivant répertorie les dépendances pour la version 2.0.1 de ce composant.
- 2.0.0
-
Le tableau suivant répertorie les dépendances pour la version 2.0.0 de ce composant.
- 1.2.2 – 1.2.3
-
Le tableau suivant répertorie les dépendances pour les versions 1.2.2 à 1.2.3 de ce composant.
- 1.2.0 and 1.2.1
-
Le tableau suivant répertorie les dépendances pour les versions 1.2.0 et 1.2.1 de ce composant.
- 1.0.0 and 1.1.0
-
Le tableau suivant répertorie les dépendances pour les versions 1.0.0 et 1.1.0 de ce composant.
Pour plus d'informations sur les dépendances des composants, consultez la référence de la recette des composants.
Configuration
- 2.0.0 - 2.0.1
-
Ce composant fournit les paramètres de configuration suivants que vous pouvez personnaliser lorsque vous déployez le composant.
Si vous utilisez la version 2 du composant MQTT 5 broker (EMQX), vous devez mettre à jour votre fichier de configuration. Les fichiers de configuration de la version 1 ne fonctionnent pas avec la version 2.
- Configuration EMQX
-
(Facultatif) La configuration du broker EMQX MQTT à utiliser. Vous pouvez définir les options de configuration EMQX dans ce composant.
Lorsque vous utilisez le broker EMQX, Greengrass utilise une configuration par défaut. Cette configuration est utilisée sauf si vous la modifiez à l'aide de ce champ.
La modification des paramètres de configuration suivants entraîne le redémarrage du composant du broker EMQX. Les autres modifications de configuration s'appliquent sans redémarrer le composant.
-
emqxConfig/cluster
-
emqxConfig/node
-
emqxConfig/rpc
aws.greengrass.clientdevices.mqtt.EMQXvous permet de configurer des options sensibles à la sécurité. Il s'agit notamment des paramètres TLS, de l'authentification et des fournisseurs d'autorisation. Nous avons recommandé la configuration par défaut qui utilise l'authentification TLS mutuelle et le fournisseur d'authentification des appareils clients Greengrass.
Exemple : configuration par défaut
L'exemple suivant montre les valeurs par défaut définies pour le broker MQTT 5 (EMQX). Vous pouvez remplacer ces paramètres à l'aide du paramètre emqxConfig de configuration.
{
"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"
}
}
- Mode Auth
-
(Facultatif) Définit le fournisseur d'autorisation pour le courtier. Il peut avoir l'une des valeurs suivantes :
-
enabled— (Par défaut) Utilisez le fournisseur d'authentification et d'autorisation Greengrass.
-
bypass_on_failure— Utilisez le fournisseur d'authentification Greengrass, puis utilisez tous les fournisseurs d'authentification restants de la chaîne de fournisseurs EMQX si Greengrass refuse l'authentification ou l'autorisation.
-
bypass— Le fournisseur Greengrass est désactivé. L'authentification et l'autorisation sont gérées par la chaîne de fournisseurs EMQX.
requiresPrivilege-
(Facultatif) Sur les appareils principaux Linux, vous pouvez spécifier d'exécuter le broker EMQX MQTT sans droits root ou administrateur. Si vous définissez cette option surfalse, l'utilisateur du système qui exécute ce composant doit être membre du docker groupe.
Par défaut : true
startupTimeoutSeconds-
(Facultatif) Durée maximale en secondes pendant laquelle le broker EMQX MQTT démarre. L'état du composant passe à BROKEN s'il dépasse ce délai d'attente.
Par défaut : 90
ipcTimeoutSeconds-
(Facultatif) Durée maximale en secondes pendant laquelle le composant attend que le noyau Greengrass réponde aux demandes de communication interprocessus (IPC). Augmentez ce nombre si ce composant signale des erreurs de temporisation lorsqu'il vérifie si un appareil client est autorisé.
Par défaut : 5
crtLogLevel-
(Facultatif) Le niveau de journalisation de la bibliothèque AWS Common Runtime (CRT).
La valeur par défaut est le niveau de journalisation du broker EMQX MQTT (in). log.level emqx
restartIdentifier-
(Facultatif) Configurez cette option pour redémarrer le broker EMQX MQTT. Lorsque cette valeur de configuration change, ce composant redémarre le broker MQTT. Vous pouvez utiliser cette option pour forcer les appareils clients à se déconnecter.
dockerOptions-
(Facultatif) Configurez cette option uniquement sur les systèmes d'exploitation Linux pour ajouter des paramètres à la ligne de commande Docker. Par exemple, pour mapper des ports supplémentaires, utilisez le paramètre -p Docker :
"-p 1883:1883"
Exemple : mise à jour d'un fichier de configuration v1.x vers la version 2.x
L'exemple suivant montre les modifications nécessaires pour mettre à jour un fichier de configuration v1.x vers la version 2.x.
Le fichier de configuration de la version 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"
}
}
Le fichier de configuration équivalent pour la 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"
}
Il n'existe aucun équivalent à l'entrée listener.ssl.external.rate_limit de configuration. L'option use_greengrass_managed_certificates de configuration a été supprimée.
Exemple : définir un nouveau port pour le courtier
Dans l'exemple suivant, le port sur lequel le broker MQTT opère passe du port par défaut 8883 au port 1234. Si vous utilisez Linux, incluez le dockerOptions champ.
{
"emqxConfig": {
"listeners": {
"ssl": {
"default": {
"bind": 1234
}
}
}
},
"dockerOptions": "-p 1234:1234"
}
Exemple : ajuster le niveau de journalisation du broker MQTT
L'exemple suivant change le niveau de journalisation du broker MQTT endebug. Vous pouvez choisir l'un des niveaux de journalisation suivants :
-
debug
-
info
-
notice
-
warning
-
error
-
critical
-
alert
-
emergency
Le niveau de journalisation par défaut estwarning.
{
"emqxConfig": {
"log": {
"console": {
"level": "debug"
}
}
}
}
Exemple : activer le tableau de bord EMQX
L'exemple suivant active le tableau de bord EMQX afin que vous puissiez surveiller et gérer votre courtier. Si vous utilisez Linux, incluez le dockerOptions champ.
{
"emqxConfig": {
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"dockerOptions": "-p 18083:18083"
}
- 1.0.0 - 1.2.2
-
Ce composant fournit les paramètres de configuration suivants que vous pouvez personnaliser lorsque vous déployez le composant.
emqx-
(Facultatif) La configuration du broker EMQX MQTT à utiliser. Vous pouvez configurer un sous-ensemble d'options de configuration EMQX dans ce composant.
Cet objet contient les informations suivantes :
listener.ssl.external-
(Facultatif) Le port sur lequel le broker MQTT fonctionne.
Si vous spécifiez un port différent et que vous utilisez le composant pont MQTT pour relayer les messages MQTT à d'autres courtiers, vous devez utiliser le pont MQTT v2.1.0 ou version ultérieure. Configurez-le pour utiliser le port sur lequel le broker MQTT fonctionne.
Si vous spécifiez un port différent et que vous utilisez le composant de détection IP pour gérer les points de terminaison du broker MQTT, vous devez utiliser le détecteur IP v2.1.0 ou version ultérieure. Configurez-le pour signaler le port sur lequel le broker MQTT fonctionne.
Par défaut : 8883
listener.ssl.external.max_connections-
(Facultatif) Le nombre maximum de connexions simultanées prises en charge par le broker MQTT.
Par défaut : 1024000
listener.ssl.external.max_conn_rate-
(Facultatif) Le nombre maximum de nouvelles connexions par seconde que le broker MQTT peut recevoir.
Par défaut : 500
listener.ssl.external.rate_limit-
(Facultatif) Limite de bande passante pour toutes les connexions au broker MQTT. Spécifiez la bande passante et la durée de cette bande passante séparées par une virgule (,) au format suivant :bandwidth,duration. Par exemple, vous pouvez spécifier de 50KB,5s limiter le broker MQTT à 50 kilo-octets (Ko) de données toutes les 5 secondes.
listener.ssl.external.handshake_timeout-
(Facultatif) Durée pendant laquelle le broker MQTT attend pour terminer l'authentification d'une nouvelle connexion.
Par défaut : 15s
mqtt.max_packet_size-
(Facultatif) Taille maximale d'un message MQTT.
Par défaut : 268435455 (256 Mo moins 1)
log.level-
(Facultatif) Le niveau de journalisation du broker MQTT. Sélectionnez parmi les options suivantes :
-
debug
-
info
-
notice
-
warning
-
error
-
critical
-
alert
-
emergency
Le niveau de journalisation par défaut estwarning.
requiresPrivilege-
(Facultatif) Sur les appareils principaux Linux, vous pouvez spécifier d'exécuter le broker EMQX MQTT sans droits root ou administrateur. Si vous définissez cette option surfalse, l'utilisateur du système qui exécute ce composant doit être membre du docker groupe.
Par défaut : true
startupTimeoutSeconds-
(Facultatif) Durée maximale en secondes pendant laquelle le broker EMQX MQTT démarre. L'état du composant passe à BROKEN s'il dépasse ce délai d'attente.
Par défaut : 90
ipcTimeoutSeconds-
(Facultatif) Durée maximale en secondes pendant laquelle le composant attend que le noyau Greengrass réponde aux demandes de communication interprocessus (IPC). Augmentez ce nombre si ce composant signale des erreurs de temporisation lorsqu'il vérifie si un appareil client est autorisé.
Par défaut : 5
crtLogLevel-
(Facultatif) Le niveau de journalisation de la bibliothèque AWS Common Runtime (CRT).
La valeur par défaut est le niveau de journalisation du broker EMQX MQTT (in). log.level emqx
restartIdentifier-
(Facultatif) Configurez cette option pour redémarrer le broker EMQX MQTT. Lorsque cette valeur de configuration change, ce composant redémarre le broker MQTT. Vous pouvez utiliser cette option pour forcer les appareils clients à se déconnecter.
dockerOptions-
(Facultatif) Configurez cette option uniquement sur les systèmes d'exploitation Linux pour ajouter des paramètres à la ligne de commande Docker. Par exemple, pour mapper des ports supplémentaires, utilisez le paramètre -p Docker :
"-p 1883:1883"
mergeConfigurationFiles-
(Facultatif) Configurez cette option pour ajouter ou remplacer les valeurs par défaut dans les fichiers de configuration EMQX spécifiés. Pour plus d'informations sur les fichiers de configuration et leurs formats, consultez la section Configuration dans la documentation d'EMQX 4.0. Les valeurs que vous spécifiez sont ajoutées au fichier de configuration.
L'exemple suivant met à jour le etc/emqx.conf fichier.
"mergeConfigurationFiles": {
"etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},
Outre les fichiers de configuration pris en charge par EMQX, Greengrass prend en charge un fichier qui configure le plugin d'authentification Greengrass pour EMQX appelé. etc/plugins/aws_greengrass_emqx_auth.conf Il existe deux options prises en charge, auth_mode etuse_greengrass_managed_certificates. Pour utiliser un autre fournisseur d'authentification, définissez l'auth_modeoption sur l'une des options suivantes :
-
enabled— (Par défaut) Utilisez le fournisseur d'authentification et d'autorisation Greengrass.
-
bypass_on_failure— Utilisez le fournisseur d'authentification Greengrass, puis utilisez tous les fournisseurs d'authentification restants de la chaîne de fournisseurs EMQX si Greengrass refuse l'authentification ou l'autorisation.
-
bypass— Le fournisseur Greengrass est désactivé. L'authentification et l'autorisation sont ensuite gérées par la chaîne de fournisseurs EMQX.
Dans l'use_greengrass_managed_certificatesaffirmativetrue, cette option indique que Greengrass gère les certificats TLS du courtier. Sifalse, cela indique que vous fournissez les certificats via une autre source.
L'exemple suivant met à jour les valeurs par défaut du fichier etc/plugins/aws_greengrass_emqx_auth.conf de configuration.
"mergeConfigurationFiles": {
"etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
},
aws.greengrass.clientdevices.mqtt.EMQXvous permet de configurer des options sensibles à la sécurité. Il s'agit notamment des paramètres TLS, de l'authentification et des fournisseurs d'autorisation. La configuration recommandée est la configuration par défaut qui utilise l'authentification TLS mutuelle et le fournisseur Greengrass Client Device Auth.
replaceConfigurationFiles-
(Facultatif) Configurez cette option pour remplacer les fichiers de configuration EMQX spécifiés. Les valeurs que vous spécifiez remplacent l'intégralité du fichier de configuration existant. Vous ne pouvez pas spécifier le etc/emqx.conf fichier dans cette section. Vous devez utiliser mergeConfigurationFile pour modifieretc/emqx.conf.
Exemple : mise à jour de la fusion de configurations
L'exemple de configuration suivant indique de faire fonctionner le broker MQTT sur le port 443.
{
"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"
}
Fichier journal local
Ce composant utilise le fichier journal suivant.
- Linux
-
/greengrass/v2
- Windows
-
C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log
Pour consulter les journaux de ce composant
Licences
Sur les systèmes d'exploitation Windows, ce logiciel inclut du code distribué conformément aux termes du contrat de licence logiciel Microsoft - Microsoft Visual Studio Community 2022. En téléchargeant ce logiciel, vous acceptez les termes du contrat de licence de ce code.
Ce composant est publié dans le cadre du contrat de licence logicielle Greengrass Core.
Journal des modifications
Le tableau suivant décrit les modifications apportées à chaque version du composant.
- v2.x
-
|
Version
|
Modifications
|
|
2.0.1
|
Version mise à jour pour la version 2.5.0 d'authentification du périphérique client.
|
2.0.0 |
Cette version du broker MQTT 5 (EMQX) attend des paramètres de configuration différents de ceux de la version 1.x. Si vous utilisez une configuration autre que celle par défaut pour la version 1.x, vous devez mettre à jour la configuration du composant pour 2.x. Pour plus d’informations, consultez Configuration.
- Nouvelles fonctionnalités
-
- Mises à jour
-
|
- v1.x
-
|
Version
|
Modifications
|
|
1.2.3
|
- Corrections de bugs et améliorations
-
|
|
1.2.2
|
Version mise à jour pour la version 2.4.0 d'authentification du périphérique client.
|
|
1.2.1
|
- Corrections de bugs et améliorations
-
|
|
1.2.0
|
Ajoute le support pour les chaînes de certificats.
|
|
1.1.0
|
- Nouvelles fonctionnalités
-
- Corrections de bugs et améliorations
-
|
|
1.0.1
|
Résout un problème lors de la prise de contact TLS qui empêchait certains clients MQTT de se connecter.
|
|
1.0.0
|
Première version.
|
