'\" t
|
.\" Title: mosquitto_rr
|
.\" Author: [see the "Author" section]
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
.\" Date: 06/18/2019
|
.\" Manual: Commands
|
.\" Source: Mosquitto Project
|
.\" Language: English
|
.\"
|
.TH "MOSQUITTO_RR" "1" "06/18/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, defaults to mosquitto_rr_ appended with the process id of the client\&. 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>
|
