Provided by: mosquitto-clients_0.12-1_i386 bug

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>

                                 25 July 2011                 mosquitto_sub(1)