'\" t
.\"     Title: mosquitto_rr
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/28/2019
.\"    Manual: Commands
.\"    Source: Mosquitto Project
.\"  Language: English
.\"
.TH "MOSQUITTO_RR" "1" "11/28/2019" "Mosquitto Project" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mosquitto_rr \- an MQTT version 5/3\&.1\&.1 client for request/response messaging
.SH "SYNOPSIS"
.HP \w'\fBmosquitto_rr\fR\ 'u
\fBmosquitto_rr\fR {[\fB\-h\fR\ \fIhostname\fR]\ [\fB\-p\fR\ \fIport\-number\fR]\ [\fB\-u\fR\ \fIusername\fR]\ [\fB\-P\fR\ \fIpassword\fR]\ \fB\-t\fR\ \fImessage\-topic\fR...  | \fB\-L\fR\ \fIURL\fR\ [\fB\-t\fR\ \fImessage\-topic\fR...]  | [\fB\-e\fR\ \fIresponse\-topic\fR]} {\fB\-f\fR\ \fIfile\fR | \fB\-m\fR\ \fImessage\fR | \fB\-n\fR | \fB\-s\fR} [\fB\-A\fR\ \fIbind\-address\fR] [\fB\-c\fR] [\fB\-d\fR] [\fB\-D\fR\ \fIcommand\fR\ \fIidentifier\fR\ \fIvalue\fR] [\fB\-i\fR\ \fIclient\-id\fR] [\fB\-I\fR\ \fIclient\-id\-prefix\fR] [\fB\-k\fR\ \fIkeepalive\-time\fR] [\fB\-N\fR] [\fB\-q\fR\ \fImessage\-QoS\fR] [\fB\-R\fR] [\fB\-S\fR] [\fB\-v\fR] [\fB\-V\fR\ \fIprotocol\-version\fR] [\fB\-W\fR\ \fImessage\-processing\-timeout\fR] [\fB\-\-proxy\fR\ \fIsocks\-url\fR] [\fB\-\-quiet\fR] [\fB\-\-will\-topic\fR\ \fItopic\fR\ [\fB\-\-will\-payload\fR\ \fIpayload\fR]\ [\fB\-\-will\-qos\fR\ \fIqos\fR]\ [\fB\-\-will\-retain\fR]] [[{\fB\-\-cafile\fR\ \fIfile\fR\ |\ \fB\-\-capath\fR\ \fIdir\fR}\ [\fB\-\-cert\fR\ \fIfile\fR]\ [\fB\-\-key\fR\ \fIfile\fR]\ [\fB\-\-ciphers\fR\ \fIciphers\fR]\ [\fB\-\-tls\-version\fR\ \fIversion\fR]\ [\fB\-\-tls\-alpn\fR\ \fIprotocol\fR]\ [\fB\-\-tls\-engine\fR\ \fIengine\fR]\ [\fB\-\-keyform\fR\ {\fIpem\fR\ |\ \fIengine\fR}]\ [\fB\-\-tls\-engine\-kpass\-sha1\fR\ \fIkpass\-sha1\fR]\ [\fB\-\-insecure\fR]] | [\fB\-\-psk\fR\ \fIhex\-key\fR\ \fB\-\-psk\-identity\fR\ \fIidentity\fR\ [\fB\-\-ciphers\fR\ \fIciphers\fR]\ [\fB\-\-tls\-version\fR\ \fIversion\fR]]]
.HP \w'\fBmosquitto_rr\fR\ 'u
\fBmosquitto_rr\fR [\fB\-\-help\fR] 
.SH "DESCRIPTION"
.PP
\fBmosquitto_rr\fR
is an MQTT version 5/3\&.1\&.1 client that can be used to publish a request message and wait for a response\&. When using MQTT v5, which is the default,
\fBmosquitto_rr\fR
will use the Request\-Response feature\&.
.SH "ENCRYPTED CONNECTIONS"
.PP
\fBmosquitto_rr\fR
supports TLS encrypted connections\&. It is strongly recommended that you use an encrypted connection for anything more than the most basic setup\&.
.PP
To enable TLS connections when using x509 certificates, one of either
\fB\-\-cafile\fR
or
\fB\-\-capath\fR
must be provided as an option\&.
.PP
To enable TLS connections when using TLS\-PSK, you must use the
\fB\-\-psk\fR
and the
\fB\-\-psk\-identity\fR
options\&.
.SH "OPTIONS"
.PP
The options below may be given on the command line, but may also be placed in a config file located at
\fB$XDG_CONFIG_HOME/mosquitto_rr\fR
or
\fB$HOME/\&.config/mosquitto_rr\fR
with one pair of
\fB\-option \fR\fB\fIvalue\fR\fR
per line\&. The values in the config file will be used as defaults and can be overridden by using the command line\&. The exceptions to this is
\fB\-t\fR, which if given in the config file will not be overridden\&. Note also that currently some options cannot be negated, e\&.g\&.
\fB\-S\fR\&. Config file lines that have a
\fB#\fR
as the first character are treated as comments and not processed any further\&.
.PP
\fB\-A\fR
.RS 4
Bind the outgoing connection to a local ip address/hostname\&. Use this argument if you need to restrict network communication to a particular interface\&.
.RE
.PP
\fB\-c\fR, \fB\-\-disable\-clean\-session\fR
.RS 4
Disable the \*(Aqclean session\*(Aq flag\&. This means that all of the subscriptions for the client will be maintained after it disconnects, along with subsequent QoS 1 and QoS 2 messages that arrive\&. When the client reconnects, it will receive all of the queued messages\&.
.sp
If using this option, the client id must be set manually with
\fB\-\-id\fR
.RE
.PP
\fB\-\-cafile\fR
.RS 4
Define the path to a file containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
See also
\fB\-\-capath\fR
.RE
.PP
\fB\-\-capath\fR
.RS 4
Define the path to a directory containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
For
\fB\-\-capath\fR
to work correctly, the certificate files must have "\&.crt" as the file ending and you must run "openssl rehash <path to capath>" each time you add/remove a certificate\&.
.sp
See also
\fB\-\-cafile\fR
.RE
.PP
\fB\-\-cert\fR
.RS 4
Define the path to a file containing a PEM encoded certificate for this client, if required by the server\&.
.sp
See also
\fB\-\-key\fR\&.
.RE
.PP
\fB\-\-ciphers\fR
.RS 4
An openssl compatible list of TLS ciphers to support in the client\&. See
\fBciphers\fR(1)
for more information\&.
.RE
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Enable debug messages\&.
.RE
.PP
\fB\-D\fR, \fB\-\-property\fR
.RS 4
Use an MQTT v5 property with this publish\&. If you use this option, the client will be set to be an MQTT v5 client\&. This option has two forms:
.sp
\fB\-D command identifier value\fR
.sp
\fB\-D command identifier name value\fR
.sp
\fBcommand\fR
is the MQTT command/packet identifier and can be one of CONNECT, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, AUTH, or WILL\&. The properties available for each command are listed in the Properties section\&.
.sp
\fBidentifier\fR
is the name of the property to add\&. This is as described in the specification, but with \*(Aq\-\*(Aq as a word separator\&. For example:
\fBpayload\-format\-indicator\fR\&. More details are in the
Properties
section\&.
.sp
\fBvalue\fR
is the value of the property to add, with a data type that is property specific\&.
.sp
\fBname\fR
is only used for the
\fBuser\-property\fR
property as the first of the two strings in the string pair\&. In that case,
\fBvalue\fR
is the second of the strings in the pair\&.
.RE
.PP
\fB\-f\fR, \fB\-\-file\fR
.RS 4
Send the contents of a file as the request message\&.
.RE
.PP
\fB\-F\fR
.RS 4
Specify output printing format\&. This option allows you to choose what information from each message is printed to the screen\&. See the
Output Format
section below for full details\&.
.sp
This option overrides the
\fB\-v\fR
option, but does not override the
\fB\-N\fR
option\&.
.RE
.PP
\fB\-\-help\fR
.RS 4
Display usage information\&.
.RE
.PP
\fB\-h\fR, \fB\-\-host\fR
.RS 4
Specify the host to connect to\&. Defaults to localhost\&.
.RE
.PP
\fB\-i\fR, \fB\-\-id\fR
.RS 4
The id to use for this client\&. If not given, a client id will be generated depending on the MQTT version being used\&. For v3\&.1\&.1/v3\&.1, the client generates a client id in the format
\fBmosq\-XXXXXXXXXXXXXXXXXX\fR, where the
\fBX\fR
are replaced with random alphanumeric characters\&. For v5\&.0, the client sends a zero length client id, and the server will generate a client id for the client\&.
.sp
This option cannot be used at the same time as the
\fB\-\-id\-prefix\fR
argument\&.
.RE
.PP
\fB\-I\fR, \fB\-\-id\-prefix\fR
.RS 4
Provide a prefix that the client id will be built from by appending the process id of the client\&. This is useful where the broker is using the clientid_prefixes option\&. Cannot be used at the same time as the
\fB\-\-id\fR
argument\&.
.RE
.PP
\fB\-\-insecure\fR
.RS 4
When using certificate based encryption, this option disables verification of the server hostname in the server certificate\&. This can be useful when testing initial server configurations but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example\&. Use this option in testing
\fIonly\fR\&. If you need to resort to using this option in a production environment, your setup is at fault and there is no point using encryption\&.
.RE
.PP
\fB\-k\fR, \fB\-\-keepalive\fR
.RS 4
The number of seconds between sending PING commands to the broker for the purposes of informing it we are still connected and functioning\&. Defaults to 60 seconds\&.
.RE
.PP
\fB\-\-key\fR
.RS 4
Define the path to a file containing a PEM encoded private key for this client, if required by the server\&.
.sp
See also
\fB\-\-cert\fR\&.
.RE
.PP
\fB\-\-keyform\fR
.RS 4
Specifies the type of private key in use when making TLS connections\&.\&. This can be "pem" or "engine"\&. This parameter is useful when a TPM module is being used and the private key has been created with it\&. Defaults to "pem", which means normal private key files are used\&.
.sp
See also
\fB\-\-tls\-engine\fR\&.
.RE
.PP
\fB\-L\fR, \fB\-\-url\fR
.RS 4
Specify specify user, password, hostname, port and topic at once as a URL\&. The URL must be in the form: mqtt(s)://[username[:password]@]host[:port]/topic
.sp
If the scheme is mqtt:// then the port defaults to 1883\&. If the scheme is mqtts:// then the port defaults to 8883\&.
.RE
.PP
\fB\-m\fR, \fB\-\-message\fR
.RS 4
Send a single request message from the command line\&.
.RE
.PP
\fB\-N\fR
.RS 4
Do not append an end of line character to the payload when printing\&. This allows streaming of payload data from multiple messages directly to another application unmodified\&. Only really makes sense when not using
\fB\-v\fR\&.
.RE
.PP
\fB\-n\fR, \fB\-\-null\-message\fR
.RS 4
Send a null (zero length) request message\&.
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
Connect to the port specified\&. If not given, the default of 1883 for plain MQTT or 8883 for MQTT over TLS will be used\&.
.RE
.PP
\fB\-P\fR, \fB\-\-pw\fR
.RS 4
Provide a password to be used for authenticating with the broker\&. Using this argument without also specifying a username is invalid when using MQTT v3\&.1 or v3\&.1\&.1\&. See also the
\fB\-\-username\fR
option\&.
.RE
.PP
\fB\-\-proxy\fR
.RS 4
Specify a SOCKS5 proxy to connect through\&. "None" and "username" authentication types are supported\&. The
\fBsocks\-url\fR
must be of the form
\fBsocks5h://[username[:password]@]host[:port]\fR\&. The protocol prefix
\fBsocks5h\fR
means that hostnames are resolved by the proxy\&. The symbols %25, %3A and %40 are URL decoded into %, : and @ respectively, if present in the username or password\&.
.sp
If username is not given, then no authentication is attempted\&. If the port is not given, then the default of 1080 is used\&.
.sp
More SOCKS versions may be available in the future, depending on demand, and will use different protocol prefixes as described in
\fBcurl\fR(1)\&.
.RE
.PP
\fB\-\-psk\fR
.RS 4
Provide the hexadecimal (no leading 0x) pre\-shared\-key matching the one used on the broker to use TLS\-PSK encryption support\&.
\fB\-\-psk\-identity\fR
must also be provided to enable TLS\-PSK\&.
.RE
.PP
\fB\-\-psk\-identity\fR
.RS 4
The client identity to use with TLS\-PSK support\&. This may be used instead of a username if the broker is configured to do so\&.
.RE
.PP
\fB\-q\fR, \fB\-\-qos\fR
.RS 4
Specify the quality of service desired for the incoming messages, from 0, 1 and 2\&. Defaults to 0\&. See
\fBmqtt\fR(7)
for more information on QoS\&.
.sp
The QoS is identical for all topics subscribed to in a single instance of mosquitto_rr\&.
.RE
.PP
\fB\-\-quiet\fR
.RS 4
If this argument is given, no runtime errors will be printed\&. This excludes any error messages given in case of invalid user input (e\&.g\&. using
\fB\-\-port\fR
without a port)\&.
.RE
.PP
\fB\-R\fR
.RS 4
If this argument is given, messages that are received that have the retain bit set will not be printed\&. Messages with retain set are "stale", in that it is not known when they were originally published\&. When subscribing to a wildcard topic there may be a large number of retained messages\&. This argument suppresses their display\&.
.RE
.PP
\fB\-S\fR
.RS 4
Use SRV lookups to determine which host to connect to\&. Performs lookups to
\fB_mqtt\&._tcp\&.<host>\fR
when used in conjunction with
\fB\-h\fR, otherwise uses
\fB_mqtt\&._tcp\&.<local dns domain>\fR\&.
.RE
.PP
\fB\-s\fR, \fB\-\-stdin\-file\fR
.RS 4
Send a request message read from stdin, sending the entire content as a single message\&.
.RE
.PP
\fB\-t\fR, \fB\-\-topic\fR
.RS 4
The MQTT topic to subscribe to, where responses will be waited for\&. See
\fBmqtt\fR(7)
for more information on MQTT topics\&.
.sp
This option may be repeated to subscribe to multiple topics\&.
.RE
.PP
\fB\-\-tls\-alpn\fR
.RS 4
Provide a protocol to use when connecting to a broker that has multiple protocols available on a single port, e\&.g\&. MQTT and WebSockets\&.
.RE
.PP
\fB\-\-tls\-engine\fR
.RS 4
A valid openssl engine id\&. These can be listed with openssl engine command\&.
.sp
See also
\fB\-\-keyform\fR\&.
.RE
.PP
\fB\-\-tls\-engine\-kpass\-sha1\fR
.RS 4
SHA1 of the private key password when using an TLS engine\&. Some TLS engines such as the TPM engine may require the use of a password in order to be accessed\&. This option allows a hex encoded SHA1 hash of the password to the engine directly, instead of the user being prompted for the password\&.
.sp
See also
\fB\-\-tls\-engine\fR\&.
.RE
.PP
\fB\-\-tls\-version\fR
.RS 4
Choose which TLS protocol version to use when communicating with the broker\&. Valid options are
\fBtlsv1\&.3\fR,
\fBtlsv1\&.2\fR
and
\fBtlsv1\&.1\fR\&. The default value is
\fBtlsv1\&.2\fR\&. Must match the protocol version used by the broker\&.
.RE
.PP
\fB\-u\fR, \fB\-\-username\fR
.RS 4
Provide a username to be used for authenticating with the broker\&. See also the
\fB\-\-pw\fR
argument\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Print received messages verbosely\&. With this argument, messages will be printed as "topic payload"\&. When this argument is not given, the messages are printed as "payload"\&.
.RE
.PP
\fB\-V\fR, \fB\-\-protocol\-version\fR
.RS 4
Specify which version of the MQTT protocol should be used when connecting to the rmeote broker\&. Can be
\fB5\fR,
\fB311\fR,
\fB31\fR, or the more verbose
\fBmqttv5\fR,
\fBmqttv311\fR, or
\fBmqttv31\fR\&. Defaults to
\fB311\fR\&.
.RE
.PP
\fB\-\-will\-payload\fR
.RS 4
Specify a message that will be stored by the broker and sent out if this client disconnects unexpectedly\&. This must be used in conjunction with
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-qos\fR
.RS 4
The QoS to use for the Will\&. Defaults to 0\&. This must be used in conjunction with
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-retain\fR
.RS 4
If given, if the client disconnects unexpectedly the message sent out will be treated as a retained message\&. This must be used in conjunction with
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-topic\fR
.RS 4
The topic on which to send a Will, in the event that the client disconnects unexpectedly\&.
.RE
.SH "OUTPUT FORMAT"
.PP
There are three ways of formatting the output from mosquitto_rr\&. In all cases a new\-line character is appended for each message received unless the
\fB\-N\fR
argument is passed to mosquitto_rr\&.
.PP
Payload\-only is the default output format and will print the payload exactly as it is received\&.
.PP
Verbose mode is activated with
\fB\-v\fR
and prints the message topic and the payload, separated by a space\&.
.PP
The final option is formatted output, which allows the user to define a custom output format\&. The behaviour is controlled with the
\fB\-F format\-string\fR
option\&. The format string is a free text string where interpreted sequences are replaced by different parameters\&. The available interpreted sequences are described below\&.
.PP
Three characters are used to start an interpreted sequence:
\fB%\fR,
\fB@\fR
and
\fB\e\fR\&. Sequences starting with
\fB%\fR
are either parameters related to the MQTT message being printed, or are helper sequences to avoid the need to type long date format strings for example\&. Sequences starting with
\fB@\fR
are passed to the
\fBstrftime\fR(3)
function (with the @ replaced with a % \- note that only the character immediately after the @ is passed to strftime)\&. This allows the construction of a wide variety of time based outputs\&. The output options for strftime vary from platform to platform, so please check what is available for your platform\&. mosquitto_rr does provide one extension to strftime which is
\fB@N\fR, which can be used to obtain the number of nanoseconds passed in the current second\&. The resolution of this option varies depending on the platform\&. The final sequence character is
\fB\e\fR, which is used to input some characters that would otherwise be difficult to enter\&.
.SS "MQTT related parameters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%%\fR
a literal %\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%l\fR
the length of the payload in bytes\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%m\fR
the message id (only relevant for messages with QoS>0)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%p\fR
the payload raw bytes (may produce non\-printable characters depending on the payload)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%q\fR
the message QoS\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%r\fR
the retained flag for the message\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%t\fR
the message topic\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%x\fR
the payload with each byte as a hexadecimal number (lower case)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%X\fR
the payload with each byte as a hexadecimal number (upper case)\&.
.RE
.SS "Helpers"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%I\fR
ISO\-8601 format date and time, e\&.g\&. 2016\-08\-10T09:47:38+0100
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%j\fR
JSON output of message parameters and timestamp, with a quoted and escaped payload\&. For example
{"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello world"}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%J\fR
JSON output of message parameters and timestamp, with a non\-quoted and non\-escaped payload \- this means the payload must itself be valid JSON\&. For example:
{"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27\&.0,"humidity":57}}\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%I\fR
ISO\-8601 format date and time, e\&.g\&. 2016\-08\-10T09:47:38+0100
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%U\fR
Unix timestamp with nanoseconds, e\&.g\&. 1470818943\&.786368637
.RE
.SS "Time related parameters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@@\fR
a literal @\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@X\fR
pass the character represented by
\fBX\fR
to the strftime function as
\fB%X\fR\&. The options supported are platform dependent\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@N\fR
the number of nanoseconds that have passed in the current second, with varying timing resolution depending on platform\&.
.RE
.SS "Escape characters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\e\e\fR
a literal \e\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\e0\fR
a null character\&. Can be used to separate different parameters that may contain spaces (e\&.g\&. topic, payload) so that processing with tools such as
\fBxargs\fR(1)
is easier\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ea\fR
alert/bell\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ee\fR
the escape sequence, which can be used with ANSI colour codes to provide coloured output for example\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\en\fR
end of line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\er\fR
carriage return\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\et\fR
horizontal tab\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ev\fR
vertical tab\&.
.RE
.SH "WILLS"
.PP
mosquitto_rr can register a message with the broker that will be sent out if it disconnects unexpectedly\&. See
\fBmqtt\fR(7)
for more information\&.
.PP
The minimum requirement for this is to use
\fB\-\-will\-topic\fR
to specify which topic the will should be sent out on\&. This will result in a non\-retained, zero length message with QoS 0\&.
.PP
Use the
\fB\-\-will\-retain\fR,
\fB\-\-will\-payload\fR
and
\fB\-\-will\-qos\fR
arguments to modify the other will parameters\&.
.SH "PROPERTIES"
.PP
The
\fB\-D\fR
/
\fB\-\-property\fR
option allows adding properties to different stages of the mosquitto_rr run\&. The properties supported for each command are as follows:
.SS "Connect"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBauthentication\-data\fR
(binary data \- note treated as a string in mosquitto_rr)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBauthentication\-method\fR
(UTF\-8 string pair)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmaximum\-packet\-size\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBreceive\-maximum\fR
(16\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBrequest\-problem\-information\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBrequest\-response\-information\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsession\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBtopic\-alias\-maximum\fR
(16\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Publish"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcontent\-type\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcorrelation\-data\fR
(binary data \- note treated as a string in mosquitto_rr)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmessage\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpayload\-format\-indicator\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBresponse\-topic\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBtopic\-alias\fR
(16\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Subscribe"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Unsubscribe"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Disconnect"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsession\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Will properties"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcontent\-type\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcorrelation\-data\fR
(binary data \- note treated as a string in mosquitto_pub)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmessage\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpayload\-format\-indicator\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBresponse\-topic\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBwill\-delay\-interval\fR
(32\-bit unsigned integer)
.RE
.SH "FILES"
.PP
$XDG_CONFIG_HOME/mosquitto_rr, $HOME/\&.config/mosquitto_rr
.RS 4
Configuration file for default options\&.
.RE
.SH "BUGS"
.PP
\fBmosquitto\fR
bug information can be found at
\m[blue]\fB\%https://github.com/eclipse/mosquitto/issues\fR\m[]
.SH "SEE ALSO"
\fBmqtt\fR(7), \fBmosquitto_pub\fR(1), \fBmosquitto_sub\fR(1), \fBmosquitto\fR(8), \fBlibmosquitto\fR(3), \fBmosquitto-tls\fR(7)
.SH "AUTHOR"
.PP
Roger Light
<roger@atchoo\&.org>