mosquitto_sub

Subscribe to the topic sensors/temperature information with Quality of Service (QoS) set to 1. (The default hostname is localhost and port 1883)

$ mosquitto_sub [[-t|--topic]] [sensors/temperature] [[-q|--qos]] [1]

$ mosquitto_sub [[-v|--verbose]] [[-h|--host]] "iot.eclipse.org" [[-p|--port]] 1885 [[-t|--topic]] [\$SYS/#]

$ mosquitto_sub [[-t|--topic]] [sensors/machines/+/temperature/+]

mosquitto_sub [OPTIONS] -t <topic> [-t <topic> ...]

-h <hostname>
    Specify the IP address or hostname of the MQTT broker.

-p <port>
    Set the network port of the MQTT broker (default: 1883).

-t <topic>
    Required. The MQTT topic to subscribe to. This option can be used multiple times for subscribing to multiple topics.

-q <qos>
    Define the Quality of Service level for the subscription (0, 1, or 2). Default is 0.

-i <id>
    Set the MQTT client ID. If not provided, a random ID will be generated.

-u <username>
    Provide a username for broker authentication.

-P <password>
    Provide a password for broker authentication.

-k <keepalive>
    Set the keepalive interval in seconds (default: 60). This is the maximum period between messages sent or received.

-c
    Use a clean session (default). This means the broker will discard any previous session information for this client upon connection.

-C <count>
    Exit after receiving <count> messages.

-T <filter_topic>
    Only print messages received on topics that match <filter_topic>, even if subscribed to broader topics.

-d
    Enable debug messages for detailed client activity, useful for troubleshooting.

-v
    Print the topic name before the payload of each received message.

-r
    Receive retained messages when subscribing. By default, retained messages are not sent.

--capath <directory>
    Specify a directory containing CA certificates for SSL/TLS server validation.

--cafile <file>
    Specify a file containing CA certificates for SSL/TLS server validation.

--cert <file>
    Specify the client certificate file for SSL/TLS mutual authentication.

--key <file>
    Specify the client private key file for SSL/TLS mutual authentication.

--tls-version <version>
    Specify the minimum TLS protocol version to use (e.g., tlsv1.2).

--insecure
    Allow untrusted server certificates for SSL/TLS connections. Use with extreme caution, as it bypasses security checks.

mosquitto_sub is a command-line client provided by the Mosquitto project, designed to interact with MQTT brokers. It enables users to subscribe to one or more MQTT topics and receive messages published on those topics. Upon execution, it establishes a connection to a specified MQTT broker (defaulting to localhost:1883), subscribes with a defined Quality of Service (QoS) level, and then continuously listens for incoming messages. All received messages on the subscribed topics are printed to standard output. This functionality makes mosquitto_sub an essential tool for debugging MQTT-based applications, monitoring sensor data, or observing message traffic within an MQTT network. It supports various connection options, including SSL/TLS for secure communication, username/password authentication, and specific MQTT protocol versions.

When using SSL/TLS, ensuring correct certificate paths is crucial for secure connections. The --insecure option bypasses certificate validation and should be avoided in production environments due to significant security risks.
By default, mosquitto_sub operates with a 'clean session', meaning it will not receive messages published while it was disconnected, nor will it resume previous subscriptions. If persistent sessions are required, this behavior needs to be managed externally or by the broker. Understanding MQTT topic wildcards (+ for single level, # for multi-level) is essential to avoid subscribing to unintended message streams.

The -t option can be specified multiple times within a single command invocation to subscribe to several distinct topics simultaneously. For example:
mosquitto_sub -t sensors/temperature -t actuators/control

By default, mosquitto_sub prints only the payload of the received message. When the -v (verbose) option is used, it prints the topic name followed by the payload (e.g., 'topic payload'). More advanced custom output formats can be achieved using the -F option (format string), allowing users to define how messages are displayed based on various message properties.

mosquitto_sub is an integral part of the Mosquitto project, an open-source MQTT broker and client library initiated by Roger Light. The project saw its first releases around 2009-2010, aiming to provide a lightweight and efficient implementation of the MQTT protocol. The MQTT protocol itself, designed by IBM and Eurotech in 1999 for constrained devices and networks, gained significant traction with the rise of IoT. mosquitto_sub has since become a standard command-line utility for developers and system administrators working with MQTT, offering a reliable way to monitor and interact with message brokers.

mosquitto_pub(1), mosquitto(8), netcat(1), openssl(1ssl)