]> mosquitto_sub 1 Mosquitto Project Commands mosquitto_sub an MQTT version 5/3.1.1/3.1 client for subscribing to topics 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 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 mosquitto_sub --help mosquitto_sub is a simple MQTT version 5/3.1.1 client that will subscribe to topics and print the messages that it receives. In addition to subscribing to topics, mosquitto_sub can filter out received messages so they are not printed (see the -T option) or unsubscribe from topics (see the -U option). Unsubscribing from topics is useful for clients connecting with clean session set to false. &options-intro; -C Disconnect and exit the program immediately after the given count of messages have been received. This may be useful in shell scripts where on a single status value is required, for example. Combine with -R or --retain-handling never to print only the first set of fresh messages (i.e. that does not have the retained flag set), or with -T to filter which topics are processed. -E If this option is given, mosquitto_sub will exit immediately that all of its subscriptions have been acknowledged by the broker. In conjunction with -c this allows a durable client session to be initialised on the broker for future use without requiring any messages to be received. --message-rate &from-version21; Instead of printing the messages received, print a count of the messages received at one second intervals. Other options related to output formatting are not valid when this option is active. --random-filter This option can be used to reduce the proportion of messages that mosquitto_sub prints. The default behaviour is to print all incoming messages. Setting the chance to a floating point value between 0.1 and 100.0 will ensure that on average that percentage of messages will be printed. --remove-retained If this argument is given, then when mosquitto_sub receives a message with the retained bit set, it will send a message to the broker to clear that retained message. This applies to all received messages except those that are filtered out by the -T option. This option still takes effect even if -R is used. See also the --retain-as-published and --retained-only options. Remove all retained messages on the server, assuming we have access to do so, and then exit: mosquitto_sub -t '#' --remove-retained --retained-only Remove a whole tree, with the exception of a single topic: mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained --retained-only If this argument is given, only messages that are received that have the retain bit set will be printed. Messages with retain set are "stale", in that it is not known when they were originally published. With this argument in use, the receipt of the first non-stale message will cause the client to exit. See also the --retain-as-published option. --retain-as-published If this argument is given, the subscriptions will have the "retain as published" option set. This means that the retain flag on an incoming message will be exactly as set by the publishing client, rather than indicating whether the message is fresh/stale. This option is not valid for MQTT v3.1/v3.1.1 clients. -t --topic The MQTT topic to subscribe to. See mqtt7 for more information on MQTT topics. This option may be repeated to subscribe to multiple topics. -T --filter-out Suppress printing of topics that match the filter. This allows subscribing to a wildcard topic and only printing a partial set of the wildcard hierarchy. For example, subscribe to the BBC tree, but suppress output from Radio 3: mosquitto_sub -t bbc/# -T bbc/radio3 This option may be repeated to filter out multiple topics or topic trees. -U --unsubscribe A topic that will be unsubscribed from. This may be used on its own or in conjunction with the --topic option and only makes sense when used in conjunction with --clean-session. If used with --topic then subscriptions will be processed before unsubscriptions. Note that it is only possible to unsubscribe from subscriptions that have previously been made. It is not possible to punch holes in wildcard subscriptions. For example, subscribing to sensors/# and then unsubscribing from sensors/+/temperature as shown below will still result in messages matching the sensors/+/temperature being delivered to the client. mosquitto_sub -t sensors/# -U sensors/+/temperature -v Note also that because retained messages are published by the broker on receipt of a SUBSCRIBE command, subscribing and unsubscribing to the same topic may result in messages being received at the client. This option may be repeated to unsubscribe from multiple topics. -w --watch &from-version21; Messages will be printed on a fixed line number based on the topic and order in which topics are received. Useful for monitoring multiple topics that have single line payloads. Unexpected behaviour will occur if there are more topics than lines in the terminal, or if the payload occupies more than a single line. This can be used in conjuction with other output options e.g. -F. Requires ANSI escape code support in the terminal. The -D / --property option allows adding properties to different stages of the mosquitto_sub run. The properties supported for each command are as follows: Note that these really are examples - the subscriptions will work if you run them as shown, but there must be something publishing messages on those topics for you to receive anything. Subscribe to temperature information on localhost with QoS 1: mosquitto_sub -t sensors/temperature -q 1 Subscribe to hard drive temperature updates on multiple machines/hard drives. This expects each machine to be publishing its hard drive temperature to sensors/machines/HOSTNAME/temperature/HD_NAME. mosquitto_sub -t sensors/machines/+/temperature/+ Subscribe to all broker status messages: mosquitto_sub -v -t \$SYS/# Specify the output format as "ISO-8601 date : topic : payload in hex" mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#' Specify the output format as "seconds since epoch.nanoseconds : retained flag : qos : mid : payload length" mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#' Topic and payload output, but with colour where supported. mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#' $XDG_CONFIG_HOME/mosquitto_sub $HOME/.config/mosquitto_sub $HOME/snap/mosquitto/current/.config/mosquitto_sub (for snap installs) Configuration file for default options. mosquitto 7 mqtt 7 mosquitto_pub 1 mosquitto_rr 1 mosquitto 8 libmosquitto 3 mosquitto-tls 7 Roger Light roger@atchoo.org