MQTT5 corretor (sEMQX) - AWS IoT Greengrass

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

MQTT5 corretor (sEMQX)

O componente EMQX MQTT broker (aws.greengrass.clientdevices.mqtt.EMQX) manipula MQTT mensagens entre dispositivos cliente e um dispositivo principal do Greengrass. Esse componente fornece uma versão modificada do broker EMQX MQTT 5.0. Implante esse MQTT agente para usar MQTT 5 recursos na comunicação entre dispositivos cliente e um dispositivo principal. Para obter mais informações sobre como escolher um MQTT corretor, consulteEscolher um agente MQTT.

Esse corretor implementa o protocolo MQTT 5.0. Ele inclui suporte para intervalos de expiração de sessões e mensagens, propriedades do usuário, assinaturas compartilhadas, aliases de tópicos e muito mais. MQTTO 5 é compatível com versões anteriores do MQTT 3.1.1, portanto, se você executar o broker Moquette MQTT 3.1.1, poderá substituí-lo pelo corretor EMQX MQTT 5, e os dispositivos cliente poderão continuar se conectando e operando normalmente.

nota

Os dispositivos cliente são dispositivos IoT locais que se conectam a um dispositivo principal do Greengrass para enviar MQTT mensagens e dados para processamento. Para obter mais informações, consulte Interagir com dispositivos de IoT locais.

Versões

Esse componente tem as seguintes versões:

  • 2.0.x

  • 1.2.x

  • 1.1.x

  • 1.0.x

Tipo

Esse é um componente genérico (aws.greengrass.generic). O núcleo do Greengrass executa os scripts do ciclo de vida do componente.

Para obter mais informações, consulte Tipos de componente.

Sistema operacional

Esse componente pode ser instalado em dispositivos principais que executam os seguintes sistemas operacionais:

  • Linux

  • Windows

Requisitos

Esse componente tem os seguintes requisitos:

  • O dispositivo principal deve ser capaz de aceitar conexões na porta em que o MQTT agente opera. Esse componente executa o MQTT broker na porta 8883 por padrão. Você pode especificar uma porta diferente ao configurar esse componente.

    Se você especificar uma porta diferente e usar o componente MQTT bridge para retransmitir MQTT mensagens para outros brokers, deverá usar o MQTT bridge v2.1.0 ou posterior. Configure-o para usar a porta em que o MQTT agente opera.

    Se você especificar uma porta diferente e usar o componente detector de IP para gerenciar endpoints do MQTT broker, deverá usar o detector de IP v2.1.0 ou posterior. Configure-o para relatar a porta em que o MQTT agente opera.

  • Nos dispositivos principais do Linux, o Docker é instalado e configurado no dispositivo principal:

    • Docker Engine 1.9.1 ou versão posterior instalado no dispositivo principal do Greengrass. A versão 20.10 é a versão mais recente verificada para funcionar com o software AWS IoT Greengrass Core. É preciso instalar o Docker diretamente no dispositivo principal antes de implantar componentes que executam contêineres do Docker.

    • O daemon do Docker foi iniciado e executado no dispositivo principal antes de você implantar esse componente.

    • O usuário do sistema que executa esse componente deve ter permissões de root ou administrador. Como alternativa, você pode executar esse componente como usuário do sistema no docker grupo e configurar a requiresPrivileges opção desse componente false para executar o EQMX MQTT broker sem privilégios.

  • O componente EMQX MQTT broker tem suporte para ser executado em umVPC.

  • O componente de EMQX MQTT corretor não é suportado na armv7 plataforma.

Dependências

Quando você implanta um componente, AWS IoT Greengrass também implanta versões compatíveis de suas dependências. Isso significa que é preciso atender aos requisitos do componente e de todas as dependências dele para implantá-lo com êxito. Nesta seção, há uma lista de todas as dependências das versões lançadas desse componente e as restrições de versão semântica que definem as versões dos componentes para cada dependência. Também é possível visualizar as dependências de cada versão do componente no console do AWS IoT Greengrass. Na página de detalhes do componente, procure a lista de dependências.

2.0.2

A seguinte tabela lista as dependências da versão 2.0.2 desse componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.6.0 Flexível
2.0.1

A tabela a seguir lista as dependências da versão 2.0.1 deste componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.6.0 Rígido
2.0.0

A tabela a seguir lista as dependências da versão 2.0.0 desse componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.5.0 Rígido
1.2.2 – 1.2.3

A tabela a seguir lista as dependências das versões 1.2.2 a 1.2.3 desse componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.5.0 Rígido
1.2.0 and 1.2.1

A tabela a seguir lista as dependências das versões 1.2.0 e 1.2.1 desse componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.4.0 Rígido
1.0.0 and 1.1.0

A tabela a seguir lista as dependências das versões 1.0.0 e 1.1.0 desse componente.

Dependência Versões compatíveis Tipo de dependência
Autenticação do dispositivo cliente >=2.2.0 <2.3.0 Rígido

Para obter mais informações sobre as dependências dos componentes, consulte referência de fórmula do componente.

Configuração

2.0.0 - 2.0.1

Esse componente fornece os seguintes parâmetros de configuração que podem ser personalizados ao implantar o componente.

Importante

Se você usar a versão 2 do componente MQTT 5 broker (EMQX), deverá atualizar seu arquivo de configuração. Os arquivos de configuração da versão 1 não funcionam com a versão 2.

emqxConfig

(Opcional) A configuração do EMQXMQTTagente a ser usada. Você pode definir EMQX as opções de configuração nesse componente.

Quando você usa o EMQX broker, o Greengrass usa uma configuração padrão. Essa configuração é usada, a menos que você a modifique usando esse campo.

A modificação das seguintes configurações faz com que o componente EMQX broker seja reiniciado. Outras alterações de configuração se aplicam sem reiniciar o componente.

  • emqxConfig/cluster

  • emqxConfig/node

  • emqxConfig/rpc

nota

aws.greengrass.clientdevices.mqtt.EMQX permite configurar opções sensíveis à segurança. Isso inclui TLS configurações, autenticação e provedores de autorização. Recomendamos a configuração padrão que usa TLS autenticação mútua e o provedor de autenticação de dispositivos do cliente Greengrass.

exemplo Exemplo: configuração padrão

O exemplo a seguir mostra os padrões definidos para o broker MQTT 5 (EMQX). Você pode substituir essas configurações usando a configuração 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) Define o provedor de autorização para o agente. Pode ser um dos valores a seguir:

  • enabled (padrão): usar o provedor de autenticação e autorização do Greengrass.

  • bypass_on_failure— Use o provedor de autenticação Greengrass e, em seguida, use qualquer provedor de autenticação restante na cadeia de provedores se o EMQX Greengrass negar a autenticação ou a autorização.

  • bypass: o provedor Greengrass está desativado. A autenticação e a autorização são gerenciadas pela cadeia EMQX de fornecedores.

requiresPrivilege

(Opcional) Nos dispositivos principais do Linux, você pode especificar a execução do EMQX MQTT broker sem privilégios de root ou administrador. Se você definir essa opção como false, o usuário do sistema que executa esse componente deverá ser membro do grupo docker.

Padrão: true

startupTimeoutSeconds

(Opcional) O tempo máximo em segundos para o EMQX MQTT corretor começar. O estado do componente muda para BROKEN se ele exceder esse tempo limite.

Padrão: 90

ipcTimeoutSeconds

(Opcional) O tempo máximo em segundos para o componente esperar que o núcleo do Greengrass responda às solicitações de comunicação entre processos (). IPC Aumente esse número se esse componente relatar erros de tempo limite ao verificar se um dispositivo cliente está autorizado.

Padrão: 5

crtLogLevel

(Opcional) O nível de registro da biblioteca AWS Common Runtime (CRT).

O padrão é o nível de log do EMQX MQTT broker (log.levelinemqx).

restartIdentifier

(Opcional) Configure essa opção para reiniciar o EMQX MQTT broker. Quando esse valor de configuração é alterado, esse componente reinicia o MQTT broker. Você pode usar essa opção para forçar a desconexão dos dispositivos cliente.

dockerOptions

(Opcional) Configure essa opção somente em sistemas operacionais Linux para adicionar parâmetros à linha de comando do Docker. Por exemplo, para mapear portas adicionais, use o parâmetro -p do Docker:

"-p 1883:1883"
exemplo Exemplo: atualização de um arquivo de configuração v1.x para v2.x

O exemplo a seguir mostra as alterações necessárias para atualizar um arquivo de configuração v1.x para a versão 2.x.

O arquivo de configuração da versão 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" } }

O arquivo de configuração equivalente para 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" }

Não há equivalente à entrada de configuração listener.ssl.external.rate_limit. A opção de configuração use_greengrass_managed_certificates foi removida.

exemplo Exemplo: definir uma nova porta para o agente

O exemplo a seguir altera a porta em que o MQTT broker opera da 8883 padrão para a porta 1234. Se você estiver usando Linux, inclua o campo dockerOptions.

{ "emqxConfig": { "listeners": { "ssl": { "default": { "bind": 1234 } } } }, "dockerOptions": "-p 1234:1234" }
exemplo Exemplo: ajuste o nível de registro do MQTT corretor

O exemplo a seguir altera o nível de registro do MQTT corretor paradebug. Você pode escolher entre os seguintes níveis de log:

  • debug

  • info

  • notice

  • warning

  • error

  • critical

  • alert

  • emergency

O nível padrão do log é warning.

{ "emqxConfig": { "log": { "console": { "level": "debug" } } } }
exemplo Exemplo: Ativar o EMQX painel

O exemplo a seguir ativa o EMQX painel para que você possa monitorar e gerenciar seu corretor. Se você estiver usando Linux, inclua o campo dockerOptions.

{ "emqxConfig": { "dashboard": { "listeners": { "http": { "bind": 18083 } } } }, "dockerOptions": "-p 18083:18083" }
1.0.0 - 1.2.2

Esse componente fornece os seguintes parâmetros de configuração que podem ser personalizados ao implantar o componente.

emqx

(Opcional) A configuração do EMQXMQTTagente a ser usada. Você pode configurar um subconjunto de opções de EMQX configuração nesse componente.

Esse objeto contém as informações a seguir:

listener.ssl.external

(Opcional) A porta em que o MQTT corretor opera.

nota

Se você especificar uma porta diferente e usar o componente MQTT bridge para retransmitir MQTT mensagens para outros brokers, deverá usar o MQTT bridge v2.1.0 ou posterior. Configure-o para usar a porta em que o MQTT agente opera.

Se você especificar uma porta diferente e usar o componente detector de IP para gerenciar endpoints do MQTT broker, deverá usar o detector de IP v2.1.0 ou posterior. Configure-o para relatar a porta em que o MQTT agente opera.

Padrão: 8883

listener.ssl.external.max_connections

(Opcional) O número máximo de conexões simultâneas que o MQTT broker suporta.

Padrão: 1024000

listener.ssl.external.max_conn_rate

(Opcional) O número máximo de novas conexões por segundo que o MQTT agente pode receber.

Padrão: 500

listener.ssl.external.rate_limit

(Opcional) O limite de largura de banda para todas as conexões com o MQTT broker. Especifique a largura de banda e a duração dessa largura de banda separadas por uma vírgula (,) no seguinte formato:. bandwidth,duration Por exemplo, você pode especificar 50KB,5s para limitar o MQTT agente a 50 kilobytes (KB) de dados a cada 5 segundos.

listener.ssl.external.handshake_timeout

(Opcional) A quantidade de tempo que o MQTT corretor espera para concluir a autenticação de uma nova conexão.

Padrão: 15s

mqtt.max_packet_size

(Opcional) O tamanho máximo de uma MQTT mensagem.

Padrão: 268435455 (256 MB menos 1)

log.level

(Opcional) O nível de registro do MQTT corretor. Escolha uma das seguintes opções:

  • debug

  • info

  • notice

  • warning

  • error

  • critical

  • alert

  • emergency

O nível padrão do log é warning.

requiresPrivilege

(Opcional) Nos dispositivos principais do Linux, você pode especificar a execução do EMQX MQTT broker sem privilégios de root ou administrador. Se você definir essa opção como false, o usuário do sistema que executa esse componente deverá ser membro do grupo docker.

Padrão: true

startupTimeoutSeconds

(Opcional) O tempo máximo em segundos para o EMQX MQTT corretor começar. O estado do componente muda para BROKEN se ele exceder esse tempo limite.

Padrão: 90

ipcTimeoutSeconds

(Opcional) O tempo máximo em segundos para o componente esperar que o núcleo do Greengrass responda às solicitações de comunicação entre processos (). IPC Aumente esse número se esse componente relatar erros de tempo limite ao verificar se um dispositivo cliente está autorizado.

Padrão: 5

crtLogLevel

(Opcional) O nível de registro da biblioteca AWS Common Runtime (CRT).

O padrão é o nível de log do EMQX MQTT broker (log.levelinemqx).

restartIdentifier

(Opcional) Configure essa opção para reiniciar o EMQX MQTT broker. Quando esse valor de configuração é alterado, esse componente reinicia o MQTT broker. Você pode usar essa opção para forçar a desconexão dos dispositivos cliente.

dockerOptions

(Opcional) Configure essa opção somente em sistemas operacionais Linux para adicionar parâmetros à linha de comando do Docker. Por exemplo, para mapear portas adicionais, use o parâmetro -p do Docker:

"-p 1883:1883"
mergeConfigurationFiles

(Opcional) Configure essa opção para adicionar ou substituir os padrões nos arquivos de configuração EMQX especificados. Para obter informações sobre os arquivos de configuração e seus formatos, consulte Configuração na documentação EMQX 4.0. Os valores que você especifica são anexados ao arquivo de configuração.

O exemplo a seguir atualiza o arquivo etc/emqx.conf.

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

Além dos arquivos de configuração suportados peloEMQX, o Greengrass suporta um arquivo que configura o plug-in de autenticação do Greengrass para call. EMQX etc/plugins/aws_greengrass_emqx_auth.conf Duas opções são aceitas: auth_mode e use_greengrass_managed_certificates. Para usar outro provedor de autenticação, defina a opção auth_mode de uma das seguintes maneiras:

  • enabled (padrão): usar o provedor de autenticação e autorização do Greengrass.

  • bypass_on_failure— Use o provedor de autenticação Greengrass e, em seguida, use qualquer provedor de autenticação restante na cadeia de provedores se o EMQX Greengrass negar a autenticação ou a autorização.

  • bypass: o provedor Greengrass está desativado. A autenticação e a autorização são então tratadas pela cadeia EMQX de fornecedores.

Se use_greengrass_managed_certificates fortrue, essa opção indica que o Greengrass gerencia os certificados do brokerTLS. Se for false, isso indica que você fornece os certificados por meio de outra fonte.

O exemplo a seguir atualiza os padrões no arquivo de configuração 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" },
nota

aws.greengrass.clientdevices.mqtt.EMQX permite configurar opções sensíveis à segurança. Isso inclui TLS configurações, autenticação e provedores de autorização. A configuração recomendada é a configuração padrão que usa TLS autenticação mútua e o provedor Greengrass Client Device Auth.

replaceConfigurationFiles

(Opcional) Configure essa opção para substituir os arquivos de EMQX configuração especificados. Os valores que você especifica substituem todo o arquivo de configuração existente. Não é possível especificar o arquivo etc/emqx.conf nessa seção. Você deve usar mergeConfigurationFile para modificar etc/emqx.conf.

exemplo Exemplo: atualização da mesclagem de configuração

O exemplo de configuração a seguir especifica a operação do MQTT broker na porta 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" }

Arquivo de log local

Esse componente usa o arquivo de log abaixo.

Linux
/greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
Windows
C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log
Para exibir os logs desse componente
  • Execute o comando a seguir no dispositivo principal para visualizar o arquivo de log desse componente em tempo real. Substitua /greengrass/v2 ou C:\greengrass\v2 pelo caminho para a pasta AWS IoT Greengrass raiz.

    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

Licenças

Nos sistemas operacionais Windows, esse software inclui código distribuído de acordo com os Termos de Licença de Software da Microsoft - Microsoft Visual Studio Community 2022. Ao baixar esse software, você concorda com os termos da licença desse código.

Esse componente é liberado de acordo com o Contrato de licença de software Greengrass Core.

Changelog

A tabela a seguir descreve as alterações em cada versão do componente.

v2.x

Versão

Alterações

2.0.2

Correções de bugs e melhorias
  • Corrige um problema em que EMQX é inicializado antes que o componente de autenticação do dispositivo cliente esteja pronto.

2.0.1

Versão atualizada para autenticação de dispositivo cliente versão 2.5.0.

2.0.0

Essa versão do MQTT 5 broker (EMQX) espera parâmetros de configuração diferentes da versão 1.x. Se você usar uma configuração não padrão para a versão 1.x, deverá atualizar a configuração do componente para 2.x. Para obter mais informações, consulte Configuração.

Novos recursos
  • Atualiza o MQTT corretor para EMQX 5.1.1.

  • Permite alterações na configuração do agente sem reiniciar o componente.

Atualizações
  • Adiciona um novo campo de configuração emqxConfig que substitui os campos de configuração emqx, mergeConfigurationFiles e replaceConfigurationFiles.

v1.x

Versão

Alterações

1.2.3

Correções de bugs e melhorias
  • Corrige um problema em que os clientes não conseguiam interagir EMQX após a autenticação anterior, desconectando e reautenticando o cliente.

1.2.2

Versão atualizada para autenticação de dispositivo cliente versão 2.4.0.

1.2.1

Correções de bugs e melhorias
  • Corrige um problema em que o componente não inicializa no Windows se o Visual C++ Redistributable ainda não estiver presente.

  • Atualizações EMQX para a versão 4.4.14.

1.2.0

Adiciona suporte para cadeias de certificados.

1.1.0

Novos recursos
  • Adiciona suporte para EMQX configurações, incluindo opções de corretor e plug-ins.

Correções de bugs e melhorias
  • Atualizações EMQX para a versão 4.4.9.

1.0.1

Corrige um problema durante o TLS handshake que faz com que alguns MQTT clientes não consigam se conectar.

1.0.0

Versão inicial.