NAME

       mosquitto_sub - an mqtt version 3.1 client for subscribing to topics

SYNOPSIS

       mosquitto_sub [-c] [-d] [-h hostname] [-i client_id] [-I client id prefix] [-k keepalive
                     time] [-p port number] [-q message QoS] [--quiet] [-v] [ -u username [-P
                     password] ] [ --will-topic topic [--will-payload payload] [--will-qos qos]
                     [--will-retain] ] -t message topic ...

DESCRIPTION

       mosquitto_sub is a simple mqtt version 3.1 client that will subscribe to a topic and print
       the messages that it receives.

OPTIONS

       -c, --disable-clean-session
              Disable  the 'clean session' flag. This means that all of the subscriptions for the
              client will be maintained after it disconnects, along with subsequent QoS 1 and QoS
              2  messages  that  arrive.  When  the client reconnects, it will receive all of the
              queued messages.

              If using this option, it is recommended that the client id  is  set  manually  with
              --id

       -d, --debug
              Enable debug messages.

       -h, --host
              Specify the host to connect to. Defaults to localhost.

       -i, --id
              The  id  to  use for this client. If not given, defaults to mosquitto_sub_ appended
              with the process id of the  client.  Cannot  be  used  at  the  same  time  as  the
              --id-prefix argument.

       -I, --id-prefix
              Provide  a prefix that the client id will be built from by appending the process id
              of the client. This is useful where  the  broker  is  using  the  clientid_prefixes
              option. Cannot be used at the same time as the --id argument.

       -k, --keepalive
              The  number of seconds between sending PING commands to the broker for the purposes
              of informing it we are still connected and functioning. Defaults to 60 seconds.

       -p, --port
              Connect to the port specified instead of the default 1883.

       -P, --pw
              Provide a password to be used  for  authenticating  with  the  broker.  Using  this
              argument without also specifying a username is invalid. This requires a broker that
              supports MQTT v3.1. See also the --username option.

       -q, --qos
              Specify the quality of service desired for the incoming messages, from 0, 1 and  2.
              Defaults to 0. See mqtt(7) for more information on QoS.

              The  QoS  is  identical  for  all  topics  subscribed  to  in  a single instance of
              mosquitto_sub.

       --quiet
              If this argument is given, no runtime errors will be  printed.  This  excludes  any
              error  messages  given  in  case of invalid user input (e.g. using --port without a
              port).

       -t, --topic
              The mqtt topic to subscribe to. See mqtt(7) for more information on mqtt topics.

              This option may be repeated to subscribe to multiple topics.

       -u, --username
              Provide a username to be used for authenticating with the broker. This  requires  a
              broker that supports MQTT v3.1.  See also the --pw argument.

       -v, --verbose
              Print  received messages verbosely. With this argument, messages will be printed as
              "topic payload". When this argument is not  given,  the  messages  are  printed  as
              "payload".

       --will-payload
              Specify  a  message  that  will be stored by the broker and sent out if this client
              disconnects unexpectedly. This must be used in conjunction with --will-topic.

       --will-qos
              The QoS to use for the Will. Defaults to 0. This must be used in  conjunction  with
              --will-topic.

       --will-retain
              If  given,  if  the  client  disconnects  unexpectedly the message sent out will be
              treated as a retained message.  This must be used in conjunction with --will-topic.

       --will-topic
              The topic on which to send a  Will,  in  the  event  that  the  client  disconnects
              unexpectedly.

WILLS

       mosquitto_sub  can  register  a  message  with  the  broker  that  will  be sent out if it
       disconnects unexpectedly. See mqtt(7) for more information.

       The minimum requirement for this is to use --will-topic to specify which  topic  the  will
       should be sent out on. This will result in a non-retained, zero length message with QoS 0.

       Use  the  --will-retain,  --will-payload and --will-qos arguments to modify the other will
       parameters.

EXAMPLES

       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/#

BUGS

       mosquitto_sub bug information can be found at http://launchpad.net/mosquitto

SEE ALSO

       mqtt(7) mosquitto_pub(1) mosquitto(8) libmosquitto(3)

AUTHOR

       Roger Light <roger@atchoo.org>

                                         5 February 2012                         mosquitto_sub(1)