Publicar y recibir mensajes MQTT con Mosquitto

MQTT utiliza un modelo de publicación y suscripción: los clientes envían mensajes a un broker en un tema, y otros clientes se suscriben a los temas que les interesan. Los programas mosquitto_pub y mosquitto_sub permiten probar ese flujo desde la terminal [1][2]. Esta guía usa temas ficticios y evita escribir contraseñas directamente en la línea de comandos.

Precaución: publicar en un tema puede activar acciones en dispositivos reales. Comprueba el tema y el contenido del mensaje antes de enviar datos al broker de producción.

Instalar los clientes

En Debian, instala el paquete de clientes Mosquitto:

sudo apt update
sudo apt install mosquitto-clients

Este paquete proporciona las herramientas mosquitto_pub y mosquitto_sub; no instala necesariamente un broker local [1]. Para probar contra un broker de tu red, necesitarás su nombre o dirección, el puerto y los permisos de acceso que te haya asignado su administrador.

Probar una suscripción y una publicación

En una primera terminal, suscríbete a un filtro de prueba:

mosquitto_sub -h broker.example.net -t 'casa/+/temperatura' -v

En otra terminal, publica un mensaje en un tema que coincida:

mosquitto_pub -h broker.example.net \
  -t 'casa/salon/temperatura' \
  -m '21.5'

Sustituye broker.example.net por la dirección del broker. -v hace que la suscripción muestre el tema junto al contenido recibido. Si el acceso requiere autenticación, configura las credenciales en los archivos indicados en la sección siguiente.

Entender los temas y comodines

Los temas se organizan en niveles separados por /, por ejemplo casa/salon/temperatura. Los comodines solo se usan en filtros de suscripción, no en el tema al publicar [3]:

• + coincide con un único nivel. Por ejemplo, casa/+/temperatura coincide con casa/salon/temperatura y casa/cocina/temperatura.
• # coincide con cero o más niveles y debe aparecer al final del filtro. Por ejemplo, casa/# incluye temas bajo casa/ en cualquier nivel.

Usa filtros tan concretos como sea posible. Una suscripción amplia como # puede recibir gran cantidad de mensajes y, según el broker, mensajes retenidos publicados anteriormente [2][3].

Guardar la configuración de conexión

Mosquitto admite archivos de configuración para los clientes. En sistemas POSIX, mosquitto_pub y mosquitto_sub pueden leer sus opciones predeterminadas de ~/.config/mosquitto_pub y ~/.config/mosquitto_sub, respectivamente. La documentación recomienda esta vía para autenticarse sin mostrar usuario y contraseña en los argumentos del proceso [2][4].

Crea el directorio y restringe sus permisos:

mkdir -p "$HOME/.config"
chmod 700 "$HOME/.config"

Crea ~/.config/mosquitto_pub con los datos de conexión:

-h broker.example.net
-p 8883
-u mqtt_user
-P <PASSWORD_EJEMPLO>

Y crea ~/.config/mosquitto_sub con la misma configuración. Sustituye el placeholder por la contraseña real solo en tu equipo, no en un post, repositorio o historial compartido. Protege ambos archivos:

chmod 600 "$HOME/.config/mosquitto_pub" "$HOME/.config/mosquitto_sub"

El puerto MQTT sobre TLS suele ser 8883; Mosquitto puede utilizar los certificados de confianza del sistema en ese puerto. Confirma con el administrador del broker qué puerto y certificados requiere [2][4]. TLS protege el transporte; los permisos del archivo protegen las credenciales almacenadas en el equipo. El archivo no está cifrado por chmod, así que el usuario local y sus copias de seguridad también deben protegerse.

Con los archivos predeterminados preparados, los comandos quedan sin credenciales en la línea de órdenes:

mosquitto_sub -t 'casa/+/temperatura' -v

mosquitto_pub -t 'casa/salon/temperatura' -m '21.5'

Los clientes toman el host, puerto, usuario y contraseña de su archivo de configuración predeterminado. También permiten indicar un archivo concreto con -o [2][4].

Diagnosticar una conexión

Si no llegan mensajes, comprueba cada punto por separado:

1. Confirma que el host y el puerto corresponden al listener configurado en el broker.
2. Comprueba que el cliente puede alcanzar el puerto a través de la red y el firewall.
3. Revisa que el usuario esté autorizado tanto para publicar como para suscribirse a esos temas; los permisos pueden ser distintos.
4. Verifica que el filtro de suscripción coincide con el tema publicado.
5. Revisa la salida de error del cliente. Para depuración temporal, -d muestra detalles del protocolo; no la uses para registrar credenciales o datos sensibles.

Para comprobar la recepción, publica un valor inocuo en un tema de prueba y observa la salida de mosquitto_sub. En producción, confirma el efecto en el consumidor correspondiente antes de enviar mensajes que puedan controlar un dispositivo [2].

En resumen

• mosquitto_pub publica un mensaje y mosquitto_sub escucha un filtro de temas.
• + coincide con un nivel; # cubre los niveles restantes y solo va al final del filtro.
• Guarda usuario y contraseña en los archivos de configuración del cliente con permisos restrictivos, en vez de ponerlos en los argumentos del comando.
• Usa TLS según la configuración del broker y limita la autorización a los temas necesarios.
• Valida el destino y el payload antes de publicar en un entorno real.

📚 Fuentes consultadas

1. Package mosquitto-clients — Debian Packages
2. mosquitto_pub man page — Eclipse Mosquitto
3. MQTT Version 5.0 — OASIS Standard, Topic Names and Topic Filters
4. mosquitto_sub man page — Eclipse Mosquitto

Imagen