Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MOSQUITTO_RR(1)			   Commands		       MOSQUITTO_RR(1)

       mosquitto_rr - an MQTT version 5/3.1.1 client for request/response

       mosquitto_rr -e response-topic
		    {[-h hostname] [--unix socket path]	[-p port-number] [-u username] [-P password] -t	message-topic...
		    | -L URL [-t message-topic...] } {-f file |	-m message |
		    -n | -s} [-A bind-address] [-c] [-d]
		    [-D	command	identifier value] [-i client-id]
		    [-I	client-id-prefix] [-k keepalive-time] [-N] [--nodelay]
		    [--pretty] [-q message-QoS]	[-R] [-S] [-v]
		    [-V	protocol-version] [-W message-processing-timeout]
		    [-x	session-expiry-interval] [--proxy socks-url] [--quiet]
		    [--will-topic topic	[--will-payload	payload] [--will-qos qos] [--will-retain]]
		    [[{--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]	[--tls-use-os-certs] [--insecure]]
		    [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]

       mosquitto_rr [--help]

       mosquitto_rr 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, mosquitto_rr will use the Request-Response

       The important options are -t, -e, and one of -f,	-m, -n,	and -s.

       Example:	mosquitto_rr -t	request-topic -e response-topic	-m message

       mosquitto_rr supports TLS encrypted connections.	It is strongly
       recommended that	you use	an encrypted connection	for anything more than
       the most	basic setup.

       To enable TLS connections when using x509 certificates, one of either
       --cafile	or --capath must be provided as	an option.

       To enable TLS connections when using TLS-PSK, you must use the --psk
       and the --psk-identity options.

       The options below may be	given on the command line, but may also	be
       placed in a config file located at $XDG_CONFIG_HOME/mosquitto_rr	or
       $HOME/.config/mosquitto_rr with one pair	of -option value 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 -t,
       which if	given in the config file will not be overridden. Note also
       that currently some options cannot be negated, e.g.  -S.	Config file
       lines that have a # as the first	character are treated as comments and
       not processed any further.

	   Bind	the outgoing connection	to a local ip address/hostname.	Use
	   this	argument if you	need to	restrict network communication to a
	   particular interface.

       -c, --disable-clean-session
	   Disable 'clean session' / enable persistent client mode. When this
	   argument is used, the broker	will be	instructed not to clean
	   existing sessions for the same client id when the client connects,
	   and sessions	will never expire when the client disconnects. MQTT v5
	   clients can change their session expiry interval with the -x

	   When	a session is persisted on the broker, 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 and does not clean the session, it will receive all of
	   the queued messages.

	   If using this option, the client id must be set manually with --id

	   Define the path to a	file containing	PEM encoded CA certificates
	   that	are trusted. Used to enable SSL	communication.

	   See also --capath

	   Define the path to a	directory containing PEM encoded CA
	   certificates	that are trusted. Used to enable SSL communication.

	   For --capath	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.

	   See also --cafile

	   Define the path to a	file containing	a PEM encoded certificate for
	   this	client,	if required by the server.

	   See also --key.

	   An openssl compatible list of TLS ciphers to	support	in the client.
	   See ciphers(1) for more information.

       -d, --debug
	   Enable debug	messages.

       -D, --property
	   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

	   -D command identifier value

	   -D command identifier name value

	   command is the MQTT command/packet identifier and can be one	of
	   DISCONNECT, AUTH, or	WILL. The properties available for each
	   command are listed in the Properties	section.

	   identifier is the name of the property to add. This is as described
	   in the specification, but with '-' as a word	separator. For
	   example: payload-format-indicator. More details are in the
	   Properties section.

	   value is the	value of the property to add, with a data type that is
	   property specific.

	   name	is only	used for the user-property property as the first of
	   the two strings in the string pair. In that case, value is the
	   second of the strings in the	pair.

	   Response topic. The client will subscribe to	this topic to wait for
	   a response.

       -f, --file
	   Send	the contents of	a file as the request message.

	   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.

	   This	option overrides the -v	option,	but does not override the -N

	   Display usage information.

       -h, --host
	   Specify the host to connect to. Defaults to localhost.

       -i, --id
	   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
	   mosq-XXXXXXXXXXXXXXXXXX, where the X	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.

	   This	option cannot be used at the same time as the --id-prefix

       -I, --id-prefix
	   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 --id argument.

	   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 only.
	   If you need to resort to using this option in a production
	   environment,	your setup is at fault and there is no point using

       -k, --keepalive
	   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.

	   Define the path to a	file containing	a PEM encoded private key for
	   this	client,	if required by the server.

	   See also --cert.

	   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.

	   See also --tls-engine.

       -L, --url
	   Specify specify user, password, hostname, port and topic at once as
	   a URL. The URL must be in the form:

	   If the scheme is mqtt:// then the port defaults to 1883. If the
	   scheme is mqtts:// then the port defaults to	8883.

       -m, --message
	   Send	a single request message from the command line.

	   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 -v.

       -n, --null-message
	   Send	a null (zero length) request message.

	   Disable Nagle's algorithm for the socket. This means	that latency
	   of sent messages is reduced,	which is particularly noticable	for
	   small, reasonably infrequent	messages. Using	this option may	result
	   in more packets being sent than would normally be necessary.

       -p, --port
	   Connect to the port specified. If not given,	the default of 1883
	   for plain MQTT or 8883 for MQTT over	TLS will be used.

       -P, --pw
	   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	--username option.

	   When	using the JSON output format %j	or %J, the default is to print
	   in an unformatted fashion. Specifying --pretty prints messages in a
	   prettier, more human	readable format.

	   Specify a SOCKS5 proxy to connect through. "None" and "username"
	   authentication types	are supported. The socks-url must be of	the
	   form	socks5h://[username[:password]@]host[:port]. The protocol
	   prefix socks5h 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.

	   If username is not given, then no authentication is attempted. If
	   the port is not given, then the default of 1080 is used.

	   More	SOCKS versions may be available	in the future, depending on
	   demand, and will use	different protocol prefixes as described in

	   Provide the hexadecimal (no leading 0x) pre-shared-key matching the
	   one used on the broker to use TLS-PSK encryption support.
	   --psk-identity must also be provided	to enable TLS-PSK.

	   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.

       -q, --qos
	   Specify the quality of service desired for the incoming messages,
	   from	0, 1 and 2. Defaults to	0. See mqtt(7) for more	information on

	   The QoS is identical	for all	topics subscribed to in	a single
	   instance of mosquitto_rr.

	   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 --port without a	port).

	   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

	   Use SRV lookups to determine	which host to connect to. Performs
	   lookups to _mqtt._tcp.<host>	when used in conjunction with -h,
	   otherwise uses _mqtt._tcp.<local dns	domain>.

       -s, --stdin-file
	   Send	a request message read from stdin, sending the entire content
	   as a	single message.

       -t, --topic
	   The MQTT topic where	the request message will be sent.

	   Provide a protocol to use when connecting to	a broker that has
	   multiple protocols available	on a single port, e.g. MQTT and

	   A valid openssl engine id. These can	be listed with openssl engine

	   See also --keyform.

	   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.

	   See also --tls-engine.

	   If used, this will load and trust the OS provided CA	certificates.
	   This	can be used in conjunction with	--cafile and --capath and can
	   be used on its own to enable	TLS mode. This will be set by default
	   if -L mqtts://...  is used, or if port is 8883 and no other
	   certificate options are used.

	   Choose which	TLS protocol version to	use when communicating with
	   the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
	   default value is tlsv1.2. Must match	the protocol version used by
	   the broker.

       -u, --username
	   Provide a username to be used for authenticating with the broker.
	   See also the	--pw argument.

	   Connect to a	broker through a local unix domain socket instead of a
	   TCP socket. This is a replacement for -h and	-L. For	example:
	   mosquitto_pub --unix	/tmp/mosquitto.sock ...

	   See the socket_domain option	in mosquitto.conf(5) to	configure
	   Mosquitto to	listen on a unix socket.

       -v, --verbose
	   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".

       -V, --protocol-version
	   Specify which version of the	MQTT protocol should be	used when
	   connecting to the rmeote broker. Can	be 5, 311, 31, or the more
	   verbose mqttv5, mqttv311, or	mqttv31. Defaults to 5.

	   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 --will-topic.

	   The QoS to use for the Will.	Defaults to 0. This must be used in
	   conjunction with --will-topic.

	   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 --will-topic.

	   The topic on	which to send a	Will, in the event that	the client
	   disconnects unexpectedly.

	   Set the session-expiry-interval property on the CONNECT packet.
	   Applies to MQTT v5 clients only. Set	to 0-4294967294	to specify the
	   session will	expire in that many seconds after the client
	   disconnects,	or use -1, 4294967295, or a for	a session that does
	   not expire. Defaults	to -1 if -c is also given, or 0	if -c not

	   If the session is set to never expire, either with -x or -c,	then a
	   client id must be provided.

       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 -N argument is passed to mosquitto_rr.

       Payload-only is the default output format and will print	the payload
       exactly as it is	received.

       Verbose mode is activated with -v and prints the	message	topic and the
       payload,	separated by a space.

       The final option	is formatted output, which allows the user to define a
       custom output format. The behaviour is controlled with the -F
       format-string option. The format	string is a free text string where
       interpreted sequences are replaced by different parameters. The
       available interpreted sequences are described below.

       Three characters	are used to start an interpreted sequence: %, @	and \.
       Sequences starting with % 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 @
       are passed to the strftime(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 @N,	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 \, which	is used	to input some
       characters that would otherwise be difficult to enter.

   MQTT	related	parameters
       o   %% a	literal	%.

       o   %A the MQTT v5 topic-alias property,	if present.

       o   %C the MQTT v5 content-type property, if present.

       o   %D the MQTT v5 correlation-data property, if	present. Note that
	   this	property is specified as binary	data, so may produce
	   non-printable characters.

       o   %E the MQTT v5 message-expiry-interval property, if present.

       o   %F the MQTT v5 payload-format-indicator property, if	present.

       o   %l the length of the	payload	in bytes.

       o   %m the message id (only relevant for	messages with QoS>0).

       o   %P the MQTT v5 user-property	property, if present. This will	be
	   printed in the form key:value. It is	possible for any number	of
	   user	properties to be attached to a message,	and to have duplicate

       o   %p the payload raw bytes (may produce non-printable characters
	   depending on	the payload).

       o   %q the message QoS.

       o   %R the MQTT v5 response-topic property, if present.

       o   %r the retained flag	for the	message.

       o   %S the MQTT v5 subscription-identifier property, if present.

       o   %t the message topic.

       o   %x the payload with each byte as a hexadecimal number (lower	case).

       o   %X the payload with each byte as a hexadecimal number (upper	case).

       o   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100

       o   %j JSON output of message parameters	and timestamp, with a quoted
	   and escaped payload.	For example

       o   %J 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:

	   If the payload is not valid JSON, then the error message "Error:
	   Message payload is not valid	JSON on	topic <topic>" will be printed
	   to stderr.

       o   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100

       o   %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637

   Time	related	parameters
       o   @@ a	literal	@.

       o   @X pass the character represented by	X to the strftime function as
	   %X. The options supported are platform dependent.

       o   @N the number of nanoseconds	that have passed in the	current
	   second, with	varying	timing resolution depending on platform.

   Escape characters
       o   \\ a	literal	\.

       o   \0 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 xargs(1) is easier.

       o   \a alert/bell.

       o   \e the escape sequence, which can be	used with ANSI colour codes to
	   provide coloured output for example.

       o   \n end of line.

       o   \r carriage return.

       o   \t horizontal tab.

       o   \v vertical tab.

       mosquitto_rr can	register a message with	the broker that	will be	sent
       out if it disconnects unexpectedly. See mqtt(7) for more	information.

       The minimum requirement for this	is to use --will-topic to specify
       which topic the will should be sent out on. This	will result in a
       non-retained, zero length message with QoS 0.

       Use the --will-retain, --will-payload and --will-qos arguments to
       modify the other	will parameters.

       The -D /	--property option allows adding	properties to different	stages
       of the mosquitto_rr run.	The properties supported for each command are
       as follows:

       o   authentication-data (binary data - note treated as a	string in

       o   authentication-method (UTF-8	string pair)

       o   maximum-packet-size (32-bit unsigned	integer)

       o   receive-maximum (16-bit unsigned integer)

       o   request-problem-information (8-bit unsigned integer)

       o   request-response-information	(8-bit unsigned	integer)

       o   session-expiry-interval (32-bit unsigned integer, note use -x

       o   topic-alias-maximum (16-bit unsigned	integer)

       o   user-property (UTF-8	string pair)

       o   content-type	(UTF-8 string)

       o   correlation-data (binary data - note	treated	as a string in

       o   message-expiry-interval (32-bit unsigned integer)

       o   payload-format-indicator (8-bit unsigned integer)

       o   response-topic (UTF-8 string)

       o   topic-alias (16-bit unsigned	integer)

       o   user-property (UTF-8	string pair)

       o   user-property (UTF-8	string pair)

       o   user-property (UTF-8	string pair)

       o   session-expiry-interval (32-bit unsigned integer)

       o   user-property (UTF-8	string pair)

   Will	properties
       o   content-type	(UTF-8 string)

       o   correlation-data (binary data - note	treated	as a string in

       o   message-expiry-interval (32-bit unsigned integer)

       o   payload-format-indicator (8-bit unsigned integer)

       o   response-topic (UTF-8 string)

       o   user-property (UTF-8	string pair)

       o   will-delay-interval (32-bit unsigned	integer)


	   Timed out waiting for message

       Other non-zero value
	   Unspecified failure

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

       mosquitto bug information can be	found at

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

       Roger Light <>

Mosquitto Project		  11/05/2021		       MOSQUITTO_RR(1)


Want to link to this manual page? Use this URL:

home | help