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_sub 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, defaults to
131 mosquitto_pub_ appended with the process id of the client. Cannot
132 be used at the same time as the --id-prefix argument.
133 -I, --id-prefix
135 Provide a prefix that the client id will be built from by appending
136 the process id of the client. This is useful where the broker is
137 using the clientid_prefixes option. Cannot be used at the same time
138 as the --id argument.
139 --insecure
141 When using certificate based encryption, this option disables
142 verification of the server hostname in the server certificate. This
143 can be useful when testing initial server configurations but makes
144 it possible for a malicious third party to impersonate your server
145 through DNS spoofing, for example. Use this option in testing only.
146 If you need to resort to using this option in a production
147 environment, your setup is at fault and there is no point using
148 encryption.
149 -k, --keepalive
151 The number of seconds between sending PING commands to the broker
152 for the purposes of informing it we are still connected and
153 functioning. Defaults to 60 seconds.
154 --key
156 Define the path to a file containing a PEM encoded private key for
157 this client, if required by the server.
158 See also --cert.
160 --keyform
162 Specifies the type of private key in use when making TLS
163 connections.. This can be "pem" or "engine". This parameter is
164 useful when a TPM module is being used and the private key has been
165 created with it. Defaults to "pem", which means normal private key
166 files are used.
167 See also --tls-engine.
169 -L, --url
171 Specify specify user, password, hostname, port and topic at once as
172 a URL. The URL must be in the form:
173 mqtt(s)://[username[:password]@]host[:port]/topic
174 If the scheme is mqtt:// then the port defaults to 1883. If the
176 scheme is mqtts:// then the port defaults to 8883.
177 -l, --stdin-line
179 Send messages read from stdin, splitting separate lines into
180 separate messages. Note that blank lines won't be sent.
181 -m, --message
183 Send a single message from the command line.
184 -n, --null-message
186 Send a null (zero length) message.
187 -p, --port
189 Connect to the port specified. If not given, the default of 1883
190 for plain MQTT or 8883 for MQTT over TLS will be used.
191 -P, --pw
193 Provide a password to be used for authenticating with the broker.
194 Using this argument without also specifying a username is invalid.
195 See also the --username option.
196 --proxy
198 Specify a SOCKS5 proxy to connect through. "None" and "username"
199 authentication types are supported. The socks-url must be of the
200 form socks5h://[username[:password]@]host[:port]. The protocol
201 prefix socks5h means that hostnames are resolved by the proxy. The
202 symbols %25, %3A and %40 are URL decoded into %, : and @
203 respectively, if present in the username or password.
204 If username is not given, then no authentication is attempted. If
206 the port is not given, then the default of 1080 is used.
207 More SOCKS versions may be available in the future, depending on
209 demand, and will use different protocol prefixes as described in
210 curl(1).
211 --psk
213 Provide the hexadecimal (no leading 0x) pre-shared-key matching the
214 one used on the broker to use TLS-PSK encryption support.
215 --psk-identity must also be provided to enable TLS-PSK.
216 --psk-identity
218 The client identity to use with TLS-PSK support. This may be used
219 instead of a username if the broker is configured to do so.
220 -q, --qos
222 Specify the quality of service to use for the message, from 0, 1
223 and 2. Defaults to 0.
224 --quiet
226 If this argument is given, no runtime errors will be printed. This
227 excludes any error messages given in case of invalid user input
228 (e.g. using --port without a port).
229 -r, --retain
231 If retain is given, the message will be retained as a "last known
232 good" value on the broker. See mqtt(7) for more information.
233 --repeat
235 If the publish mode is-m, -f, or -s (i.e. the modes where only a
236 single message is sent), then --repeat can be used to specify that
237 the message will be published multiple times.
238 See also --repeat-delay.
240 --repeat-delay
242 If using --repeat, then the default behaviour is to publish
243 repeated messages as soon as the previous message is delivered. Use
244 --repeat-delay to specify the number of seconds to wait after the
245 previous message was delivered before publishing the next. Does not
246 need to be an integer number of seconds.
247 Note that there is no guarantee as to the actual interval between
249 messages, this option simply defines the minimum time from delivery
250 of one message to the start of the publish of the next.
251 -s, --stdin-file
253 Send a message read from stdin, sending the entire content as a
254 single message.
255 -S
257 Use SRV lookups to determine which host to connect to. Performs
258 lookups to _mqtt._tcp.<host> when used in conjunction with -h,
259 otherwise uses _mqtt._tcp.<local dns domain>.
260 -t, --topic
262 The MQTT topic on which to publish the message. See mqtt(7) for
263 more information on MQTT topics.
264 --tls-alpn
266 Provide a protocol to use when connecting to a broker that has
267 multiple protocols available on a single port, e.g. MQTT and
268 WebSockets.
269 --tls-engine
271 A valid openssl engine id. These can be listed with openssl engine
272 command.
273 See also --keyform.
275 --tls-engine-kpass-sha1
277 SHA1 of the private key password when using an TLS engine. Some TLS
278 engines such as the TPM engine may require the use of a password in
279 order to be accessed. This option allows a hex encoded SHA1 hash of
280 the password to the engine directly, instead of the user being
281 prompted for the password.
282 See also --tls-engine.
284 --tls-version
286 Choose which TLS protocol version to use when communicating with
287 the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
288 default value is tlsv1.2. Must match the protocol version used by
289 the broker.
290 -u, --username
292 Provide a username to be used for authenticating with the broker.
293 See also the --pw argument.
294 -V, --protocol-version
296 Specify which version of the MQTT protocol should be used when
297 connecting to the rmeote broker. Can be 5, 311, 31, or the more
298 verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
299 --will-payload
301 Specify a message that will be stored by the broker and sent out if
302 this client disconnects unexpectedly. This must be used in
303 conjunction with --will-topic.
304 --will-qos
306 The QoS to use for the Will. Defaults to 0. This must be used in
307 conjunction with --will-topic.
308 --will-retain
310 If given, if the client disconnects unexpectedly the message sent
311 out will be treated as a retained message. This must be used in
312 conjunction with --will-topic.
313 --will-topic
315 The topic on which to send a Will, in the event that the client
316 disconnects unexpectedly.
317
319 mosquitto_sub can register a message with the broker that will be sent
320 out if it disconnects unexpectedly. See mqtt(7) for more information.
321 The minimum requirement for this is to use --will-topic to specify
323 which topic the will should be sent out on. This will result in a
324 non-retained, zero length message with QoS 0.
325 Use the --will-retain, --will-payload and --will-qos arguments to
327 modify the other will parameters.
328
330 The -D / --property option allows adding properties to different stages
331 of the mosquitto_pub run. The properties supported for each command are
332 as follows:
333 Connect
335 · authentication-data (binary data - note treated as a string in
336 mosquitto_pub)
337 · authentication-method (UTF-8 string pair)
339 · maximum-packet-size (32-bit unsigned integer)
341 · receive-maximum (16-bit unsigned integer)
343 · request-problem-information (8-bit unsigned integer)
345 · request-response-information (8-bit unsigned integer)
347 · session-expiry-interval (32-bit unsigned integer)
349 · topic-alias-maximum (16-bit unsigned integer)
351 · user-property (UTF-8 string pair)
353 Publish
355 · content-type (UTF-8 string)
356 · correlation-data (binary data - note treated as a string in
358 mosquitto_pub)
359 · message-expiry-interval (32-bit unsigned integer)
361 · payload-format-indicator (8-bit unsigned integer)
363 · response-topic (UTF-8 string)
365 · topic-alias (16-bit unsigned integer)
367 · user-property (UTF-8 string pair)
369 Disconnect
371 · session-expiry-interval (32-bit unsigned integer)
372 · user-property (UTF-8 string pair)
374 Will properties
376 · content-type (UTF-8 string)
377 · correlation-data (binary data - note treated as a string in
379 mosquitto_pub)
380 · message-expiry-interval (32-bit unsigned integer)
382 · payload-format-indicator (8-bit unsigned integer)
384 · response-topic (UTF-8 string)
386 · user-property (UTF-8 string pair)
388 · will-delay-interval (32-bit unsigned integer)
390
392 Publish temperature information to localhost with QoS 1:
393 · mosquitto_pub -t sensors/temperature -m 32 -q 1
395 Publish timestamp and temperature information to a remote host on a
397 non-standard port and QoS 0:
398 · mosquitto_pub -h 192.168.1.1 -p 1885 -t sensors/temperature -m
400 "1266193804 32"
401 Publish light switch status. Message is set to retained because there
403 may be a long period of time between light switch events:
404 · mosquitto_pub -r -t switches/kitchen_lights/status -m "on"
406 Send the contents of a file in two ways:
408 · mosquitto_pub -t my/topic -f ./data
410 · mosquitto_pub -t my/topic -s < ./data
412 Send parsed electricity usage data from a Current Cost meter, reading
414 from stdin with one line/reading as one message:
415 · read_cc128.pl | mosquitto_pub -t sensors/cc128 -l
417
419 $XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub
420 Configuration file for default options.
421
423 mosquitto bug information can be found at
424 https://github.com/eclipse/mosquitto/issues
425
427 mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8),
428 libmosquitto(3), mosquitto-tls(7)
429
431 Roger Light <roger@atchoo.org>
432Mosquitto Project 04/30/2019 MOSQUITTO_PUB(1)