Checklist de pruebas de un broker MQTT: 25 comprobaciones antes de producción

Antes de que un broker MQTT reciba dispositivos reales, recorre este checklist de pruebas de un broker MQTT: 25 comprobaciones concretas, cada una con un comando y el resultado esperado. Cubre conectividad, TLS, autenticación, ACL, semántica de mensajes, resiliencia y capacidad: las áreas donde realmente empiezan los incidentes en producción.

Todos los ejemplos usan los clientes de línea de comandos de Mosquitto (mosquitto_pub, mosquitto_sub) y broker.connectmq.com. Sustituye el host, los puertos y las credenciales por los de tu propio broker. Salvo que se indique lo contrario, los clientes hablan MQTT 3.1.1; añade -V mqttv5 para probar el comportamiento de MQTT 5.

export HOST=broker.connectmq.com
export T=testmqtt/checklist-$RANDOM     # prefijo de topic único para esta ejecución
export AUTH="-u $MQTT_USER -P $MQTT_PASS"
export TLS="-p 8883 --capath /etc/ssl/certs"

Conectividad (comprobaciones 1–5)

1. El DNS resuelve a la dirección esperada. dig +short $HOST devuelve las IP que esperas desde todas las redes que usan tus clientes (oficina, VPC en la nube, APN móvil).

2. Todos los puertos de los listeners son accesibles. Espera succeeded (u open) en cada puerto que quieras exponer, y un fallo en los que no:

for p in 1883 8883 8083 8084; do nc -zv -w 3 $HOST $p; done

3. Un cliente recibe un CONNACK. mosquitto_pub -h $HOST -t $T/ping -m hi -d imprime Client … received CONNACK (0). Cualquier otra cosa, o que se quede colgado, indica un problema de firewall, proxy o listener.

4. El endpoint WebSocket hace el upgrade. Los navegadores necesitan el puerto 8084 con la ruta /mqtt. El handshake debe responder HTTP/1.1 101 Switching Protocols:

curl -si --http1.1 -m 5 https://$HOST:8084/mqtt \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Protocol: mqtt" \
  -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" | head -1

Después conéctate desde el cliente MQTT online para confirmar que un navegador real también funciona.

5. El tiempo de conexión está dentro del presupuesto. time mosquitto_pub -h $HOST $TLS $AUTH -t $T/ping -m hi por TLS desde la región de tus dispositivos. Define un presupuesto (por ejemplo 1–2 segundos en red móvil) y da la comprobación por fallida si lo superas.

TLS y autenticación (comprobaciones 6–11)

6. La cadena de certificados y el hostname se verifican. Espera Verify return code: 0 (ok) y una fecha de caducidad a meses vista:

openssl s_client -connect $HOST:8883 -servername $HOST -verify_return_error </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -enddate

Un fallo aquí es lo que los dispositivos reportan después como certificate verify failed. Probar una conexión TLS de MQTT cubre cada variante.

7. El texto plano está desactivado donde debe estarlo. Si los clientes de producción deben usar TLS, el puerto 1883 de tu broker de producción debe rechazar conexiones (la comprobación 2 debe fallar para 1883).

8. Se rechazan los clientes anónimos. Sin credenciales, espera Connection error: Connection Refused: not authorised.

mosquitto_pub -h $HOST $TLS -t $T/anon -m x

9. Se rechazan las contraseñas erróneas. Con una contraseña incorrecta, espera Connection Refused: bad user name or password. (en MQTT 5: reason code 0x86). Consulta cualquier otro código con la herramienta de reason codes MQTT.

mosquitto_pub -h $HOST $TLS -u "$MQTT_USER" -P wrong-password -t $T/auth -m x

10. Las ACL bloquean los topics ajenos. Inicia sesión como usuario de un dispositivo y publica fuera de su espacio de nombres. Con MQTT 3.1.1 el broker descarta el mensaje en silencio, así que verifica con un suscriptor privilegiado que no llega nada. Con MQTT 5 y QoS 1 el PUBACK lleva el rechazo: la salida de depuración muestra RC:135 (0x87 Not authorized):

mosquitto_pub -h $HOST $TLS $AUTH -V mqttv5 -q 1 -d -t other-tenant/secret -m x

11. Los usuarios de dispositivos no pueden suscribirse a #. mosquitto_sub -h $HOST $TLS $AUTH -t '#' -C 1 -W 5 debería imprimir All subscription requests were denied. Consulta cómo probar los permisos ACL de MQTT para una prueba completa de la matriz de ACL.

Semántica de mensajes (comprobaciones 12–18)

12. El ciclo publish/subscribe funciona. Suscríbete, publica un token único y recíbelo antes de un timeout. El script de smoke test de un minuto hace exactamente esto con un código de salida de éxito o fallo.

13. QoS 1 recibe confirmación. mosquitto_pub -h $HOST -q 1 -d -t $T/qos -m x muestra received PUBACK. Con -q 2, espera PUBREC y PUBCOMP.

14. Los mensajes retenidos se guardan y se borran.

mosquitto_pub -h $HOST -t $T/retained -m on -r -q 1
mosquitto_sub -h $HOST -t $T/retained -C 1 -W 5 -v   # imprime el valor retenido
mosquitto_pub -h $HOST -t $T/retained -r -n          # un payload retenido vacío lo borra
mosquitto_sub -h $HOST -t $T/retained -C 1 -W 5 -v   # timeout: no queda nada retenido

15. El Last Will se publica en una desconexión no limpia.

mosquitto_sub -h $HOST -t $T/status -v &
mosquitto_sub -h $HOST -i lwt-check -k 5 -t $T/none \
  --will-topic $T/status --will-payload offline &
sleep 2; kill -9 $!                                   # caída simulada

El primer suscriptor imprime …/status offline. Un DISCONNECT limpio no debe dispararlo.

16. Las sesiones persistentes encolan los mensajes offline. Conéctate con un client ID fijo y -c (clean session desactivado), detén el cliente, publica con QoS 1 y vuelve a conectar con el mismo comando: llega el mensaje encolado.

mosquitto_sub -h $HOST -i queue-check -c -q 1 -t $T/queue -W 3   # crea la sesión
mosquitto_pub -h $HOST -q 1 -t $T/queue -m while-offline
mosquitto_sub -h $HOST -i queue-check -c -q 1 -t $T/queue -C 1 -W 5

17. Los client ID duplicados se comportan como esperas. Arranca dos clientes con el mismo -i; el broker desconecta al primero. Asegúrate de que cada dispositivo genere un ID único (el generador de client ID ayuda) o verás bucles de reconexión interminables.

18. Conoces el tamaño máximo de mensaje. Publica un payload justo por encima de tu mensaje real más grande y confirma cómo se comporta el broker. Probar payloads MQTT grandes incluye un script de barrido de tamaños.

Resiliencia (comprobaciones 19–22)

19. Los clientes se reconectan tras reiniciar el broker. En staging, reinicia el broker (docker restart mosquitto o systemctl restart mosquitto) y confirma que cada tipo de cliente se reconecta, se vuelve a suscribir y sigue publicando sin intervención manual.

20. Se detectan las conexiones muertas. Descarta en silencio el tráfico hacia el broker (sudo iptables -A OUTPUT -p tcp --dport 8883 -j DROP) y verifica que el cliente lo detecta en aproximadamente 1,5 × su intervalo de keep-alive; después elimina la regla. Chaos testing en MQTT muestra cómo automatizarlo con tc netem y Toxiproxy.

21. Las reconexiones usan backoff con jitter. Tras un reinicio, los intentos de conexión deberían repartirse a lo largo de varios segundos en lugar de llegar en un único pico. Revisa los logs del cliente o la gráfica de tasa de conexiones del broker.

22. El failover funciona, si usas un clúster. Detén un nodo y confirma que los clientes pasan a otro, que las sesiones sobreviven según lo diseñado y que no se pierde estado retenido.

Capacidad y operación (comprobaciones 23–25)

23. El broker aguanta el doble del pico esperado. Ejecuta una prueba de carga con tu tamaño de payload, QoS y estructura de topics reales (consulta pruebas de carga de brokers MQTT) y registra la latencia p99 y la tasa de errores.

24. Las métricas son visibles. Clientes conectados, tasas de mensajes y mensajes descartados aparecen en un dashboard. En Mosquitto (si está permitido): mosquitto_sub -h $HOST $AUTH -t '$SYS/broker/clients/connected' -C 1 -v.

25. Las alertas se disparan de verdad. Provoca una a propósito: detén un cliente de prueba que debería estar siempre online, o apunta una comprobación a un certificado a punto de caducar, y confirma que la alerta llega a una persona.

Convertir el checklist en un script

Empieza automatizando las comprobaciones rápidas y ejecútalas en CI y después de cada cambio en el broker; deja las lentas en el checklist de cada release.

Ejecuta las comprobaciones 3, 12 y 14 en tu navegador

Un broker que supera estas 25 comprobaciones ha demostrado lo que importa el primer día: los clientes llegan a él de forma segura, solo entran los clientes correctos, los mensajes se comportan según lo diseñado y los fallos se recuperan solos. Guarda los comandos en tu repositorio y vuelve a ejecutarlos cada vez que cambien el broker, su configuración o sus certificados.

Preguntas frecuentes