Cómo instalar el broker MQTT Mosquitto (Ubuntu, Debian, Windows, macOS)

Eclipse Mosquitto es el broker MQTT open source más usado: pequeño, rápido y disponible para prácticamente cualquier sistema operativo. Este tutorial muestra cómo instalar Mosquitto en Ubuntu, Debian, Windows y macOS, ejecutarlo como servicio en segundo plano, verificarlo con los clientes de línea de comandos y evitar la trampa más común de Mosquitto 2.x — el broker que rechaza en silencio las conexiones remotas.

¿Eres nuevo en MQTT? Lee primero qué es MQTT; si prefieres no instalar nada en el host, consulta Mosquitto en Docker.

Instalar Mosquitto en Ubuntu y Debian

Mosquitto está en los repositorios por defecto de Ubuntu y Debian. El broker y los clientes CLI son paquetes separados, así que instala ambos:

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Los paquetes de las distribuciones pueden ir por detrás de las versiones oficiales. Si necesitas la versión más reciente en Ubuntu, el proyecto Mosquitto publica un PPA:

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Comprueba qué versión tienes:

mosquitto -h | head -n 1

Ejecutar Mosquitto como servicio de systemd

El paquete de Debian registra una unidad systemd mosquitto y normalmente la arranca de inmediato. Usa los comandos habituales para gestionarla:

sudo systemctl enable --now mosquitto   # start now and at boot
sudo systemctl status mosquitto         # is it running?
sudo systemctl restart mosquitto        # after editing the config
journalctl -u mosquitto -f              # follow the logs

El archivo de configuración principal es /etc/mosquitto/mosquitto.conf. Incluye todos los archivos *.conf de /etc/mosquitto/conf.d/, que es el lugar más limpio para tus propios ajustes.

Instalar Mosquitto en Windows

1. Descarga el instalador de Windows (.exe de 64 bits) desde la página oficial de descargas en mosquitto.org/download.
2. Ejecútalo. Deja seleccionado el componente Service si quieres que Mosquitto se ejecute como servicio de Windows. La ruta de instalación por defecto es C:\Program Files\mosquitto.
3. Añade esa carpeta a tu PATH para que mosquitto_pub y mosquitto_sub funcionen desde cualquier terminal.

Inicia el servicio desde un PowerShell o Símbolo del sistema como administrador:

net start mosquitto
# or run in the foreground with verbose logging:
cd "C:\Program Files\mosquitto"
.\mosquitto.exe -c mosquitto.conf -v

Instalar Mosquitto en macOS

Con Homebrew basta una línea, y el gestor de servicios de Homebrew lo mantiene ejecutándose en segundo plano:

brew install mosquitto
brew services start mosquitto     # run as a background service
brew services info mosquitto      # check status

El archivo de configuración está bajo el prefijo de Homebrew: /opt/homebrew/etc/mosquitto/mosquitto.conf en Apple Silicon o /usr/local/etc/mosquitto/mosquitto.conf en Macs Intel. Los clientes vienen incluidos en la misma fórmula.

Verificar la instalación con mosquitto_sub y mosquitto_pub

Abre dos terminales en la máquina donde corre el broker. Suscríbete en la primera:

mosquitto_sub -h localhost -t 'test/#' -v

Publica desde la segunda:

mosquitto_pub -h localhost -t 'test/hello' -m 'Mosquitto works'

La terminal 1 debería mostrar test/hello Mosquitto works. Para ver todas las opciones, ten a mano nuestra chuleta de mosquitto_pub y mosquitto_sub.

La trampa del “local only mode” de Mosquitto 2.x

La prueba en localhost funciona, pero un cliente en otra máquina recibe connection refused. Es así por diseño. Desde la versión 2.0, si mosquitto.conf no define ningún listener, Mosquitto solo escucha en la interfaz de loopback y escribe en el log algo como:

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

Además, Mosquitto 2.x usa por defecto allow_anonymous false en cuanto defines un listener. Así que abrir el puerto no basta — también tienes que decidir cómo se autentican los clientes. Crea un pequeño archivo de configuración:

listener 1883
allow_anonymous true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Reinicia el broker (sudo systemctl restart mosquitto) y el puerto será accesible desde la red. Crear el archivo de contraseñas y añadir ACL y TLS se explica paso a paso en cómo proteger Mosquitto. Para generar una configuración sin memorizar directivas, usa el generador de mosquitto.conf.

Opcional: activar WebSockets

Los clientes en el navegador no pueden usar TCP directo. Para probar tu broker desde una página web, añade un segundo listener con el protocolo WebSockets (consulta MQTT sobre WebSockets y los puertos MQTT):

listener 9001
protocol websockets

Ten en cuenta que una página servida por HTTPS solo puede abrir conexiones wss://, así que para un cliente web en internet también necesitarás TLS en ese listener. Antes de llegar tan lejos, puedes hacerte una idea de MQTT con un broker público de prueba en el navegador:

Pruébalo en el cliente MQTT online

Dónde guarda Mosquitto sus archivos

Sea cual sea la plataforma, ejecuta mosquitto -c <path-to-conf> -v en una terminal cuando algo no arranque: muestra los errores de configuración directamente en lugar de esconderlos en el log de un servicio. Detén antes el servicio, o la instancia en primer plano fallará porque el puerto ya está ocupado.

Solución de problemas en una instalación nueva

Para otros códigos CONNACK y timeouts, consulta la guía de errores de conexión MQTT.

Próximos pasos

• Protégelo con contraseñas, ACL y TLS: autenticación en Mosquitto.
• ¿Prefieres contenedores? Ejecuta Mosquitto en Docker.
• Compara Mosquitto con otros brokers en nuestro directorio de brokers.

Preguntas frecuentes