Agente MQTT 5 (EMQX)
El componente agente MQTT de EMQX (aws.greengrass.clientdevices.mqtt.EMQX) gestiona los mensajes MQTT entre los dispositivos de cliente y un dispositivo principal de Greengrass. Este componente proporciona una versión modificada del agente EMQX MQTT 5.0. Implemente el agente MQTT para usar las características de MQTT 5 en la comunicación entre los dispositivos de cliente y el dispositivo principal. Para más información sobre cómo elegir un agente MQTT, consulte Elección de un agente MQTT.
Este agente implementa el protocolo MQTT 5.0. Incluye compatibilidad con intervalos de expiración de sesiones y mensajes, propiedades de usuario, suscripciones compartidas, alias de temas y más. MQTT 5 es compatible con versiones anteriores de MQTT 3.1.1, por lo que si ejecuta el agente Moquette MQTT 3.1.1, puede reemplazarlo con el agente EMQX MQTT 5 y los dispositivos de cliente pueden continuar conectándose y funcionando normalmente.
Los dispositivos de cliente son dispositivos IoT locales que se conectan a un dispositivo principal de Greengrass para enviar mensajes MQTT y datos para su procesamiento. Para obtener más información, consulte Interacción con dispositivos IoT locales.
Versiones
Este componente tiene las siguientes versiones:
Tipo
Este componente es un componente genérico (aws.greengrass.generic). El núcleo de Greengrass ejecuta los scripts del ciclo de vida del componente.
Para obtener más información, consulte Tipos de componentes.
Sistema operativo
Este componente se puede instalar en los dispositivos principales que ejecutan los siguientes sistemas operativos:
Requisitos
Este componente tiene los siguientes requisitos:
-
El dispositivo principal debe poder aceptar conexiones en el puerto en el que opera el agente MQTT. Este componente ejecuta el agente MQTT en el puerto 8883 de forma predeterminada. O puede especificar un puerto diferente al configurar este componente.
Si especifica un puerto diferente y utiliza el componente de puente MQTT para retransmitir mensajes MQTT a otros intermediarios, debe utilizar el puente de MQTT versión 2.1.0 o posterior. Configúrelo para que use el puerto en el que opera el agente MQTT.
Si especifica un puerto diferente y utiliza el componente IP detector para administrar los puntos de conexión del agente MQTT, debe utilizar la versión 2.1.0 o posterior del detector IP. Configúrelo para que informe el puerto en el que opera el agente MQTT.
-
En los dispositivos principales de Linux, Docker se instala y configura en el dispositivo principal:
-
Versión 1.9.1 o posterior de Docker Engine instalada en el dispositivo principal de Greengrass. La versión 20.10 es la última versión cuyo funcionamiento se ha verificado con el software AWS IoT Greengrass Core. Debe instalar Docker directamente en el dispositivo principal antes de implementar componentes que ejecuten contenedores de Docker.
-
El daemon de Docker se inició y se ejecutó en el dispositivo principal antes de implementar este componente.
-
El usuario del sistema que ejecuta este componente debe tener permisos de administrador o raíz. Como alternativa, puede ejecutar este componente como usuario del sistema en el grupo docker y configurar la opción requiresPrivileges de este componente false para ejecutar el agente MQTT de EQMX sin privilegios.
-
Se admite la ejecución del componente agente MQTT de EMQX en una VPC.
-
No se admite el componente agente MQTT de EMQX en la plataforma armv7.
Dependencias
Cuando implementa un componente, AWS IoT Greengrass también implementa versiones compatibles de sus dependencias. Esto significa que debe cumplir los requisitos del componente y de todas sus dependencias para poder implementar el componente correctamente. En esta sección, se enumeran las dependencias de las versiones publicadas de este componente y las restricciones de las versiones semánticas que definen las versiones de los componentes para cada dependencia. También puede ver las dependencias de cada versión del componente en la consola de AWS IoT Greengrass. En la página de detalles del componente, busque la lista de Dependencias.
- 2.0.1
-
En la siguiente tabla, se muestran las dependencias de la versión 2.0.1 de este componente.
- 2.0.0
-
En la siguiente tabla, se muestran las dependencias de la versión 2.0.0 de este componente.
- 1.2.2 – 1.2.3
-
En la siguiente tabla, se muestran las dependencias de las versiones 1.2.2 a 1.2.3 de este componente.
- 1.2.0 and 1.2.1
-
En la siguiente tabla, se muestran las dependencias de las versiones 1.2.0 y 1.2.1 de este componente.
- 1.0.0 and 1.1.0
-
En la siguiente tabla, se muestran las dependencias de las versiones 1.0.0 y 1.1.0 de este componente.
Para obtener más información sobre las dependencias del componente, consulte la referencia de receta de componentes.
Configuración
- 2.0.0 - 2.0.1
-
Este componente ofrece los siguientes parámetros de configuración que puede personalizar cuando implemente el componente.
Si utiliza la versión 2 del componente agente MQTT 5 (EMQX), debe actualizar el archivo de configuración. Los archivos de configuración de la versión 1 no funcionan con la versión 2.
- emqxConfig
-
(Opcional) La configuración del agente EMQX MQTT que se va a utilizar. Puede configurar las opciones de configuración de EMQX en este componente.
Cuando se utiliza el agente EMQX, Greengrass utiliza una configuración predeterminada. Esta configuración se utiliza a menos que la modifique mediante este campo.
La modificación de los siguientes ajustes de configuración provoca el reinicio del componente agente EMQX. Se aplican otros cambios de configuración sin reiniciar el componente.
-
emqxConfig/cluster
-
emqxConfig/node
-
emqxConfig/rpc
aws.greengrass.clientdevices.mqtt.EMQX permite configurar opciones sensibles a la seguridad. Estas incluyen la configuración de TLS, la autenticación y los proveedores de autorización. Recomendamos la configuración predeterminada que utiliza la autenticación TLS mutua y el proveedor de autenticación de dispositivos de cliente Greengrass.
ejemplo Ejemplo: configuración predeterminada
El siguiente ejemplo muestra los valores predeterminados establecidos para el agente MQTT 5 (EMQX). Puede anular estos parámetros mediante el ajuste de configuración 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
-
(Opcional) Establece el proveedor de autorización del agente. Puede ser uno de los siguientes valores:
-
enabled: (predeterminado) utilice el proveedor de autenticación y autorización de Greengrass.
-
bypass_on_failure: utilice el proveedor de autenticación de Greengrass y, a continuación, utilice los demás proveedores de autenticación de la cadena de proveedores de EMQX si Greengrass deniega la autenticación o la autorización.
-
bypass: el proveedor de Greengrass está deshabilitado. La cadena de proveedores de EMQX gestiona la autenticación y la autorización.
requiresPrivilege-
(Opcional) En los dispositivos principales de Linux, puede especificar que se ejecute el agente de MQTT EMQX sin privilegios de administrador o raíz. Si establece esta opción en false, el usuario del sistema que ejecute este componente debe ser miembro del grupo docker.
Valor predeterminado: true
startupTimeoutSeconds-
(Opcional) El tiempo máximo en segundos para que se inicie el agente de MQTT EMQX. El estado del componente cambia a BROKEN si supera este tiempo de espera.
Valor predeterminado: 90
ipcTimeoutSeconds-
(Opcional) El tiempo máximo en segundos que tarda el componente en esperar a que el núcleo de Greengrass responda a las solicitudes de comunicación entre procesos (IPC). Aumente este número si este componente informa de errores de tiempo de espera al comprobar si un dispositivo de cliente está autorizado.
Valor predeterminado: 5
crtLogLevel-
(Opcional) El nivel de registro de la biblioteca AWS Common Runtime (CRT).
El valor predeterminado es el nivel de registro del agente de MQTT EMQX (log.level en emqx).
restartIdentifier-
(Opcional) Configure esta opción para reiniciar el agente de MQTT EMQX. Cuando este valor de configuración cambia, este componente reinicia el agente de MQTT. Puede utilizar esta opción para forzar la desconexión de los dispositivos de cliente.
dockerOptions-
(Opcional) Configure esta opción solo en los sistemas operativos Linux para agregar parámetros a la línea de comandos de Docker. Por ejemplo, para asignar puertos adicionales, utilice el parámetro -p de Docker:
"-p 1883:1883"
ejemplo Ejemplo: actualizar un archivo de configuración de la versión 1.x a la versión 2.x
El siguiente ejemplo muestra los cambios necesarios para actualizar un archivo de configuración de la versión 1.x a la versión 2.x.
El archivo de configuración de la versión 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"
}
}
El archivo de configuración equivalente para la versión 2:
{
"emqxConfig": {
"listeners": {
"ssl": {
"default": {
"bind": "8883",
"max_connections": "1024000",
"max_conn_rate": "500",
"handshake_timeout": "15s"
}
}
},
"log": {
"console": {
"enable": true,
"level": "warning"
}
}
},
"authMode": "enabled"
}
No hay ningún equivalente a la entrada listener.ssl.external.rate_limit de configuración. La opción use_greengrass_managed_certificates de configuración se ha eliminado.
ejemplo Ejemplo: establecer un puerto nuevo para el agente
El siguiente ejemplo cambia el puerto en el que opera el agente de MQTT del 8883 predeterminado al puerto 1234. Si utiliza Linux, incluya el campo dockerOptions.
{
"emqxConfig": {
"listeners": {
"ssl": {
"default": {
"bind": 1234
}
}
}
},
"dockerOptions": "-p 1234:1234"
}
ejemplo Ejemplo: ajustar el nivel de registro del agente de MQTT
El siguiente ejemplo cambia el nivel de registro del agente de MQTT a debug. Puede elegir entre los siguientes niveles de registro:
-
debug
-
info
-
notice
-
warning
-
error
-
critical
-
alert
-
emergency
El nivel de registro predeterminado es warning.
{
"emqxConfig": {
"log": {
"console": {
"level": "debug"
}
}
}
}
ejemplo Ejemplo: habilitar el panel de EMQX
El siguiente ejemplo habilita el panel de EMQX para que pueda monitorear y administrar su agente. Si utiliza Linux, incluya el campo dockerOptions.
{
"emqxConfig": {
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"dockerOptions": "-p 18083:18083"
}
- 1.0.0 - 1.2.2
-
Este componente ofrece los siguientes parámetros de configuración que puede personalizar cuando implemente el componente.
emqx-
(Opcional) La configuración del agente EMQX MQTT que se va a utilizar. Puede configurar un subconjunto de opciones de configuración de EMQX en este componente.
Este objeto contiene la siguiente información:
listener.ssl.external-
(Opcional) El puerto en el que opera el agente de MQTT.
Si especifica un puerto diferente y utiliza el componente de puente MQTT para retransmitir mensajes MQTT a otros intermediarios, debe utilizar el puente de MQTT versión 2.1.0 o posterior. Configúrelo para que use el puerto en el que opera el agente MQTT.
Si especifica un puerto diferente y utiliza el componente IP detector para administrar los puntos de conexión del agente MQTT, debe utilizar la versión 2.1.0 o posterior del detector IP. Configúrelo para que informe el puerto en el que opera el agente MQTT.
Valor predeterminado: 8883
listener.ssl.external.max_connections-
(Opcional) el número máximo de conexiones simultáneas que admite el agente MQTT.
Valor predeterminado: 1024000
listener.ssl.external.max_conn_rate-
(Opcional) El número máximo de conexiones nuevas por segundo que puede recibir el agente de MQTT.
Valor predeterminado: 500
listener.ssl.external.rate_limit-
(Opcional) El límite de ancho de banda para todas las conexiones al agente de MQTT. Especifique el ancho de banda y la duración de ese ancho de banda separados por una coma (,) en el siguiente formato: bandwidth,duration. Por ejemplo, puede especificar 50KB,5s para limitar el agente de MQTT a 50 kilobytes (KB) de datos cada 5 segundos.
listener.ssl.external.handshake_timeout-
(Opcional) El tiempo que espera el agente de MQTT para terminar de autenticar una nueva conexión.
Valor predeterminado: 15s
mqtt.max_packet_size-
(Opcional) El tamaño máximo de un mensaje MQTT.
Predeterminado: 268435455 (256 MB menos 1)
log.level-
(Opcional) El nivel de registro del agente de MQTT. Puede elegir entre las siguientes opciones:
-
debug
-
info
-
notice
-
warning
-
error
-
critical
-
alert
-
emergency
El nivel de registro predeterminado es warning.
requiresPrivilege-
(Opcional) En los dispositivos principales de Linux, puede especificar que se ejecute el agente de MQTT EMQX sin privilegios de administrador o raíz. Si establece esta opción en false, el usuario del sistema que ejecute este componente debe ser miembro del grupo docker.
Valor predeterminado: true
startupTimeoutSeconds-
(Opcional) El tiempo máximo en segundos para que se inicie el agente de MQTT EMQX. El estado del componente cambia a BROKEN si supera este tiempo de espera.
Valor predeterminado: 90
ipcTimeoutSeconds-
(Opcional) El tiempo máximo en segundos que tarda el componente en esperar a que el núcleo de Greengrass responda a las solicitudes de comunicación entre procesos (IPC). Aumente este número si este componente informa de errores de tiempo de espera al comprobar si un dispositivo de cliente está autorizado.
Valor predeterminado: 5
crtLogLevel-
(Opcional) El nivel de registro de la biblioteca AWS Common Runtime (CRT).
El valor predeterminado es el nivel de registro del agente de MQTT EMQX (log.level en emqx).
restartIdentifier-
(Opcional) Configure esta opción para reiniciar el agente de MQTT EMQX. Cuando este valor de configuración cambia, este componente reinicia el agente de MQTT. Puede utilizar esta opción para forzar la desconexión de los dispositivos de cliente.
dockerOptions-
(Opcional) Configure esta opción solo en los sistemas operativos Linux para agregar parámetros a la línea de comandos de Docker. Por ejemplo, para asignar puertos adicionales, utilice el parámetro -p de Docker:
"-p 1883:1883"
mergeConfigurationFiles-
(Opcional) Configure esta opción para agregar o anular los valores predeterminados de los archivos de configuración de EMQX especificados. Para obtener información sobre los archivos de configuración y sus formatos, consulte Configuración en la documentación de EMQX 4.0. Los valores que especifique se adjuntan al archivo de configuración.
El siguiente ejemplo actualiza el archivo etc/emqx.conf.
"mergeConfigurationFiles": {
"etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},
Además de los archivos de configuración compatibles con EMQX, Greengrass admite un archivo que configura el complemento de autenticación de Greengrass para EMQX llamado etc/plugins/aws_greengrass_emqx_auth.conf. Hay dos opciones compatibles: auth_mode y use_greengrass_managed_certificates. Para usar otro proveedor de autenticación, defina la opción auth_mode en una de las siguientes opciones:
-
enabled: (predeterminado) utilice el proveedor de autenticación y autorización de Greengrass.
-
bypass_on_failure: utilice el proveedor de autenticación de Greengrass y, a continuación, utilice los demás proveedores de autenticación de la cadena de proveedores de EMQX si Greengrass deniega la autenticación o la autorización.
-
bypass: el proveedor de Greengrass está deshabilitado. La cadena de proveedores de EMQX gestiona la autenticación y la autorización.
Si use_greengrass_managed_certificates es true, esta opción indica que Greengrass administra los certificados TLS del agente. Si false, indica que proporciona los certificados a través de otro origen.
En el siguiente ejemplo, se actualizan los valores predeterminados del archivo etc/plugins/aws_greengrass_emqx_auth.conf de configuración.
"mergeConfigurationFiles": {
"etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
},
aws.greengrass.clientdevices.mqtt.EMQX permite configurar opciones sensibles a la seguridad. Estas incluyen la configuración de TLS, la autenticación y los proveedores de autorización. La configuración recomendada es la configuración predeterminada que utiliza autenticación TLS mutua y el proveedor de autenticación de dispositivo de cliente de Greengrass.
replaceConfigurationFiles-
(Opcional) Configure esta opción para reemplazar los archivos de configuración de EMQX especificados. Los valores que especifique reemplazan todo el archivo de configuración existente. No puede especificar el archivo etc/emqx.conf en esta sección. Debe usar mergeConfigurationFile para modificar etc/emqx.conf.
ejemplo Ejemplo: actualización de la combinación de configuraciones
El siguiente ejemplo de configuración especifica el funcionamiento del agente de MQTT en el puerto 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"
}
Archivo de registro local
Este componente usa el siguiente archivo de registro.
- Linux
-
/greengrass/v2
- Windows
-
C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log
Visualización de los registros de este componente
Licencias
En los sistemas operativos Windows, este software incluye código distribuido según los términos de licencia del software de Microsoft: Microsoft Visual Studio Community 2022. Al descargar este software, acepta los términos de licencia del código.
Este conector se publica en el Contrato de Licencia de Software de Greengrass Core.
Registros de cambios
En la siguiente tabla, se describen los cambios en cada versión del componente.
- v2.x
-
|
Versión
|
Cambios
|
|
2.0.1
|
Versión actualizada para la versión 2.5.0 de autenticación de dispositivos de cliente.
|
2.0.0 |
Esta versión del agente MQTT 5 (EMQX) espera parámetros de configuración diferentes a los de la versión 1.x. Si utiliza una configuración no predeterminada para la versión 1.x, debe actualizar la configuración del componente para la versión 2.x. Para obtener más información, consulte Configuración.
- Nuevas características
-
- Actualizaciones
-
|
- v1.x
-
|
Versión
|
Cambios
|
|
1.2.3
|
- Mejoras y correcciones de errores
-
|
|
1.2.2
|
Versión actualizada para la versión 2.4.0 de autenticación de dispositivos de cliente.
|
|
1.2.1
|
- Mejoras y correcciones de errores
-
|
|
1.2.0
|
Se agregó compatibilidad con las cadenas de certificados.
|
|
1.1.0
|
- Nuevas características
-
- Mejoras y correcciones de errores
-
|
|
1.0.1
|
Corrige un problema durante el protocolo de enlace TLS que provocaba que algunos clientes MQTT no pudieran conectarse.
|
|
1.0.0
|
Versión inicial.
|
