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 must be provided as an option.
38 To enable TLS connections when using TLS-PSK, you must use the --psk
40 and the --psk-identity options.
41
43 The options below may be given on the command line, but may also be
44 placed in a config file located at $XDG_CONFIG_HOME/mosquitto_pub or
45 $HOME/.config/mosquitto_pub with one pair of -option value per line.
46 The values in the config file will be used as defaults and can be
47 overridden by using the command line. The exceptions to this are the
48 message type options, of which only one can be specified. Note also
49 that currently some options cannot be negated, e.g. -S. Config file
50 lines that have a # as the first character are treated as comments and
51 not processed any further.
52 -A
54 Bind the outgoing connection to a local ip address/hostname. Use
55 this argument if you need to restrict network communication to a
56 particular interface.
57 -c, --disable-clean-session
59 Disable 'clean session' / enable persistent client mode. When this
60 argument is used, the broker will be instructed not to clean
61 existing sessions for the same client id when the client connects,
62 and sessions will never expire when the client disconnects. MQTT v5
63 clients can change their session expiry interval with the -x
64 argument.
65 When a session is persisted on the broker, the subscriptions for
67 the client will be maintained after it disconnects, along with
68 subsequent QoS 1 and QoS 2 messages that arrive. When the client
69 reconnects and does not clean the session, it will receive all of
70 the queued messages.
71 If using this option, the client id must be set manually with --id
73 --cafile
75 Define the path to a file containing PEM encoded CA certificates
76 that are trusted. Used to enable SSL communication.
77 See also --capath
79 --capath
81 Define the path to a directory containing PEM encoded CA
82 certificates that are trusted. Used to enable SSL communication.
83 For --capath to work correctly, the certificate files must have
85 ".crt" as the file ending and you must run "openssl rehash <path to
86 capath>" each time you add/remove a certificate.
87 See also --cafile
89 --cert
91 Define the path to a file containing a PEM encoded certificate for
92 this client, if required by the server.
93 See also --key.
95 --ciphers
97 An openssl compatible list of TLS ciphers to support in the client.
98 See ciphers(1) for more information.
99 -d, --debug
101 Enable debug messages.
102 -D, --property
104 Use an MQTT v5 property with this publish. If you use this option,
105 the client will be set to be an MQTT v5 client. This option has two
106 forms:
107 -D command identifier value
109 -D command identifier name value
111 command is the MQTT command/packet identifier and can be one of
113 CONNECT, PUBLISH, PUBREL, DISCONNECT, AUTH, or WILL. The properties
114 available for each command are listed in the Properties section.
115 identifier is the name of the property to add. This is as described
117 in the specification, but with '-' as a word separator. For
118 example: payload-format-indicator. More details are in the
119 Properties section.
120 value is the value of the property to add, with a data type that is
122 property specific.
123 name is only used for the user-property property as the first of
125 the two strings in the string pair. In that case, value is the
126 second of the strings in the pair.
127 -f, --file
129 Send the contents of a file as the message.
130 --help
132 Display usage information.
133 -h, --host
135 Specify the host to connect to. Defaults to localhost.
136 -i, --id
138 The id to use for this client. If not given, a client id will be
139 generated depending on the MQTT version being used. For
140 v3.1.1/v3.1, the client generates a client id in the format
141 mosq-XXXXXXXXXXXXXXXXXX, where the X are replaced with random
142 alphanumeric characters. For v5.0, the client sends a zero length
143 client id, and the server will generate a client id for the client.
144 This option cannot be used at the same time as the --id-prefix
146 argument.
147 -I, --id-prefix
149 Provide a prefix that the client id will be built from by appending
150 the process id of the client. This is useful where the broker is
151 using the clientid_prefixes option. Cannot be used at the same time
152 as the --id argument.
153 --insecure
155 When using certificate based encryption, this option disables
156 verification of the server hostname in the server certificate. This
157 can be useful when testing initial server configurations but makes
158 it possible for a malicious third party to impersonate your server
159 through DNS spoofing, for example. Use this option in testing only.
160 If you need to resort to using this option in a production
161 environment, your setup is at fault and there is no point using
162 encryption.
163 -k, --keepalive
165 The number of seconds between sending PING commands to the broker
166 for the purposes of informing it we are still connected and
167 functioning. Defaults to 60 seconds.
168 --key
170 Define the path to a file containing a PEM encoded private key for
171 this client, if required by the server.
172 See also --cert.
174 --keyform
176 Specifies the type of private key in use when making TLS
177 connections.. This can be "pem" or "engine". This parameter is
178 useful when a TPM module is being used and the private key has been
179 created with it. Defaults to "pem", which means normal private key
180 files are used.
181 See also --tls-engine.
183 -L, --url
185 Specify specify user, password, hostname, port and topic at once as
186 a URL. The URL must be in the form:
187 mqtt(s)://[username[:password]@]host[:port]/topic
188 If the scheme is mqtt:// then the port defaults to 1883. If the
190 scheme is mqtts:// then the port defaults to 8883.
191 -l, --stdin-line
193 Send messages read from stdin, splitting separate lines into
194 separate messages.
195 -m, --message
197 Send a single message from the command line.
198 -n, --null-message
200 Send a null (zero length) message.
201 --nodelay
203 Disable Nagle's algorithm for the socket. This means that latency
204 of sent messages is reduced, which is particularly noticable for
205 small, reasonably infrequent messages. Using this option may result
206 in more packets being sent than would normally be necessary.
207 -p, --port
209 Connect to the port specified. If not given, the default of 1883
210 for plain MQTT or 8883 for MQTT over TLS will be used.
211 -P, --pw
213 Provide a password to be used for authenticating with the broker.
214 Using this argument without also specifying a username is invalid
215 when using MQTT v3.1 or v3.1.1. See also the --username option.
216 --proxy
218 Specify a SOCKS5 proxy to connect through. "None" and "username"
219 authentication types are supported. The socks-url must be of the
220 form socks5h://[username[:password]@]host[:port]. The protocol
221 prefix socks5h means that hostnames are resolved by the proxy. The
222 symbols %25, %3A and %40 are URL decoded into %, : and @
223 respectively, if present in the username or password.
224 If username is not given, then no authentication is attempted. If
226 the port is not given, then the default of 1080 is used.
227 More SOCKS versions may be available in the future, depending on
229 demand, and will use different protocol prefixes as described in
230 curl(1).
231 --psk
233 Provide the hexadecimal (no leading 0x) pre-shared-key matching the
234 one used on the broker to use TLS-PSK encryption support.
235 --psk-identity must also be provided to enable TLS-PSK.
236 --psk-identity
238 The client identity to use with TLS-PSK support. This may be used
239 instead of a username if the broker is configured to do so.
240 -q, --qos
242 Specify the quality of service to use for the message, from 0, 1
243 and 2. Defaults to 0.
244 --quiet
246 If this argument is given, no runtime errors will be printed. This
247 excludes any error messages given in case of invalid user input
248 (e.g. using --port without a port).
249 -r, --retain
251 If retain is given, the message will be retained as a "last known
252 good" value on the broker. See mqtt(7) for more information. Note
253 that zero length payloads are never retained. If you send a zero
254 length payload retained message it will clear any retained message
255 on the topic.
256 --repeat
258 If the publish mode is-m, -f, or -s (i.e. the modes where only a
259 single message is sent), then --repeat can be used to specify that
260 the message will be published multiple times.
261 See also --repeat-delay.
263 --repeat-delay
265 If using --repeat, then the default behaviour is to publish
266 repeated messages as soon as the previous message is delivered. Use
267 --repeat-delay to specify the number of seconds to wait after the
268 previous message was delivered before publishing the next. Does not
269 need to be an integer number of seconds.
270 Note that there is no guarantee as to the actual interval between
272 messages, this option simply defines the minimum time from delivery
273 of one message to the start of the publish of the next.
274 -s, --stdin-file
276 Send a message read from stdin, sending the entire content as a
277 single message.
278 -S
280 Use SRV lookups to determine which host to connect to. Performs
281 lookups to _mqtt._tcp.<host> when used in conjunction with -h,
282 otherwise uses _mqtt._tcp.<local dns domain>.
283 -t, --topic
285 The MQTT topic on which to publish the message. See mqtt(7) for
286 more information on MQTT topics.
287 --tls-alpn
289 Provide a protocol to use when connecting to a broker that has
290 multiple protocols available on a single port, e.g. MQTT and
291 WebSockets.
292 --tls-engine
294 A valid openssl engine id. These can be listed with openssl engine
295 command.
296 See also --keyform.
298 --tls-engine-kpass-sha1
300 SHA1 of the private key password when using an TLS engine. Some TLS
301 engines such as the TPM engine may require the use of a password in
302 order to be accessed. This option allows a hex encoded SHA1 hash of
303 the password to the engine directly, instead of the user being
304 prompted for the password.
305 See also --tls-engine.
307 --tls-use-os-certs
309 If used, this will load and trust the OS provided CA certificates.
310 This can be used in conjunction with --cafile and --capath and can
311 be used on its own to enable TLS mode. This will be set by default
312 if -L mqtts://... is used, or if port is 8883 and no other
313 certificate options are used.
314 --tls-version
316 Choose which TLS protocol version to use when communicating with
317 the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
318 default value is tlsv1.2. Must match the protocol version used by
319 the broker.
320 -u, --username
322 Provide a username to be used for authenticating with the broker.
323 See also the --pw argument.
324 --unix
326 Connect to a broker through a local unix domain socket instead of a
327 TCP socket. This is a replacement for -h and -L. For example:
328 mosquitto_pub --unix /tmp/mosquitto.sock ...
329 See the socket_domain option in mosquitto.conf[1m(5) to configure
331 Mosquitto to listen on a unix socket.
332 -V, --protocol-version
334 Specify which version of the MQTT protocol should be used when
335 connecting to the rmeote broker. Can be 5, 311, 31, or the more
336 verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
337 --will-payload
339 Specify a message that will be stored by the broker and sent out if
340 this client disconnects unexpectedly. This must be used in
341 conjunction with --will-topic.
342 --will-qos
344 The QoS to use for the Will. Defaults to 0. This must be used in
345 conjunction with --will-topic.
346 --will-retain
348 If given, if the client disconnects unexpectedly the message sent
349 out will be treated as a retained message. This must be used in
350 conjunction with --will-topic. Note that zero length payloads are
351 never retained. If you send a zero length payload retained message
352 it will clear any retained message on the topic.
353 --will-topic
355 The topic on which to send a Will, in the event that the client
356 disconnects unexpectedly.
357 -x
359 Set the session-expiry-interval property on the CONNECT packet.
360 Applies to MQTT v5 clients only. Set to 0-4294967294 to specify the
361 session will expire in that many seconds after the client
362 disconnects, or use -1, 4294967295, or ∞ for a session that does
363 not expire. Defaults to -1 if -c is also given, or 0 if -c not
364 given.
365 If the session is set to never expire, either with -x or -c, then a
367 client id must be provided.
368
370 mosquitto_sub can register a message with the broker that will be sent
371 out if it disconnects unexpectedly. See mqtt(7) for more information.
372 The minimum requirement for this is to use --will-topic to specify
374 which topic the will should be sent out on. This will result in a
375 non-retained, zero length message with QoS 0.
376 Use the --will-retain, --will-payload and --will-qos arguments to
378 modify the other will parameters.
379
381 The -D / --property option allows adding properties to different stages
382 of the mosquitto_pub run. The properties supported for each command are
383 as follows:
384 Connect
386 • authentication-data (binary data - note treated as a string in
387 mosquitto_pub)
388 • authentication-method (UTF-8 string pair)
390 • maximum-packet-size (32-bit unsigned integer)
392 • receive-maximum (16-bit unsigned integer)
394 • request-problem-information (8-bit unsigned integer)
396 • request-response-information (8-bit unsigned integer)
398 • session-expiry-interval (32-bit unsigned integer, note use -x
400 instead)
401 • topic-alias-maximum (16-bit unsigned integer)
403 • user-property (UTF-8 string pair)
405 Publish
407 • content-type (UTF-8 string)
408 • correlation-data (binary data - note treated as a string in
410 mosquitto_pub)
411 • message-expiry-interval (32-bit unsigned integer)
413 • payload-format-indicator (8-bit unsigned integer)
415 • response-topic (UTF-8 string)
417 • topic-alias (16-bit unsigned integer)
419 • user-property (UTF-8 string pair)
421 Disconnect
423 • session-expiry-interval (32-bit unsigned integer)
424 • user-property (UTF-8 string pair)
426 Will properties
428 • content-type (UTF-8 string)
429 • correlation-data (binary data - note treated as a string in
431 mosquitto_pub)
432 • message-expiry-interval (32-bit unsigned integer)
434 • payload-format-indicator (8-bit unsigned integer)
436 • response-topic (UTF-8 string)
438 • user-property (UTF-8 string pair)
440 • will-delay-interval (32-bit unsigned integer)
442
444 mosquitto_sub returns zero on success, or non-zero on error. If the
445 connection is refused by the broker at the MQTT level, then the exit
446 code is the CONNACK reason code. If another error occurs, the exit code
447 is a libmosquitto return value.
448 MQTT v3.1.1 CONNACK codes:
450 • 0 Success
452 • 1 Connection refused: Bad protocol version
454 • 2 Connection refused: Identifier rejected
456 • 3 Connection refused: Server unavailable
458 • 4 Connection refused: Bad username/password
460 • 5 Connection refused: Not authorized
462 MQTT v5 CONNACK codes:
464 • 0 Success
466 • 128 Unspecified error
468 • 129 Malformed packet
470 • 130 Protocol error
472 • 131 Implementation specific error
474 • 132 Unsupported protocol version
476 • 133 Client ID not valid
478 • 134 Bad username or password
480 • 135 Not authorized
482 • 136 Server unavailable
484 • 137 Server busy
486 • 138 Banned
488 • 139 Server shutting down
490 • 140 Bad authentication method
492 • 141 Keep alive timeout
494 • 142 Session taken over
496 • 143 Topic filter invalid
498 • 144 Topic name invalid
500 • 147 Receive maximum exceeded
502 • 148 Topic alias invalid
504 • 149 Packet too large
506 • 148 Message rate too high
508 • 151 Quota exceeded
510 • 152 Administrative action
512 • 153 Payload format invalid
514 • 154 Retain not supported
516 • 155 QoS not supported
518 • 156 Use another server
520 • 157 Server moved
522 • 158 Shared subscriptions not supported
524 • 159 Connection rate exceeded
526 • 160 Maximum connect time
528 • 161 Subscription IDs not supported
530 • 162 Wildcard subscriptions not supported
532
534 Publish temperature information to localhost with QoS 1:
535 • mosquitto_pub -t sensors/temperature -m 32 -q 1
537 Publish timestamp and temperature information to a remote host on a
539 non-standard port and QoS 0:
540 • mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
542 "1266193804 32"
543 Publish light switch status. Message is set to retained because there
545 may be a long period of time between light switch events:
546 • mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
548 Send the contents of a file in two ways:
550 • mosquitto_pub -t my/topic -f ./data
552 • mosquitto_pub -t my/topic -s < ./data
554 Send parsed electricity usage data from a Current Cost meter, reading
556 from stdin with one line/reading as one message:
557 • read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
559
561 $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
562 Configuration file for default options.
563
565 mosquitto bug information can be found at
566 https://github.com/eclipse/mosquitto/issues
567
569 mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
570 libmosquitto(3), mosquitto-tls(7)
571
573 Roger Light <roger@atchoo.org>
574Mosquitto Project 04/03/2021 MOSQUITTO_PUB(1)