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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       mosquitto_rr
		    {[-h hostname] [-p port-number] [-u	username] [-P password]	-t message-topic...
		    | -L URL [-t message-topic...]  | [-e response-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]
		    [-q	message-QoS] [-R] [-S] [-v] [-V	protocol-version]
		    [-W	message-processing-timeout] [--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]	[--insecure]]
		    |
		    [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]

       mosquitto_rr [--help]

DESCRIPTION
       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
       feature.

ENCRYPTED CONNECTIONS
       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.

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.

       -A
	   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 the 'clean session' 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.

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

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

	   See also --capath

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

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

	   See also --key.

       --ciphers
	   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
	   forms:

	   -D command identifier value

	   -D command identifier name value

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

	   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.

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

       -F
	   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
	   option.

       --help
	   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
	   argument.

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

       --insecure
	   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
	   encryption.

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

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

	   See also --cert.

       --keyform
	   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:
	   mqtt(s)://[username[:password]@]host[:port]/topic

	   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.

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

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

       --proxy
	   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
	   curl(1).

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

       --psk-identity
	   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
	   QoS.

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

       --quiet
	   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).

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

       -S
	   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 to subscribe to, where responses will	be waited for.
	   See mqtt(7) for more	information on MQTT topics.

	   This	option may be repeated to subscribe to multiple	topics.

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

       --tls-engine
	   A valid openssl engine id. These can	be listed with openssl engine
	   command.

	   See also --keyform.

       --tls-engine-kpass-sha1
	   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.

       --tls-version
	   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.

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

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

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

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

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

OUTPUT FORMAT
       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   %l the length of the	payload	in bytes.

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

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

       o   %q the message QoS.

       o   %r the retained flag	for the	message.

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

   Helpers
       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
	   {"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello
	   world"}

       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:
	   {"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.

       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.

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

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

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

       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)

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

       o   user-property (UTF-8	string pair)

   Publish
       o   content-type	(UTF-8 string)

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

       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)

   Subscribe
       o   user-property (UTF-8	string pair)

   Unsubscribe
       o   user-property (UTF-8	string pair)

   Disconnect
       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
	   mosquitto_pub)

       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)

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

BUGS
       mosquitto bug information can be	found at
       https://github.com/eclipse/mosquitto/issues

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

AUTHOR
       Roger Light <roger@atchoo.org>

Mosquitto Project		  09/25/2019		       MOSQUITTO_RR(1)

NAME | SYNOPSIS | DESCRIPTION | ENCRYPTED CONNECTIONS | OPTIONS | OUTPUT FORMAT | WILLS | PROPERTIES | FILES | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mosquitto_rr&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help