1MOSQUITTO_PUB(1) Commands MOSQUITTO_PUB(1)
2
6 mosquitto_pub - an MQTT version 5/3.1.1/3.1 client for publishing
7 simple messages
8
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 mosquitto_pub [--help]
26
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
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 To enable TLS connections when using x509 certificates, one of either
37 --cafile or --capath can be provided as an option.
38 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 To enable TLS connections when using TLS-PSK, you must use the --psk
43 and the --psk-identity options.
44
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 -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 -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 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 If using this option, the client id must be set manually with --id
76 --cafile
78 Define the path to a file containing PEM encoded CA certificates
79 that are trusted. Used to enable SSL communication.
80 See also --capath
82 --capath
84 Define the path to a directory containing PEM encoded CA
85 certificates that are trusted. Used to enable SSL communication.
86 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 See also --cafile
92 --cert
94 Define the path to a file containing a PEM encoded certificate for
95 this client, if required by the server.
96 See also --key.
98 --ciphers
100 An openssl compatible list of TLS ciphers to support in the client.
101 See ciphers(1) for more information.
102 -d, --debug
104 Enable debug messages.
105 -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 -D command identifier value
112 -D command identifier name value
114 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 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 value is the value of the property to add, with a data type that is
125 property specific.
126 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 -f, --file
132 Send the contents of a file as the message.
133 --help
135 Display usage information.
136 -h, --host
138 Specify the host to connect to. Defaults to localhost.
139 -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 This option cannot be used at the same time as the --id-prefix
149 argument.
150 -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 --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 -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 --key
173 Define the path to a file containing a PEM encoded private key for
174 this client, if required by the server.
175 See also --cert.
177 --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 See also --tls-engine.
186 -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 If the scheme is mqtt:// then the port defaults to 1883. If the
193 scheme is mqtts:// then the port defaults to 8883.
194 -l, --stdin-line
196 Send messages read from stdin, splitting separate lines into
197 separate messages.
198 -m, --message
200 Send a single message from the command line.
201 -n, --null-message
203 Send a null (zero length) message.
204 --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 -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 -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 --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 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 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 --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 --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 -q, --qos
245 Specify the quality of service to use for the message, from 0, 1
246 and 2. Defaults to 0.
247 --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 -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 --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 See also --repeat-delay.
266 --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 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 -s, --stdin-file
279 Send a message read from stdin, sending the entire content as a
280 single message.
281 -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 -t, --topic
288 The MQTT topic on which to publish the message. See mqtt(7) for
289 more information on MQTT topics.
290 --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 --tls-engine
297 A valid openssl engine id. These can be listed with openssl engine
298 command.
299 See also --keyform.
301 --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 See also --tls-engine.
310 --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 --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 -u, --username
325 Provide a username to be used for authenticating with the broker.
326 See also the --pw argument.
327 --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 See the socket_domain option in mosquitto.conf[1m(5) to configure
334 Mosquitto to listen on a unix socket.
335 -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 --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 --will-qos
347 The QoS to use for the Will. Defaults to 0. This must be used in
348 conjunction with --will-topic.
349 --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 --will-topic
358 The topic on which to send a Will, in the event that the client
359 disconnects unexpectedly.
360 -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 If the session is set to never expire, either with -x or -c, then a
370 client id must be provided.
371
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 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 Use the --will-retain, --will-payload and --will-qos arguments to
381 modify the other will parameters.
382
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 Connect
389 • authentication-data (binary data - note treated as a string in
390 mosquitto_pub)
391 • authentication-method (UTF-8 string pair)
393 • maximum-packet-size (32-bit unsigned integer)
395 • receive-maximum (16-bit unsigned integer)
397 • request-problem-information (8-bit unsigned integer)
399 • request-response-information (8-bit unsigned integer)
401 • session-expiry-interval (32-bit unsigned integer, note use -x
403 instead)
404 • topic-alias-maximum (16-bit unsigned integer)
406 • user-property (UTF-8 string pair)
408 Publish
410 • content-type (UTF-8 string)
411 • correlation-data (binary data - note treated as a string in
413 mosquitto_pub)
414 • message-expiry-interval (32-bit unsigned integer)
416 • payload-format-indicator (8-bit unsigned integer)
418 • response-topic (UTF-8 string)
420 • topic-alias (16-bit unsigned integer)
422 • user-property (UTF-8 string pair)
424 Disconnect
426 • session-expiry-interval (32-bit unsigned integer)
427 • user-property (UTF-8 string pair)
429 Will properties
431 • content-type (UTF-8 string)
432 • correlation-data (binary data - note treated as a string in
434 mosquitto_pub)
435 • message-expiry-interval (32-bit unsigned integer)
437 • payload-format-indicator (8-bit unsigned integer)
439 • response-topic (UTF-8 string)
441 • user-property (UTF-8 string pair)
443 • will-delay-interval (32-bit unsigned integer)
445
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 MQTT v3.1.1 CONNACK codes:
453 • 0 Success
455 • 1 Connection refused: Bad protocol version
457 • 2 Connection refused: Identifier rejected
459 • 3 Connection refused: Server unavailable
461 • 4 Connection refused: Bad username/password
463 • 5 Connection refused: Not authorized
465 MQTT v5 CONNACK codes:
467 • 0 Success
469 • 128 Unspecified error
471 • 129 Malformed packet
473 • 130 Protocol error
475 • 131 Implementation specific error
477 • 132 Unsupported protocol version
479 • 133 Client ID not valid
481 • 134 Bad username or password
483 • 135 Not authorized
485 • 136 Server unavailable
487 • 137 Server busy
489 • 138 Banned
491 • 139 Server shutting down
493 • 140 Bad authentication method
495 • 141 Keep alive timeout
497 • 142 Session taken over
499 • 143 Topic filter invalid
501 • 144 Topic name invalid
503 • 147 Receive maximum exceeded
505 • 148 Topic alias invalid
507 • 149 Packet too large
509 • 148 Message rate too high
511 • 151 Quota exceeded
513 • 152 Administrative action
515 • 153 Payload format invalid
517 • 154 Retain not supported
519 • 155 QoS not supported
521 • 156 Use another server
523 • 157 Server moved
525 • 158 Shared subscriptions not supported
527 • 159 Connection rate exceeded
529 • 160 Maximum connect time
531 • 161 Subscription IDs not supported
533 • 162 Wildcard subscriptions not supported
535
537 Publish temperature information to localhost with QoS 1:
538 • mosquitto_pub -t sensors/temperature -m 32 -q 1
540 Publish timestamp and temperature information to a remote host on a
542 non-standard port and QoS 0:
543 • mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
545 "1266193804 32"
546 Publish light switch status. Message is set to retained because there
548 may be a long period of time between light switch events:
549 • mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
551 Send the contents of a file in two ways:
553 • mosquitto_pub -t my/topic -f ./data
555 • mosquitto_pub -t my/topic -s < ./data
557 Send parsed electricity usage data from a Current Cost meter, reading
559 from stdin with one line/reading as one message:
560 • read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
562
564 $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
565 Configuration file for default options.
566
568 mosquitto bug information can be found at
569 https://github.com/eclipse/mosquitto/issues
570
572 mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
573 libmosquitto(3), mosquitto-tls(7)
574
576 Roger Light <roger@atchoo.org>
577Mosquitto Project 09/18/2023 MOSQUITTO_PUB(1)