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] [-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 mosquitto_pub [--help]
25
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
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 To enable TLS connections when using x509 certificates, one of either
36 --cafile or --capath must be provided as an option.
37 To enable TLS connections when using TLS-PSK, you must use the --psk
39 and the --psk-identity options.
40
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 -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 -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 If using this option, the client id must be set manually with --id
65 --cafile
67 Define the path to a file containing PEM encoded CA certificates
68 that are trusted. Used to enable SSL communication.
69 See also --capath
71 --capath
73 Define the path to a directory containing PEM encoded CA
74 certificates that are trusted. Used to enable SSL communication.
75 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 See also --cafile
81 --cert
83 Define the path to a file containing a PEM encoded certificate for
84 this client, if required by the server.
85 See also --key.
87 --ciphers
89 An openssl compatible list of TLS ciphers to support in the client.
90 See ciphers(1) for more information.
91 -d, --debug
93 Enable debug messages.
94 -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 -D command identifier value
101 -D command identifier name value
103 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 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 value is the value of the property to add, with a data type that is
114 property specific.
115 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 -f, --file
121 Send the contents of a file as the message.
122 --help
124 Display usage information.
125 -h, --host
127 Specify the host to connect to. Defaults to localhost.
128 -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 This option cannot be used at the same time as the --id-prefix
138 argument.
139 -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 --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 -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 --key
162 Define the path to a file containing a PEM encoded private key for
163 this client, if required by the server.
164 See also --cert.
166 --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 See also --tls-engine.
175 -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 If the scheme is mqtt:// then the port defaults to 1883. If the
182 scheme is mqtts:// then the port defaults to 8883.
183 -l, --stdin-line
185 Send messages read from stdin, splitting separate lines into
186 separate messages.
187 -m, --message
189 Send a single message from the command line.
190 -n, --null-message
192 Send a null (zero length) message.
193 -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 -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 --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 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 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 --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 --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 -q, --qos
228 Specify the quality of service to use for the message, from 0, 1
229 and 2. Defaults to 0.
230 --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 -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 --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 See also --repeat-delay.
246 --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 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 -s, --stdin-file
259 Send a message read from stdin, sending the entire content as a
260 single message.
261 -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 -t, --topic
268 The MQTT topic on which to publish the message. See mqtt(7) for
269 more information on MQTT topics.
270 --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 --tls-engine
277 A valid openssl engine id. These can be listed with openssl engine
278 command.
279 See also --keyform.
281 --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 See also --tls-engine.
290 --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 -u, --username
298 Provide a username to be used for authenticating with the broker.
299 See also the --pw argument.
300 -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 --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 --will-qos
312 The QoS to use for the Will. Defaults to 0. This must be used in
313 conjunction with --will-topic.
314 --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 --will-topic
321 The topic on which to send a Will, in the event that the client
322 disconnects unexpectedly.
323
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 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 Use the --will-retain, --will-payload and --will-qos arguments to
333 modify the other will parameters.
334
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 Connect
341 · authentication-data (binary data - note treated as a string in
342 mosquitto_pub)
343 · authentication-method (UTF-8 string pair)
345 · maximum-packet-size (32-bit unsigned integer)
347 · receive-maximum (16-bit unsigned integer)
349 · request-problem-information (8-bit unsigned integer)
351 · request-response-information (8-bit unsigned integer)
353 · session-expiry-interval (32-bit unsigned integer)
355 · topic-alias-maximum (16-bit unsigned integer)
357 · user-property (UTF-8 string pair)
359 Publish
361 · content-type (UTF-8 string)
362 · correlation-data (binary data - note treated as a string in
364 mosquitto_pub)
365 · message-expiry-interval (32-bit unsigned integer)
367 · payload-format-indicator (8-bit unsigned integer)
369 · response-topic (UTF-8 string)
371 · topic-alias (16-bit unsigned integer)
373 · user-property (UTF-8 string pair)
375 Disconnect
377 · session-expiry-interval (32-bit unsigned integer)
378 · user-property (UTF-8 string pair)
380 Will properties
382 · content-type (UTF-8 string)
383 · correlation-data (binary data - note treated as a string in
385 mosquitto_pub)
386 · message-expiry-interval (32-bit unsigned integer)
388 · payload-format-indicator (8-bit unsigned integer)
390 · response-topic (UTF-8 string)
392 · user-property (UTF-8 string pair)
394 · will-delay-interval (32-bit unsigned integer)
396
398 mosquitto_sub returns zero on success, or non-zero on error. If the
399 connection is refused by the broker at the MQTT level, then the exit
400 code is the CONNACK reason code. If another error occurs, the exit code
401 is a libmosquitto return value.
402 MQTT v3.1.1 CONNACK codes:
404 · 0 Success
406 · 1 Connection refused: Bad protocol version
408 · 2 Connection refused: Identifier rejected
410 · 3 Connection refused: Server unavailable
412 · 4 Connection refused: Bad username/password
414 · 5 Connection refused: Not authorized
416 MQTT v5 CONNACK codes:
418 · 0 Success
420 · 128 Unspecified error
422 · 129 Malformed packet
424 · 130 Protocol error
426 · 131 Implementation specific error
428 · 132 Unsupported protocol version
430 · 133 Client ID not valid
432 · 134 Bad username or password
434 · 135 Not authorized
436 · 136 Server unavailable
438 · 137 Server busy
440 · 138 Banned
442 · 139 Server shutting down
444 · 140 Bad authentication method
446 · 141 Keep alive timeout
448 · 142 Session taken over
450 · 143 Topic filter invalid
452 · 144 Topic name invalid
454 · 147 Receive maximum exceeded
456 · 148 Topic alias invalid
458 · 149 Packet too large
460 · 148 Message rate too high
462 · 151 Quota exceeded
464 · 152 Administrative action
466 · 153 Payload format invalid
468 · 154 Retain not supported
470 · 155 QoS not supported
472 · 156 Use another server
474 · 157 Server moved
476 · 158 Shared subscriptions not supported
478 · 159 Connection rate exceeded
480 · 160 Maximum connect time
482 · 161 Subscription IDs not supported
484 · 162 Wildcard subscriptions not supported
486
488 Publish temperature information to localhost with QoS 1:
489 · mosquitto_pub -t sensors/temperature -m 32 -q 1
491 Publish timestamp and temperature information to a remote host on a
493 non-standard port and QoS 0:
494 · mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
496 "1266193804 32"
497 Publish light switch status. Message is set to retained because there
499 may be a long period of time between light switch events:
500 · mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
502 Send the contents of a file in two ways:
504 · mosquitto_pub -t my/topic -f ./data
506 · mosquitto_pub -t my/topic -s < ./data
508 Send parsed electricity usage data from a Current Cost meter, reading
510 from stdin with one line/reading as one message:
511 · read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
513
515 $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
516 Configuration file for default options.
517
519 mosquitto bug information can be found at
520 https://github.com/eclipse/mosquitto/issues
521
523 mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
524 libmosquitto(3), mosquitto-tls(7)
525
527 Roger Light <roger@atchoo.org>
528Mosquitto Project 08/19/2020 MOSQUITTO_PUB(1)