1 | <?xml version='1.0' encoding='UTF-8'?>
|
2 | <?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
3 |
|
4 | <refentry xml:id="mosquitto_sub" xmlns:xlink="http://www.w3.org/1999/xlink">
|
5 | <refmeta>
|
6 | <refentrytitle>mosquitto_sub</refentrytitle>
|
7 | <manvolnum>1</manvolnum>
|
8 | <refmiscinfo class="source">Mosquitto Project</refmiscinfo>
|
9 | <refmiscinfo class="manual">Commands</refmiscinfo>
|
10 | </refmeta>
|
11 |
|
12 | <refnamediv>
|
13 | <refname>mosquitto_sub</refname>
|
14 | <refpurpose>an MQTT version 3.1 client for subscribing to topics</refpurpose>
|
15 | </refnamediv>
|
16 |
|
17 | <refsynopsisdiv>
|
18 | <cmdsynopsis>
|
19 | <command>mosquitto_sub</command>
|
20 | <arg><option>-A</option> <replaceable>bind_address</replaceable></arg>
|
21 | <arg><option>-c</option></arg>
|
22 | <arg><option>-d</option></arg>
|
23 | <arg><option>-h</option> <replaceable>hostname</replaceable></arg>
|
24 | <arg><option>-i</option> <replaceable>client_id</replaceable></arg>
|
25 | <arg><option>-I</option> <replaceable>client id prefix</replaceable></arg>
|
26 | <arg><option>-k</option> <replaceable>keepalive time</replaceable></arg>
|
27 | <arg><option>-p</option> <replaceable>port number</replaceable></arg>
|
28 | <arg><option>-q</option> <replaceable>message QoS</replaceable></arg>
|
29 | <arg><option>-R</option></arg>
|
30 | <arg><option>-S</option></arg>
|
31 | <arg><option>-N</option></arg>
|
32 | <arg><option>--quiet</option></arg>
|
33 | <arg><option>-v</option></arg>
|
34 | <arg>
|
35 | <arg><option>-u</option> <replaceable>username</replaceable></arg>
|
36 | <arg><option>-P</option> <replaceable>password</replaceable></arg>
|
37 | </arg>
|
38 | <arg>
|
39 | <option>--will-topic</option> <replaceable>topic</replaceable>
|
40 | <arg><option>--will-payload</option> <replaceable>payload</replaceable></arg>
|
41 | <arg><option>--will-qos</option> <replaceable>qos</replaceable></arg>
|
42 | <arg><option>--will-retain</option></arg>
|
43 | </arg>
|
44 | <group>
|
45 | <arg>
|
46 | <group choice='req'>
|
47 | <arg choice='plain'><option>--cafile</option> <replaceable>file</replaceable></arg>
|
48 | <arg choice='plain'><option>--capath</option> <replaceable>dir</replaceable></arg>
|
49 | </group>
|
50 | <arg><option>--cert</option> <replaceable>file</replaceable></arg>
|
51 | <arg><option>--key</option> <replaceable>file</replaceable></arg>
|
52 | <arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
53 | <arg><option>--insecure</option></arg>
|
54 | </arg>
|
55 | <arg>
|
56 | <arg choice='plain'><option>--psk</option> <replaceable>hex-key</replaceable></arg>
|
57 | <arg choice='plain'><option>--psk-identity</option> <replaceable>identity</replaceable></arg>
|
58 | <arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
59 | </arg>
|
60 | </group>
|
61 | <arg choice='opt' rep='repeat'><option>-T</option> <replaceable>filter-out</replaceable></arg>
|
62 | <arg choice='plain' rep='repeat'><option>-t</option> <replaceable>message-topic</replaceable></arg>
|
63 | </cmdsynopsis>
|
64 | <cmdsynopsis>
|
65 | <command>mosquitto_sub</command>
|
66 | <group choice='plain'>
|
67 | <arg><option>--help</option></arg>
|
68 | </group>
|
69 | </cmdsynopsis>
|
70 | </refsynopsisdiv>
|
71 |
|
72 | <refsect1>
|
73 | <title>Description</title>
|
74 | <para><command>mosquitto_sub</command> is a simple MQTT version 3.1
|
75 | client that will subscribe to a topic and print the messages that it
|
76 | receives.</para>
|
77 | </refsect1>
|
78 |
|
79 | <refsect1>
|
80 | <title>Options</title>
|
81 | <variablelist>
|
82 | <varlistentry>
|
83 | <term><option>-A</option></term>
|
84 | <listitem>
|
85 | <para>Bind the outgoing connection to a local ip
|
86 | address/hostname. Use this argument if you need to
|
87 | restrict network communication to a particular
|
88 | interface.</para>
|
89 | </listitem>
|
90 | </varlistentry>
|
91 | <varlistentry>
|
92 | <term><option>-c</option></term>
|
93 | <term><option>--disable-clean-session</option></term>
|
94 | <listitem>
|
95 | <para>Disable the 'clean session' flag. This means that all
|
96 | of the subscriptions for the client will be maintained
|
97 | after it disconnects, along with subsequent QoS 1 and QoS 2
|
98 | messages that arrive. When the client reconnects, it will
|
99 | receive all of the queued messages.</para>
|
100 | <para>If using this option, it is recommended that the
|
101 | client id is set manually with <option>--id</option></para>
|
102 | </listitem>
|
103 | </varlistentry>
|
104 | <varlistentry>
|
105 | <term><option>--cafile</option></term>
|
106 | <listitem>
|
107 | <para>Define the path to a file containing PEM encoded CA
|
108 | certificates that are trusted. Used to enable SSL
|
109 | communication.</para>
|
110 | <para>See also <option>--capath</option></para>
|
111 | </listitem>
|
112 | </varlistentry>
|
113 | <varlistentry>
|
114 | <term><option>--capath</option></term>
|
115 | <listitem>
|
116 | <para>Define the path to a directory containing PEM encoded CA
|
117 | certificates that are trusted. Used to enable SSL
|
118 | communication.</para>
|
119 | <para>For <option>--capath</option> to work correctly, the
|
120 | certificate files must have ".crt" as the file ending
|
121 | and you must run "c_rehash <path to capath>" each
|
122 | time you add/remove a certificate.</para>
|
123 | <para>See also <option>--cafile</option></para>
|
124 | </listitem>
|
125 | </varlistentry>
|
126 | <varlistentry>
|
127 | <term><option>--cert</option></term>
|
128 | <listitem>
|
129 | <para>Define the path to a file containing a PEM encoded
|
130 | certificate for this client, if required by the
|
131 | server.</para>
|
132 | <para>See also <option>--key</option>.</para>
|
133 | </listitem>
|
134 | </varlistentry>
|
135 | <varlistentry>
|
136 | <term><option>--ciphers</option></term>
|
137 | <listitem>
|
138 | <para>An openssl compatible list of TLS ciphers to support
|
139 | in the client. See
|
140 | <citerefentry><refentrytitle>ciphers</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
141 | for more information.</para>
|
142 | </listitem>
|
143 | </varlistentry>
|
144 | <varlistentry>
|
145 | <term><option>-d</option></term>
|
146 | <term><option>--debug</option></term>
|
147 | <listitem>
|
148 | <para>Enable debug messages.</para>
|
149 | </listitem>
|
150 | </varlistentry>
|
151 | <varlistentry>
|
152 | <term><option>--help</option></term>
|
153 | <listitem>
|
154 | <para>Display usage information.</para>
|
155 | </listitem>
|
156 | </varlistentry>
|
157 | <varlistentry>
|
158 | <term><option>-h</option></term>
|
159 | <term><option>--host</option></term>
|
160 | <listitem>
|
161 | <para>Specify the host to connect to. Defaults to localhost.</para>
|
162 | </listitem>
|
163 | </varlistentry>
|
164 | <varlistentry>
|
165 | <term><option>-i</option></term>
|
166 | <term><option>--id</option></term>
|
167 | <listitem>
|
168 | <para>The id to use for this client. If not given, defaults
|
169 | to mosquitto_sub_ appended with the process id of the
|
170 | client. Cannot be used at the same time as the
|
171 | <option>--id-prefix</option> argument.</para>
|
172 | </listitem>
|
173 | </varlistentry>
|
174 | <varlistentry>
|
175 | <term><option>-I</option></term>
|
176 | <term><option>--id-prefix</option></term>
|
177 | <listitem>
|
178 | <para>Provide a prefix that the client id will be built
|
179 | from by appending the process id of the client. This is
|
180 | useful where the broker is using the clientid_prefixes
|
181 | option. Cannot be used at the same time as the
|
182 | <option>--id</option> argument.</para>
|
183 | </listitem>
|
184 | </varlistentry>
|
185 | <varlistentry>
|
186 | <term><option>--insecure</option></term>
|
187 | <listitem>
|
188 | <para>When using certificate based encryption, this option
|
189 | disables verification of the server hostname in the
|
190 | server certificate. This can be useful when testing
|
191 | initial server configurations but makes it possible for
|
192 | a malicious third party to impersonate your server
|
193 | through DNS spoofing, for example. Use this option in
|
194 | testing <emphasis>only</emphasis>. If you need to
|
195 | resort to using this option in a production
|
196 | environment, your setup is at fault and there is no
|
197 | point using encryption.</para>
|
198 | </listitem>
|
199 | </varlistentry>
|
200 | <varlistentry>
|
201 | <term><option>-k</option></term>
|
202 | <term><option>--keepalive</option></term>
|
203 | <listitem>
|
204 | <para>The number of seconds between sending PING commands
|
205 | to the broker for the purposes of informing it we are still
|
206 | connected and functioning. Defaults to 60 seconds.</para>
|
207 | </listitem>
|
208 | </varlistentry>
|
209 | <varlistentry>
|
210 | <term><option>--key</option></term>
|
211 | <listitem>
|
212 | <para>Define the path to a file containing a PEM encoded
|
213 | private key for this client, if required by the
|
214 | server.</para>
|
215 | <para>See also <option>--cert</option>.</para>
|
216 | </listitem>
|
217 | </varlistentry>
|
218 | <varlistentry>
|
219 | <term><option>-N</option></term>
|
220 | <listitem>
|
221 | <para>Do not append an end of line character to the payload
|
222 | when printing. This allows streaming of payload data
|
223 | from multiple messages directly to another application
|
224 | unmodified. Only really makes sense when not using
|
225 | <option>-v</option>.</para>
|
226 | </listitem>
|
227 | </varlistentry>
|
228 | <varlistentry>
|
229 | <term><option>-p</option></term>
|
230 | <term><option>--port</option></term>
|
231 | <listitem>
|
232 | <para>Connect to the port specified instead of the default 1883.</para>
|
233 | </listitem>
|
234 | </varlistentry>
|
235 | <varlistentry>
|
236 | <term><option>-P</option></term>
|
237 | <term><option>--pw</option></term>
|
238 | <listitem>
|
239 | <para>Provide a password to be used for authenticating with
|
240 | the broker. Using this argument without also specifying a
|
241 | username is invalid. This requires a broker that supports
|
242 | MQTT v3.1. See also the <option>--username</option> option.</para>
|
243 | </listitem>
|
244 | </varlistentry>
|
245 | <varlistentry>
|
246 | <term><option>--psk</option></term>
|
247 | <listitem>
|
248 | <para>Provide the hexadecimal (no leading 0x)
|
249 | pre-shared-key matching the one used on the broker to
|
250 | use TLS-PSK encryption support.
|
251 | <option>--psk-identity</option> must also be provided
|
252 | to enable TLS-PSK.</para>
|
253 | </listitem>
|
254 | </varlistentry>
|
255 | <varlistentry>
|
256 | <term><option>--psk-identity</option></term>
|
257 | <listitem>
|
258 | <para>The client identity to use with TLS-PSK support. This
|
259 | may be used instead of a username if the broker is
|
260 | configured to do so.</para>
|
261 | </listitem>
|
262 | </varlistentry>
|
263 | <varlistentry>
|
264 | <term><option>-q</option></term>
|
265 | <term><option>--qos</option></term>
|
266 | <listitem>
|
267 | <para>Specify the quality of service desired for the
|
268 | incoming messages, from 0, 1 and 2. Defaults to 0. See
|
269 | <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
270 | for more information on QoS.</para>
|
271 | <para>The QoS is identical for all topics subscribed to in
|
272 | a single instance of mosquitto_sub.</para>
|
273 | </listitem>
|
274 | </varlistentry>
|
275 | <varlistentry>
|
276 | <term><option>--quiet</option></term>
|
277 | <listitem>
|
278 | <para>If this argument is given, no runtime errors will be
|
279 | printed. This excludes any error messages given in case of
|
280 | invalid user input (e.g. using <option>--port</option> without a
|
281 | port).</para>
|
282 | </listitem>
|
283 | </varlistentry>
|
284 | <varlistentry>
|
285 | <term><option>-R</option></term>
|
286 | <listitem>
|
287 | <para>If this argument is given, messages that are received
|
288 | that have the retain bit set will not be printed.
|
289 | Messages with retain set are "stale", in that it is not
|
290 | known when they were originally published. When
|
291 | subscribing to a wildcard topic there may be a large
|
292 | number of retained messages. This argument suppresses
|
293 | their display.</para>
|
294 | </listitem>
|
295 | </varlistentry>
|
296 | <varlistentry>
|
297 | <term><option>-S</option></term>
|
298 | <listitem>
|
299 | <para>Use SRV lookups to determine which host to connect
|
300 | to. Performs lookups to
|
301 | <option>_mqtt._tcp.<host></option> when used in
|
302 | conjunction with <option>-h</option>, otherwise uses
|
303 | <option>_mqtt._tcp.<local dns
|
304 | domain></option>.</para>
|
305 | </listitem>
|
306 | </varlistentry>
|
307 | <varlistentry>
|
308 | <term><option>-t</option></term>
|
309 | <term><option>--topic</option></term>
|
310 | <listitem>
|
311 | <para>The MQTT topic to subscribe to. See
|
312 | <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
313 | for more information on MQTT topics.</para>
|
314 | <para>This option may be repeated to subscribe to multiple topics.</para>
|
315 | </listitem>
|
316 | </varlistentry>
|
317 | <varlistentry>
|
318 | <term><option>-T</option></term>
|
319 | <term><option>--filter-out</option></term>
|
320 | <listitem>
|
321 | <para>Suppress printing of topics that match the filter.
|
322 | This allows subscribing to a wildcard topic and only
|
323 | printing a partial set of the wildcard
|
324 | hierarchy.</para>
|
325 | <para>For example, subscribe to the BBC tree, but suppress output from Radio 3:</para>
|
326 | <itemizedlist mark="circle">
|
327 | <listitem><para>mosquitto_sub <literal>-t</literal>
|
328 | bbc/# <literal>-T</literal>
|
329 | bbc/radio3</para></listitem>
|
330 | </itemizedlist>
|
331 | <para>This option may be repeated to filter out multiple
|
332 | topics or topic trees.</para>
|
333 | </listitem>
|
334 | </varlistentry>
|
335 | <varlistentry>
|
336 | <term><option>--tls-version</option></term>
|
337 | <listitem>
|
338 | <para>Choose which TLS protocol version to use when
|
339 | communicating with the broker. Valid options are
|
340 | <option>tlsv1.2</option>, <option>tlsv1.1</option> and
|
341 | <option>tlsv1</option>. The default value is
|
342 | <option>tlsv1.2</option>. If the installed version of
|
343 | openssl is too old, only <option>tlsv1</option> will be
|
344 | available. Must match the protocol version used by the
|
345 | broker.</para>
|
346 | </listitem>
|
347 | </varlistentry>
|
348 | <varlistentry>
|
349 | <term><option>-u</option></term>
|
350 | <term><option>--username</option></term>
|
351 | <listitem>
|
352 | <para>Provide a username to be used for authenticating with
|
353 | the broker. This requires a broker that supports MQTT v3.1.
|
354 | See also the <option>--pw</option> argument.</para>
|
355 | </listitem>
|
356 | </varlistentry>
|
357 | <varlistentry>
|
358 | <term><option>-v</option></term>
|
359 | <term><option>--verbose</option></term>
|
360 | <listitem>
|
361 | <para>Print received messages verbosely. With this
|
362 | argument, messages will be printed as "topic payload". When
|
363 | this argument is not given, the messages are printed as
|
364 | "payload".</para>
|
365 | </listitem>
|
366 | </varlistentry>
|
367 | <varlistentry>
|
368 | <term><option>--will-payload</option></term>
|
369 | <listitem>
|
370 | <para>Specify a message that will be stored by the broker
|
371 | and sent out if this client disconnects unexpectedly. This
|
372 | must be used in conjunction with <option>--will-topic</option>.</para>
|
373 | </listitem>
|
374 | </varlistentry>
|
375 | <varlistentry>
|
376 | <term><option>--will-qos</option></term>
|
377 | <listitem>
|
378 | <para>The QoS to use for the Will. Defaults to 0. This must
|
379 | be used in conjunction with <option>--will-topic</option>.</para>
|
380 | </listitem>
|
381 | </varlistentry>
|
382 | <varlistentry>
|
383 | <term><option>--will-retain</option></term>
|
384 | <listitem>
|
385 | <para>If given, if the client disconnects unexpectedly the
|
386 | message sent out will be treated as a retained message.
|
387 | This must be used in conjunction with <option>--will-topic</option>.</para>
|
388 | </listitem>
|
389 | </varlistentry>
|
390 | <varlistentry>
|
391 | <term><option>--will-topic</option></term>
|
392 | <listitem>
|
393 | <para>The topic on which to send a Will, in the event that
|
394 | the client disconnects unexpectedly.</para>
|
395 | </listitem>
|
396 | </varlistentry>
|
397 | </variablelist>
|
398 | </refsect1>
|
399 |
|
400 | <refsect1>
|
401 | <title>Wills</title>
|
402 | <para>mosquitto_sub can register a message with the broker that will be
|
403 | sent out if it disconnects unexpectedly. See
|
404 | <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
405 | for more information.</para>
|
406 | <para>The minimum requirement for this is to use <option>--will-topic</option> to
|
407 | specify which topic the will should be sent out on. This will result in
|
408 | a non-retained, zero length message with QoS 0.</para>
|
409 | <para>Use the <option>--will-retain</option>, <option>--will-payload</option> and <option>--will-qos</option> arguments to
|
410 | modify the other will parameters.</para>
|
411 | </refsect1>
|
412 |
|
413 | <refsect1>
|
414 | <title>Examples</title>
|
415 | <para>Note that these really are examples - the subscriptions will work
|
416 | if you run them as shown, but there must be something publishing
|
417 | messages on those topics for you to receive anything.</para>
|
418 | <para>Subscribe to temperature information on localhost with QoS 1:</para>
|
419 | <itemizedlist mark="circle">
|
420 | <listitem><para>mosquitto_sub <literal>-t</literal> sensors/temperature <literal>-q</literal> 1</para></listitem>
|
421 | </itemizedlist>
|
422 | <para>Subscribe to hard drive temperature updates on multiple
|
423 | machines/hard drives. This expects each machine to be publishing its
|
424 | hard drive temperature to
|
425 | sensors/machines/HOSTNAME/temperature/HD_NAME.</para>
|
426 | <itemizedlist mark="circle">
|
427 | <listitem><para>mosquitto_sub <literal>-t</literal> sensors/machines/+/temperature/+</para></listitem>
|
428 | </itemizedlist>
|
429 | <para>Subscribe to all broker status messages:</para>
|
430 | <itemizedlist mark="circle">
|
431 | <listitem><para>mosquitto_sub <literal>-v</literal> <literal>-t</literal> \$SYS/#</para></listitem>
|
432 | </itemizedlist>
|
433 | </refsect1>
|
434 |
|
435 | <refsect1>
|
436 | <title>Bugs</title>
|
437 | <para><command>mosquitto_sub</command> bug information can be found at
|
438 | <uri type="webpage">http://launchpad.net/mosquitto</uri></para>
|
439 | </refsect1>
|
440 |
|
441 | <refsect1>
|
442 | <title>See Also</title>
|
443 | <simplelist type="inline">
|
444 | <member>
|
445 | <citerefentry>
|
446 | <refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
|
447 | <manvolnum>7</manvolnum>
|
448 | </citerefentry>
|
449 | </member>
|
450 | <member>
|
451 | <citerefentry>
|
452 | <refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
|
453 | <manvolnum>1</manvolnum>
|
454 | </citerefentry>
|
455 | </member>
|
456 | <member>
|
457 | <citerefentry>
|
458 | <refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
|
459 | <manvolnum>8</manvolnum>
|
460 | </citerefentry>
|
461 | </member>
|
462 | <member>
|
463 | <citerefentry>
|
464 | <refentrytitle><link xlink:href="libmosquitto-3.html">libmosquitto</link></refentrytitle>
|
465 | <manvolnum>3</manvolnum>
|
466 | </citerefentry>
|
467 | </member>
|
468 | <member>
|
469 | <citerefentry>
|
470 | <refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
|
471 | <manvolnum>7</manvolnum>
|
472 | </citerefentry>
|
473 | </member>
|
474 | </simplelist>
|
475 | </refsect1>
|
476 |
|
477 | <refsect1>
|
478 | <title>Acknowledgements</title>
|
479 | <para>This product includes software developed by the OpenSSL Project
|
480 | for use in the OpenSSL Toolkit. (http://www.openssl.org/)</para>
|
481 | <para>This product includes cryptographic software written by Eric
|
482 | Young (eay@cryptsoft.com)</para>
|
483 | <para>This product includes software written by Tim Hudson
|
484 | (tjh@cryptsoft.com)</para>
|
485 | </refsect1>
|
486 |
|
487 | <refsect1>
|
488 | <title>Author</title>
|
489 | <para>Roger Light <email>roger@atchoo.org</email></para>
|
490 | </refsect1>
|
491 | </refentry>
|