MOSQUITTO_SUB(1) Commands MOSQUITTO_SUB(1) (NAME) mosquitto_sub - MQTT .. . (SYNOPSIS) mosquitto_sub [options] {-t message-topic... | -U unsubscribe-topic...} options: [auth-options] [connection-options] [misc-options] [mqtt-options] [output-options] [tls-certificate-options | tls-psk-options] auth-options: [-u username] [-P password] connection-options: {[-h hostname] [--unix socket path] [-p port-number] | -L URL } [-A bind-address] [--nodelay] [-S] [--ws] [--proxy socks-url] misc-options: [-E] [-o config-file] [-W message-processing-timeout] mqtt-options: [-c] [-D command identifier value] [-i client-id] [-I client-id-prefix] [-k keepalive-time] [-q message-QoS] [--retain-as-published] [--retain-handling always | new | never] [-V protocol-version] [-x session-expiry-interval] [--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]] output-options: [-d] [-C msg-count] [--message-rate] [-N] [--pretty] [--random-filter chance] [--remove-retained] [-R | --retained-only] [--quiet] [-T filter-out...] [-v] [-w | --watch] tls-certificate-options: [--no-tls] {--cafile file | --capath dir} [--tls-use-os-certs] [--cert file] [--key file] [--ciphers ciphers] [--insecure] [--tls-alpn protocol] [--tls-keylog file] [--tls-version version] [--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1] tls-psk-options: --psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version] mosquitto_sub [--help] (DESCRIPTION) mosquitto_sub MQTT .. . (topics) . mosquitto_sub ( -T ) ( -U ). (clean session) . (ENCRYPTED CONNECTIONS) TLS . . TLS x509 --cafile --capath . -p 8883 --cafile --capath . TLS TLS-PSK --psk --psk-identity . (OPTIONS) mosquitto_sub : . (Default Config File) $XDG_CONFIG_HOME/mosquitto_sub $HOME/.config/mosquitto_sub POSIX %USERPROFILE%\mosquitto_sub . : -option value. . . -S. TLS --no-tls . # . . . (Config File) . . -o config-file . -o . . (The options) -A IP (bind) . . -c, --disable-clean-session << >> (clean session) / . . MQTT -x . QoS 1 QoS 2 . . --id . --cafile (CA) PEM . SSL/TLS . : --capath --capath (CA) PEM . SSL/TLS . --capath <<.crt>> <>> . : --cafile --cert PEM ( ). : --key << >>. --ciphers TLS OpenSSL . ciphers(1) . -C . . ( retain ) -R --retain-handling never -T . -d, --debug (debug). -D, --property MQTT . MQTT . : -D command identifier value -D command identifier name value command MQTT CONNECT PUBLISH PUBACK PUBREC PUBCOMP SUBSCRIBE UNSUBSCRIBE DISCONNECT AUTH WILL . . identifier . <<->> : payload-format-indicator. . value . name user-property . value . -E mosquitto_sub . -c . -F . . (OUTPUT FORMAT) . -v -N . --help . -h, --host . localhost . -i, --id . MQTT . v3.1.1/v3.1 mosq-XXXXXXXXXXXXXXXXXX X - . v5.0 . -I, --id-prefix (PID) . clientid_prefixes . --id . --insecure . DNS . . . -k, --keepalive PING . . --key PEM TLS . : --cert << >>. --keyform TLS . <> <> . TPM . <> . : --tls-engine. -L, --url URL. : mqtt(s)://[username[:password]@]host[:port]/topic ws(s)://[username[:password]@]host[:port]/path (scheme) : mqtt:// - 1883 mqtts:// - 8883 ws:// - 80 wss:// - 443. --message-rate . . . . -N (payload) (newline) . . -v . --nodelay (Nagle) . . . --no-tls . . TLS. TLS . TLS 8883 . -o config-file . . . << >> << >> . -p, --port . MQTT MQTT TLS . -P, --pw . v3.1 v3.1.1 MQTT . --username . --pretty JSON %j %J . --pretty . --proxy SOCKS5 . <> <> . socks-url socks5h://[username[:password]@]host[:port] . socks5h . %25 %3A %40 % : @ . . . IPv6 socks5h://[::1]:1080. . SOCKS curl(1) . --psk (PSK) ( 0x) TLS-PSK. TLS-PSK --psk-identity . --psk-identity TLS-PSK. . -q, --qos (Quality of Service) . . QoS mqtt(7) . . --quiet . ( --port ). -R (retain) . retain <<>> (stale) . (wildcard) . . : --retain-handling. --random-filter mosquitto_sub . . chance 0.1 100.0 . --remove-retained mosquitto_sub (retain) . -T . -R . --retain-as-published --retained-only . . ( ) : mosquitto_sub -t '#' --remove-retained --retained-only . : mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained --retained-only (retain) . retain <<>> (stale) . . --retain-as-published . --retain-as-published << >> (retain as published) . retain . MQTT v3.1 v3.1.1 . --retain-handling always | new | never . . . . o always - o new - . (non-clean session) . . o never - -S SRV DNS . -h _mqtt._tcp. _mqtt._tcp. . -t, --topic (topic) MQTT . MQTT mqtt(7) . . -T, --filter-out . (wildcard) . BBC Radio 3: o mosquitto_sub -t bbc/# -T bbc/radio3 . --tls-alpn ( MQTT WebSockets). --tls-engine OpenSSL ( ). openssl engine . : --keyform. --tls-engine-kpass-sha1 SHA1 TLS. TLS TPM . SHA1 . : --tls-engine. --tls-keylog file . . TLS file. tcpdump wireshark mqttshark TLS MQTT . Wireshark (Pre)-Master-Secret log filename Transport Layer Security . . --tls-use-os-certs (CA) . --cafile --capath TLS . -L mqtts://... . --tls-version TLS . tlsv1.3 tlsv1.2 . tlsv1.2 . . -u, --username . --pw . --unix (unix domain socket) TCP. -h -L : mosquitto_pub --unix /tmp/mosquitto.sock ... Mosquitto socket_domain mosquitto.conf(5) . -U, --unsubscribe . --topic --clean-session ( ) . --topic . . (wildcard) . sensors/# sensors/+/temperature sensors/+/temperature : o mosquitto_sub -t sensors/# -U sensors/+/temperature -v SUBSCRIBE . . -v, --verbose . <> . <> . : -F. -V, --protocol-version MQTT . 5 311 31 mqttv5 mqttv311 mqttv31 . 311 . -W (timeout) . . . -w, --watch . . . . . -F . ANSI . --will-payload . --will-topic . --will-qos (QoS) (Will). . --will-topic . --will-retain (retained) . --will-topic . --will-topic (topic) . --ws (WebSockets) TCP . -x session-expiry-interval CONNECT. MQTT . 0 4294967294 -1 4294967295 . -c -1 0 . -x -c . (OUTPUT FORMAT) . (newline) -N . << >> (Payload-only) . (Verbose) -v (space) . . -F format-string . . . : % @ \. % MQTT . @ strftime(3) ( @ % - @ strftime ). . strftime . strftime @N . . \ . (Flag characters) %A %C %d %E %F %f %I %l %m %p %R %S %t %x %X % . 0 (zero-padded). %A %E %d %F %f %l %m %S %X %x . - 0 . - . . (Field width) MQTT printf . . %A %C %d %E %F %f %I %l %m %p %R %S %t %x %X . %10t . (Maximum width) MQTT printf %.20t . %C %I %R %t . %10.10t . (Hexadecimal binary field width) %x %X . (nibbles) . %.2x ( ) 18 83 . !"#$&'()*+,-./:;<=>?@[\]^_`{|}~ . %.2:x 18:83 . (Floating point number printing consideration) IEEE 754 F ISO/IEC 9899:1999 . IEEE 754 %f %d . IEEE 754 . IEEE 754 . IEEE 754 . . MQTT (MQTT related parameters) o %% %. o %A topic-alias MQTT . o %C content-type MQTT . o %D correlation-data MQTT . . o %d IEEE 754 (double) . o %E message-expiry-interval MQTT . o %F payload-format-indicator MQTT . o %f IEEE 754 . o %l . o %m ( QoS>0 ). o %P user-property MQTT . key:value . . o %p ( ). o %q (QoS) . o %R response-topic MQTT . o %r (retain) . o %S subscription-identifier MQTT . o %t . o %x ( ). o %X ( ). (Helpers) o %I ISO-8601 2016-08-10T09:47:38+0100 o %j JSON . {"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello world"} o %J JSON - JSON . : {"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}. JSON "Error: Message payload is not valid JSON on topic " stderr . o %U 1470818943.786368637 (Time related parameters) o @@ @. o @X X strftime %X. . o @N . (Escape characters) o \\ \. o \0 (null character). ( topic payload) xargs(1) . o \a / (alert/bell). o \e (escape sequence) ANSI . o \n (newline). o \r (carriage return). o \t (horizontal tab). o \v (vertical tab). (WILLS) . mqtt(7) . --will-topic . (non- retained) QoS 0 . --will-retain --will-payload --will-qos . (PROPERTIES) -D / --property mosquitto_sub . : (Connect) o authentication-data ( - : ) o authentication-method ( UTF-8) o maximum-packet-size ( ) o receive-maximum ( ) o request-problem-information ( ) o request-response-information ( ) o session-expiry-interval ( : -x ) o topic-alias-maximum ( ) o user-property ( UTF-8) (Subscribe) o user-property ( UTF-8) (Unsubscribe) o user-property ( UTF-8) (Disconnect) o session-expiry-interval ( ) o user-property ( UTF-8) (Will properties) o content-type ( UTF-8) o correlation-data ( - : ) o message-expiry-interval ( ) o payload-format-indicator ( ) o response-topic ( UTF-8) o user-property ( UTF-8) o will-delay-interval ( ) (EXIT STATUS) . MQTT CONNACK . libmosquitto . CONNACK MQTT v3.1.1: o 0 (Success) o 1 : (Connection refused: Bad protocol version) o 2 : (Connection refused: Identifier rejected) o 3 : (Connection refused: Server unavailable) o 4 : (Connection refused: Bad username/password) o 5 : (Connection refused: Not authorized) CONNACK MQTT v5: o 0 (Success) o 128 (Unspecified error) o 129 (Malformed packet) o 130 (Protocol error) o 131 (Implementation specific error) o 132 (Unsupported protocol version) o 133 (Client ID not valid) o 134 (Bad username or password) o 135 (Not authorized) o 136 (Server unavailable) o 137 (Server busy) o 138 (Banned) o 139 (Server shutting down) o 140 (Bad authentication method) o 141 (Keep alive timeout) o 142 (Session taken over) o 143 (Topic filter invalid) o 144 (Topic name invalid) o 147 (Receive maximum exceeded) o 148 (Topic alias invalid) o 149 (Packet too large) o 148 (Message rate too high) o 151 (Quota exceeded) o 152 (Administrative action) o 153 (Payload format invalid) o 154 (Retain not supported) o 155 (QoS not supported) o 156 (Use another server) o 157 (Server moved) o 158 (Shared subscriptions not supported) o 159 (Connection rate exceeded) o 160 (Maximum connect time) o 161 (Subscription IDs not supported) o 162 (Wildcard subscriptions not supported) (Other codes): o 27 (Timed out waiting for message) (EXAMPLES) - . localhost QoS 1: o mosquitto_sub -t sensors/temperature -q 1 / . sensors/machines/HOSTNAME/temperature/HD_NAME : o mosquitto_sub -t sensors/machines/+/temperature/+ : o mosquitto_sub -v -t \$SYS/# "ISO-8601 date : topic : payload in hex": o mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#' "seconds since epoch.nanoseconds : retained flag : qos : mid : payload length": o mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#' : o mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#' (FILES) $XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub, $HOME/snap/mosquitto/current/.config/mosquitto_sub ( snap) . (BUGS) mosquitto : https://github.com/eclipse- mosquitto/mosquitto/issues (SEE ALSO) mosquitto(7), mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8), libmosquitto(3), mosquitto-tls(7) (AUTHOR) Roger Light Mosquitto Project 04/03/2026 MOSQUITTO_SUB(1)