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, 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
148           This option cannot be used at the same time as the --id-prefix
149           argument.
150
151       -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
157       --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
167       -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
172       --key
173           Define the path to a file containing a PEM encoded private key for
174           this client, if required by the server.
175
176           See also --cert.
177
178       --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
185           See also --tls-engine.
186
187       -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
192           If the scheme is mqtt:// then the port defaults to 1883. If the
193           scheme is mqtts:// then the port defaults to 8883.
194
195       -m, --message
196           Send a single request message from the command line.
197
198       -N
199           Do not append an end of line character to the payload when
200           printing. This allows streaming of payload data from multiple
201           messages directly to another application unmodified. Only really
202           makes sense when not using -v.
203
204       -n, --null-message
205           Send a null (zero length) request message.
206
207       -p, --port
208           Connect to the port specified. If not given, the default of 1883
209           for plain MQTT or 8883 for MQTT over TLS will be used.
210
211       -P, --pw
212           Provide a password to be used for authenticating with the broker.
213           Using this argument without also specifying a username is invalid
214           when using MQTT v3.1 or v3.1.1. See also the --username option.
215
216       --proxy
217           Specify a SOCKS5 proxy to connect through. "None" and "username"
218           authentication types are supported. The socks-url must be of the
219           form socks5h://[username[:password]@]host[:port]. The protocol
220           prefix socks5h means that hostnames are resolved by the proxy. The
221           symbols %25, %3A and %40 are URL decoded into %, : and @
222           respectively, if present in the username or password.
223
224           If username is not given, then no authentication is attempted. If
225           the port is not given, then the default of 1080 is used.
226
227           More SOCKS versions may be available in the future, depending on
228           demand, and will use different protocol prefixes as described in
229           curl(1).
230
231       --psk
232           Provide the hexadecimal (no leading 0x) pre-shared-key matching the
233           one used on the broker to use TLS-PSK encryption support.
234           --psk-identity must also be provided to enable TLS-PSK.
235
236       --psk-identity
237           The client identity to use with TLS-PSK support. This may be used
238           instead of a username if the broker is configured to do so.
239
240       -q, --qos
241           Specify the quality of service desired for the incoming messages,
242           from 0, 1 and 2. Defaults to 0. See mqtt(7) for more information on
243           QoS.
244
245           The QoS is identical for all topics subscribed to in a single
246           instance of mosquitto_rr.
247
248       --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
253       -R
254           If this argument is given, messages that are received that have the
255           retain bit set will not be printed. Messages with retain set are
256           "stale", in that it is not known when they were originally
257           published. When subscribing to a wildcard topic there may be a
258           large number of retained messages. This argument suppresses their
259           display.
260
261       -S
262           Use SRV lookups to determine which host to connect to. Performs
263           lookups to _mqtt._tcp.<host> when used in conjunction with -h,
264           otherwise uses _mqtt._tcp.<local dns domain>.
265
266       -s, --stdin-file
267           Send a request message read from stdin, sending the entire content
268           as a single message.
269
270       -t, --topic
271           The MQTT topic to subscribe to, where responses will be waited for.
272           See mqtt(7) for more information on MQTT topics.
273
274           This option may be repeated to subscribe to multiple topics.
275
276       --tls-alpn
277           Provide a protocol to use when connecting to a broker that has
278           multiple protocols available on a single port, e.g. MQTT and
279           WebSockets.
280
281       --tls-engine
282           A valid openssl engine id. These can be listed with openssl engine
283           command.
284
285           See also --keyform.
286
287       --tls-engine-kpass-sha1
288           SHA1 of the private key password when using an TLS engine. Some TLS
289           engines such as the TPM engine may require the use of a password in
290           order to be accessed. This option allows a hex encoded SHA1 hash of
291           the password to the engine directly, instead of the user being
292           prompted for the password.
293
294           See also --tls-engine.
295
296       --tls-version
297           Choose which TLS protocol version to use when communicating with
298           the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
299           default value is tlsv1.2. Must match the protocol version used by
300           the broker.
301
302       -u, --username
303           Provide a username to be used for authenticating with the broker.
304           See also the --pw argument.
305
306       -v, --verbose
307           Print received messages verbosely. With this argument, messages
308           will be printed as "topic payload". When this argument is not
309           given, the messages are printed as "payload".
310
311       -V, --protocol-version
312           Specify which version of the MQTT protocol should be used when
313           connecting to the rmeote broker. Can be 5, 311, 31, or the more
314           verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
315
316       --will-payload
317           Specify a message that will be stored by the broker and sent out if
318           this client disconnects unexpectedly. This must be used in
319           conjunction with --will-topic.
320
321       --will-qos
322           The QoS to use for the Will. Defaults to 0. This must be used in
323           conjunction with --will-topic.
324
325       --will-retain
326           If given, if the client disconnects unexpectedly the message sent
327           out will be treated as a retained message. This must be used in
328           conjunction with --will-topic.
329
330       --will-topic
331           The topic on which to send a Will, in the event that the client
332           disconnects unexpectedly.
333

OUTPUT FORMAT

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

WILLS

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

PROPERTIES

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

FILES

512       $XDG_CONFIG_HOME/mosquitto_rr, $HOME/.config/mosquitto_rr
513           Configuration file for default options.
514

BUGS

516       mosquitto bug information can be found at
517       https://github.com/eclipse/mosquitto/issues
518

SEE ALSO

520       mqtt(7), mosquitto_pub(1), mosquitto_sub(1), mosquitto(8),
521       libmosquitto(3), mosquitto-tls(7)
522

AUTHOR

524       Roger Light <roger@atchoo.org>
525
526
527
528Mosquitto Project                 11/28/2019                   MOSQUITTO_RR(1)
Impressum