1 | <?xml version='1.0' encoding='UTF-8'?>
|
2 | <?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
3 |
|
4 | <refentry xml:id="mosquitto_pub" xmlns:xlink="http://www.w3.org/1999/xlink">
|
5 | <refmeta>
|
6 | <refentrytitle>mosquitto_pub</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_pub</refname>
|
14 | <refpurpose>an MQTT version 3.1 client for publishing simple messages</refpurpose>
|
15 | </refnamediv>
|
16 |
|
17 | <refsynopsisdiv>
|
18 | <cmdsynopsis>
|
19 | <command>mosquitto_pub</command>
|
20 | <arg><option>-A</option> <replaceable>bind_address</replaceable></arg>
|
21 | <arg><option>-d</option></arg>
|
22 | <arg><option>-h</option> <replaceable>hostname</replaceable></arg>
|
23 | <arg><option>-i</option> <replaceable>client_id</replaceable></arg>
|
24 | <arg><option>-I</option> <replaceable>client id prefix</replaceable></arg>
|
25 | <arg><option>-p</option> <replaceable>port number</replaceable></arg>
|
26 | <arg><option>-q</option> <replaceable>message QoS</replaceable></arg>
|
27 | <arg><option>--quiet</option></arg>
|
28 | <arg><option>-r</option></arg>
|
29 | <arg><option>-S</option></arg>
|
30 | <group choice='req'>
|
31 | <arg choice='plain'><option>-f</option> <replaceable>file</replaceable></arg>
|
32 | <arg choice='plain'><option>-l</option></arg>
|
33 | <arg choice='plain'><option>-m</option> <replaceable>message</replaceable></arg>
|
34 | <arg choice='plain'><option>-n</option></arg>
|
35 | <arg choice='plain'><option>-s</option></arg>
|
36 | </group>
|
37 | <arg>
|
38 | <arg><option>-u</option> <replaceable>username</replaceable></arg>
|
39 | <arg><option>-P</option> <replaceable>password</replaceable></arg>
|
40 | </arg>
|
41 | <arg>
|
42 | <option>--will-topic</option> <replaceable>topic</replaceable>
|
43 | <arg><option>--will-payload</option> <replaceable>payload</replaceable></arg>
|
44 | <arg><option>--will-qos</option> <replaceable>qos</replaceable></arg>
|
45 | <arg><option>--will-retain</option></arg>
|
46 | </arg>
|
47 | <group>
|
48 | <arg>
|
49 | <group choice='req'>
|
50 | <arg choice='plain'><option>--cafile</option> <replaceable>file</replaceable></arg>
|
51 | <arg choice='plain'><option>--capath</option> <replaceable>dir</replaceable></arg>
|
52 | </group>
|
53 | <arg><option>--cert</option> <replaceable>file</replaceable></arg>
|
54 | <arg><option>--key</option> <replaceable>file</replaceable></arg>
|
55 | <arg><option>--ciphers</option> <replaceable>ciphers</replaceable></arg>
|
56 | <arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
57 | <arg><option>--insecure</option></arg>
|
58 | </arg>
|
59 | <arg>
|
60 | <arg choice='plain'><option>--psk</option> <replaceable>hex-key</replaceable></arg>
|
61 | <arg choice='plain'><option>--psk-identity</option> <replaceable>identity</replaceable></arg>
|
62 | <arg><option>--ciphers</option> <replaceable>ciphers</replaceable></arg>
|
63 | <arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
64 | </arg>
|
65 | </group>
|
66 | <arg choice='plain'><option>-t</option> <replaceable>message-topic</replaceable></arg>
|
67 | </cmdsynopsis>
|
68 | <cmdsynopsis>
|
69 | <command>mosquitto_pub</command>
|
70 | <group choice='plain'>
|
71 | <arg><option>--help</option></arg>
|
72 | </group>
|
73 | </cmdsynopsis>
|
74 | </refsynopsisdiv>
|
75 |
|
76 | <refsect1>
|
77 | <title>Description</title>
|
78 | <para><command>mosquitto_pub</command> is a simple MQTT version 3.1 client that will publish a single message on a topic and exit.</para>
|
79 | </refsect1>
|
80 |
|
81 | <refsect1>
|
82 | <title>Options</title>
|
83 | <variablelist>
|
84 | <varlistentry>
|
85 | <term><option>-A</option></term>
|
86 | <listitem>
|
87 | <para>Bind the outgoing connection to a local ip
|
88 | address/hostname. Use this argument if you need to
|
89 | restrict network communication to a particular
|
90 | interface.</para>
|
91 | </listitem>
|
92 | </varlistentry>
|
93 | <varlistentry>
|
94 | <term><option>--cafile</option></term>
|
95 | <listitem>
|
96 | <para>Define the path to a file containing PEM encoded CA
|
97 | certificates that are trusted. Used to enable SSL
|
98 | communication.</para>
|
99 | <para>See also <option>--capath</option></para>
|
100 | </listitem>
|
101 | </varlistentry>
|
102 | <varlistentry>
|
103 | <term><option>--capath</option></term>
|
104 | <listitem>
|
105 | <para>Define the path to a directory containing PEM encoded CA
|
106 | certificates that are trusted. Used to enable SSL
|
107 | communication.</para>
|
108 | <para>For <option>--capath</option> to work correctly, the
|
109 | certificate files must have ".crt" as the file ending
|
110 | and you must run "c_rehash <path to capath>" each
|
111 | time you add/remove a certificate.</para>
|
112 | <para>See also <option>--cafile</option></para>
|
113 | </listitem>
|
114 | </varlistentry>
|
115 | <varlistentry>
|
116 | <term><option>--cert</option></term>
|
117 | <listitem>
|
118 | <para>Define the path to a file containing a PEM encoded
|
119 | certificate for this client, if required by the
|
120 | server.</para>
|
121 | <para>See also <option>--key</option>.</para>
|
122 | </listitem>
|
123 | </varlistentry>
|
124 | <varlistentry>
|
125 | <term><option>--ciphers</option></term>
|
126 | <listitem>
|
127 | <para>An openssl compatible list of TLS ciphers to support
|
128 | in the client. See
|
129 | <citerefentry><refentrytitle>ciphers</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
130 | for more information.</para>
|
131 | </listitem>
|
132 | </varlistentry>
|
133 | <varlistentry>
|
134 | <term><option>-d</option></term>
|
135 | <term><option>--debug</option></term>
|
136 | <listitem>
|
137 | <para>Enable debug messages.</para>
|
138 | </listitem>
|
139 | </varlistentry>
|
140 | <varlistentry>
|
141 | <term><option>-f</option></term>
|
142 | <term><option>--file</option></term>
|
143 | <listitem>
|
144 | <para>Send the contents of a file as the message.</para>
|
145 | </listitem>
|
146 | </varlistentry>
|
147 | <varlistentry>
|
148 | <term><option>--help</option></term>
|
149 | <listitem>
|
150 | <para>Display usage information.</para>
|
151 | </listitem>
|
152 | </varlistentry>
|
153 | <varlistentry>
|
154 | <term><option>-h</option></term>
|
155 | <term><option>--host</option></term>
|
156 | <listitem>
|
157 | <para>Specify the host to connect to. Defaults to localhost.</para>
|
158 | </listitem>
|
159 | </varlistentry>
|
160 | <varlistentry>
|
161 | <term><option>-i</option></term>
|
162 | <term><option>--id</option></term>
|
163 | <listitem>
|
164 | <para>The id to use for this client. If not given, defaults
|
165 | to mosquitto_pub_ appended with the process id of the
|
166 | client. Cannot be used at the same time as the
|
167 | <option>--id-prefix</option> argument.</para>
|
168 | </listitem>
|
169 | </varlistentry>
|
170 | <varlistentry>
|
171 | <term><option>-I</option></term>
|
172 | <term><option>--id-prefix</option></term>
|
173 | <listitem>
|
174 | <para>Provide a prefix that the client id will be built
|
175 | from by appending the process id of the client. This is
|
176 | useful where the broker is using the clientid_prefixes
|
177 | option. Cannot be used at the same time as the
|
178 | <option>--id</option> argument.</para>
|
179 | </listitem>
|
180 | </varlistentry>
|
181 | <varlistentry>
|
182 | <term><option>--insecure</option></term>
|
183 | <listitem>
|
184 | <para>When using certificate based encryption, this option
|
185 | disables verification of the server hostname in the
|
186 | server certificate. This can be useful when testing
|
187 | initial server configurations but makes it possible for
|
188 | a malicious third party to impersonate your server
|
189 | through DNS spoofing, for example. Use this option in
|
190 | testing <emphasis>only</emphasis>. If you need to
|
191 | resort to using this option in a production
|
192 | environment, your setup is at fault and there is no
|
193 | point using encryption.</para>
|
194 | </listitem>
|
195 | </varlistentry>
|
196 | <varlistentry>
|
197 | <term><option>--key</option></term>
|
198 | <listitem>
|
199 | <para>Define the path to a file containing a PEM encoded
|
200 | private key for this client, if required by the
|
201 | server.</para>
|
202 | <para>See also <option>--cert</option>.</para>
|
203 | </listitem>
|
204 | </varlistentry>
|
205 | <varlistentry>
|
206 | <term><option>-l</option></term>
|
207 | <term><option>--stdin-line</option></term>
|
208 | <listitem>
|
209 | <para>Send messages read from stdin, splitting separate lines into separate messages. Note that blank lines won't be sent.</para>
|
210 | </listitem>
|
211 | </varlistentry>
|
212 | <varlistentry>
|
213 | <term><option>-m</option></term>
|
214 | <term><option>--message</option></term>
|
215 | <listitem>
|
216 | <para>Send a single message from the command line.</para>
|
217 | </listitem>
|
218 | </varlistentry>
|
219 | <varlistentry>
|
220 | <term><option>-n</option></term>
|
221 | <term><option>--null-message</option></term>
|
222 | <listitem>
|
223 | <para>Send a null (zero length) message.</para>
|
224 | </listitem>
|
225 | </varlistentry>
|
226 | <varlistentry>
|
227 | <term><option>-p</option></term>
|
228 | <term><option>--port</option></term>
|
229 | <listitem>
|
230 | <para>Connect to the port specified instead of the default 1883.</para>
|
231 | </listitem>
|
232 | </varlistentry>
|
233 | <varlistentry>
|
234 | <term><option>-P</option></term>
|
235 | <term><option>--pw</option></term>
|
236 | <listitem>
|
237 | <para>Provide a password to be used for authenticating with
|
238 | the broker. Using this argument without also specifying a
|
239 | username is invalid. This requires a broker that supports
|
240 | MQTT v3.1. See also the <option>--username</option> option.</para>
|
241 | </listitem>
|
242 | </varlistentry>
|
243 | <varlistentry>
|
244 | <term><option>--psk</option></term>
|
245 | <listitem>
|
246 | <para>Provide the hexadecimal (no leading 0x)
|
247 | pre-shared-key matching the one used on the broker to
|
248 | use TLS-PSK encryption support.
|
249 | <option>--psk-identity</option> must also be provided
|
250 | to enable TLS-PSK.</para>
|
251 | </listitem>
|
252 | </varlistentry>
|
253 | <varlistentry>
|
254 | <term><option>--psk-identity</option></term>
|
255 | <listitem>
|
256 | <para>The client identity to use with TLS-PSK support. This
|
257 | may be used instead of a username if the broker is
|
258 | configured to do so.</para>
|
259 | </listitem>
|
260 | </varlistentry>
|
261 | <varlistentry>
|
262 | <term><option>-q</option></term>
|
263 | <term><option>--qos</option></term>
|
264 | <listitem>
|
265 | <para>Specify the quality of service to use for the message, from 0, 1 and 2. Defaults to 0.</para>
|
266 | </listitem>
|
267 | </varlistentry>
|
268 | <varlistentry>
|
269 | <term><option>--quiet</option></term>
|
270 | <listitem>
|
271 | <para>If this argument is given, no runtime errors will be
|
272 | printed. This excludes any error messages given in case of
|
273 | invalid user input (e.g. using <option>--port</option> without a
|
274 | port).</para>
|
275 | </listitem>
|
276 | </varlistentry>
|
277 | <varlistentry>
|
278 | <term><option>-r</option></term>
|
279 | <term><option>--retain</option></term>
|
280 | <listitem>
|
281 | <para>If retain is given, the message will be retained as a "last known good" value on the broker. See <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more information.</para>
|
282 | </listitem>
|
283 | </varlistentry>
|
284 | <varlistentry>
|
285 | <term><option>-s</option></term>
|
286 | <term><option>--stdin-file</option></term>
|
287 | <listitem>
|
288 | <para>Send a message read from stdin, sending the entire content as a single message.</para>
|
289 | </listitem>
|
290 | </varlistentry>
|
291 | <varlistentry>
|
292 | <term><option>-S</option></term>
|
293 | <listitem>
|
294 | <para>Use SRV lookups to determine which host to connect
|
295 | to. Performs lookups to
|
296 | <option>_mqtt._tcp.<host></option> when used in
|
297 | conjunction with <option>-h</option>, otherwise uses
|
298 | <option>_mqtt._tcp.<local dns
|
299 | domain></option>.</para>
|
300 | </listitem>
|
301 | </varlistentry>
|
302 | <varlistentry>
|
303 | <term><option>-t</option></term>
|
304 | <term><option>--topic</option></term>
|
305 | <listitem>
|
306 | <para>The MQTT topic on which to publish the message. See <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more information on MQTT topics.</para>
|
307 | </listitem>
|
308 | </varlistentry>
|
309 | <varlistentry>
|
310 | <term><option>--tls-version</option></term>
|
311 | <listitem>
|
312 | <para>Choose which TLS protocol version to use when
|
313 | communicating with the broker. Valid options are
|
314 | <option>tlsv1.2</option>, <option>tlsv1.1</option> and
|
315 | <option>tlsv1</option>. The default value is
|
316 | <option>tlsv1.2</option>. If the installed version of
|
317 | openssl is too old, only <option>tlsv1</option> will be
|
318 | available. Must match the protocol version used by the
|
319 | broker.</para>
|
320 | </listitem>
|
321 | </varlistentry>
|
322 | <varlistentry>
|
323 | <term><option>-u</option></term>
|
324 | <term><option>--username</option></term>
|
325 | <listitem>
|
326 | <para>Provide a username to be used for authenticating with
|
327 | the broker. This requires a broker that supports MQTT v3.1.
|
328 | See also the <option>--pw</option> argument.</para>
|
329 | </listitem>
|
330 | </varlistentry>
|
331 | <varlistentry>
|
332 | <term><option>--will-payload</option></term>
|
333 | <listitem>
|
334 | <para>Specify a message that will be stored by the broker
|
335 | and sent out if this client disconnects unexpectedly. This
|
336 | must be used in conjunction with <option>--will-topic</option>.</para>
|
337 | </listitem>
|
338 | </varlistentry>
|
339 | <varlistentry>
|
340 | <term><option>--will-qos</option></term>
|
341 | <listitem>
|
342 | <para>The QoS to use for the Will. Defaults to 0. This must
|
343 | be used in conjunction with <option>--will-topic</option>.</para>
|
344 | </listitem>
|
345 | </varlistentry>
|
346 | <varlistentry>
|
347 | <term><option>--will-retain</option></term>
|
348 | <listitem>
|
349 | <para>If given, if the client disconnects unexpectedly the
|
350 | message sent out will be treated as a retained message.
|
351 | This must be used in conjunction with <option>--will-topic</option>.</para>
|
352 | </listitem>
|
353 | </varlistentry>
|
354 | <varlistentry>
|
355 | <term><option>--will-topic</option></term>
|
356 | <listitem>
|
357 | <para>The topic on which to send a Will, in the event that
|
358 | the client disconnects unexpectedly.</para>
|
359 | </listitem>
|
360 | </varlistentry>
|
361 | </variablelist>
|
362 | </refsect1>
|
363 |
|
364 | <refsect1>
|
365 | <title>Wills</title>
|
366 | <para>mosquitto_sub can register a message with the broker that will be
|
367 | sent out if it disconnects unexpectedly. See
|
368 | <citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
369 | for more information.</para>
|
370 | <para>The minimum requirement for this is to use <option>--will-topic</option> to
|
371 | specify which topic the will should be sent out on. This will result in
|
372 | a non-retained, zero length message with QoS 0.</para>
|
373 | <para>Use the <option>--will-retain</option>,
|
374 | <option>--will-payload</option> and <option>--will-qos</option>
|
375 | arguments to modify the other will parameters.</para>
|
376 | </refsect1>
|
377 |
|
378 | <refsect1>
|
379 | <title>Examples</title>
|
380 | <para>Publish temperature information to localhost with QoS 1:</para>
|
381 | <itemizedlist mark="circle">
|
382 | <listitem><para>mosquitto_pub <literal>-t</literal> sensors/temperature <literal>-m</literal> 32 <literal>-q</literal> 1</para></listitem>
|
383 | </itemizedlist>
|
384 | <para>Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0:</para>
|
385 | <itemizedlist mark="circle">
|
386 | <listitem><para>mosquitto_pub <literal>-h</literal> 192.168.1.1
|
387 | <literal>-p</literal> 1885 <literal>-t</literal>
|
388 | sensors/temperature <literal>-m</literal> "1266193804
|
389 | 32"</para></listitem>
|
390 | </itemizedlist>
|
391 | <para>Publish light switch status. Message is set to retained because there may be a long period of time between light switch events:</para>
|
392 | <itemizedlist mark="circle">
|
393 | <listitem><para>mosquitto_pub <literal>-r</literal> <literal>-t</literal> switches/kitchen_lights/status <literal>-m</literal> "on"</para></listitem>
|
394 | </itemizedlist>
|
395 | <para>Send the contents of a file in two ways:</para>
|
396 | <itemizedlist mark="circle">
|
397 | <listitem><para>mosquitto_pub <literal>-t</literal> my/topic <literal>-f</literal> ./data</para></listitem>
|
398 | <listitem><para>mosquitto_pub <literal>-t</literal> my/topic <literal>-s</literal> < ./data</para></listitem>
|
399 | </itemizedlist>
|
400 | <para>Send parsed electricity usage data from a Current Cost meter, reading from stdin with one line/reading as one message:</para>
|
401 | <itemizedlist mark="circle">
|
402 | <listitem><para>read_cc128.pl | mosquitto_pub <literal>-t</literal> sensors/cc128 <literal>-l</literal></para></listitem>
|
403 | </itemizedlist>
|
404 | </refsect1>
|
405 |
|
406 | <refsect1>
|
407 | <title>Bugs</title>
|
408 | <para><command>mosquitto_pub</command> bug information can be found at <uri type="webpage">http://launchpad.net/mosquitto</uri></para>
|
409 | </refsect1>
|
410 |
|
411 | <refsect1>
|
412 | <title>See Also</title>
|
413 | <simplelist type="inline">
|
414 | <member>
|
415 | <citerefentry>
|
416 | <refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
|
417 | <manvolnum>7</manvolnum>
|
418 | </citerefentry>
|
419 | </member>
|
420 | <member>
|
421 | <citerefentry>
|
422 | <refentrytitle><link xlink:href="mosquitto_sub-1.html">mosquitto_sub</link></refentrytitle>
|
423 | <manvolnum>1</manvolnum>
|
424 | </citerefentry>
|
425 | </member>
|
426 | <member>
|
427 | <citerefentry>
|
428 | <refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
|
429 | <manvolnum>8</manvolnum>
|
430 | </citerefentry>
|
431 | </member>
|
432 | <member>
|
433 | <citerefentry>
|
434 | <refentrytitle><link xlink:href="libmosquitto-3.html">libmosquitto</link></refentrytitle>
|
435 | <manvolnum>3</manvolnum>
|
436 | </citerefentry>
|
437 | </member>
|
438 | <member>
|
439 | <citerefentry>
|
440 | <refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
|
441 | <manvolnum>7</manvolnum>
|
442 | </citerefentry>
|
443 | </member>
|
444 | </simplelist>
|
445 | </refsect1>
|
446 |
|
447 | <refsect1>
|
448 | <title>Acknowledgements</title>
|
449 | <para>This product includes software developed by the OpenSSL Project
|
450 | for use in the OpenSSL Toolkit. (http://www.openssl.org/)</para>
|
451 | <para>This product includes cryptographic software written by Eric
|
452 | Young (eay@cryptsoft.com)</para>
|
453 | <para>This product includes software written by Tim Hudson
|
454 | (tjh@cryptsoft.com)</para>
|
455 | </refsect1>
|
456 |
|
457 | <refsect1>
|
458 | <title>Author</title>
|
459 | <para>Roger Light <email>roger@atchoo.org</email></para>
|
460 | </refsect1>
|
461 | </refentry>
|