mosquitto-clients (MQTT pub/sub CLI)

What it is

mosquitto_pub / mosquitto_sub — the reference MQTT command-line clients from the Eclipse Mosquitto project. The quickest way to poke a broker from a shell or script.

Install

Debian/Ubuntu:

sudo apt install mosquitto-clients

(The mosquitto package is the broker — only install that on a broker host.)

Authenticate

Broker-dependent. Typical username/password:

mosquitto_sub -h <broker> -t 'lab/#' -u <user> -P <password>

Keep broker credentials in Vaultwarden (https://vault.portugalfuturista.org). For TLS brokers: -p 8883 --cafile <ca.crt> (+ --cert/--key for mutual TLS).

Configure for this environment

Convenience env for the lab broker:

export MQTT_HOST=192.168.0.40     # or wherever the broker CT lands
export MQTT_PORT=1883

mosquitto_sub -h $MQTT_HOST -t 'lab/#' -v &        # watch everything
mosquitto_pub -h $MQTT_HOST -t lab/test -m "hello"

Self-hosted equivalent

The broker itself: mosquitto in a Proxmox LXC (Debian template):

# on the Proxmox host, in the CT console:
apt update && apt install mosquitto mosquitto-clients
systemctl enable --now mosquitto

Minimal hardening (/etc/mosquitto/conf.d/lab.conf):

listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/passwd

mosquitto_passwd -c /etc/mosquitto/passwd labuser
systemctl restart mosquitto

(LAN-only, so no TLS required; add it if the broker ever leaves the LAN.) Cloud MQTT (AWS IoT Core etc.) is only for production device fleets.

Aurélio integration

The cli-iot skill uses mosquitto_pub/sub to probe device topics during IoT bring-up. Connector registry ids: mqtt-local (LAN broker), aws-iot (cloud counterpart).

Verify

mosquitto_sub --help | head -3
# mosquitto_sub is a simple mqtt client ...
mosquitto_pub -h $MQTT_HOST -t lab/test -m ping
mosquitto_sub -h $MQTT_HOST -t lab/test -C 1 -W 5
# ping

Troubleshooting

Connection refused — broker not running, or listening on 127.0.0.1 only (default on many distros); add listener 1883 0.0.0.0.
Not authorized — anonymous access disabled; pass -u/-P, and check the password file matches the config path.
Nothing received but publish succeeds — topic mismatch; remember MQTT wildcards: + single level, # multi-level (and # must be quoted in bash).
TLS handshake failure — wrong CA file or hostname mismatch; use --insecure only as a temporary diagnostic, never in scripts.

2.5 KiB Raw Blame History