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] [--unix socket path] [-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] [--nodelay]
15                     [-q message-QoS] [--quiet] [-r] [--repeat count]
16                     [--repeat-delay seconds] [-S] [-V protocol-version]
17                     [-x session-expiry-interval] {-f file | -l | -m message |
18                     -n | -s}
19                     [--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]
20                     [[{--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] [--tls-use-os-certs] [--insecure]]
21                     |
22                     [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]
23                     [--proxy socks-url]
24
25       mosquitto_pub [--help]
26

DESCRIPTION

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

ENCRYPTED CONNECTIONS

32       mosquitto_pub supports TLS encrypted connections. It is strongly
33       recommended that you use an encrypted connection for anything more than
34       the most basic setup.
35
36       To enable TLS connections when using x509 certificates, one of either
37       --cafile or --capath can be provided as an option.
38
39       Alternatively, if the -p 8883 option is used then the OS provided
40       certificates will be loaded and neither --cafile or --capath are needed
41
42       To enable TLS connections when using TLS-PSK, you must use the --psk
43       and the --psk-identity options.
44

OPTIONS

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

WILLS

373       mosquitto_sub can register a message with the broker that will be sent
374       out if it disconnects unexpectedly. See mqtt(7) for more information.
375
376       The minimum requirement for this is to use --will-topic to specify
377       which topic the will should be sent out on. This will result in a
378       non-retained, zero length message with QoS 0.
379
380       Use the --will-retain, --will-payload and --will-qos arguments to
381       modify the other will parameters.
382

PROPERTIES

384       The -D / --property option allows adding properties to different stages
385       of the mosquitto_pub run. The properties supported for each command are
386       as follows:
387
388   Connect
389authentication-data (binary data - note treated as a string in
390           mosquitto_pub)
391
392authentication-method (UTF-8 string pair)
393
394maximum-packet-size (32-bit unsigned integer)
395
396receive-maximum (16-bit unsigned integer)
397
398request-problem-information (8-bit unsigned integer)
399
400request-response-information (8-bit unsigned integer)
401
402session-expiry-interval (32-bit unsigned integer, note use -x
403           instead)
404
405topic-alias-maximum (16-bit unsigned integer)
406
407user-property (UTF-8 string pair)
408
409   Publish
410content-type (UTF-8 string)
411
412correlation-data (binary data - note treated as a string in
413           mosquitto_pub)
414
415message-expiry-interval (32-bit unsigned integer)
416
417payload-format-indicator (8-bit unsigned integer)
418
419response-topic (UTF-8 string)
420
421topic-alias (16-bit unsigned integer)
422
423user-property (UTF-8 string pair)
424
425   Disconnect
426session-expiry-interval (32-bit unsigned integer)
427
428user-property (UTF-8 string pair)
429
430   Will properties
431content-type (UTF-8 string)
432
433correlation-data (binary data - note treated as a string in
434           mosquitto_pub)
435
436message-expiry-interval (32-bit unsigned integer)
437
438payload-format-indicator (8-bit unsigned integer)
439
440response-topic (UTF-8 string)
441
442user-property (UTF-8 string pair)
443
444will-delay-interval (32-bit unsigned integer)
445

EXIT STATUS

447       mosquitto_sub returns zero on success, or non-zero on error. If the
448       connection is refused by the broker at the MQTT level, then the exit
449       code is the CONNACK reason code. If another error occurs, the exit code
450       is a libmosquitto return value.
451
452       MQTT v3.1.1 CONNACK codes:
453
4540 Success
455
4561 Connection refused: Bad protocol version
457
4582 Connection refused: Identifier rejected
459
4603 Connection refused: Server unavailable
461
4624 Connection refused: Bad username/password
463
4645 Connection refused: Not authorized
465
466       MQTT v5 CONNACK codes:
467
4680 Success
469
470128 Unspecified error
471
472129 Malformed packet
473
474130 Protocol error
475
476131 Implementation specific error
477
478132 Unsupported protocol version
479
480133 Client ID not valid
481
482134 Bad username or password
483
484135 Not authorized
485
486136 Server unavailable
487
488137 Server busy
489
490138 Banned
491
492139 Server shutting down
493
494140 Bad authentication method
495
496141 Keep alive timeout
497
498142 Session taken over
499
500143 Topic filter invalid
501
502144 Topic name invalid
503
504147 Receive maximum exceeded
505
506148 Topic alias invalid
507
508149 Packet too large
509
510148 Message rate too high
511
512151 Quota exceeded
513
514152 Administrative action
515
516153 Payload format invalid
517
518154 Retain not supported
519
520155 QoS not supported
521
522156 Use another server
523
524157 Server moved
525
526158 Shared subscriptions not supported
527
528159 Connection rate exceeded
529
530160 Maximum connect time
531
532161 Subscription IDs not supported
533
534162 Wildcard subscriptions not supported
535

EXAMPLES

537       Publish temperature information to localhost with QoS 1:
538
539       •   mosquitto_pub -t sensors/temperature -m 32 -q 1
540
541       Publish timestamp and temperature information to a remote host on a
542       non-standard port and QoS 0:
543
544       •   mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
545           "1266193804 32"
546
547       Publish light switch status. Message is set to retained because there
548       may be a long period of time between light switch events:
549
550       •   mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
551
552       Send the contents of a file in two ways:
553
554       •   mosquitto_pub -t my/topic -f ./data
555
556       •   mosquitto_pub -t my/topic -s < ./data
557
558       Send parsed electricity usage data from a Current Cost meter, reading
559       from stdin with one line/reading as one message:
560
561       •   read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
562

FILES

564       $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
565           Configuration file for default options.
566

BUGS

568       mosquitto bug information can be found at
569       https://github.com/eclipse/mosquitto/issues
570

SEE ALSO

572       mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
573       libmosquitto(3), mosquitto-tls(7)
574

AUTHOR

576       Roger Light <roger@atchoo.org>
577
578
579
580Mosquitto Project                 09/18/2023                  MOSQUITTO_PUB(1)
Impressum