1MOSQUITTO_PUB(1)                   Commands                   MOSQUITTO_PUB(1)
2
3
4

NAME

6       mosquitto_pub - an MQTT version 5/3.1.1/3.1 client for publishing
7       simple messages
8

SYNOPSIS

10       mosquitto_pub
11                     {[-h hostname] [-p port-number] [-u username] [-P password] -t message-topic...
12                     | -L URL} [-A bind-address] [-c] [-d]
13                     [-D command identifier value] [-i client-id]
14                     [-I client-id-prefix] [-k keepalive-time]
15                     [-q message-QoS] [--quiet] [-r] [--repeat count]
16                     [--repeat-delay seconds] [-S] {-f file | -l | -m message
17                     | -n | -s}
18                     [--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]
19                     [[{--cafile file | --capath dir} [--cert file] [--key file] [--ciphers ciphers] [--tls-version version] [--tls-alpn protocol] [--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1] [--insecure]]
20                     |
21                     [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]
22                     [--proxy socks-url] [-V protocol-version]
23
24       mosquitto_pub [--help]
25

DESCRIPTION

27       mosquitto_pub is a simple MQTT version 5/3.1.1 client that will publish
28       a single message on a topic and exit.
29

ENCRYPTED CONNECTIONS

31       mosquitto_pub supports TLS encrypted connections. It is strongly
32       recommended that you use an encrypted connection for anything more than
33       the most basic setup.
34
35       To enable TLS connections when using x509 certificates, one of either
36       --cafile or --capath must be provided as an option.
37
38       To enable TLS connections when using TLS-PSK, you must use the --psk
39       and the --psk-identity options.
40

OPTIONS

42       The options below may be given on the command line, but may also be
43       placed in a config file located at $XDG_CONFIG_HOME/mosquitto_pub or
44       $HOME/.config/mosquitto_pub with one pair of -option value per line.
45       The values in the config file will be used as defaults and can be
46       overridden by using the command line. The exceptions to this are the
47       message type options, of which only one can be specified. Note also
48       that currently some options cannot be negated, e.g.  -S. Config file
49       lines that have a # as the first character are treated as comments and
50       not processed any further.
51
52       -A
53           Bind the outgoing connection to a local ip address/hostname. Use
54           this argument if you need to restrict network communication to a
55           particular interface.
56
57       -c, --disable-clean-session
58           Disable the 'clean session' flag. This means that all of the
59           subscriptions for the client will be maintained after it
60           disconnects, along with subsequent QoS 1 and QoS 2 messages that
61           arrive. When the client reconnects, it will receive all of the
62           queued messages.
63
64           If using this option, the client id must be set manually with --id
65
66       --cafile
67           Define the path to a file containing PEM encoded CA certificates
68           that are trusted. Used to enable SSL communication.
69
70           See also --capath
71
72       --capath
73           Define the path to a directory containing PEM encoded CA
74           certificates that are trusted. Used to enable SSL communication.
75
76           For --capath to work correctly, the certificate files must have
77           ".crt" as the file ending and you must run "openssl rehash <path to
78           capath>" each time you add/remove a certificate.
79
80           See also --cafile
81
82       --cert
83           Define the path to a file containing a PEM encoded certificate for
84           this client, if required by the server.
85
86           See also --key.
87
88       --ciphers
89           An openssl compatible list of TLS ciphers to support in the client.
90           See ciphers(1) for more information.
91
92       -d, --debug
93           Enable debug messages.
94
95       -D, --property
96           Use an MQTT v5 property with this publish. If you use this option,
97           the client will be set to be an MQTT v5 client. This option has two
98           forms:
99
100           -D command identifier value
101
102           -D command identifier name value
103
104           command is the MQTT command/packet identifier and can be one of
105           CONNECT, PUBLISH, PUBREL, DISCONNECT, AUTH, or WILL. The properties
106           available for each command are listed in the Properties section.
107
108           identifier is the name of the property to add. This is as described
109           in the specification, but with '-' as a word separator. For
110           example: payload-format-indicator. More details are in the
111           Properties section.
112
113           value is the value of the property to add, with a data type that is
114           property specific.
115
116           name is only used for the user-property property as the first of
117           the two strings in the string pair. In that case, value is the
118           second of the strings in the pair.
119
120       -f, --file
121           Send the contents of a file as the message.
122
123       --help
124           Display usage information.
125
126       -h, --host
127           Specify the host to connect to. Defaults to localhost.
128
129       -i, --id
130           The id to use for this client. If not given, a client id will be
131           generated depending on the MQTT version being used. For
132           v3.1.1/v3.1, the client generates a client id in the format
133           mosq-XXXXXXXXXXXXXXXXXX, where the X are replaced with random
134           alphanumeric characters. For v5.0, the client sends a zero length
135           client id, and the server will generate a client id for the client.
136
137           This option cannot be used at the same time as the --id-prefix
138           argument.
139
140       -I, --id-prefix
141           Provide a prefix that the client id will be built from by appending
142           the process id of the client. This is useful where the broker is
143           using the clientid_prefixes option. Cannot be used at the same time
144           as the --id argument.
145
146       --insecure
147           When using certificate based encryption, this option disables
148           verification of the server hostname in the server certificate. This
149           can be useful when testing initial server configurations but makes
150           it possible for a malicious third party to impersonate your server
151           through DNS spoofing, for example. Use this option in testing only.
152           If you need to resort to using this option in a production
153           environment, your setup is at fault and there is no point using
154           encryption.
155
156       -k, --keepalive
157           The number of seconds between sending PING commands to the broker
158           for the purposes of informing it we are still connected and
159           functioning. Defaults to 60 seconds.
160
161       --key
162           Define the path to a file containing a PEM encoded private key for
163           this client, if required by the server.
164
165           See also --cert.
166
167       --keyform
168           Specifies the type of private key in use when making TLS
169           connections.. This can be "pem" or "engine". This parameter is
170           useful when a TPM module is being used and the private key has been
171           created with it. Defaults to "pem", which means normal private key
172           files are used.
173
174           See also --tls-engine.
175
176       -L, --url
177           Specify specify user, password, hostname, port and topic at once as
178           a URL. The URL must be in the form:
179           mqtt(s)://[username[:password]@]host[:port]/topic
180
181           If the scheme is mqtt:// then the port defaults to 1883. If the
182           scheme is mqtts:// then the port defaults to 8883.
183
184       -l, --stdin-line
185           Send messages read from stdin, splitting separate lines into
186           separate messages.
187
188       -m, --message
189           Send a single message from the command line.
190
191       -n, --null-message
192           Send a null (zero length) message.
193
194       -p, --port
195           Connect to the port specified. If not given, the default of 1883
196           for plain MQTT or 8883 for MQTT over TLS will be used.
197
198       -P, --pw
199           Provide a password to be used for authenticating with the broker.
200           Using this argument without also specifying a username is invalid
201           when using MQTT v3.1 or v3.1.1. See also the --username option.
202
203       --proxy
204           Specify a SOCKS5 proxy to connect through. "None" and "username"
205           authentication types are supported. The socks-url must be of the
206           form socks5h://[username[:password]@]host[:port]. The protocol
207           prefix socks5h means that hostnames are resolved by the proxy. The
208           symbols %25, %3A and %40 are URL decoded into %, : and @
209           respectively, if present in the username or password.
210
211           If username is not given, then no authentication is attempted. If
212           the port is not given, then the default of 1080 is used.
213
214           More SOCKS versions may be available in the future, depending on
215           demand, and will use different protocol prefixes as described in
216           curl(1).
217
218       --psk
219           Provide the hexadecimal (no leading 0x) pre-shared-key matching the
220           one used on the broker to use TLS-PSK encryption support.
221           --psk-identity must also be provided to enable TLS-PSK.
222
223       --psk-identity
224           The client identity to use with TLS-PSK support. This may be used
225           instead of a username if the broker is configured to do so.
226
227       -q, --qos
228           Specify the quality of service to use for the message, from 0, 1
229           and 2. Defaults to 0.
230
231       --quiet
232           If this argument is given, no runtime errors will be printed. This
233           excludes any error messages given in case of invalid user input
234           (e.g. using --port without a port).
235
236       -r, --retain
237           If retain is given, the message will be retained as a "last known
238           good" value on the broker. See mqtt(7) for more information.
239
240       --repeat
241           If the publish mode is-m, -f, or -s (i.e. the modes where only a
242           single message is sent), then --repeat can be used to specify that
243           the message will be published multiple times.
244
245           See also --repeat-delay.
246
247       --repeat-delay
248           If using --repeat, then the default behaviour is to publish
249           repeated messages as soon as the previous message is delivered. Use
250           --repeat-delay to specify the number of seconds to wait after the
251           previous message was delivered before publishing the next. Does not
252           need to be an integer number of seconds.
253
254           Note that there is no guarantee as to the actual interval between
255           messages, this option simply defines the minimum time from delivery
256           of one message to the start of the publish of the next.
257
258       -s, --stdin-file
259           Send a message read from stdin, sending the entire content as a
260           single message.
261
262       -S
263           Use SRV lookups to determine which host to connect to. Performs
264           lookups to _mqtt._tcp.<host> when used in conjunction with -h,
265           otherwise uses _mqtt._tcp.<local dns domain>.
266
267       -t, --topic
268           The MQTT topic on which to publish the message. See mqtt(7) for
269           more information on MQTT topics.
270
271       --tls-alpn
272           Provide a protocol to use when connecting to a broker that has
273           multiple protocols available on a single port, e.g. MQTT and
274           WebSockets.
275
276       --tls-engine
277           A valid openssl engine id. These can be listed with openssl engine
278           command.
279
280           See also --keyform.
281
282       --tls-engine-kpass-sha1
283           SHA1 of the private key password when using an TLS engine. Some TLS
284           engines such as the TPM engine may require the use of a password in
285           order to be accessed. This option allows a hex encoded SHA1 hash of
286           the password to the engine directly, instead of the user being
287           prompted for the password.
288
289           See also --tls-engine.
290
291       --tls-version
292           Choose which TLS protocol version to use when communicating with
293           the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
294           default value is tlsv1.2. Must match the protocol version used by
295           the broker.
296
297       -u, --username
298           Provide a username to be used for authenticating with the broker.
299           See also the --pw argument.
300
301       -V, --protocol-version
302           Specify which version of the MQTT protocol should be used when
303           connecting to the rmeote broker. Can be 5, 311, 31, or the more
304           verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
305
306       --will-payload
307           Specify a message that will be stored by the broker and sent out if
308           this client disconnects unexpectedly. This must be used in
309           conjunction with --will-topic.
310
311       --will-qos
312           The QoS to use for the Will. Defaults to 0. This must be used in
313           conjunction with --will-topic.
314
315       --will-retain
316           If given, if the client disconnects unexpectedly the message sent
317           out will be treated as a retained message. This must be used in
318           conjunction with --will-topic.
319
320       --will-topic
321           The topic on which to send a Will, in the event that the client
322           disconnects unexpectedly.
323

WILLS

325       mosquitto_sub can register a message with the broker that will be sent
326       out if it disconnects unexpectedly. See mqtt(7) for more information.
327
328       The minimum requirement for this is to use --will-topic to specify
329       which topic the will should be sent out on. This will result in a
330       non-retained, zero length message with QoS 0.
331
332       Use the --will-retain, --will-payload and --will-qos arguments to
333       modify the other will parameters.
334

PROPERTIES

336       The -D / --property option allows adding properties to different stages
337       of the mosquitto_pub run. The properties supported for each command are
338       as follows:
339
340   Connect
341       ·   authentication-data (binary data - note treated as a string in
342           mosquitto_pub)
343
344       ·   authentication-method (UTF-8 string pair)
345
346       ·   maximum-packet-size (32-bit unsigned integer)
347
348       ·   receive-maximum (16-bit unsigned integer)
349
350       ·   request-problem-information (8-bit unsigned integer)
351
352       ·   request-response-information (8-bit unsigned integer)
353
354       ·   session-expiry-interval (32-bit unsigned integer)
355
356       ·   topic-alias-maximum (16-bit unsigned integer)
357
358       ·   user-property (UTF-8 string pair)
359
360   Publish
361       ·   content-type (UTF-8 string)
362
363       ·   correlation-data (binary data - note treated as a string in
364           mosquitto_pub)
365
366       ·   message-expiry-interval (32-bit unsigned integer)
367
368       ·   payload-format-indicator (8-bit unsigned integer)
369
370       ·   response-topic (UTF-8 string)
371
372       ·   topic-alias (16-bit unsigned integer)
373
374       ·   user-property (UTF-8 string pair)
375
376   Disconnect
377       ·   session-expiry-interval (32-bit unsigned integer)
378
379       ·   user-property (UTF-8 string pair)
380
381   Will properties
382       ·   content-type (UTF-8 string)
383
384       ·   correlation-data (binary data - note treated as a string in
385           mosquitto_pub)
386
387       ·   message-expiry-interval (32-bit unsigned integer)
388
389       ·   payload-format-indicator (8-bit unsigned integer)
390
391       ·   response-topic (UTF-8 string)
392
393       ·   user-property (UTF-8 string pair)
394
395       ·   will-delay-interval (32-bit unsigned integer)
396

EXAMPLES

398       Publish temperature information to localhost with QoS 1:
399
400       ·   mosquitto_pub -t sensors/temperature -m 32 -q 1
401
402       Publish timestamp and temperature information to a remote host on a
403       non-standard port and QoS 0:
404
405       ·   mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
406           "1266193804 32"
407
408       Publish light switch status. Message is set to retained because there
409       may be a long period of time between light switch events:
410
411       ·   mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
412
413       Send the contents of a file in two ways:
414
415       ·   mosquitto_pub -t my/topic -f ./data
416
417       ·   mosquitto_pub -t my/topic -s < ./data
418
419       Send parsed electricity usage data from a Current Cost meter, reading
420       from stdin with one line/reading as one message:
421
422       ·   read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
423

FILES

425       $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
426           Configuration file for default options.
427

BUGS

429       mosquitto bug information can be found at
430       https://github.com/eclipse/mosquitto/issues
431

SEE ALSO

433       mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
434       libmosquitto(3), mosquitto-tls(7)
435

AUTHOR

437       Roger Light <roger@atchoo.org>
438
439
440
441Mosquitto Project                 02/27/2020                  MOSQUITTO_PUB(1)
Impressum