> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md).
# External MQTT
Ligue o Kilo IoT Server ao seu próprio broker MQTT — Mosquitto, AWS IoT Core, HiveMQ — com autenticação TLS e encaminhamento de tópicos.
O External MQTT liga o Kilo IoT Server a um broker MQTT que já opera. A plataforma liga-se ao broker, subscreve os tópicos relevantes e consome mensagens no mesmo pipeline de encaminhamento que os dados do Cloud MQTT. Escolha esta opção quando o broker já fizer parte da sua infraestrutura — um cluster Mosquitto local, AWS IoT Core, uma implementação empresarial do HiveMQ ou um broker gerido pelo fornecedor partilhado entre sites.
## Quando o External MQTT é a escolha certa
* **Um broker existente já faz parte das operações.** Os dispositivos já publicam para ele; vários subscritores (historiadores, dashboards, plataformas de integração) já consomem dele. Adicionar a plataforma como mais um subscritor é operacionalmente mais simples do que reencaminhar publicadores.
* **Requisitos de conformidade ou residência de dados** especificam que a telemetria deve passar pelo seu próprio broker antes de chegar aos consumidores SaaS.
* **Arquiteturas híbridas** em que o processamento de edge local acontece antes de um subconjunto da telemetria ser encaminhado para a plataforma.
Para implementações sem um broker existente, [Cloud MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/cloud-mqtt.md) é o caminho de menor sobrecarga.
## Requisito de acessibilidade
O Kilo IoT Server liga-se ao seu broker, pelo que o broker tem de ser acessível a partir da Internet pública via DDNS, reencaminhamento de portas ou um IP público dedicado. Um broker acessível apenas numa VLAN privada não é alcançável pelo plano de controlo cloud da plataforma.
O padrão de produção é um IP público ou um nome de anfitrião DDNS para o broker, com regras de firewall a controlar que origens se podem ligar.
Para implementações de desenvolvimento ou piloto, um túnel de exposição como ngrok funciona para testes de curta duração — mas note que executar uma ferramenta de exposição não confirma, por si só, que o Kilo consiga alcançar o broker. Depois de guardar o conector, **publique uma mensagem de teste e confirme se Últimos dados recebidos atualiza** na página de detalhes do conector. Esta é a única forma de verificar a acessibilidade ponta a ponta.
## Opções de autenticação
O conector suporta quatro métodos de autenticação, selecionáveis na criação:
| Método | Quando usar | Campos de configuração |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anónimo** | Apenas brokers de desenvolvimento. **Não utilize para brokers expostos em produção** — qualquer pessoa na Internet que encontre o broker pode publicar ou subscrever. | Nenhum |
| **Básico** | Autenticação por nome de utilizador + palavra-passe. A configuração mais comum para implementações de produção em que o TLS protege a credencial em trânsito. | Nome de utilizador, Palavra-passe |
| **Certificado** | Autenticação mútua TLS usando certificados de cliente. Máxima garantia; padrão para implementações regulamentadas. | Ficheiro de certificado da CA, ficheiro de certificado do cliente, ficheiro de chave privada (carregados como ficheiros; não cole conteúdo PEM) |
| **Token JWT** | Autenticação baseada em token compatível com brokers que validam JWTs (por exemplo, AWS IoT Core com autorizadores personalizados ou outros brokers com plugins JWT). | Token |
No método de autenticação por certificado, os três ficheiros carregados formam o lado do cliente de uma troca mTLS; o broker tem de estar configurado para confiar na CA e validar o certificado do cliente contra ela. A Chave Privada tem de estar não encriptada no momento do carregamento.
## Provisionamento do conector
1. Navegue para **Conectores** na barra lateral.
2. Clica em **Adicionar conector**.
3. Seleciona **External MQTT** a partir do **Tipo de conector** menu suspenso.
4. Preencha:
| Campo | Obrigatório | Detalhes |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Nome** | Sim | Etiqueta operacional, p. ex. `Mosquitto da Fábrica 3` ou `Cluster de Brokers da América do Norte`. |
| **URL do broker** | Sim | URL completa com esquema e porta. Exemplos: `mqtts://broker.facility.example.com:8883`, `ssl://broker.example.com:8883`. |
5. Escolha o método de autenticação e preencha os respetivos campos.
6. Clica em **Adicione**.
O conector aparece na tabela de conectores. Clique na página de detalhes para encontrar o **Últimos dados recebidos** indicador.
## Passo de verificação
A acessibilidade ponta a ponta só é confirmada por uma publicação real que chegue à plataforma. Depois de guardar o conector:
1. Publique uma mensagem de teste no seu broker em qualquer tópico a que o conector se subscreva.
2. Abra a página de detalhes do conector no Kilo.
3. Confirme **Últimos dados recebidos** atualizações em poucos segundos.
Um teste simples de uma única execução a partir de um anfitrião que consiga alcançar o broker:
```bash
mosquitto_pub \\
-h broker.facility.example.com -p 8883 \\
--cafile /path/to/ca.crt \\
-u {username} -P {password} \\
-t "test/connectivity" \\
-m '{"hello":"world"}'
```
(Substitua o esquema/porta e as credenciais pelo método de autenticação do seu broker.)
Se **Últimos dados recebidos** não atualizar após uma publicação local bem-sucedida, consulte [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md). As causas mais comuns são regras de firewall entre a saída da plataforma e o seu broker, desencontros de listas de IP permitidos, sessões de túnel expiradas ao usar ngrok para testes ou configuração TLS incorreta do lado do broker.
## Implementação de referência Mosquitto autoalojada
Para implementações que necessitem de uma referência rápida para configurar um broker Mosquitto autoalojado para testes ou fins de piloto, o Docker Compose mínimo é:
```yaml
services:
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
restart: unless-stopped
ports:
- "1883:1883"
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
```
`mosquitto.conf`:
```
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
log_dest stdout
```
Duas notas operacionais:
* **`log_dest stdout`** é preferível ao registo baseado em ficheiros em implementações contentorizadas. Diretórios de registo montados por bind frequentemente falham sob SELinux/AppArmor ou devido a incompatibilidades de propriedade; o stdout do contentor é recolhido pelo driver de registo do Docker.
* **Conflitos na porta 1883.** Em infraestrutura de desenvolvimento ou partilhada, a porta 1883 pode já estar em uso (por exemplo, um kubectl port-forward, outro broker local). `ss -tlnp \\| grep 1883` identifica o processo que faz o bind. Remapeie a porta do lado do anfitrião (por exemplo, `"1885:1883"`) e encaminhe em vez disso a nova porta do anfitrião — a porta interna do contentor pode permanecer 1883 para publicadores na rede.
Para terminação TLS, é necessário um reverse-proxy separado ou a configuração TLS nativa do Mosquitto (fora do âmbito aqui — consulte a documentação do Mosquitto) antes da exposição pública.
## Limites
Os conectores External MQTT estão limitados a 10 por organização. Para implementações que necessitem de integrações adicionais com brokers para além deste limite, contacte a equipa de engenharia da plataforma durante o planeamento da implementação.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
