Broker MQTT con Mosquitto y TLS: instalación y configuración en Linux y Windows · Index AMI

¿Qué es MQTT?

MQTT (Message Queuing Telemetry Transport) es un protocolo de mensajería ligero basado en el modelo publicación-suscripción, diseñado para redes con ancho de banda limitado y conexiones intermitentes — las condiciones típicas de un gateway 4G en campo. Un dispositivo publica mensajes en un tópico (ej. device/001/energy); otros dispositivos suscritos a ese tópico los reciben automáticamente. El broker actúa de intermediario: recibe, filtra y distribuye los mensajes sin que publicador y suscriptor necesiten conectarse directamente. MQTT opera sobre TCP/IP (puerto 1883 sin cifrado, 8883 con TLS) y es estándar ISO/IEC 20922.

Mosquitto es el broker MQTT de referencia de código abierto, mantenido por la Eclipse Foundation. Soporta MQTT 3.1, 3.1.1 y 5.0, pesa menos de 1 MB y se instala en menos de 5 minutos. Esta guía cubre la instalación en Windows y Linux, la generación de certificados TLS con OpenSSL y la configuración de autenticación por usuario y contraseña — los mismos pasos que necesitas para recibir datos de un gateway IoT de forma segura.

Cuándo usar Mosquitto

Instalaciones self-hosted donde tienes control total del servidor (VPS, servidor local, Raspberry Pi).
Entornos de desarrollo y pruebas antes de migrar a un broker cloud (AWS IoT Core, HiveMQ Cloud).
Despliegues con requisitos de privacidad estrictos donde los datos no pueden salir de tu red.
Proyectos de bajo presupuesto — Mosquitto es completamente gratuito y sin límite de conexiones.

Arquitectura de certificados TLS

Para MQTT sobre TLS (puerto 8883) necesitas tres archivos: un certificado de autoridad (CA) que firmas tú mismo, un certificado de servidor firmado por esa CA, y —opcionalmente— certificados de cliente para autenticación mutua (mTLS). Los gateways IoT soportan los tres modos.

Requisitos

Servidor con IP pública o nombre de dominio accesible desde el Index AMI (si es externo).
Puerto 8883 TCP abierto en el firewall del servidor.
OpenSSL instalado (viene incluido con Mosquitto en Windows; en Linux está disponible como paquete).

Paso 1 — Instalar Mosquitto

Linux (Ubuntu / Debian)

En Ubuntu 22.04 / Debian 12:

sudo apt update && sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto

Verifica que el servicio está activo:

systemctl status mosquitto
# ● mosquitto.service - Mosquitto MQTT Broker
#    Active: active (running)

Windows 10 / 11

Descarga el instalador oficial desde mosquitto.org/download (elige la versión Win64 .exe). Ejecuta como Administrador. El instalador incluye mosquitto.exe, mosquitto_passwd.exe y OpenSSL.

# Alternativa via winget
winget install EclipseFoundation.Mosquitto

Verifica que el servicio está instalado:

sc query mosquitto
# STATE : 4  RUNNING

El instalador registra Mosquitto como servicio de Windows (nombre: mosquitto). Puedes gestionarlo desde services.msc o PowerShell.

Paso 2 — Generar certificados TLS con OpenSSL

Los certificados son iguales en Linux y Windows — el proceso OpenSSL es idéntico. Genera tres archivos: CA, servidor y, opcionalmente, cliente.

Genera los certificados una sola vez y reutilízalos para todos los gateways que se conecten al mismo broker.

Linux (Ubuntu / Debian)

Desde terminal (Linux) — crea un directorio de trabajo:

mkdir ~/mosquitto-certs && cd ~/mosquitto-certs

# 1. Crea la CA (autoridad certificadora propia)
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
  -subj "/CN=MiCA-MQTT/O=MiOrganizacion/C=CO"

# 2. Crea el certificado del servidor
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=broker.midominio.com/O=MiOrganizacion/C=CO"
openssl x509 -req -days 3650 -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

# 3. (Opcional) Crea el certificado del cliente (para mTLS)
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/CN=Index AMI-001/O=MiOrganizacion/C=CO"
openssl x509 -req -days 3650 -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

Windows 10 / 11

Desde PowerShell o CMD como Administrador (OpenSSL incluido con Mosquitto en C:\Program Files\mosquitto\):

cd "C:\Program Files\mosquitto"
mkdir certs && cd certs

# 1. Crea la CA
.\openssl.exe genrsa -out ca.key 4096
.\openssl.exe req -new -x509 -days 3650 -key ca.key -out ca.crt `
  -subj "/CN=MiCA-MQTT/O=MiOrganizacion/C=CO"

# 2. Crea el certificado del servidor
.\openssl.exe genrsa -out server.key 2048
.\openssl.exe req -new -key server.key -out server.csr `
  -subj "/CN=broker.midominio.com/O=MiOrganizacion/C=CO"
.\openssl.exe x509 -req -days 3650 -in server.csr `
  -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

El CN del certificado del servidor debe coincidir con el hostname o IP que usarán los clientes para conectarse. Si usas IP directa, pon la IP en el CN. Si tienes dominio, pon el FQDN.

Paso 3 — Configurar mosquitto.conf

Linux (Ubuntu / Debian)

Edita o crea el archivo de configuración principal: /etc/mosquitto/conf.d/tls.conf

# Puerto estándar MQTT sobre TLS
listener 8883

# Certificados TLS
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

# Requiere certificado de cliente (mTLS) — pon false si solo quieres TLS sin mTLS
require_certificate false

# Deshabilita el listener no cifrado (recomendado en producción)
# listener 1883
# allow_anonymous false

# Autenticación por usuario y contraseña (ver Paso 5)
# password_file /etc/mosquitto/passwd

Windows 10 / 11

En Windows, el archivo de configuración está en: C:\Program Files\mosquitto\mosquitto.conf

Abre el puerto 8883 en el firewall:

sudo ufw allow 8883/tcp
sudo ufw reload

New-NetFirewallRule -DisplayName "Mosquitto MQTT TLS" `
  -Direction Inbound -Protocol TCP `
  -LocalPort 8883 -Action Allow

Paso 4 — Verificar el broker con mosquitto_sub y mosquitto_pub

Desde otro terminal (o desde el mismo servidor como prueba), suscríbete a un tópico de prueba:

Linux (Ubuntu / Debian)

# Terminal 1 — suscribirse
mosquitto_sub -h broker.midominio.com -p 8883 \
  --cafile ~/mosquitto-certs/ca.crt \
  -t "test/mensaje" -v

# Terminal 2 — publicar
mosquitto_pub -h broker.midominio.com -p 8883 \
  --cafile ~/mosquitto-certs/ca.crt \
  -t "test/mensaje" -m "Hola broker TLS"

Windows 10 / 11

En Windows, mosquitto_sub.exe y mosquitto_pub.exe están en C:\Program Files\mosquitto\:

cd "C:\Program Files\mosquitto"
.\mosquitto_sub.exe -h broker.midominio.com -p 8883 `
  --cafile "C:\Program Files\mosquitto\certs\ca.crt" `
  -t "test/mensaje" -v

.\mosquitto_pub.exe -h broker.midominio.com -p 8883 `
  --cafile "C:\Program Files\mosquitto\certs\ca.crt" `
  -t "test/mensaje" -m "Hola broker TLS"

El terminal 1 debe mostrar: test/mensaje Hola broker TLS — esto confirma que el broker TLS está operativo.

Paso 5 — Autenticación por usuario y contraseña (recomendado)

Crea un archivo de contraseñas para evitar conexiones anónimas. Cada Index AMI debe tener sus propias credenciales.

Linux (Ubuntu / Debian)

# Crea el archivo de contraseñas y añade un usuario
sudo mosquitto_passwd -c /etc/mosquitto/passwd gateway_user
# Te pedirá la contraseña — usa una fuerte y única por dispositivo

# Reinicia el broker para aplicar
sudo systemctl restart mosquitto

Windows 10 / 11

# En PowerShell como Administrador
cd "C:\Program Files\mosquitto"
.\mosquitto_passwd.exe -c "C:\Program Files\mosquitto\passwd" gateway_user
# Reinicia el servicio
Restart-Service -Name "mosquitto"

Añade estas líneas en mosquitto.conf para activar la autenticación:

allow_anonymous false
password_file /etc/mosquitto/passwd    # Linux
# password_file C:\Program Files\mosquitto\passwd    # Windows

Conectar el Index AMI al broker

Una vez que el broker está activo con TLS, configura los siguientes parámetros en el Index AMI (guía de configuración MQTT):

Host MQTT: IP pública o FQDN del servidor donde corre Mosquitto.
Puerto: 8883 (MQTT sobre TLS).
Transporte: MQTT sobre SSL.
Certificado CA: el archivo ca.crt generado en el Paso 2.
Certificado cliente y clave privada: client.crt y client.key si usas mTLS.
Usuario y contraseña: las credenciales creadas en el Paso 5.
Client ID: un identificador único por Index AMI (ej. gw-MED-NORTE-001).

Resolución de problemas

Síntoma	Causa probable	Solución
El cliente no conecta: Connection refused	Puerto 8883 cerrado o Mosquitto no arrancado	Verifica que el servicio está activo (systemctl status mosquitto) y que el puerto está abierto en el firewall
SSL handshake failed	El CN del certificado no coincide con el hostname	Regenera server.crt con el CN correcto (IP o FQDN exacto del servidor)
Connection lost / keepalive timeout	El Index AMI perdió la conexión y no reconecta	Verifica el Keepalive en el Index AMI (≥ 60 s) y que el broker no tiene max_keepalive demasiado bajo
No message received en subscriber	Tópico mal escrito o QoS diferente	Verifica que publisher y subscriber usan exactamente el mismo tópico (case-sensitive)
Authentication failed	Credenciales incorrectas o allow_anonymous true	Verifica usuario/contraseña y que allow_anonymous false está activo en mosquitto.conf

Próximos pasos

Con el broker activo, configura el Index AMI en la guía de MQTT. Para interpretar las métricas de señal LTE que aparecen en el Overview del Index AMI, consulta el artículo sobre señal LTE.