1MOSQUITTO_RR(1)                    Commands                    MOSQUITTO_RR(1)
2
3
4

NAME

6       mosquitto_rr - an MQTT version 5/3.1.1 client for request/response
7       messaging
8

SYNOPSIS

10       mosquitto_rr
11                    {[-h hostname] [-p port-number] [ [-u username] [-P password] ] -t message-topic...
12                    | -L URL [-t message-topic...]  | [-e response-topic]}
13                    {-f file | -m message | -n | -s} [-A bind-address] [-c]
14                    [-d] [-D command identifier value] [-i client-id]
15                    [-I client-id-prefix] [-k keepalive-time] [-N]
16                    [-q message-QoS] [-R] [-S] [-v] [-V protocol-version]
17                    [-W message-processing-timeout] [--proxy socks-url]
18                    [--quiet]
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] [--insecure]]
21                    |
22                    [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]
23
24       mosquitto_rr [--help]
25

DESCRIPTION

27       mosquitto_rr is an MQTT version 5/3.1.1 client that can be used to
28       publish a request message and wait for a response. When using MQTT v5,
29       which is the default, mosquitto_rr will use the Request-Response
30       feature.
31

ENCRYPTED CONNECTIONS

33       mosquitto_rr supports TLS encrypted connections. It is strongly
34       recommended that you use an encrypted connection for anything more than
35       the most basic setup.
36
37       To enable TLS connections when using x509 certificates, one of either
38       --cafile or --capath must be provided as an option.
39
40       To enable TLS connections when using TLS-PSK, you must use the --psk
41       and the --psk-identity options.
42

OPTIONS

44       The options below may be given on the command line, but may also be
45       placed in a config file located at $XDG_CONFIG_HOME/mosquitto_rr or
46       $HOME/.config/mosquitto_rr with one pair of -option value per line. The
47       values in the config file will be used as defaults and can be
48       overridden by using the command line. The exceptions to this is -t,
49       which if given in the config file will not be overridden. Note also
50       that currently some options cannot be negated, e.g.  -S. Config file
51       lines that have a # as the first character are treated as comments and
52       not processed any further.
53
54       -A
55           Bind the outgoing connection to a local ip address/hostname. Use
56           this argument if you need to restrict network communication to a
57           particular interface.
58
59       -c, --disable-clean-session
60           Disable the 'clean session' flag. This means that all of the
61           subscriptions for the client will be maintained after it
62           disconnects, along with subsequent QoS 1 and QoS 2 messages that
63           arrive. When the client reconnects, it will receive all of the
64           queued messages.
65
66           If using this option, the client id must be set manually with --id
67
68       --cafile
69           Define the path to a file containing PEM encoded CA certificates
70           that are trusted. Used to enable SSL communication.
71
72           See also --capath
73
74       --capath
75           Define the path to a directory containing PEM encoded CA
76           certificates that are trusted. Used to enable SSL communication.
77
78           For --capath to work correctly, the certificate files must have
79           ".crt" as the file ending and you must run "openssl rehash <path to
80           capath>" each time you add/remove a certificate.
81
82           See also --cafile
83
84       --cert
85           Define the path to a file containing a PEM encoded certificate for
86           this client, if required by the server.
87
88           See also --key.
89
90       --ciphers
91           An openssl compatible list of TLS ciphers to support in the client.
92           See ciphers(1) for more information.
93
94       -d, --debug
95           Enable debug messages.
96
97       -D, --property
98           Use an MQTT v5 property with this publish. If you use this option,
99           the client will be set to be an MQTT v5 client. This option has two
100           forms:
101
102           -D command identifier value
103
104           -D command identifier name value
105
106           command is the MQTT command/packet identifier and can be one of
107           CONNECT, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, UNSUBSCRIBE,
108           DISCONNECT, AUTH, or WILL. The properties available for each
109           command are listed in the Properties section.
110
111           identifier is the name of the property to add. This is as described
112           in the specification, but with '-' as a word separator. For
113           example: payload-format-indicator. More details are in the
114           Properties section.
115
116           value is the value of the property to add, with a data type that is
117           property specific.
118
119           name is only used for the user-property property as the first of
120           the two strings in the string pair. In that case, value is the
121           second of the strings in the pair.
122
123       -f, --file
124           Send the contents of a file as the request message.
125
126       -F
127           Specify output printing format. This option allows you to choose
128           what information from each message is printed to the screen. See
129           the Output Format section below for full details.
130
131           This option overrides the -v option, but does not override the -N
132           option.
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, defaults to
142           mosquitto_rr_ appended with the process id of the client. Cannot be
143           used at the same time as the --id-prefix argument.
144
145       -I, --id-prefix
146           Provide a prefix that the client id will be built from by appending
147           the process id of the client. This is useful where the broker is
148           using the clientid_prefixes option. Cannot be used at the same time
149           as the --id argument.
150
151       --insecure
152           When using certificate based encryption, this option disables
153           verification of the server hostname in the server certificate. This
154           can be useful when testing initial server configurations but makes
155           it possible for a malicious third party to impersonate your server
156           through DNS spoofing, for example. Use this option in testing only.
157           If you need to resort to using this option in a production
158           environment, your setup is at fault and there is no point using
159           encryption.
160
161       -k, --keepalive
162           The number of seconds between sending PING commands to the broker
163           for the purposes of informing it we are still connected and
164           functioning. Defaults to 60 seconds.
165
166       --key
167           Define the path to a file containing a PEM encoded private key for
168           this client, if required by the server.
169
170           See also --cert.
171
172       --keyform
173           Specifies the type of private key in use when making TLS
174           connections.. This can be "pem" or "engine". This parameter is
175           useful when a TPM module is being used and the private key has been
176           created with it. Defaults to "pem", which means normal private key
177           files are used.
178
179           See also --tls-engine.
180
181       -L, --url
182           Specify specify user, password, hostname, port and topic at once as
183           a URL. The URL must be in the form:
184           mqtt(s)://[username[:password]@]host[:port]/topic
185
186           If the scheme is mqtt:// then the port defaults to 1883. If the
187           scheme is mqtts:// then the port defaults to 8883.
188
189       -m, --message
190           Send a single request message from the command line.
191
192       -N
193           Do not append an end of line character to the payload when
194           printing. This allows streaming of payload data from multiple
195           messages directly to another application unmodified. Only really
196           makes sense when not using -v.
197
198       -n, --null-message
199           Send a null (zero length) request message.
200
201       -p, --port
202           Connect to the port specified. If not given, the default of 1883
203           for plain MQTT or 8883 for MQTT over TLS will be used.
204
205       -P, --pw
206           Provide a password to be used for authenticating with the broker.
207           Using this argument without also specifying a username is invalid.
208           See also the --username option.
209
210       --proxy
211           Specify a SOCKS5 proxy to connect through. "None" and "username"
212           authentication types are supported. The socks-url must be of the
213           form socks5h://[username[:password]@]host[:port]. The protocol
214           prefix socks5h means that hostnames are resolved by the proxy. The
215           symbols %25, %3A and %40 are URL decoded into %, : and @
216           respectively, if present in the username or password.
217
218           If username is not given, then no authentication is attempted. If
219           the port is not given, then the default of 1080 is used.
220
221           More SOCKS versions may be available in the future, depending on
222           demand, and will use different protocol prefixes as described in
223           curl(1).
224
225       --psk
226           Provide the hexadecimal (no leading 0x) pre-shared-key matching the
227           one used on the broker to use TLS-PSK encryption support.
228           --psk-identity must also be provided to enable TLS-PSK.
229
230       --psk-identity
231           The client identity to use with TLS-PSK support. This may be used
232           instead of a username if the broker is configured to do so.
233
234       -q, --qos
235           Specify the quality of service desired for the incoming messages,
236           from 0, 1 and 2. Defaults to 0. See mqtt(7) for more information on
237           QoS.
238
239           The QoS is identical for all topics subscribed to in a single
240           instance of mosquitto_rr.
241
242       --quiet
243           If this argument is given, no runtime errors will be printed. This
244           excludes any error messages given in case of invalid user input
245           (e.g. using --port without a port).
246
247       -R
248           If this argument is given, messages that are received that have the
249           retain bit set will not be printed. Messages with retain set are
250           "stale", in that it is not known when they were originally
251           published. When subscribing to a wildcard topic there may be a
252           large number of retained messages. This argument suppresses their
253           display.
254
255       -S
256           Use SRV lookups to determine which host to connect to. Performs
257           lookups to _mqtt._tcp.<host> when used in conjunction with -h,
258           otherwise uses _mqtt._tcp.<local dns domain>.
259
260       -s, --stdin-file
261           Send a request message read from stdin, sending the entire content
262           as a single message.
263
264       -t, --topic
265           The MQTT topic to subscribe to, where responses will be waited for.
266           See mqtt(7) for more information on MQTT topics.
267
268           This option may be repeated to subscribe to multiple topics.
269
270       --tls-alpn
271           Provide a protocol to use when connecting to a broker that has
272           multiple protocols available on a single port, e.g. MQTT and
273           WebSockets.
274
275       --tls-engine
276           A valid openssl engine id. These can be listed with openssl engine
277           command.
278
279           See also --keyform.
280
281       --tls-engine-kpass-sha1
282           SHA1 of the private key password when using an TLS engine. Some TLS
283           engines such as the TPM engine may require the use of a password in
284           order to be accessed. This option allows a hex encoded SHA1 hash of
285           the password to the engine directly, instead of the user being
286           prompted for the password.
287
288           See also --tls-engine.
289
290       --tls-version
291           Choose which TLS protocol version to use when communicating with
292           the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
293           default value is tlsv1.2. Must match the protocol version used by
294           the broker.
295
296       -u, --username
297           Provide a username to be used for authenticating with the broker.
298           See also the --pw argument.
299
300       -v, --verbose
301           Print received messages verbosely. With this argument, messages
302           will be printed as "topic payload". When this argument is not
303           given, the messages are printed as "payload".
304
305       -V, --protocol-version
306           Specify which version of the MQTT protocol should be used when
307           connecting to the rmeote broker. Can be 5, 311, 31, or the more
308           verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
309
310       --will-payload
311           Specify a message that will be stored by the broker and sent out if
312           this client disconnects unexpectedly. This must be used in
313           conjunction with --will-topic.
314
315       --will-qos
316           The QoS to use for the Will. Defaults to 0. This must be used in
317           conjunction with --will-topic.
318
319       --will-retain
320           If given, if the client disconnects unexpectedly the message sent
321           out will be treated as a retained message. This must be used in
322           conjunction with --will-topic.
323
324       --will-topic
325           The topic on which to send a Will, in the event that the client
326           disconnects unexpectedly.
327

OUTPUT FORMAT

329       There are three ways of formatting the output from mosquitto_rr. In all
330       cases a new-line character is appended for each message received unless
331       the -N argument is passed to mosquitto_rr.
332
333       Payload-only is the default output format and will print the payload
334       exactly as it is received.
335
336       Verbose mode is activated with -v and prints the message topic and the
337       payload, separated by a space.
338
339       The final option is formatted output, which allows the user to define a
340       custom output format. The behaviour is controlled with the -F
341       format-string option. The format string is a free text string where
342       interpreted sequences are replaced by different parameters. The
343       available interpreted sequences are described below.
344
345       Three characters are used to start an interpreted sequence: %, @ and \.
346       Sequences starting with % are either parameters related to the MQTT
347       message being printed, or are helper sequences to avoid the need to
348       type long date format strings for example. Sequences starting with @
349       are passed to the strftime(3) function (with the @ replaced with a % -
350       note that only the character immediately after the @ is passed to
351       strftime). This allows the construction of a wide variety of time based
352       outputs. The output options for strftime vary from platform to
353       platform, so please check what is available for your platform.
354       mosquitto_rr does provide one extension to strftime which is @N, which
355       can be used to obtain the number of nanoseconds passed in the current
356       second. The resolution of this option varies depending on the platform.
357       The final sequence character is \, which is used to input some
358       characters that would otherwise be difficult to enter.
359
360   MQTT related parameters
361       ·   %% a literal %.
362
363       ·   %l the length of the payload in bytes.
364
365       ·   %m the message id (only relevant for messages with QoS>0).
366
367       ·   %p the payload raw bytes (may produce non-printable characters
368           depending on the payload).
369
370       ·   %q the message QoS.
371
372       ·   %r the retained flag for the message.
373
374       ·   %t the message topic.
375
376       ·   %x the payload with each byte as a hexadecimal number (lower case).
377
378       ·   %X the payload with each byte as a hexadecimal number (upper case).
379
380   Helpers
381       ·   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
382
383       ·   %j JSON output of message parameters and timestamp, with a quoted
384           and escaped payload. For example
385           {"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello
386           world"}
387
388       ·   %J JSON output of message parameters and timestamp, with a
389           non-quoted and non-escaped payload - this means the payload must
390           itself be valid JSON. For example:
391           {"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.
392
393       ·   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
394
395       ·   %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637
396
397   Time related parameters
398       ·   @@ a literal @.
399
400       ·   @X pass the character represented by X to the strftime function as
401           %X. The options supported are platform dependent.
402
403       ·   @N the number of nanoseconds that have passed in the current
404           second, with varying timing resolution depending on platform.
405
406   Escape characters
407       ·   \\ a literal \.
408
409       ·   \0 a null character. Can be used to separate different parameters
410           that may contain spaces (e.g. topic, payload) so that processing
411           with tools such as xargs(1) is easier.
412
413       ·   \a alert/bell.
414
415       ·   \e the escape sequence, which can be used with ANSI colour codes to
416           provide coloured output for example.
417
418       ·   \n end of line.
419
420       ·   \r carriage return.
421
422       ·   \t horizontal tab.
423
424       ·   \v vertical tab.
425

WILLS

427       mosquitto_rr can register a message with the broker that will be sent
428       out if it disconnects unexpectedly. See mqtt(7) for more information.
429
430       The minimum requirement for this is to use --will-topic to specify
431       which topic the will should be sent out on. This will result in a
432       non-retained, zero length message with QoS 0.
433
434       Use the --will-retain, --will-payload and --will-qos arguments to
435       modify the other will parameters.
436

PROPERTIES

438       The -D / --property option allows adding properties to different stages
439       of the mosquitto_rr run. The properties supported for each command are
440       as follows:
441
442   Connect
443       ·   authentication-data (binary data - note treated as a string in
444           mosquitto_rr)
445
446       ·   authentication-method (UTF-8 string pair)
447
448       ·   maximum-packet-size (32-bit unsigned integer)
449
450       ·   receive-maximum (16-bit unsigned integer)
451
452       ·   request-problem-information (8-bit unsigned integer)
453
454       ·   request-response-information (8-bit unsigned integer)
455
456       ·   session-expiry-interval (32-bit unsigned integer)
457
458       ·   topic-alias-maximum (16-bit unsigned integer)
459
460       ·   user-property (UTF-8 string pair)
461
462   Publish
463       ·   content-type (UTF-8 string)
464
465       ·   correlation-data (binary data - note treated as a string in
466           mosquitto_rr)
467
468       ·   message-expiry-interval (32-bit unsigned integer)
469
470       ·   payload-format-indicator (8-bit unsigned integer)
471
472       ·   response-topic (UTF-8 string)
473
474       ·   topic-alias (16-bit unsigned integer)
475
476       ·   user-property (UTF-8 string pair)
477
478   Subscribe
479       ·   user-property (UTF-8 string pair)
480
481   Unsubscribe
482       ·   user-property (UTF-8 string pair)
483
484   Disconnect
485       ·   session-expiry-interval (32-bit unsigned integer)
486
487       ·   user-property (UTF-8 string pair)
488
489   Will properties
490       ·   content-type (UTF-8 string)
491
492       ·   correlation-data (binary data - note treated as a string in
493           mosquitto_pub)
494
495       ·   message-expiry-interval (32-bit unsigned integer)
496
497       ·   payload-format-indicator (8-bit unsigned integer)
498
499       ·   response-topic (UTF-8 string)
500
501       ·   user-property (UTF-8 string pair)
502
503       ·   will-delay-interval (32-bit unsigned integer)
504

FILES

506       $XDG_CONFIG_HOME/mosquitto_rr, $HOME/.config/mosquitto_rr
507           Configuration file for default options.
508

BUGS

510       mosquitto bug information can be found at
511       https://github.com/eclipse/mosquitto/issues
512

SEE ALSO

514       mqtt(7), mosquitto_pub(1), mosquitto_sub(1), mosquitto(8),
515       libmosquitto(3), mosquitto-tls(7)
516

AUTHOR

518       Roger Light <roger@atchoo.org>
519
520
521
522Mosquitto Project                 04/26/2019                   MOSQUITTO_RR(1)
Impressum